From 666049ac5db5634ba8694e64684b31ab2d1f1549 Mon Sep 17 00:00:00 2001 From: Brad Dunbar Date: Sat, 17 Mar 2012 13:02:17 -0400 Subject: [PATCH 1/4] Add utility function `getValue`. --- index.html | 195 ++++++++++++++++++++++++++---------------------- test/utility.js | 9 +++ underscore.js | 6 ++ 3 files changed, 119 insertions(+), 91 deletions(-) diff --git a/index.html b/index.html index 9165f1428..c6818b7a7 100644 --- a/index.html +++ b/index.html @@ -3,7 +3,7 @@ - + Underscore.js - +
@@ -297,7 +298,7 @@ A complete Test & Benchmark Suite is included for your perusal.

- +

You may also read through the annotated source code.

@@ -327,7 +328,7 @@ < 4kb, Minified and Gzipped - +
Upgrade warning: version 1.3.0 removes AMD (RequireJS) support.
@@ -525,7 +526,7 @@ _.min(numbers);

sortBy_.sortBy(list, iterator, [context])
- Returns a sorted copy of list, ranked in ascending order by the + Returns a sorted copy of list, ranked in ascending order by the results of running each value through iterator. 

@@ -565,7 +566,7 @@ _.sortedIndex([10, 20, 30, 40, 50], 35);
       

         shuffle_.shuffle(list)
         

-        Returns a shuffled copy of the list, using a version of the 
+        Returns a shuffled copy of the list, using a version of the
         Fisher-Yates shuffle.
       

       
@@ -751,7 +752,7 @@ _.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
         

         Returns the index at which value can be found in the array,
         or -1 if value is not present in the array. Uses the native
-        indexOf function unless it's missing. If you're working with a 
+        indexOf function unless it's missing. If you're working with a
         large array, and you know that the array is already sorted, pass true
         for isSorted to use a faster binary search.
       

@@ -836,7 +837,7 @@ jQuery('#underscore_button').bind('click', buttonView.onClick);
         memoize_.memoize(function, [hashFunction])
         

         Memoizes a given function by caching the computed result. Useful
-        for speeding up slow-running computations. If passed an optional 
+        for speeding up slow-running computations. If passed an optional
         hashFunction, it will be used to compute the hash key for storing
         the result, based on the arguments to the original function. The default
         hashFunction just uses the first argument to the memoized function
@@ -877,8 +878,8 @@ _.defer(function(){ alert('deferred'); });
       

         throttle_.throttle(function, wait)
         

-        Creates and returns a new, throttled version of the passed function, 
-        that, when invoked repeatedly, will only actually call the original function 
+        Creates and returns a new, throttled version of the passed function,
+        that, when invoked repeatedly, will only actually call the original function
         at most once per every wait
         milliseconds. Useful for rate-limiting events that occur faster than you
         can keep up with.
@@ -892,11 +893,11 @@ $(window).scroll(throttled);
         debounce_.debounce(function, wait)
         

         Creates and returns a new debounced version of the passed function that
-        will postpone its execution until after 
-        wait milliseconds have elapsed since the last time it  
-        was invoked. Useful for implementing behavior that should only happen 
-        after the input has stopped arriving. For example: rendering a 
-        preview of a Markdown comment, recalculating a layout after the window 
+        will postpone its execution until after
+        wait milliseconds have elapsed since the last time it
+        was invoked. Useful for implementing behavior that should only happen
+        after the input has stopped arriving. For example: rendering a
+        preview of a Markdown comment, recalculating a layout after the window
         has stopped being resized, and so on.
       

       
@@ -907,7 +908,7 @@ $(window).resize(lazyLayout);
       

         once_.once(function)
         

-        Creates a version of the function that can only be called one time. 
+        Creates a version of the function that can only be called one time.
         Repeated calls to the modified function will have no effect, returning
         the value from the original call. Useful for initialization functions,
         instead of having to set a boolean flag and then check it later.
@@ -922,7 +923,7 @@ initialize();
       

         after_.after(count, function)
         

