coffeescript

Version:

Unfancy JavaScript

132 lines • 128 kB

HTML

<!DOCTYPE html> <html> <head> <title>underscore.coffee</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> underscore.coffee </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">¶</a> </div> Underscore.coffee (c) 2010 Jeremy Ashkenas, DocumentCloud Inc. Underscore is freely distributable under the terms of the <a href="http://en.wikipedia.org/wiki/MIT_License">MIT license</a>. Portions of Underscore are inspired by or borrowed from <a href="http://prototypejs.org/api">Prototype.js</a>, Oliver Steele's <a href="http://osteele.com">Functional</a>, and John Resig's <a href="http://ejohn.org">Micro-Templating</a>. For all details and documentation: http://documentcloud.github.com/underscore/ </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> <h2>Baseline setup</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> Establish the root object, <code>window</code> in the browser, or <code>global</code> on the server. </td> <td class="code"> <div class="highlight"><pre>root = this</pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> Save the previous value of the <code>_</code> variable. </td> <td class="code"> <div class="highlight"><pre>previousUnderscore = root._</pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> Establish the object that gets thrown to break out of a loop iteration. <code>StopIteration</code> is SOP on Mozilla. </td> <td class="code"> <div class="highlight"><pre>breaker = if typeof(StopIteration) is 'undefined' then '__break__' else StopIteration</pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</a> </div> Helper function to escape RegExp contents, because JS doesn't have one. </td> <td class="code"> <div class="highlight"><pre>escapeRegExp = (string) -> string.replace(/([.*+?^${}()|[\]\/\\])/g, '\\$1')</pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</a> </div> Save bytes in the minified (but not gzipped) version: </td> <td class="code"> <div class="highlight"><pre>ArrayProto = Array.prototype ObjProto = Object.prototype</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</a> </div> Create quick reference variables for speed access to core prototypes. </td> <td class="code"> <div class="highlight"><pre>slice = ArrayProto.slice unshift = ArrayProto.unshift toString = ObjProto.toString hasOwnProperty = ObjProto.hasOwnProperty propertyIsEnumerable = ObjProto.propertyIsEnumerable</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> All ECMA5 native implementations we hope to use are declared here. </td> <td class="code"> <div class="highlight"><pre>nativeForEach = ArrayProto.forEach nativeMap = ArrayProto.map nativeReduce = ArrayProto.reduce nativeReduceRight = ArrayProto.reduceRight nativeFilter = ArrayProto.filter nativeEvery = ArrayProto.every nativeSome = ArrayProto.some nativeIndexOf = ArrayProto.indexOf nativeLastIndexOf = ArrayProto.lastIndexOf nativeIsArray = Array.isArray nativeKeys = Object.keys</pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> Create a safe reference to the Underscore object for use below. </td> <td class="code"> <div class="highlight"><pre>_ = (obj) -> new wrapper(obj)</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</a> </div> Export the Underscore object for CommonJS. </td> <td class="code"> <div class="highlight"><pre>if typeof(exports) != 'undefined' then exports._ = _</pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> Export Underscore to global scope. </td> <td class="code"> <div class="highlight"><pre>root._ = _</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</a> </div> Current version. </td> <td class="code"> <div class="highlight"><pre>_.VERSION = '1.1.0'</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">¶</a> </div> <h2>Collection Functions</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> The cornerstone, an each implementation. Handles objects implementing forEach, arrays, and raw objects. </td> <td class="code"> <div class="highlight"><pre>_.each = (obj, iterator, context) -> try if nativeForEach and obj.forEach is nativeForEach obj.forEach iterator, context else if _.isNumber obj.length iterator.call context, obj[i], i, obj for i in [0...obj.length] else iterator.call context, val, key, obj for key, val of obj catch e throw e if e isnt breaker obj</pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</a> </div> Return the results of applying the iterator to each element. Use JavaScript 1.6's version of map, if possible. </td> <td class="code"> <div class="highlight"><pre>_.map = (obj, iterator, context) -> return obj.map(iterator, context) if nativeMap and obj.map is nativeMap results = [] _.each obj, (value, index, list) -> results.push iterator.call context, value, index, list results</pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> Reduce builds up a single result from a list of values. Also known as inject, or foldl. Uses JavaScript 1.8's version of reduce, if possible. </td> <td class="code"> <div class="highlight"><pre>_.reduce = (obj, iterator, memo, context) -> if nativeReduce and obj.reduce is nativeReduce iterator = _.bind iterator, context if context return obj.reduce iterator, memo _.each obj, (value, index, list) -> memo = iterator.call context, memo, value, index, list memo</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> The right-associative version of reduce, also known as foldr. Uses JavaScript 1.8's version of reduceRight, if available. </td> <td class="code"> <div class="highlight"><pre>_.reduceRight = (obj, iterator, memo, context) -> if nativeReduceRight and obj.reduceRight is nativeReduceRight iterator = _.bind iterator, context if context return obj.reduceRight iterator, memo reversed = _.clone(_.toArray(obj)).reverse() _.reduce reversed, iterator, memo, context</pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</a> </div> Return the first value which passes a truth test. </td> <td class="code"> <div class="highlight"><pre>_.detect = (obj, iterator, context) -> result = null _.each obj, (value, index, list) -> if iterator.call context, value, index, list result = value _.breakLoop() result</pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</a> </div> Return all the elements that pass a truth test. Use JavaScript 1.6's filter, if it exists. </td> <td class="code"> <div class="highlight"><pre>_.filter = (obj, iterator, context) -> return obj.filter iterator, context if nativeFilter and obj.filter is nativeFilter results = [] _.each obj, (value, index, list) -> results.push value if iterator.call context, value, index, list results</pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-21">¶</a> </div> Return all the elements for which a truth test fails. </td> <td class="code"> <div class="highlight"><pre>_.reject = (obj, iterator, context) -> results = [] _.each obj, (value, index, list) -> results.push value if not iterator.call context, value, index, list results</pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-22">¶</a> </div> Determine whether all of the elements match a truth test. Delegate to JavaScript 1.6's every, if it is present. </td> <td class="code"> <div class="highlight"><pre>_.every = (obj, iterator, context) -> iterator ||= _.identity return obj.every iterator, context if nativeEvery and obj.every is nativeEvery result = true _.each obj, (value, index, list) -> _.breakLoop() unless (result = result and iterator.call(context, value, index, list)) result</pre></div> </td> </tr> <tr id="section-23"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-23">¶</a> </div> Determine if at least one element in the object matches a truth test. Use JavaScript 1.6's some, if it exists. </td> <td class="code"> <div class="highlight"><pre>_.some = (obj, iterator, context) -> iterator ||= _.identity return obj.some iterator, context if nativeSome and obj.some is nativeSome result = false _.each obj, (value, index, list) -> _.breakLoop() if (result = iterator.call(context, value, index, list)) result</pre></div> </td> </tr> <tr id="section-24"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-24">¶</a> </div> Determine if a given value is included in the array or object, based on <code>===</code>. </td> <td class="code"> <div class="highlight"><pre>_.include = (obj, target) -> return _.indexOf(obj, target) isnt -1 if nativeIndexOf and obj.indexOf is nativeIndexOf for key, val of obj return true if val is target false</pre></div> </td> </tr> <tr id="section-25"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-25">¶</a> </div> Invoke a method with arguments on every item in a collection. </td> <td class="code"> <div class="highlight"><pre>_.invoke = (obj, method) -> args = _.rest arguments, 2 (if method then val[method] else val).apply(val, args) for val in obj</pre></div> </td> </tr> <tr id="section-26"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-26">¶</a> </div> Convenience version of a common use case of map: fetching a property. </td> <td class="code"> <div class="highlight"><pre>_.pluck = (obj, key) -> _.map(obj, (val) -> val[key])</pre></div> </td> </tr> <tr id="section-27"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-27">¶</a> </div> Return the maximum item or (item-based computation). </td> <td class="code"> <div class="highlight"><pre>_.max = (obj, iterator, context) -> return Math.max.apply(Math, obj) if not iterator and _.isArray(obj) result = computed: -Infinity _.each obj, (value, index, list) -> computed = if iterator then iterator.call(context, value, index, list) else value computed >= result.computed and (result = {value: value, computed: computed}) result.value</pre></div> </td> </tr> <tr id="section-28"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-28">¶</a> </div> Return the minimum element (or element-based computation). </td> <td class="code"> <div class="highlight"><pre>_.min = (obj, iterator, context) -> return Math.min.apply(Math, obj) if not iterator and _.isArray(obj) result = computed: Infinity _.each obj, (value, index, list) -> computed = if iterator then iterator.call(context, value, index, list) else value computed < result.computed and (result = {value: value, computed: computed}) result.value</pre></div> </td> </tr> <tr id="section-29"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-29">¶</a> </div> Sort the object's values by a criterion produced by an iterator. </td> <td class="code"> <div class="highlight"><pre>_.sortBy = (obj, iterator, context) -> _.pluck(((_.map obj, (value, index, list) -> {value: value, criteria: iterator.call(context, value, index, list)} ).sort((left, right) -> a = left.criteria; b = right.criteria if a < b then -1 else if a > b then 1 else 0 )), 'value')</pre></div> </td> </tr> <tr id="section-30"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-30">¶</a> </div> Use a comparator function to figure out at what index an object should be inserted so as to maintain order. Uses binary search. </td> <td class="code"> <div class="highlight"><pre>_.sortedIndex = (array, obj, iterator) -> iterator ||= _.identity low = 0 high = array.length while low < high mid = (low + high) >> 1 if iterator(array[mid]) < iterator(obj) then low = mid + 1 else high = mid low</pre></div> </td> </tr> <tr id="section-31"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-31">¶</a> </div> Convert anything iterable into a real, live array. </td> <td class="code"> <div class="highlight"><pre>_.toArray = (iterable) -> return [] if (!iterable) return iterable.toArray() if (iterable.toArray) return iterable if (_.isArray(iterable)) return slice.call(iterable) if (_.isArguments(iterable)) _.values(iterable)</pre></div> </td> </tr> <tr id="section-32"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-32">¶</a> </div> Return the number of elements in an object. </td> <td class="code"> <div class="highlight"><pre>_.size = (obj) -> _.toArray(obj).length</pre></div> </td> </tr> <tr id="section-33"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-33">¶</a> </div> <h2>Array Functions</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-34"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-34">¶</a> </div> Get the first element of an array. Passing <code>n</code> will return the first N values in the array. Aliased as head. The <code>guard</code> check allows it to work with map. </td> <td class="code"> <div class="highlight"><pre>_.first = (array, n, guard) -> if n and not guard then slice.call(array, 0, n) else array[0]</pre></div> </td> </tr> <tr id="section-35"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-35">¶</a> </div> Returns everything but the first entry of the array. Aliased as tail. Especially useful on the arguments object. Passing an <code>index</code> will return the rest of the values in the array from that index onward. The <code>guard</code> check allows it to work with map. </td> <td class="code"> <div class="highlight"><pre>_.rest = (array, index, guard) -> slice.call(array, if _.isUndefined(index) or guard then 1 else <span cl