underscore.

cofee
Underscore.coffee (c) 2011 Jeremy Ashkenas, DocumentCloud Inc. Underscore is freely distributable under the terms of the MIT license. Portions of Underscore are inspired by or borrowed fromPrototype.js, Oliver Steele's Functional, and John Resig's Micro-Templating. For all details and documentation: http://documentcloud.github.com/underscore/

Baseline setup
Establish the root object, window in the browser, or global on the server. Save the previous value of the _ variable.
root = this

previousUnderscore = root._ breaker = if typeof(StopIteration) is 'undefined' then escapeRegExp = (string) -> string.replace(/([.*+?^${}()| [\]\/\\])/g, '\\$1') ArrayProto = Object.prototype = Array.prototype ObjProto

Establish the object that gets thrown to break out of a loop '__break__' else StopIteration iteration. StopIteration is SOP on Mozilla. Helper function to escape RegExp contents, because JS doesn't have one. Save bytes in the minified (but not gzipped) version: Create quick reference variables for speed access to core prototypes.

slice = ArrayProto.slice unshift = ArrayProto.unshift toString = ObjProto.toString hasOwnProperty = ObjProto.hasOwnProperty propertyIsEnumerable = ObjProto.propertyIsEnumerable 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 _ = (obj) -> new wrapper(obj)

All ECMA5 native implementations we hope to use are declared here.

Create a safe reference to the Underscore object for use below. Export the Underscore object for CommonJS. Export Underscore to global scope. Current version.

if typeof(exports) != 'undefined' then exports._ = _ root._ = _ _.VERSION = '1.1.0'

Collection Functions
The cornerstone, an each implementation. Handles objects nativeForEach and obj.forEach is nativeForEach implementing forEach, arrays, and raw objects.
_.each = (obj, iterator, context) -> try if 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 own key, val of obj catch e

throw e if e isnt breaker obj _.map = (obj, iterator, context) -> return Return the results of applying the iterator to each element. obj.map(iterator, context) if nativeMap and obj.map is Use JavaScript 1.6's version of map, if possible. nativeMap results = [] _.each obj, (value, index, list) -> results.push iterator.call context, value, index, list results

Reduce builds up a single result from a list of values. Also nativeReduce and obj.reduce is nativeReduce iterator known as inject, or foldl. Uses JavaScript 1.8's version = _.bind iterator, context if context return of reduce, if possible.
obj.reduce iterator, memo _.each obj, (value, index, list) -> memo = iterator.call context, memo, value, index, list memo _.reduceRight = (obj, iterator, memo, context) -> if The right-associative version of reduce, also known as foldr. Uses JavaScript 1.8's version of reduceRight, if nativeReduceRight and obj.reduceRight is nativeReduceRight iterator = _.bind iterator, context available. if context return obj.reduceRight iterator, memo reversed = _.clone(_.toArray(obj)).reverse() _.reduce reversed, iterator, memo, context

_.reduce = (obj, iterator, memo, context) ->

if

Return the first value which passes a truth test.

_.detect = (obj, iterator, context) -> result = null _.each obj, (value, index, list) -> if iterator.call context, value, index, list result = value _.breakLoop() result _.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 _.reject = (obj, iterator, context) -> results = [] _.each obj, (value, index, list) -> results.push value if not iterator.call context, value, index, list results _.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 _.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 _.include = (obj, target) -> return _.indexOf(obj, target) isnt -1 if nativeIndexOf and obj.indexOf is nativeIndexOf return true for own key, val of obj when val is target false _.invoke = (obj, method) -> args = _.rest arguments, 2 (if method then val[method] else val).apply(val, args) for val in obj _.pluck = (obj, key) -> _.map(obj, (val) -> val[key])

Return all the elements that pass a truth test. Use JavaScript 1.6'sfilter, if it exists.

Return all the elements for which a truth test fails.

Determine whether all of the elements match a truth test. Delegate to JavaScript 1.6's every, if it is present.

Determine if at least one element in the object matches a truth test. Use JavaScript 1.6's some, if it exists.

Determine if a given value is included in the array or object, based on ===.