-        Creates a version of the function that will only be run after first 
+        Creates a version of the function that will only be run after first
         being called count times. Useful for grouping asynchronous responses,
         where you want to be sure that all the async calls have finished, before
         proceeding.
@@ -930,7 +931,7 @@ initialize();
       
 var renderNotes = _.after(notes.length, render);
 _.each(notes, function(note) {
-  note.asyncSave({success: renderNotes}); 
+  note.asyncSave({success: renderNotes});
 });
 // renderNotes is run once, after all notes have saved.
 

@@ -1058,9 +1059,9 @@ _.chain([1,2,3,200])
       

         has_.has(object, key)
         

-        Does the object contain the given key? Identical to 
+        Does the object contain the given key? Identical to
         object.hasOwnProperty(key), but uses a safe reference to the
-        hasOwnProperty function, in case it's been 
+        hasOwnProperty function, in case it's been
         overridden accidentally.
       

       
@@ -1238,7 +1239,7 @@ _.isNull(undefined);
 _.isUndefined(window.missingVariable);
 => true
 

-      
+
       
Utility Functions

 
       

@@ -1275,7 +1276,7 @@ _(3).times(function(){ genie.grantWish(); });

         mixin_.mixin(object)
         

         Allows you to extend Underscore with your own utility functions. Pass
-        a hash of {name: function} definitions to have your functions 
+        a hash of {name: function} definitions to have your functions
         added to the Underscore object, as well as the OOP wrapper.
       

       
@@ -1302,13 +1303,25 @@ _.uniqueId('contact_');
       

         escape_.escape(string)
         

-        Escapes a string for insertion into HTML, replacing 
+        Escapes a string for insertion into HTML, replacing
         &, <, >, ", ', and / characters.
       

       
 _.escape('Curly, Larry & Moe');
 => "Curly, Larry &amp; Moe"

 
+      

+        getValue_.getValue(object, property)
+        

+        Returns a value from an object as a property or as a function.
+      

+      
+var object = {cheese: 'crumpets', stuff: function(){ return 'nonsense'; }};
+_.getValue(object, 'cheese');
+=> "crumpets"
+_.getValue(object, 'stuff');
+=> "nonsense"

+
       

         template_.template(templateString, [context])
         

@@ -1340,7 +1353,7 @@ template({value : '<script>'});
         You can also use print from within JavaScript code.  This is
         sometimes more convenient than using <%= ... %>.
       

-      
+
       
 var compiled = _.template("<% print('Hello ' + epithet); %>");
 compiled({epithet: "stooge"});
@@ -1349,8 +1362,8 @@ compiled({epithet: "stooge"});
       

         If ERB-style delimiters aren't your cup of tea, you can change Underscore's
         template settings to use different symbols to set off interpolated code.
-        Define an interpolate regex to match expressions that should be 
-        interpolated verbatim, an escape regex to match expressions that should 
+        Define an interpolate regex to match expressions that should be
+        interpolated verbatim, an escape regex to match expressions that should
         be inserted after being HTML escaped, and an evaluate regex to match
         expressions that should be evaluated without insertion into the resulting
         string. You may define or omit any combination of the three.
@@ -1451,7 +1464,7 @@ _([1, 2, 3]).value();
         The source is
         available on GitHub.
       

-      
+
       

         Underscore.php,
         a PHP port of the functions that are applicable in both languages.
@@ -1459,17 +1472,17 @@ _([1, 2, 3]).value();
         The source is
         available on GitHub.
       

-      
+
       

         Underscore-perl,
-        a Perl port of many of the Underscore.js functions, 
-        aimed at on Perl hashes and arrays, also 
+        a Perl port of many of the Underscore.js functions,
+        aimed at on Perl hashes and arrays, also
         available on GitHub.
       

-      
+
       

         Underscore.string,
-        an Underscore extension that adds functions for string-manipulation: 
+        an Underscore extension that adds functions for string-manipulation:
         trim, startsWith, contains, capitalize,
         reverse, sprintf, and more.
       

