b39897a381c2203466da5568bfd2862a54a81311Adam Moore * The YUI module contains the components required for building the YUI
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * seed file. This includes the script loading mechanism, a simple queue,
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * and the core utilities for the library.
4778ff543a041ac356d6e661cc9b66c3fafa2092Adam Moore * @module yui
2c5ce90c334a2d0f18474e85c93b424b6ec9daaaAdam Moore * @submodule yui-base
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * Adds utilities to the YUI instance for working with objects.
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @class Object
3e4a3c30997cfa913fabd7b346e3a71388441bedRyan Grove UNDEFINED, // <-- Note the comma. We're still declaring vars.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * Returns a new object that uses _obj_ as its prototype. This method wraps the
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * native ES5 `Object.create()` method if available, but doesn't currently
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * pass through `Object.create()`'s second argument (properties) in order to
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * ensure compatibility with older browsers.
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method ()
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @param {Object} obj Prototype object.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @return {Object} New object using _obj_ as its prototype.
3e4a3c30997cfa913fabd7b346e3a71388441bedRyan GroveO = Y.Object = Lang._isNative(Object.create) ? function (obj) {
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // We currently wrap the native Object.create instead of simply aliasing it
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // to ensure consistency with our fallback shim, which currently doesn't
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // support Object.create()'s second argument (properties). Once we have a
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // safe fallback for the properties arg, we can stop wrapping
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // Object.create().
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove} : (function () {
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // Reusable constructor function for the Object.create() shim.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove function F() {}
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove // The actual shim.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove return function (obj) {
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove return new F();
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * Property names that IE doesn't enumerate in for..in loops, even when they
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * should be enumerable. When `_hasEnumBug` is `true`, it's necessary to
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * manually enumerate these properties.
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * @property _forceEnum
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * @type String[]
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * @protected
67e8ed2937abc262dbe7537695d632143294269fRyan Grove 'hasOwnProperty',
67e8ed2937abc262dbe7537695d632143294269fRyan Grove 'isPrototypeOf',
67e8ed2937abc262dbe7537695d632143294269fRyan Grove 'propertyIsEnumerable',
67e8ed2937abc262dbe7537695d632143294269fRyan Grove 'toLocaleString',
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * `true` if this browser has the JScript enumeration bug that prevents
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * enumeration of the properties named in the `_forceEnum` array, `false`
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * otherwise.
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * - <https://developer.mozilla.org/en/ECMAScript_DontEnum_attribute#JScript_DontEnum_Bug>
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * - <http://whattheheadsaid.com/2010/10/a-safer-object-keys-compatibility-implementation>
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * @property _hasEnumBug
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove * @type Boolean
67e8ed2937abc262dbe7537695d632143294269fRyan Grove * @protected
67e8ed2937abc262dbe7537695d632143294269fRyan GrovehasEnumBug = O._hasEnumBug = !{valueOf: 0}.propertyIsEnumerable('valueOf'),
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove * `true` if this browser incorrectly considers the `prototype` property of
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove * functions to be enumerable. Currently known to affect Opera 11.50.
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove * @property _hasProtoEnumBug
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove * @type Boolean
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove * @protected
6ed148777f04d35c42c9370c8108484f14be78a2Ryan GrovehasProtoEnumBug = O._hasProtoEnumBug = (function () {}).propertyIsEnumerable('prototype'),
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * Returns `true` if _key_ exists on _obj_, `false` if _key_ doesn't exist or
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * exists only on _obj_'s prototype. This is essentially a safer version of
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * `obj.hasOwnProperty()`.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @method owns
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @param {Object} obj Object to test.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @param {String} key Property name to look for.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @return {Boolean} `true` if _key_ exists on _obj_, `false` otherwise.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove}; // <-- End of var declarations.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * Alias for `owns()`.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @method hasKey
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @param {Object} obj Object to test.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @param {String} key Property name to look for.
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove * @return {Boolean} `true` if _key_ exists on _obj_, `false` otherwise.
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * Returns an array containing the object's enumerable keys. Does not include
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * prototype keys or non-enumerable keys.
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * Note that keys are returned in enumeration order (that is, in the same order
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * that they would be enumerated by a `for-in` loop), which may not be the same
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * as the order in which they were defined.
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * This method is an alias for the native ES5 `Object.keys()` method if
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * available.
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * Y.Object.keys({a: 'foo', b: 'bar', c: 'baz'});
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * // => ['a', 'b', 'c']
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method keys
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * @param {Object} obj An object.
c97ced1ebe127b04e46886f1b43dc0b00672e34bRyan Grove * @return {String[]} Array of keys.
3e4a3c30997cfa913fabd7b346e3a71388441bedRyan GroveO.keys = Lang._isNative(Object.keys) ? Object.keys : function (obj) {
67e8ed2937abc262dbe7537695d632143294269fRyan Grove throw new TypeError('Object.keys called on a non-object');
6ed148777f04d35c42c9370c8108484f14be78a2Ryan Grove if (hasProtoEnumBug && typeof obj === 'function') {
67e8ed2937abc262dbe7537695d632143294269fRyan Grove for (i = 0, len = forceEnum.length; i < len; ++i) {
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * Returns an array containing the values of the object's enumerable keys.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * Note that values are returned in enumeration order (that is, in the same
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * order that they would be enumerated by a `for-in` loop), which may not be the
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * same as the order in which they were defined.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * Y.Object.values({a: 'foo', b: 'bar', c: 'baz'});
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * // => ['foo', 'bar', 'baz']
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method values
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @param {Object} obj An object.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @return {Array} Array of values.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove for (; i < len; ++i) {
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * Returns the number of enumerable keys owned by an object.
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method size
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @param {Object} obj An object.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @return {Number} The object's size.
20ed23d33369bdd43b18a992b6fda8cbff77cc2cRyan Grove } catch (ex) {
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * Returns `true` if the object owns an enumerable property with the specified
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method hasValue
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @param {Object} obj An object.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @param {any} value The value to search for.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @return {Boolean} `true` if _obj_ contains _value_, `false` otherwise.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove return Y.Array.indexOf(O.values(obj), value) > -1;
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * Executes a function on each enumerable property in _obj_. The function
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * receives the value, the key, and the object itself as parameters (in that
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * By default, only properties owned by _obj_ are enumerated. To include
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * prototype properties, set the _proto_ parameter to `true`.
87d6b0a14cce52c4faa4b78fc9878eb553dab0d5Adam Moore * @method each
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Object} obj Object to enumerate.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Function} fn Function to execute on each enumerable property.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {mixed} fn.value Value of the current property.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {String} fn.key Key of the current property.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Object} fn.obj Object being enumerated.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Object} [thisObj] `this` object to use when calling _fn_.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Boolean} [proto=false] Include prototype properties.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {YUI} the YUI instance.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @chainable
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * Executes a function on each enumerable property in _obj_, but halts if the
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * function returns a truthy value. The function receives the value, the key,
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * and the object itself as paramters (in that order).
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * By default, only properties owned by _obj_ are enumerated. To include
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * prototype properties, set the _proto_ parameter to `true`.
23209f57fce338501bc1dc828a991d103732b92fAdam Moore * @method some
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Object} obj Object to enumerate.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Function} fn Function to execute on each enumerable property.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {mixed} fn.value Value of the current property.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {String} fn.key Key of the current property.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Object} fn.obj Object being enumerated.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Object} [thisObj] `this` object to use when calling _fn_.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @param {Boolean} [proto=false] Include prototype properties.
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * @return {Boolean} `true` if any execution of _fn_ returns a truthy value,
582df4bc8549d0008b29f98cfe582ad0dc217c9eRyan Grove * `false` otherwise.
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore return true;
e0a1d83ad86620d8fd4e2bfa3c4ec5c0944a002aAdam Moore return false;
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * Retrieves the sub value at the provided path,
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * from the value object provided.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @method getValue
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @param o The object from which to extract the property value.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param path {Array} A path array, specifying the object traversal path
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * from which to obtain the sub value.
0dca577a07715960da42d47787eecc25b285182fAdam Moore * @return {Any} The value stored in the path, undefined if not found,
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * undefined if the source is not an object. Returns the source object
0dca577a07715960da42d47787eecc25b285182fAdam Moore * if an empty path is provided.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore p = Y.Array(path),
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore o = o[p[i]];
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * Sets the sub-attribute value at the provided path on the
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * value object. Returns the modified value object, or
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * undefined if the path is invalid.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @method setValue
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param o The object on which to set the sub value.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param path {Array} A path array, specifying the object traversal path
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * at which to set the sub value.
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * @param val {Any} The new value for the sub-attribute.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore * @return {Object} The modified object, with the new sub value set, or
3395e5fc071521d4e6b258ef4c7c0ef38601b94eAdam Moore * undefined, if the path was invalid.
b39897a381c2203466da5568bfd2862a54a81311Adam Moore p = Y.Array(path),
58ce26ddee9c5cc583f031eeb1ed36aea797bdcaRyan Grove for (i = 0; ref !== UNDEFINED && i < leafIdx; i++) {
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * Returns `true` if the object has no enumerable properties of its own.
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * @method isEmpty
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @param {Object} obj An object.
3ecd40c854dca8089986ee76cac93c15f4f5f5f3Ryan Grove * @return {Boolean} `true` if the object is empty.
8c3fae1cf2a8dfa82c53922a6f99ab7b991b959cAdam Moore * @since 3.2.0