Invoke a method with arguments on every item in a collection. Convenience version of a common use case of map: fetching a property. Return the maximum item or (item-based computation).

_.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

Return the minimum element (or element-based computation).

value computed >= result.computed and (result = {value: value, computed: computed}) result.value _.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 _.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') _.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 _.toArray = (iterable) -> return [] if (!iterable) return iterable.toArray() if

Sort the object's values by a criterion produced by an iterator.

Use a comparator function to figure out at what index an object should be inserted so as to maintain order. Uses binary search.

Convert anything iterable into a real, live array.

Return the number of elements in an object.

(iterable.toArray) return iterable if (_.isArray(iterable)) return slice.call(iterable) if (_.isArguments(iterable)) _.values(iterable) _.size = (obj) -> _.toArray(obj).length

Array Functions
Get the first element of an array. Passing n will return the slice.call(array, 0, n) else array[0] first N values in the array. Aliased as head. The guard check allows it to work with map.
_.rest = (array, index, guard) -> _.first = (array, n, guard) -> if n and not guard then

Returns everything but the first entry of the array. Aliased as tail. Especially useful on the arguments object. Passing _.isUndefined(index) or guard then 1 else index) an index will return the rest of the values in the array from that index onward. The guard check allows it to work with map. Get the last element of an array. Trim out all falsy values from an array. Return a completely flattened version of an array.
_.last = (array) -> array[array.length - 1]

slice.call(array, if

_.compact = (array) -> item for item in array when item _.flatten = (array) -> _.reduce array, (memo, value) -> return memo.concat(_.flatten(value)) if _.isArray value memo.push value memo , [] _.without = (array) -> values = _.rest arguments val for val in _.toArray(array) when not _.include values, val _.uniq = (array, isSorted) -> memo = [] for el, i in _.toArray array memo.push el if i is 0 || (if isSorted is true then _.last(memo) isnt el else not _.include(memo, el)) memo _.intersect = (array) -> -> rest = _.rest arguments _.all rest, (other) _.indexOf(other, item) >= 0

Return a version of the array that does not contain the specified value(s). Produce a duplicate-free version of the array. If the array has already been sorted, you have the option of using a faster algorithm.

Produce an array that contains every item shared between _.select _.uniq(array), (item) -> all the passed-in arrays. Zip together multiple lists into a single array -- elements that share an index go together.

_.zip = -> length = _.max _.pluck arguments, 'length' results = new Array length for i in [0...length]

results[i] = _.pluck arguments, String i results _.indexOf = (array, item) -> return array.indexOf item If the browser doesn't supply us with indexOf (I'm looking i = at you, MSIE), we need this function. Return the position if nativeIndexOf and array.indexOf is nativeIndexOf 0; l = array.length while l - i if array[i] is item of the first occurrence of an item in an array, or -1 if the item is not included in the array. then return i else i++ -1

Provide JavaScript 1.6's lastIndexOf, delegating to the native function, if possible.

Generate an integer Array containing an arithmetic progression. A port of the native Python range function.

_.lastIndexOf = (array, item) -> return array.lastIndexOf(item) if nativeLastIndexOf and array.lastIndexOf is nativeLastIndexOf i = array.length while i if array[i] is item then return i else i--1 _.range = (start, stop, step) -> a = arguments solo = a.length <= 1 i = start = if solo then 0 else a[0] stop = if solo then a[0] else a[1] step = a[2] or 1 len = Math.ceil((stop start) / step) return [] if len <= 0 range = new Array len idx = 0 loop return range if (if step > 0 then i - stop else stop - i) >= 0 range[idx] = i idx++ i+= step

Function Functions
Create a function bound to a given object (assigning this, func.apply obj or root, args.concat arguments and arguments, optionally). Binding with arguments is also known ascurry. Bind all of an object's methods to that object. Useful for ensuring that all callbacks defined on an object belong to it. then _.rest(arguments) else _.functions(obj) Delays a function for the given number of milliseconds, and then calls it with the arguments supplied. Memoize an expensive function by storing its results.
_.bindAll = (obj) -> _.bind = (func, obj) -> args = _.rest arguments, 2 ->

