]>
git.wh0rd.org - tt-rss.git/blob - lib/dojo/_base/lang.js.uncompressed.js
1 define("dojo/_base/lang", ["./kernel", "../has", "../sniff"], function(dojo
, has
){
5 has
.add("bug-for-in-skips-shadowed", function(){
6 // if true, the for-in iterator skips object properties that exist in Object's prototype (IE 6 - ?)
7 for(var i
in {toString
: 1}){
15 has("bug-for-in-skips-shadowed") ?
16 "hasOwnProperty.valueOf.isPrototypeOf.propertyIsEnumerable.toLocaleString.toString.constructor".split(".") : [],
18 _extraLen
= _extraNames
.length
,
20 getProp = function(/*Array*/parts
, /*Boolean*/create
, /*Object*/context
){
21 var p
, i
= 0, dojoGlobal
= dojo
.global
;
28 context
= dojo
.scopeMap
[p
] && dojo
.scopeMap
[p
][1];
30 context
= context
|| (p
in dojoGlobal
? dojoGlobal
[p
] : (create
? dojoGlobal
[p
] = {} : undefined));
33 while(context
&& (p
= parts
[i
++])){
34 context
= (p
in context
? context
[p
] : (create
? context
[p
] = {} : undefined));
36 return context
; // mixed
39 opts
= Object
.prototype.toString
,
41 efficient = function(obj
, offset
, startWith
){
42 return (startWith
||[]).concat(Array
.prototype.slice
.call(obj
, offset
||0));
45 _pattern
= /\{([^\}]+)\}/g;
50 // This module defines Javascript language extensions.
52 // _extraNames: String[]
53 // Lists property names that must be explicitly processed during for-in iteration
54 // in environments that have has("bug-for-in-skips-shadowed") true.
55 _extraNames
:_extraNames
,
57 _mixin: function(dest
, source
, copyFunc
){
59 // Copies/adds all properties of source to dest; returns dest.
61 // The object to which to copy/add all properties contained in source.
63 // The object from which to draw all properties to copy into dest.
64 // copyFunc: Function?
65 // The process used to copy/add a property in source; defaults to the Javascript assignment operator.
69 // All properties, including functions (sometimes termed "methods"), excluding any non-standard extensions
70 // found in Object.prototype, are copied/added to dest. Copying/adding each particular property is
71 // delegated to copyFunc (if any); copyFunc defaults to the Javascript assignment operator if not provided.
72 // Notice that by default, _mixin executes a so-called "shallow copy" and aggregate types are copied/added by reference.
73 var name
, s
, i
, empty
= {};
75 // the (!(name in empty) || empty[name] !== s) condition avoids copying properties in "source"
76 // inherited from Object.prototype. For example, if dest has a custom toString() method,
77 // don't overwrite it with the toString() method that source inherited from Object.prototype
79 if(!(name
in dest
) || (dest
[name
] !== s
&& (!(name
in empty
) || empty
[name
] !== s
))){
80 dest
[name
] = copyFunc
? copyFunc(s
) : s
;
84 if(has("bug-for-in-skips-shadowed")){
86 for(i
= 0; i
< _extraLen
; ++i
){
87 name
= _extraNames
[i
];
89 if(!(name
in dest
) || (dest
[name
] !== s
&& (!(name
in empty
) || empty
[name
] !== s
))){
90 dest
[name
] = copyFunc
? copyFunc(s
) : s
;
96 return dest
; // Object
99 mixin: function(dest
, sources
){
101 // Copies/adds all properties of one or more sources to dest; returns dest.
103 // The object to which to copy/add all properties contained in source. If dest is falsy, then
104 // a new object is manufactured before copying/adding properties begins.
105 // sources: Object...
106 // One of more objects from which to draw all properties to copy into dest. sources are processed
107 // left-to-right and if more than one of these objects contain the same property name, the right-most
112 // All properties, including functions (sometimes termed "methods"), excluding any non-standard extensions
113 // found in Object.prototype, are copied/added from sources to dest. sources are processed left to right.
114 // The Javascript assignment operator is used to copy/add each property; therefore, by default, mixin
115 // executes a so-called "shallow copy" and aggregate types are copied/added by reference.
117 // make a shallow copy of an object
118 // | var copy = lang.mixin({}, source);
120 // many class constructors often take an object which specifies
121 // values to be configured on the object. In this case, it is
122 // often simplest to call `lang.mixin` on the `this` object:
123 // | declare("acme.Base", null, {
124 // | constructor: function(properties){
125 // | // property configuration:
126 // | lang.mixin(this, properties);
128 // | console.log(this.quip);
131 // | quip: "I wasn't born yesterday, you know - I've seen movies.",
135 // | // create an instance of the class and configure it
136 // | var b = new acme.Base({quip: "That's what it does!" });
138 // copy in properties from multiple objects
139 // | var flattened = lang.mixin(
141 // | name: "Frylock",
145 // | name: "Carl Brutanananadilewski"
149 // | // will print "Carl Brutanananadilewski"
150 // | console.log(flattened.name);
151 // | // will print "true"
152 // | console.log(flattened.braces);
154 if(!dest
){ dest
= {}; }
155 for(var i
= 1, l
= arguments
.length
; i
< l
; i
++){
156 lang
._mixin(dest
, arguments
[i
]);
158 return dest
; // Object
161 setObject: function(name
, value
, context
){
163 // Set a property from a dot-separated string, such as "A.B.C"
165 // Useful for longer api chains where you have to test each object in
166 // the chain, or when you have an object reference in string format.
167 // Objects are created as needed along `path`. Returns the passed
168 // value if setting is successful or `undefined` if not.
170 // Path to a property, in the form "A.B.C".
172 // value or object to place at location given by name
174 // Optional. Object to use as root of path. Defaults to
177 // set the value of `foo.bar.baz`, regardless of whether
178 // intermediate objects already exist:
179 // | lang.setObject("foo.bar.baz", value);
181 // without `lang.setObject`, we often see code like this:
182 // | // ensure that intermediate objects are available
183 // | if(!obj["parent"]){ obj.parent = {}; }
184 // | if(!obj.parent["child"]){ obj.parent.child = {}; }
185 // | // now we can safely set the property
186 // | obj.parent.child.prop = "some value";
187 // whereas with `lang.setObject`, we can shorten that to:
188 // | lang.setObject("parent.child.prop", "some value", obj);
190 var parts
= name
.split("."), p
= parts
.pop(), obj
= getProp(parts
, true, context
);
191 return obj
&& p
? (obj
[p
] = value
) : undefined; // Object
194 getObject: function(name
, create
, context
){
196 // Get a property from a dot-separated string, such as "A.B.C"
198 // Useful for longer api chains where you have to test each object in
199 // the chain, or when you have an object reference in string format.
201 // Path to an property, in the form "A.B.C".
203 // Optional. Defaults to `false`. If `true`, Objects will be
204 // created at any point along the 'path' that is undefined.
206 // Optional. Object to use as root of path. Defaults to
207 // 'dojo.global'. Null may be passed.
208 return getProp(name
.split("."), create
, context
); // Object
211 exists: function(name
, obj
){
213 // determine if an object supports a given method
215 // useful for longer api chains where you have to test each object in
216 // the chain. Useful for object and method detection.
218 // Path to an object, in the form "A.B.C".
220 // Object to use as root of path. Defaults to
221 // 'dojo.global'. Null may be passed.
223 // | // define an object
228 // | // search the global scope
229 // | lang.exists("foo.bar"); // true
230 // | lang.exists("foo.bar.baz"); // false
232 // | // search from a particular scope
233 // | lang.exists("bar", foo); // true
234 // | lang.exists("bar.baz", foo); // false
235 return lang
.getObject(name
, false, obj
) !== undefined; // Boolean
238 // Crockford (ish) functions
240 isString: function(it
){
242 // Return true if it is a String
245 return (typeof it
== "string" || it
instanceof String
); // Boolean
248 isArray: function(it
){
250 // Return true if it is an Array.
251 // Does not work on Arrays created in other windows.
254 return it
&& (it
instanceof Array
|| typeof it
== "array"); // Boolean
257 isFunction: function(it
){
259 // Return true if it is a Function
262 return opts
.call(it
) === "[object Function]";
265 isObject: function(it
){
267 // Returns true if it is a JavaScript object (or an Array, a Function
271 return it
!== undefined &&
272 (it
=== null || typeof it
== "object" || lang
.isArray(it
) || lang
.isFunction(it
)); // Boolean
275 isArrayLike: function(it
){
277 // similar to isArray() but more permissive
281 // If it walks like a duck and quacks like a duck, return `true`
283 // Doesn't strongly test for "arrayness". Instead, settles for "isn't
284 // a string or number and has a length property". Arguments objects
285 // and DOM collections will return true when passed to
286 // isArrayLike(), but will return false when passed to
288 return it
&& it
!== undefined && // Boolean
289 // keep out built-in constructors (Number, String, ...) which have length
291 !lang
.isString(it
) && !lang
.isFunction(it
) &&
292 !(it
.tagName
&& it
.tagName
.toLowerCase() == 'form') &&
293 (lang
.isArray(it
) || isFinite(it
.length
));
296 isAlien: function(it
){
298 // Returns true if it is a built-in function or some other kind of
299 // oddball that *should* report as a function but doesn't
300 return it
&& !lang
.isFunction(it
) && /\{\s*\[native code\]\s*\}/.test(String(it
)); // Boolean
303 extend: function(ctor
, props
){
305 // Adds all properties and methods of props to constructor's
306 // prototype, making them available to all instances created with
309 // Target constructor to extend.
311 // One or more objects to mix into ctor.prototype
312 for(var i
=1, l
=arguments
.length
; i
<l
; i
++){
313 lang
._mixin(ctor
.prototype, arguments
[i
]);
315 return ctor
; // Object
318 _hitchArgs: function(scope
, method
){
319 var pre
= lang
._toArray(arguments
, 2);
320 var named
= lang
.isString(method
);
322 // arrayify arguments
323 var args
= lang
._toArray(arguments
);
325 var f
= named
? (scope
||dojo
.global
)[method
] : method
;
326 // invoke with collected args
327 return f
&& f
.apply(scope
|| this, pre
.concat(args
)); // mixed
331 hitch: function(scope
, method
){
333 // Returns a function that will only ever execute in the a given scope.
334 // This allows for easy use of object member functions
335 // in callbacks and other places in which the "this" keyword may
336 // otherwise not reference the expected scope.
337 // Any number of default positional arguments may be passed as parameters
339 // Each of these values will be used to "placehold" (similar to curry)
340 // for the hitched function.
342 // The scope to use when method executes. If method is a string,
343 // scope is also the object containing method.
344 // method: Function|String...
345 // A function to be hitched to scope, or the name of the method in
346 // scope to be hitched.
348 // | lang.hitch(foo, "bar")();
349 // runs foo.bar() in the scope of foo
351 // | lang.hitch(foo, myFunction);
352 // returns a function that runs myFunction in the scope of foo
354 // Expansion on the default positional arguments passed along from
355 // hitch. Passed args are mixed first, additional args after.
356 // | var foo = { bar: function(a, b, c){ console.log(a, b, c); } };
357 // | var fn = lang.hitch(foo, "bar", 1, 2);
358 // | fn(3); // logs "1, 2, 3"
360 // | var foo = { bar: 2 };
361 // | lang.hitch(foo, function(){ this.bar = 10; })();
362 // execute an anonymous function in scope of foo
363 if(arguments
.length
> 2){
364 return lang
._hitchArgs
.apply(dojo
, arguments
); // Function
370 if(lang
.isString(method
)){
371 scope
= scope
|| dojo
.global
;
372 if(!scope
[method
]){ throw(['lang.hitch: scope["', method
, '"] is null (scope="', scope
, '")'].join('')); }
373 return function(){ return scope
[method
].apply(scope
, arguments
|| []); }; // Function
375 return !scope
? method : function(){ return method
.apply(scope
, arguments
|| []); }; // Function
378 delegate
: (function(){
379 // boodman/crockford delegation w/ cornford optimization
381 return function(obj
, props
){
384 TMP
.prototype = null;
386 lang
._mixin(tmp
, props
);
388 return tmp
; // Object
392 delegate: function(obj, props){
394 // Returns a new object which "looks" to obj for properties which it
395 // does not have a value for. Optionally takes a bag of properties to
396 // seed the returned object with initially.
398 // This is a small implementation of the Boodman/Crockford delegation
399 // pattern in JavaScript. An intermediate object constructor mediates
400 // the prototype chain for the returned object, using it to delegate
401 // down to obj for property lookup when object-local lookup fails.
402 // This can be thought of similarly to ES4's "wrap", save that it does
403 // not act on types but rather on pure objects.
405 // The object to delegate to for properties not found directly on the
406 // return object or in props.
408 // an object containing properties to assign to the returned object
410 // an Object of anonymous type
412 // | var foo = { bar: "baz" };
413 // | var thinger = lang.delegate(foo, { thud: "xyzzy"});
414 // | thinger.bar == "baz"; // delegated to foo
415 // | foo.thud == undefined; // by definition
416 // | thinger.thud == "xyzzy"; // mixed in from props
417 // | foo.bar = "thonk";
418 // | thinger.bar == "thonk"; // still delegated to foo's bar
422 _toArray
: has("ie") ?
424 function slow(obj
, offset
, startWith
){
425 var arr
= startWith
||[];
426 for(var x
= offset
|| 0; x
< obj
.length
; x
++){
431 return function(obj
){
432 return ((obj
.item
) ? slow
: efficient
).apply(this, arguments
);
436 _toArray: function(obj, offset, startWith){
438 // Converts an array-like object (i.e. arguments, DOMCollection) to an
439 // array. Returns a new Array with the elements of obj.
441 // the object to "arrayify". We expect the object to have, at a
442 // minimum, a length property which corresponds to integer-indexed
445 // the location in obj to start iterating from. Defaults to 0.
448 // An array to pack with the properties of obj. If provided,
449 // properties in obj are appended at the end of startWith and
450 // startWith is the returned array.
454 partial: function(/*Function|String*/ method
/*, ...*/){
456 // similar to hitch() except that the scope object is left to be
457 // whatever the execution context eventually becomes.
459 // Calling lang.partial is the functional equivalent of calling:
460 // | lang.hitch(null, funcName, ...);
462 // The function to "wrap"
464 return lang
.hitch
.apply(dojo
, arr
.concat(lang
._toArray(arguments
))); // Function
467 clone: function(/*anything*/ src
){
469 // Clones objects (including DOM nodes) and all children.
470 // Warning: do not clone cyclic structures.
472 // The object to clone
473 if(!src
|| typeof src
!= "object" || lang
.isFunction(src
)){
474 // null, undefined, any non-object, or function
475 return src
; // anything
477 if(src
.nodeType
&& "cloneNode" in src
){
479 return src
.cloneNode(true); // Node
481 if(src
instanceof Date
){
483 return new Date(src
.getTime()); // Date
485 if(src
instanceof RegExp
){
487 return new RegExp(src
); // RegExp
490 if(lang
.isArray(src
)){
493 for(i
= 0, l
= src
.length
; i
< l
; ++i
){
495 r
.push(lang
.clone(src
[i
]));
498 // we don't clone functions for performance reasons
499 // }else if(d.isFunction(src)){
501 // r = function(){ return src.apply(this, arguments); };
504 r
= src
.constructor ? new src
.constructor() : {};
506 return lang
._mixin(r
, src
, lang
.clone
);
510 trim
: String
.prototype.trim
?
511 function(str
){ return str
.trim(); } :
512 function(str
){ return str
.replace(/^\s\s*/, '').replace(/\s\s*$/, ''); },
516 // Trims whitespace from both sides of the string
518 // String to be trimmed
520 // Returns the trimmed string
522 // This version of trim() was selected for inclusion into the base due
523 // to its compact size and relatively good performance
524 // (see [Steven Levithan's blog](http://blog.stevenlevithan.com/archives/faster-trim-javascript)
525 // Uses String.prototype.trim instead, if available.
526 // The fastest but longest version of this function is located at
527 // lang.string.trim()
531 replace: function(tmpl
, map
, pattern
){
533 // Performs parameterized substitutions on a string. Throws an
534 // exception if any parameter is unmatched.
536 // String to be used as a template.
537 // map: Object|Function
538 // If an object, it is used as a dictionary to look up substitutions.
539 // If a function, it is called for every substitution with following parameters:
540 // a whole match, a name, an offset, and the whole template
541 // string (see https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String/replace
542 // for more details).
544 // Optional regular expression objects that overrides the default pattern.
545 // Must be global and match one item. The default is: /\{([^\}]+)\}/g,
546 // which matches patterns like that: "{xxx}", where "xxx" is any sequence
547 // of characters, which doesn't include "}".
549 // Returns the substituted string.
551 // | // uses a dictionary for substitutions:
552 // | lang.replace("Hello, {name.first} {name.last} AKA {nick}!",
556 // | first: "Robert",
558 // | last: "Cringely"
561 // | // returns: Hello, Robert Cringely AKA Bob!
563 // | // uses an array for substitutions:
564 // | lang.replace("Hello, {0} {2}!",
565 // | ["Robert", "X", "Cringely"]);
566 // | // returns: Hello, Robert Cringely!
568 // | // uses a function for substitutions:
569 // | function sum(a){
571 // | arrayforEach(a, function(x){ t += x; });
575 // | "{count} payments averaging {avg} USD per payment.",
577 // | { payments: [11, 16, 12] },
578 // | function(_, key){
580 // | case "count": return this.payments.length;
581 // | case "min": return Math.min.apply(Math, this.payments);
582 // | case "max": return Math.max.apply(Math, this.payments);
583 // | case "sum": return sum(this.payments);
584 // | case "avg": return sum(this.payments) / this.payments.length;
589 // | // prints: 3 payments averaging 13 USD per payment.
591 // | // uses an alternative PHP-like pattern for substitutions:
592 // | lang.replace("Hello, ${0} ${2}!",
593 // | ["Robert", "X", "Cringely"], /\$\{([^\}]+)\}/g);
594 // | // returns: Hello, Robert Cringely!
596 return tmpl
.replace(pattern
|| _pattern
, lang
.isFunction(map
) ?
597 map : function(_
, k
){ return lang
.getObject(k
, false, map
); });
601 1 && lang
.mixin(dojo
, lang
);