@@ -1488,7 +1501,7 @@ _([1, 2, 3]).value();
         Functional JavaScript,
         which includes comprehensive higher-order function support as well as string lambdas.
       

-      
+
       

         Michael Aufreiter's Data.js,
         a data manipulation + persistence library for JavaScript.
@@ -1499,7 +1512,7 @@ _([1, 2, 3]).value();
       

 
       
Change Log

-      
+
       

         1.3.1 — Jan. 23, 2012

         
    
@@ -1510,7 +1523,7 @@ _([1, 2, 3]).value();
             Added _.collect as an alias for _.map. Smalltalkers, rejoice.
           
           
  • 
-            Reverted an old change so that _.extend will correctly copy 
+            Reverted an old change so that _.extend will correctly copy
             over keys with undefined values again.
           
    • 
           
  • 
@@ -1518,7 +1531,7 @@ _([1, 2, 3]).value();
           
    • 
         

       

-      
+
       

         1.3.0 — Jan. 11, 2012

         
    
@@ -1529,12 +1542,12 @@ _([1, 2, 3]).value();
           
         

       

-      
+
       

         1.2.4 — Jan. 4, 2012

         
    
           
  • 
-            You now can (and probably should) write _.chain(list) 
+            You now can (and probably should) write _.chain(list)
             instead of _(list).chain().
           
    • 
           
  • 
@@ -1551,7 +1564,7 @@ _([1, 2, 3]).value();
           
    • 
         

       

-      
+
       

         1.2.3 — Dec. 7, 2011

         
    
@@ -1564,12 +1577,12 @@ _([1, 2, 3]).value();
           
           
  • 
             Both _.reduce and _.reduceRight can now be passed an