funcs = if arguments.length > 1 _.each funcs, (f) -> obj[f] = _.bind obj[f], obj obj _.delay = (func, wait) -> args = _.rest arguments, 2 setTimeout((-> func.apply(func, args)), wait) _.memoize = (func, hasher) -> memo = {} hasher or= _.identity -> key = hasher.apply this, arguments return memo[key] if key of memo memo[key] = func.apply this, arguments _.defer = (func) -> _.delay.apply _, [func, 1].concat

Defers a function, scheduling it to run after the current call _.rest arguments stack has cleared.

Returns the first function passed as an argument to the second, allowing you to adjust arguments, run code before [func].concat arguments and after, and conditionally execute the original function.
_.compose = ->

_.wrap = (func, wrapper) ->

-> wrapper.apply wrapper,

Returns a function that is the composition of a list of for i in [funcs.length - 1..0] by -1 functions, each consuming the return value of the function arguments that follows. args = [funcs[i].apply(this, args)] args[0]

funcs = arguments

->

args =

Object Functions
Retrieve the names of an object's properties. Retrieve the values of an object's properties. Return a sorted list of the function names available in Underscore.
_.keys = nativeKeys or (obj) -> return _.range 0, obj.length if _.isArray(obj) key for key, val of obj _.values = (obj) -> _.map obj, _.identity

_.functions = (obj) -> _.filter(_.keys(obj), (key) -> _.isFunction(obj[key])).sort()

Extend a given object with all of the properties in a source obj[key] = val for key, val of source object. Create a (shallow-cloned) duplicate of an object. Invokes interceptor with the obj, and then returns obj. The primary purpose of this method is to "tap into" a method chain, in order to perform operations on intermediate results within the chain. Perform a deep comparison to check if two objects are equal. Check object identity. Different types? Basic equality test (watch out for coercions). One is falsy and the other truthy. One of them implements an isEqual()? Check dates' integer values. Both are NaN? Compare regular expressions.
_.clone = (obj) -> _.extend {}, obj

_.extend = (obj) ->

for source in _.rest(arguments) obj

return obj.slice 0 if _.isArray obj interceptor obj obj

_.tap = (obj, interceptor) ->

_.isEqual = (a, b) ->

return true if a is b atype = typeof(a); btype = typeof(b) atype isnt btype return true if `a == b` return false if (!a and b) or (a and !b) return a.isEqual(b) if a.isEqual return a.getTime() is b.getTime() if _.isDate(a) and _.isDate(b) return false if _.isNaN(a) and _.isNaN(b) if _.isRegExp(a) and _.isRegExp(b) is b.source and a.global a.ignoreCase is b.ignoreCase and is b.multiline return false if atype isnt 'object' return false if a.length and (a.length isnt b.length) return a.source is b.global and a.multiline return false if

If a is not an object by this point, we can't handle it. Check for different array lengths before comparing contents. Nothing else worked, deep compare the contents. Different object sizes? Recursive comparison of contents. Is a given array or object empty?

aKeys = _.keys(a); bKeys = _.keys(b) return false if aKeys.length isnt bKeys.length return false for key, val of a when !(key of b) or ! _.isEqual(val, b[key]) true _.isEmpty = (obj) -> return obj.length is 0 if _.isArray(obj) or _.isString(obj) return false for own key of obj true _.isElement = (obj) -> obj and obj.nodeType is 1

Is a given value a DOM element? Is a given value an array? Is a given variable an arguments object? Is the given value a function?

_.isArray = nativeIsArray or (obj) -> !!(obj and obj.concat and obj.unshift and not obj.callee) _.isArguments = (obj) -> obj and obj.callee _.isFunction = (obj) -> !!(obj and obj.constructor and obj.call and obj.apply) _.isString = (obj) -> !!(obj is '' or (obj and

Is the given value a string? Is a given value a number? Is a given value a boolean? Is a given value a Date? Is the given value a regular expression?

obj.charCodeAt and obj.substr)) _.isNumber = (obj) -> (obj is +obj) or toString.call(obj) is '[object Number]' _.isBoolean = (obj) -> obj is true or obj is false

