define(["./kernel", "../has", "../sniff"], function(dojo, has){
// module:
// dojo/_base/lang
has.add("bug-for-in-skips-shadowed", function(){
// if true, the for-in iterator skips object properties that exist in Object's prototype (IE 6 - ?)
for(var i in {toString: 1}){
return 0;
}
return 1;
});
// Helper methods
var _extraNames =
has("bug-for-in-skips-shadowed") ?
"hasOwnProperty.valueOf.isPrototypeOf.propertyIsEnumerable.toLocaleString.toString.constructor".split(".") : [],
_extraLen = _extraNames.length,
getProp = function(/*Array*/parts, /*Boolean*/create, /*Object*/context){
var p, i = 0, dojoGlobal = dojo.global;
if(!context){
if(!parts.length){
return dojoGlobal;
}else{
p = parts[i++];
try{
context = dojo.scopeMap[p] && dojo.scopeMap[p][1];
}catch(e){}
context = context || (p in dojoGlobal ? dojoGlobal[p] : (create ? dojoGlobal[p] = {} : undefined));
}
}
while(context && (p = parts[i++])){
context = (p in context ? context[p] : (create ? context[p] = {} : undefined));
}
return context; // mixed
},
opts = Object.prototype.toString,
efficient = function(obj, offset, startWith){
return (startWith||[]).concat(Array.prototype.slice.call(obj, offset||0));
},
_pattern = /\{([^\}]+)\}/g;
// Module export
var lang = {
// summary:
// This module defines Javascript language extensions.
// _extraNames: String[]
// Lists property names that must be explicitly processed during for-in iteration
// in environments that have has("bug-for-in-skips-shadowed") true.
_extraNames:_extraNames,
_mixin: function(dest, source, copyFunc){
// summary:
// Copies/adds all properties of source to dest; returns dest.
// dest: Object
// The object to which to copy/add all properties contained in source.
// source: Object
// The object from which to draw all properties to copy into dest.
// copyFunc: Function?
// The process used to copy/add a property in source; defaults to the Javascript assignment operator.
// returns:
// dest, as modified
// description:
// All properties, including functions (sometimes termed "methods"), excluding any non-standard extensions
// found in Object.prototype, are copied/added to dest. Copying/adding each particular property is
// delegated to copyFunc (if any); copyFunc defaults to the Javascript assignment operator if not provided.
// Notice that by default, _mixin executes a so-called "shallow copy" and aggregate types are copied/added by reference.
var name, s, i, empty = {};
for(name in source){
// the (!(name in empty) || empty[name] !== s) condition avoids copying properties in "source"
// inherited from Object.prototype. For example, if dest has a custom toString() method,
// don't overwrite it with the toString() method that source inherited from Object.prototype
s = source[name];
if(!(name in dest) || (dest[name] !== s && (!(name in empty) || empty[name] !== s))){
dest[name] = copyFunc ? copyFunc(s) : s;
}
}
if(has("bug-for-in-skips-shadowed")){
if(source){
for(i = 0; i < _extraLen; ++i){
name = _extraNames[i];
s = source[name];
if(!(name in dest) || (dest[name] !== s && (!(name in empty) || empty[name] !== s))){
dest[name] = copyFunc ? copyFunc(s) : s;
}
}
}
}
return dest; // Object
},
mixin: function(dest, sources){
// summary:
// Copies/adds all properties of one or more sources to dest; returns dest.
// dest: Object
// The object to which to copy/add all properties contained in source. If dest is falsy, then
// a new object is manufactured before copying/adding properties begins.
// sources: Object...
// One of more objects from which to draw all properties to copy into dest. sources are processed
// left-to-right and if more than one of these objects contain the same property name, the right-most
// value "wins".
// returns: Object
// dest, as modified
// description:
// All properties, including functions (sometimes termed "methods"), excluding any non-standard extensions
// found in Object.prototype, are copied/added from sources to dest. sources are processed left to right.
// The Javascript assignment operator is used to copy/add each property; therefore, by default, mixin
// executes a so-called "shallow copy" and aggregate types are copied/added by reference.
// example:
// make a shallow copy of an object
// | var copy = lang.mixin({}, source);
// example:
// many class constructors often take an object which specifies
// values to be configured on the object. In this case, it is
// often simplest to call `lang.mixin` on the `this` object:
// | declare("acme.Base", null, {
// | constructor: function(properties){
// | // property configuration:
// | lang.mixin(this, properties);
// |
// | console.log(this.quip);
// | // ...
// | },
// | quip: "I wasn't born yesterday, you know - I've seen movies.",
// | // ...
// | });
// |
// | // create an instance of the class and configure it
// | var b = new acme.Base({quip: "That's what it does!" });
// example:
// copy in properties from multiple objects
// | var flattened = lang.mixin(
// | {
// | name: "Frylock",
// | braces: true
// | },
// | {
// | name: "Carl Brutanananadilewski"
// | }
// | );
// |
// | // will print "Carl Brutanananadilewski"
// | console.log(flattened.name);
// | // will print "true"
// | console.log(flattened.braces);
if(!dest){ dest = {}; }
for(var i = 1, l = arguments.length; i < l; i++){
lang._mixin(dest, arguments[i]);
}
return dest; // Object
},
setObject: function(name, value, context){
// summary:
// Set a property from a dot-separated string, such as "A.B.C"
// description:
// Useful for longer api chains where you have to test each object in
// the chain, or when you have an object reference in string format.
// Objects are created as needed along `path`. Returns the passed
// value if setting is successful or `undefined` if not.
// name: String
// Path to a property, in the form "A.B.C".
// value: anything
// value or object to place at location given by name
// context: Object?
// Optional. Object to use as root of path. Defaults to
// `dojo.global`.
// example:
// set the value of `foo.bar.baz`, regardless of whether
// intermediate objects already exist:
// | lang.setObject("foo.bar.baz", value);
// example:
// without `lang.setObject`, we often see code like this:
// | // ensure that intermediate objects are available
// | if(!obj["parent"]){ obj.parent = {}; }
// | if(!obj.parent["child"]){ obj.parent.child = {}; }
// | // now we can safely set the property
// | obj.parent.child.prop = "some value";
// whereas with `lang.setObject`, we can shorten that to:
// | lang.setObject("parent.child.prop", "some value", obj);
var parts = name.split("."), p = parts.pop(), obj = getProp(parts, true, context);
return obj && p ? (obj[p] = value) : undefined; // Object
},
getObject: function(name, create, context){
// summary:
// Get a property from a dot-separated string, such as "A.B.C"
// description:
// Useful for longer api chains where you have to test each object in
// the chain, or when you have an object reference in string format.
// name: String
// Path to an property, in the form "A.B.C".
// create: Boolean?
// Optional. Defaults to `false`. If `true`, Objects will be
// created at any point along the 'path' that is undefined.
// context: Object?
// Optional. Object to use as root of path. Defaults to
// 'dojo.global'. Null may be passed.
return getProp(name.split("."), create, context); // Object
},
exists: function(name, obj){
// summary:
// determine if an object supports a given method
// description:
// useful for longer api chains where you have to test each object in
// the chain. Useful for object and method detection.
// name: String
// Path to an object, in the form "A.B.C".
// obj: Object?
// Object to use as root of path. Defaults to
// 'dojo.global'. Null may be passed.
// example:
// | // define an object
// | var foo = {
// | bar: { }
// | };
// |
// | // search the global scope
// | lang.exists("foo.bar"); // true
// | lang.exists("foo.bar.baz"); // false
// |
// | // search from a particular scope
// | lang.exists("bar", foo); // true
// | lang.exists("bar.baz", foo); // false
return lang.getObject(name, false, obj) !== undefined; // Boolean
},
// Crockford (ish) functions
isString: function(it){
// summary:
// Return true if it is a String
// it: anything
// Item to test.
return (typeof it == "string" || it instanceof String); // Boolean
},
isArray: function(it){
// summary:
// Return true if it is an Array.
// Does not work on Arrays created in other windows.
// it: anything
// Item to test.
return it && (it instanceof Array || typeof it == "array"); // Boolean
},
isFunction: function(it){
// summary:
// Return true if it is a Function
// it: anything
// Item to test.
return opts.call(it) === "[object Function]";
},
isObject: function(it){
// summary:
// Returns true if it is a JavaScript object (or an Array, a Function
// or null)
// it: anything
// Item to test.
return it !== undefined &&
(it === null || typeof it == "object" || lang.isArray(it) || lang.isFunction(it)); // Boolean
},
isArrayLike: function(it){
// summary:
// similar to isArray() but more permissive
// it: anything
// Item to test.
// returns:
// If it walks like a duck and quacks like a duck, return `true`
// description:
// Doesn't strongly test for "arrayness". Instead, settles for "isn't
// a string or number and has a length property". Arguments objects
// and DOM collections will return true when passed to
// isArrayLike(), but will return false when passed to
// isArray().
return it && it !== undefined && // Boolean
// keep out built-in constructors (Number, String, ...) which have length
// properties
!lang.isString(it) && !lang.isFunction(it) &&
!(it.tagName && it.tagName.toLowerCase() == 'form') &&
(lang.isArray(it) || isFinite(it.length));
},
isAlien: function(it){
// summary:
// Returns true if it is a built-in function or some other kind of
// oddball that *should* report as a function but doesn't
return it && !lang.isFunction(it) && /\{\s*\[native code\]\s*\}/.test(String(it)); // Boolean
},
extend: function(ctor, props){
// summary:
// Adds all properties and methods of props to constructor's
// prototype, making them available to all instances created with
// constructor.
// ctor: Object
// Target constructor to extend.
// props: Object
// One or more objects to mix into ctor.prototype
for(var i=1, l=arguments.length; i<l; i++){
lang._mixin(ctor.prototype, arguments[i]);
}
return ctor; // Object
},
_hitchArgs: function(scope, method){
var pre = lang._toArray(arguments, 2);
var named = lang.isString(method);
return function(){
// arrayify arguments
var args = lang._toArray(arguments);
// locate our method
var f = named ? (scope||dojo.global)[method] : method;
// invoke with collected args
return f && f.apply(scope || this, pre.concat(args)); // mixed
}; // Function
},
hitch: function(scope, method){
// summary:
// Returns a function that will only ever execute in the a given scope.
// This allows for easy use of object member functions
// in callbacks and other places in which the "this" keyword may
// otherwise not reference the expected scope.
// Any number of default positional arguments may be passed as parameters
// beyond "method".
// Each of these values will be used to "placehold" (similar to curry)
// for the hitched function.
// scope: Object
// The scope to use when method executes. If method is a string,
// scope is also the object containing method.
// method: Function|String...
// A function to be hitched to scope, or the name of the method in
// scope to be hitched.
// example:
// | lang.hitch(foo, "bar")();
// runs foo.bar() in the scope of foo
// example:
// | lang.hitch(foo, myFunction);
// returns a function that runs myFunction in the scope of foo
// example:
// Expansion on the default positional arguments passed along from
// hitch. Passed args are mixed first, additional args after.
// | var foo = { bar: function(a, b, c){ console.log(a, b, c); } };
// | var fn = lang.hitch(foo, "bar", 1, 2);
// | fn(3); // logs "1, 2, 3"
// example:
// | var foo = { bar: 2 };
// | lang.hitch(foo, function(){ this.bar = 10; })();
// execute an anonymous function in scope of foo
if(arguments.length > 2){
return lang._hitchArgs.apply(dojo, arguments); // Function
}
if(!method){
method = scope;
scope = null;
}
if(lang.isString(method)){
scope = scope || dojo.global;
if(!scope[method]){ throw(['lang.hitch: scope["', method, '"] is null (scope="', scope, '")'].join('')); }
return function(){ return scope[method].apply(scope, arguments || []); }; // Function
}
return !scope ? method : function(){ return method.apply(scope, arguments || []); }; // Function
},
delegate: (function(){
// boodman/crockford delegation w/ cornford optimization
function TMP(){}
return function(obj, props){
TMP.prototype = obj;
var tmp = new TMP();
TMP.prototype = null;
if(props){
lang._mixin(tmp, props);
}
return tmp; // Object
};
})(),
/*=====
delegate: function(obj, props){
// summary:
// Returns a new object which "looks" to obj for properties which it
// does not have a value for. Optionally takes a bag of properties to
// seed the returned object with initially.
// description:
// This is a small implementation of the Boodman/Crockford delegation
// pattern in JavaScript. An intermediate object constructor mediates
// the prototype chain for the returned object, using it to delegate
// down to obj for property lookup when object-local lookup fails.
// This can be thought of similarly to ES4's "wrap", save that it does
// not act on types but rather on pure objects.
// obj: Object
// The object to delegate to for properties not found directly on the
// return object or in props.
// props: Object...
// an object containing properties to assign to the returned object
// returns:
// an Object of anonymous type
// example:
// | var foo = { bar: "baz" };
// | var thinger = lang.delegate(foo, { thud: "xyzzy"});
// | thinger.bar == "baz"; // delegated to foo
// | foo.thud == undefined; // by definition
// | thinger.thud == "xyzzy"; // mixed in from props
// | foo.bar = "thonk";
// | thinger.bar == "thonk"; // still delegated to foo's bar
},
=====*/
_toArray: has("ie") ?
(function(){
function slow(obj, offset, startWith){
var arr = startWith||[];
for(var x = offset || 0; x < obj.length; x++){
arr.push(obj[x]);
}
return arr;
}
return function(obj){
return ((obj.item) ? slow : efficient).apply(this, arguments);
};
})() : efficient,
/*=====
_toArray: function(obj, offset, startWith){
// summary:
// Converts an array-like object (i.e. arguments, DOMCollection) to an
// array. Returns a new Array with the elements of obj.
// obj: Object
// the object to "arrayify". We expect the object to have, at a
// minimum, a length property which corresponds to integer-indexed
// properties.
// offset: Number?
// the location in obj to start iterating from. Defaults to 0.
// Optional.
// startWith: Array?
// An array to pack with the properties of obj. If provided,
// properties in obj are appended at the end of startWith and
// startWith is the returned array.
},
=====*/
partial: function(/*Function|String*/ method /*, ...*/){
// summary:
// similar to hitch() except that the scope object is left to be
// whatever the execution context eventually becomes.
// description:
// Calling lang.partial is the functional equivalent of calling:
// | lang.hitch(null, funcName, ...);
// method:
// The function to "wrap"
var arr = [ null ];
return lang.hitch.apply(dojo, arr.concat(lang._toArray(arguments))); // Function
},
clone: function(/*anything*/ src){
// summary:
// Clones objects (including DOM nodes) and all children.
// Warning: do not clone cyclic structures.
// src:
// The object to clone
if(!src || typeof src != "object" || lang.isFunction(src)){
// null, undefined, any non-object, or function
return src; // anything
}
if(src.nodeType && "cloneNode" in src){
// DOM Node
return src.cloneNode(true); // Node
}
if(src instanceof Date){
// Date
return new Date(src.getTime()); // Date
}
if(src instanceof RegExp){
// RegExp
return new RegExp(src); // RegExp
}
var r, i, l;
if(lang.isArray(src)){
// array
r = [];
for(i = 0, l = src.length; i < l; ++i){
if(i in src){
r.push(lang.clone(src[i]));
}
}
// we don't clone functions for performance reasons
// }else if(d.isFunction(src)){
// // function
// r = function(){ return src.apply(this, arguments); };
}else{
// generic objects
r = src.constructor ? new src.constructor() : {};
}
return lang._mixin(r, src, lang.clone);
},
trim: String.prototype.trim ?
function(str){ return str.trim(); } :
function(str){ return str.replace(/^\s\s*/, '').replace(/\s\s*$/, ''); },
/*=====
trim: function(str){
// summary:
// Trims whitespace from both sides of the string
// str: String
// String to be trimmed
// returns: String
// Returns the trimmed string
// description:
// This version of trim() was selected for inclusion into the base due
// to its compact size and relatively good performance
// (see [Steven Levithan's blog](http://blog.stevenlevithan.com/archives/faster-trim-javascript)
// Uses String.prototype.trim instead, if available.
// The fastest but longest version of this function is located at
// lang.string.trim()
},
=====*/
replace: function(tmpl, map, pattern){
// summary:
// Performs parameterized substitutions on a string. Throws an
// exception if any parameter is unmatched.
// tmpl: String
// String to be used as a template.
// map: Object|Function
// If an object, it is used as a dictionary to look up substitutions.
// If a function, it is called for every substitution with following parameters:
// a whole match, a name, an offset, and the whole template
// string (see https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/replace
// for more details).
// pattern: RegEx?
// Optional regular expression objects that overrides the default pattern.
// Must be global and match one item. The default is: /\{([^\}]+)\}/g,
// which matches patterns like that: "{xxx}", where "xxx" is any sequence
// of characters, which doesn't include "}".
// returns: String
// Returns the substituted string.
// example:
// | // uses a dictionary for substitutions:
// | lang.replace("Hello, {name.first} {name.last} AKA {nick}!",
// | {
// | nick: "Bob",
// | name: {
// | first: "Robert",
// | middle: "X",
// | last: "Cringely"
// | }
// | });
// | // returns: Hello, Robert Cringely AKA Bob!
// example:
// | // uses an array for substitutions:
// | lang.replace("Hello, {0} {2}!",
// | ["Robert", "X", "Cringely"]);
// | // returns: Hello, Robert Cringely!
// example:
// | // uses a function for substitutions:
// | function sum(a){
// | var t = 0;
// | arrayforEach(a, function(x){ t += x; });
// | return t;
// | }
// | lang.replace(
// | "{count} payments averaging {avg} USD per payment.",
// | lang.hitch(
// | { payments: [11, 16, 12] },
// | function(_, key){
// | switch(key){
// | case "count": return this.payments.length;
// | case "min": return Math.min.apply(Math, this.payments);
// | case "max": return Math.max.apply(Math, this.payments);
// | case "sum": return sum(this.payments);
// | case "avg": return sum(this.payments) / this.payments.length;
// | }
// | }
// | )
// | );
// | // prints: 3 payments averaging 13 USD per payment.
// example:
// | // uses an alternative PHP-like pattern for substitutions:
// | lang.replace("Hello, ${0} ${2}!",
// | ["Robert", "X", "Cringely"], /\$\{([^\}]+)\}/g);
// | // returns: Hello, Robert Cringely!
return tmpl.replace(pattern || _pattern, lang.isFunction(map) ?
map : function(_, k){ return lang.getObject(k, false, map); });
}
};
has("extend-dojo") && lang.mixin(dojo, lang);
return lang;
});