-            explicitly undefined value. (There's no reason why you'd 
+            explicitly undefined value. (There's no reason why you'd
             want to do this.)
           
    • 
         

       

-      
+
       

         1.2.2 — Nov. 14, 2011

         
    
@@ -1588,22 +1601,22 @@ _([1, 2, 3]).value();
           
           
  • 
             _.after(callback, 0) will now trigger the callback immediately,
-            making "after" easier to use with asynchronous APIs (#366). 
+            making "after" easier to use with asynchronous APIs (#366).
           
    • 
         

       

-      
+
       

         1.2.1 — Oct. 24, 2011

         
    
           
  • 
-            Several important bug fixes for _.isEqual, which should now 
-            do better on mutated Arrays, and on non-Array objects with 
+            Several important bug fixes for _.isEqual, which should now
+            do better on mutated Arrays, and on non-Array objects with
             length properties. (#329)
           
    • 
           
  • 
             jrburke contributed Underscore exporting for AMD module loaders,
-            and tonylukasavage for Appcelerator Titanium. 
+            and tonylukasavage for Appcelerator Titanium.
             (#335, #338)
           
    • 
           
  • 
@@ -1611,7 +1624,7 @@ _([1, 2, 3]).value();
             grouping values by a particular common property.
           
    • 
           
  • 
-            _.throttle'd functions now fire immediately upon invocation, 
+            _.throttle'd functions now fire immediately upon invocation,
             and are rate-limited thereafter (#170, #266).
           
    • 
           
  • 
@@ -1619,7 +1632,7 @@ _([1, 2, 3]).value();
           
    • 
           
  • 
             The _.bind function now also works on constructors, a-la
-            ES5 ... but you would never want to use _.bind on a 
+            ES5 ... but you would never want to use _.bind on a
             constructor function.
           
    • 
           
  • 
@@ -1631,25 +1644,25 @@ _([1, 2, 3]).value();
           
    • 
         

       

-      
+
       

         1.2.0 — Oct. 5, 2011

         
    
           
  • 
-            The _.isEqual function now 
+            The _.isEqual function now
             supports true deep equality comparisons, with checks for cyclic structures,
             thanks to Kit Cambridge.
           
    • 
           
  • 
-            Underscore templates now support HTML escaping interpolations, using 
-            <%- ... %> syntax. 
+            Underscore templates now support HTML escaping interpolations, using
+            <%- ... %> syntax.
           
    • 
           
  • 
-            Ryan Tenney contributed _.shuffle, which uses a modified 
-            Fisher-Yates to give you a shuffled copy of an array. 
+            Ryan Tenney contributed _.shuffle, which uses a modified
+            Fisher-Yates to give you a shuffled copy of an array.
           
    • 
           
  • 
-            _.uniq can now be passed an optional iterator, to determine by 
+            _.uniq can now be passed an optional iterator, to determine by
             what criteria an object should be considered unique.
           
    • 
           
  • 
@@ -1658,22 +1671,22 @@ _([1, 2, 3]).value();
           
    • 
           
  • 
             A new _.initial function was added, as a mirror of _.rest,
-            which returns all the initial values of a list (except the last N). 
+            which returns all the initial values of a list (except the last N).
           
    • 
         

       

-      
+
       

         1.1.7 — July 13, 2011

         Added _.groupBy, which aggregates a collection into groups of like items.
-        Added _.union and _.difference, to complement the 
+        Added _.union and _.difference, to complement the
         (re-named) _.intersection.
         Various improvements for support of sparse arrays.
         _.toArray now returns a clone, if directly passed an array.
         _.functions now also returns the names of functions that are present
         in the prototype chain.
       

-            
+
       

         1.1.6 — April 18, 2011

         Added _.after, which will return a function that only runs after
@@ -1684,30 +1697,30 @@ _([1, 2, 3]).value();
         _.extend no longer copies keys when the value is undefined.
         _.bind now errors when trying to bind an undefined value.
       

-      
+
       

         1.1.5 — Mar 20, 2011

         Added an _.defaults function, for use merging together JS objects
         representing default options.
         Added an _.once function, for manufacturing functions that should
         only ever execute a single time.
-        _.bind now delegates to the native ECMAScript 5 version, 
+        _.bind now delegates to the native ECMAScript 5 version,
         where available.
         _.keys now throws an error when used on non-Object values, as in
         ECMAScript 5.
         Fixed a bug with _.keys when used over sparse arrays.
       

-      
+
       

         1.1.4 — Jan 9, 2011

-        Improved compliance with ES5's Array methods when passing null 
+        Improved compliance with ES5's Array methods when passing null
         as a value. _.wrap now correctly sets this for the
         wrapped function. _.indexOf now takes an optional flag for
         finding the insertion index in an array that is guaranteed to already
         be sorted. Avoiding the use of .callee, to allow _.isArray
         to work properly in ES5's strict mode.
       

-      
+
       

         1.1.3 — Dec 1, 2010

         In CommonJS, Underscore may now be required with just: 

@@ -1719,26 +1732,26 @@ _([1, 2, 3]).value();
         Improved the isType family of functions for better interoperability
         with Internet Explorer host objects.
         _.template now correctly escapes backslashes in templates.
-        Improved _.reduce compatibility with the ECMA5 version: 
+        Improved _.reduce compatibility with the ECMA5 version:
         if you don't pass an initial value, the first item in the collection is used.
         _.each no longer returns the iterated collection, for improved
         consistency with ES5's forEach.
       

-      
+
       

         1.1.2

-        Fixed _.contains, which was mistakenly pointing at 
-        _.intersect instead of _.include, like it should 
+        Fixed _.contains, which was mistakenly pointing at
+        _.intersect instead of _.include, like it should
         have been. Added _.unique as an alias for _.uniq.
       

-      
+
       

         1.1.1

         Improved the speed of _.template, and its handling of multiline
-        interpolations. Ryan Tenney contributed optimizations to many Underscore 
+        interpolations. Ryan Tenney contributed optimizations to many Underscore
         functions. An annotated version of the source code is now available.
       

-      
+
       

         1.1.0

         The method signature of _.reduce has been changed to match
@@ -1747,33 +1760,33 @@ _([1, 2, 3]).value();
         called with no arguments, and preserves whitespace. _.contains
         is a new alias for _.include.
       

-      
+
       

         1.0.4

-        Andri Möll contributed the _.memoize 
-        function, which can be used to speed up expensive repeated computations 
+        Andri Möll contributed the _.memoize
+        function, which can be used to speed up expensive repeated computations
         by caching the results.
       

-      
+
       

         1.0.3

         Patch that makes _.isEqual return false if any property
         of the compared object has a NaN value. Technically the correct
         thing to do, but of questionable semantics. Watch out for NaN comparisons.
       

-      
+
       

         1.0.2

         Fixes _.isArguments in recent versions of Opera, which have
         arguments objects as real Arrays.
       

-      
+
       

         1.0.1

-        Bugfix for _.isEqual, when comparing two objects with the same 
+        Bugfix for _.isEqual, when comparing two objects with the same
         number of undefined keys, but with different names.
       

-      
+
       

         1.0.0

         Things have been stable for many months now, so Underscore is now
@@ -1781,15 +1794,15 @@ _([1, 2, 3]).value();
         include _.isBoolean, and the ability to have _.extend
         take multiple source objects.
       

-      
+
       

         0.6.0

-        Major release. Incorporates a number of 
+        Major release. Incorporates a number of
         Mile Frawley's refactors for
         safer duck-typing on collection functions, and cleaner internals. A new
         _.mixin method that allows you to extend Underscore with utility
-        functions of your own. Added _.times, which works the same as in 
-        Ruby or Prototype.js. Native support for ECMAScript 5's Array.isArray, 
+        functions of your own. Added _.times, which works the same as in
+        Ruby or Prototype.js. Native support for ECMAScript 5's Array.isArray,
         and Object.keys.
       

 
@@ -1847,7 +1860,7 @@ _([1, 2, 3]).value();
         0.5.1

         Added an _.isArguments function. Lots of little safety checks
         and optimizations contributed by
-        Noah Sloan and 
+        Noah Sloan and
         Andri Möll.
       

 
diff --git a/test/utility.js b/test/utility.js
index c285751ea..5f2485478 100644
--- a/test/utility.js
+++ b/test/utility.js
@@ -165,4 +165,13 @@ $(document).ready(function() {
     strictEqual(tmpl(), '
\u2028\u2028\u2029\u2029
');
   });
 
+  test('getValue calls functions and returns primitives', function() {
+    var obj = {w: '', x: 'x', y: function(){ return 'y'; }};
+    strictEqual(_.getValue(obj, 'w'), '');
+    strictEqual(_.getValue(obj, 'x'), 'x');
+    strictEqual(_.getValue(obj, 'y'), 'y');
+    strictEqual(_.getValue(obj, 'z'), undefined);
+    strictEqual(_.getValue(null, 'x'), null);
+  });
+
 });
diff --git a/underscore.js b/underscore.js
index b956e21ce..720801588 100644
--- a/underscore.js
+++ b/underscore.js
@@ -873,6 +873,12 @@
     return (''+string).replace(/&/g, '&').replace(//g, '>').replace(/"/g, '"').replace(/'/g, ''').replace(/\//g,'/');
   };
 
+  // Get a value from an object as a property or as a function.
+  _.getValue = function(object, prop) {
+    if (object == null) return null;
+    return _.isFunction(object[prop]) ? object[prop]() : object[prop];
+  };
+
   // Add your own custom functions to the Underscore object, ensuring that
   // they're correctly added to the OOP wrapper as well.
   _.mixin = function(obj) {

From d0e7b397c1427bf69f2c03d45c5ce31dc60f8612 Mon Sep 17 00:00:00 2001
From: Brad Dunbar 
Date: Mon, 19 Mar 2012 14:24:59 -0400
Subject: [PATCH 2/4] Cache property value.

---
 underscore.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/underscore.js b/underscore.js
index 720801588..24dcc72be 100644
--- a/underscore.js
+++ b/underscore.js
@@ -876,7 +876,8 @@
   // Get a value from an object as a property or as a function.
   _.getValue = function(object, prop) {
     if (object == null) return null;
-    return _.isFunction(object[prop]) ? object[prop]() : object[prop];
+    var value = object[prop];
+    return _.isFunction(value) ? value() : value;
   };
 
   // Add your own custom functions to the Underscore object, ensuring that

From 5c7ccb21ef5404dbbf4d925d03f35e49967e9a3a Mon Sep 17 00:00:00 2001
From: Brad Dunbar 
Date: Mon, 19 Mar 2012 14:33:38 -0400
Subject: [PATCH 3/4] Rename `getValue` to `result`.

---
 index.html      | 10 +++++-----
 test/utility.js | 12 ++++++------
 underscore.js   |  2 +-
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/index.html b/index.html
index c6818b7a7..f2a00cae3 100644
--- a/index.html
+++ b/index.html
@@ -245,7 +245,7 @@
       
  • - mixin
    • 
       
  • - uniqueId
    • 
       
  • - escape
    • 
-      
  • - getValue
    • 
+      
  • - result
    • 
       
  • - template
    • 
     
 
@@ -1310,16 +1310,16 @@ _.uniqueId('contact_');
 _.escape('Curly, Larry & Moe');
 => "Curly, Larry &amp; Moe"
    
 
-      
    
-        getValue_.getValue(object, property)
+      
    
+        result_.result(object, property)
         
    
         Returns a value from an object as a property or as a function.
       
    
       
     var object = {cheese: 'crumpets', stuff: function(){ return 'nonsense'; }};
-_.getValue(object, 'cheese');
+_.result(object, 'cheese');
 => "crumpets"
-_.getValue(object, 'stuff');
+_.result(object, 'stuff');
 => "nonsense"
    
 
       
    
diff --git a/test/utility.js b/test/utility.js
index 5f2485478..ec9960eae 100644
--- a/test/utility.js
+++ b/test/utility.js
@@ -165,13 +165,13 @@ $(document).ready(function() {
     strictEqual(tmpl(), '
    \u2028\u2028\u2029\u2029
    ');
   });
 
-  test('getValue calls functions and returns primitives', function() {
+  test('result calls functions and returns primitives', function() {
     var obj = {w: '', x: 'x', y: function(){ return 'y'; }};
-    strictEqual(_.getValue(obj, 'w'), '');
-    strictEqual(_.getValue(obj, 'x'), 'x');
-    strictEqual(_.getValue(obj, 'y'), 'y');
-    strictEqual(_.getValue(obj, 'z'), undefined);
-    strictEqual(_.getValue(null, 'x'), null);
+    strictEqual(_.result(obj, 'w'), '');
+    strictEqual(_.result(obj, 'x'), 'x');
+    strictEqual(_.result(obj, 'y'), 'y');
+    strictEqual(_.result(obj, 'z'), undefined);
+    strictEqual(_.result(null, 'x'), null);
   });
 
 });
diff --git a/underscore.js b/underscore.js
index 24dcc72be..c00438cc5 100644
--- a/underscore.js
+++ b/underscore.js
@@ -874,7 +874,7 @@
   };
 
   // Get a value from an object as a property or as a function.
-  _.getValue = function(object, prop) {
+  _.result = function(object, prop) {
     if (object == null) return null;
     var value = object[prop];
     return _.isFunction(value) ? value() : value;

From 5545a3b68da905b7cc956c1070f45cf9127ec045 Mon Sep 17 00:00:00 2001
From: Brad Dunbar 
Date: Mon, 19 Mar 2012 14:43:20 -0400
Subject: [PATCH 4/4] Dispense with abbreviation.

---
 underscore.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/underscore.js b/underscore.js
index c00438cc5..eff693d3a 100644
--- a/underscore.js
+++ b/underscore.js
@@ -874,9 +874,9 @@
   };
 
   // Get a value from an object as a property or as a function.
-  _.result = function(object, prop) {
+  _.result = function(object, property) {
     if (object == null) return null;
-    var value = object[prop];
+    var value = object[property];
     return _.isFunction(value) ? value() : value;
   };