_.isDate = (obj) -> !!(obj and obj.getTimezoneOffset and obj.setUTCFullYear) _.isRegExp = (obj) -> !!(obj and obj.exec and (obj.ignoreCase or obj.ignoreCase is false)) _.isNaN = (obj) -> _.isNumber(obj) and

Is the given value NaN -- this one is interesting. NaN != window.isNaN(obj) NaN, andisNaN(undefined) == true, so we make sure it's a number first. Is a given value equal to null? Is a given variable undefined?
_.isNull

= (obj) -> obj is null

_.isUndefined = (obj) -> typeof obj is 'undefined'

Utility Functions
Run Underscore.js in noConflict mode, returning the _ variable to its previous owner. Returns a reference to the Underscore object. Keep the identity function around for default iterators. Run a function n times. Break out of the middle of an iteration.
_.noConflict = -> root._ = previousUnderscore this

_.identity = (value) -> value _.times = (n, iterator, context) -> context, i for i in [0...n] _.breakLoop = -> throw breaker _.mixin = (obj) -> for name in _.functions(obj) iterator.call

Add your own custom functions to the Underscore object, ensuring that they're correctly added to the OOP wrapper addToWrapper name, _[name] = obj[name] as well. Generate a unique integer id (unique within the entire client session). Useful for temporary DOM ids. By default, Underscore uses ERB-style template delimiters, change the following template settings to use alternative delimiters. JavaScript templating a-la ERB, pilfered from John Resig's Secrets of the JavaScript Ninja, page 83. Singlequote fix from Rick Strahl. With alterations for arbitrary delimiters, and to preserve whitespace.

idCounter = 0 _.uniqueId = (prefix) -> idCounter++ _.templateSettings = { start: '%>' interpolate: /<%=(.+?)%>/g }

(prefix or '') +

'<%'

end:

Aliases

_.template = (str, data) -> c = _.templateSettings endMatch = new RegExp("'(?=[^"+c.end.substr(0, 1)+"]*"+escapeRegExp(c.end)+")","g") fn = new Function 'obj', 'var p=[],print=function() {p.push.apply(p,arguments);};' + 'with(obj||{}) {p.push(\'' + str.replace(/\r/g, '\\r') .replace(/\n/g, '\\n') .replace(/\t/g, '\\t') .replace(endMatch,"") .split("'").join("\\'") .split("").join("'") .replace(c.interpolate, "', $1,'") .split(c.start).join("');") .split(c.end).join("p.push('") + "');}return p.join('');" if data then fn(data) else fn _.forEach = _.each _.foldl = _.inject = _.reduce _.foldr = _.reduceRight _.select = _.filter _.all = _.every _.any = _.some _.contains = _.include

_.head = _.first _.tail _.functions

= _.rest _.methods

Setup the OOP Wrapper

If Underscore is called as a function, it returns a wrapped object that can be used OO-style. This wrapper holds altered versions of all the underscore functions. Wrapped objects may be chained. Helper function to continue chaining intermediate results. A method to easily add functions to the OOP wrapper.
wrapper = (obj) -> this._wrapped = obj this

result = (obj, chain) -> else obj

if chain then _(obj).chain()

Add all ofthe Underscore functions to the wrapper object. Add all mutator Array functions to the wrapper.

addToWrapper = (name, func) -> wrapper.prototype[name] = -> args = _.toArray arguments unshift.call args, this._wrapped result func.apply(_, args), this._chain _.mixin _ _.each ['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], (name) -> method = Array.prototype[name] wrapper.prototype[name] = -> method.apply(this._wrapped, arguments) result(this._wrapped, this._chain) _.each ['concat', 'join', 'slice'], (name) -> method = Array.prototype[name] wrapper.prototype[name] = -> result(method.apply(this._wrapped, arguments), this._chain) wrapper::chain = -> this._chain = true this

Add all accessor Array functions to the wrapper.

Start chaining a wrapped Underscore object. Extracts the result from a wrapped and chained object.

wrapper::value = -> this._wrapped