lib/yuilib/3.7.2/build/attribute-core/attribute-core-debug.js

   1 /*
   2 YUI 3.7.2 (build 5639)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('attribute-core', function (Y, NAME) {
   8
   9     /**
  10      * The State class maintains state for a collection of named items, with
  11      * a varying number of properties defined.
  12      *
  13      * It avoids the need to create a separate class for the item, and separate instances
  14      * of these classes for each item, by storing the state in a 2 level hash table,
  15      * improving performance when the number of items is likely to be large.
  16      *
  17      * @constructor
  18      * @class State
  19      */
  20     Y.State = function() {
  21         /**
  22          * Hash of attributes
  23          * @property data
  24          */
  25         this.data = {};
  26     };
  27
  28     Y.State.prototype = {
  29
  30         /**
  31          * Adds a property to an item.
  32          *
  33          * @method add
  34          * @param name {String} The name of the item.
  35          * @param key {String} The name of the property.
  36          * @param val {Any} The value of the property.
  37          */
  38         add: function(name, key, val) {
  39             var item = this.data[name];
  40
  41             if (!item) {
  42                 item = this.data[name] = {};
  43             }
  44
  45             item[key] = val;
  46         },
  47
  48         /**
  49          * Adds multiple properties to an item.
  50          *
  51          * @method addAll
  52          * @param name {String} The name of the item.
  53          * @param obj {Object} A hash of property/value pairs.
  54          */
  55         addAll: function(name, obj) {
  56             var item = this.data[name],
  57                 key;
  58
  59             if (!item) {
  60                 item = this.data[name] = {};
  61             }
  62
  63             for (key in obj) {
  64                 if (obj.hasOwnProperty(key)) {
  65                     item[key] = obj[key];
  66                 }
  67             }
  68         },
  69
  70         /**
  71          * Removes a property from an item.
  72          *
  73          * @method remove
  74          * @param name {String} The name of the item.
  75          * @param key {String} The property to remove.
  76          */
  77         remove: function(name, key) {
  78             var item = this.data[name];
  79
  80             if (item) {
  81                 delete item[key];
  82             }
  83         },
  84
  85         /**
  86          * Removes multiple properties from an item, or removes the item completely.
  87          *
  88          * @method removeAll
  89          * @param name {String} The name of the item.
  90          * @param obj {Object|Array} Collection of properties to delete. If not provided, the entire item is removed.
  91          */
  92         removeAll: function(name, obj) {
  93             var data;
  94
  95             if (!obj) {
  96                 data = this.data;
  97
  98                 if (name in data) {
  99                     delete data[name];
 100                 }
 101             } else {
 102                 Y.each(obj, function(value, key) {
 103                     this.remove(name, typeof key === 'string' ? key : value);
 104                 }, this);
 105             }
 106         },
 107
 108         /**
 109          * For a given item, returns the value of the property requested, or undefined if not found.
 110          *
 111          * @method get
 112          * @param name {String} The name of the item
 113          * @param key {String} Optional. The property value to retrieve.
 114          * @return {Any} The value of the supplied property.
 115          */
 116         get: function(name, key) {
 117             var item = this.data[name];
 118
 119             if (item) {
 120                 return item[key];
 121             }
 122         },
 123
 124         /**
 125          * For the given item, returns an object with all of the
 126          * item's property/value pairs. By default the object returned
 127          * is a shallow copy of the stored data, but passing in true
 128          * as the second parameter will return a reference to the stored
 129          * data.
 130          *
 131          * @method getAll
 132          * @param name {String} The name of the item
 133          * @param reference {boolean} true, if you want a reference to the stored
 134          * object
 135          * @return {Object} An object with property/value pairs for the item.
 136          */
 137         getAll : function(name, reference) {
 138             var item = this.data[name],
 139                 key, obj;
 140
 141             if (reference) {
 142                 obj = item;
 143             } else if (item) {
 144                 obj = {};
 145
 146                 for (key in item) {
 147                     if (item.hasOwnProperty(key)) {
 148                         obj[key] = item[key];
 149                     }
 150                 }
 151             }
 152
 153             return obj;
 154         }
 155     };
 156     /**
 157      * The attribute module provides an augmentable Attribute implementation, which
 158      * adds configurable attributes and attribute change events to the class being
 159      * augmented. It also provides a State class, which is used internally by Attribute,
 160      * but can also be used independently to provide a name/property/value data structure to
 161      * store state.
 162      *
 163      * @module attribute
 164      */
 165
 166     /**
 167      * The attribute-core submodule provides the lightest level of attribute handling support
 168      * without Attribute change events, or lesser used methods such as reset(), modifyAttrs(),
 169      * and removeAttr().
 170      *
 171      * @module attribute
 172      * @submodule attribute-core
 173      */
 174     var O = Y.Object,
 175         Lang = Y.Lang,
 176
 177         DOT = ".",
 178
 179         // Externally configurable props
 180         GETTER = "getter",
 181         SETTER = "setter",
 182         READ_ONLY = "readOnly",
 183         WRITE_ONCE = "writeOnce",
 184         INIT_ONLY = "initOnly",
 185         VALIDATOR = "validator",
 186         VALUE = "value",
 187         VALUE_FN = "valueFn",
 188         LAZY_ADD = "lazyAdd",
 189
 190         // Used for internal state management
 191         ADDED = "added",
 192         BYPASS_PROXY = "_bypassProxy",
 193         INITIALIZING = "initializing",
 194         INIT_VALUE = "initValue",
 195         LAZY = "lazy",
 196         IS_LAZY_ADD = "isLazyAdd",
 197
 198         INVALID_VALUE;
 199
 200     /**
 201      * <p>
 202      * AttributeCore provides the lightest level of configurable attribute support. It is designed to be
 203      * augmented on to a host class, and provides the host with the ability to configure
 204      * attributes to store and retrieve state, <strong>but without support for attribute change events</strong>.
 205      * </p>
 206      * <p>For example, attributes added to the host can be configured:</p>
 207      * <ul>
 208      *     <li>As read only.</li>
 209      *     <li>As write once.</li>
 210      *     <li>With a setter function, which can be used to manipulate
 211      *     values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>
 212      *     <li>With a getter function, which can be used to manipulate stored values,
 213      *     before they are returned by Attribute's <a href="#method_get">get</a> method.</li>
 214      *     <li>With a validator function, to validate values before they are stored.</li>
 215      * </ul>
 216      *
 217      * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration
 218      * options available for attributes.</p>
 219      *
 220      * <p>Object/Classes based on AttributeCore can augment <a href="AttributeEvents.html">AttributeEvents</a>
 221      * (with true for overwrite) and <a href="AttributeExtras.html">AttributeExtras</a> to add attribute event and
 222      * additional, less commonly used attribute methods, such as `modifyAttr`, `removeAttr` and `reset`.</p>
 223      *
 224      * @class AttributeCore
 225      * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
 226      * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
 227      * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
 228      */
 229     function AttributeCore(attrs, values, lazy) {
 230         this._initAttrHost(attrs, values, lazy);
 231     }
 232
 233     /**
 234      * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>
 235      *
 236      * <p>You can return this value from your setter if you wish to combine validator and setter
 237      * functionality into a single setter function, which either returns the massaged value to be stored or
 238      * AttributeCore.INVALID_VALUE to prevent invalid values from being stored.</p>
 239      *
 240      * @property INVALID_VALUE
 241      * @type Object
 242      * @static
 243      * @final
 244      */
 245     AttributeCore.INVALID_VALUE = {};
 246     INVALID_VALUE = AttributeCore.INVALID_VALUE;
 247
 248     /**
 249      * The list of properties which can be configured for
 250      * each attribute (e.g. setter, getter, writeOnce etc.).
 251      *
 252      * This property is used internally as a whitelist for faster
 253      * Y.mix operations.
 254      *
 255      * @property _ATTR_CFG
 256      * @type Array
 257      * @static
 258      * @protected
 259      */
 260     AttributeCore._ATTR_CFG = [SETTER, GETTER, VALIDATOR, VALUE, VALUE_FN, WRITE_ONCE, READ_ONLY, LAZY_ADD, BYPASS_PROXY];
 261
 262     AttributeCore.prototype = {
 263
 264         /**
 265          * Constructor logic for attributes. Initializes the host state, and sets up the inital attributes passed to the
 266          * constructor.
 267          *
 268          * @method _initAttrHost
 269          * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
 270          * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
 271          * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
 272          * @private
 273          */
 274         _initAttrHost : function(attrs, values, lazy) {
 275             this._state = new Y.State();
 276             this._initAttrs(attrs, values, lazy);
 277         },
 278
 279         /**
 280          * <p>
 281          * Adds an attribute with the provided configuration to the host object.
 282          * </p>
 283          * <p>
 284          * The config argument object supports the following properties:
 285          * </p>
 286          *
 287          * <dl>
 288          *    <dt>value &#60;Any&#62;</dt>
 289          *    <dd>The initial value to set on the attribute</dd>
 290          *
 291          *    <dt>valueFn &#60;Function | String&#62;</dt>
 292          *    <dd>
 293          *    <p>A function, which will return the initial value to set on the attribute. This is useful
 294          *    for cases where the attribute configuration is defined statically, but needs to
 295          *    reference the host instance ("this") to obtain an initial value. If both the value and valueFn properties are defined,
 296          *    the value returned by the valueFn has precedence over the value property, unless it returns undefined, in which
 297          *    case the value property is used.</p>
 298          *
 299          *    <p>valueFn can also be set to a string, representing the name of the instance method to be used to retrieve the value.</p>
 300          *    </dd>
 301          *
 302          *    <dt>readOnly &#60;boolean&#62;</dt>
 303          *    <dd>Whether or not the attribute is read only. Attributes having readOnly set to true
 304          *        cannot be modified by invoking the set method.</dd>
 305          *
 306          *    <dt>writeOnce &#60;boolean&#62; or &#60;string&#62;</dt>
 307          *    <dd>
 308          *        Whether or not the attribute is "write once". Attributes having writeOnce set to true,
 309          *        can only have their values set once, be it through the default configuration,
 310          *        constructor configuration arguments, or by invoking set.
 311          *        <p>The writeOnce attribute can also be set to the string "initOnly", in which case the attribute can only be set during initialization
 312          *        (when used with Base, this means it can only be set during construction)</p>
 313          *    </dd>
 314          *
 315          *    <dt>setter &#60;Function | String&#62;</dt>
 316          *    <dd>
 317          *    <p>The setter function used to massage or normalize the value passed to the set method for the attribute.
 318          *    The value returned by the setter will be the final stored value. Returning
 319          *    <a href="#property_Attribute.INVALID_VALUE">Attribute.INVALID_VALUE</a>, from the setter will prevent
 320          *    the value from being stored.
 321          *    </p>
 322          *
 323          *    <p>setter can also be set to a string, representing the name of the instance method to be used as the setter function.</p>
 324          *    </dd>
 325          *
 326          *    <dt>getter &#60;Function | String&#62;</dt>
 327          *    <dd>
 328          *    <p>
 329          *    The getter function used to massage or normalize the value returned by the get method for the attribute.
 330          *    The value returned by the getter function is the value which will be returned to the user when they
 331          *    invoke get.
 332          *    </p>
 333          *
 334          *    <p>getter can also be set to a string, representing the name of the instance method to be used as the getter function.</p>
 335          *    </dd>
 336          *
 337          *    <dt>validator &#60;Function | String&#62;</dt>
 338          *    <dd>
 339          *    <p>
 340          *    The validator function invoked prior to setting the stored value. Returning
 341          *    false from the validator function will prevent the value from being stored.
 342          *    </p>
 343          *
 344          *    <p>validator can also be set to a string, representing the name of the instance method to be used as the validator function.</p>
 345          *    </dd>
 346          *
 347          *    <dt>lazyAdd &#60;boolean&#62;</dt>
 348          *    <dd>Whether or not to delay initialization of the attribute until the first call to get/set it.
 349          *    This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through
 350          *    the <a href="#method_addAttrs">addAttrs</a> method.</dd>
 351          *
 352          * </dl>
 353          *
 354          * <p>The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with
 355          * the context ("this") set to the host object.</p>
 356          *
 357          * <p>Configuration properties outside of the list mentioned above are considered private properties used internally by attribute,
 358          * and are not intended for public use.</p>
 359          *
 360          * @method addAttr
 361          *
 362          * @param {String} name The name of the attribute.
 363          * @param {Object} config An object with attribute configuration property/value pairs, specifying the configuration for the attribute.
 364          *
 365          * <p>
 366          * <strong>NOTE:</strong> The configuration object is modified when adding an attribute, so if you need
 367          * to protect the original values, you will need to merge the object.
 368          * </p>
 369          *
 370          * @param {boolean} lazy (optional) Whether or not to add this attribute lazily (on the first call to get/set).
 371          *
 372          * @return {Object} A reference to the host object.
 373          *
 374          * @chainable
 375          */
 376         addAttr: function(name, config, lazy) {
 377
 378             Y.log('Adding attribute: ' + name, 'info', 'attribute');
 379
 380             var host = this, // help compression
 381                 state = host._state,
 382                 value,
 383                 hasValue;
 384
 385             config = config || {};
 386
 387             lazy = (LAZY_ADD in config) ? config[LAZY_ADD] : lazy;
 388
 389             if (lazy && !host.attrAdded(name)) {
 390                 state.addAll(name, {
 391                     lazy : config,
 392                     added : true
 393                 });
 394             } else {
 395
 396                 if (host.attrAdded(name) && !state.get(name, IS_LAZY_ADD)) { Y.log('Attribute: ' + name + ' already exists. Cannot add it again without removing it first', 'warn', 'attribute'); }
 397
 398                 if (!host.attrAdded(name) || state.get(name, IS_LAZY_ADD)) {
 399
 400                     hasValue = (VALUE in config);
 401
 402                     if (config.readOnly && !hasValue) { Y.log('readOnly attribute: ' + name + ', added without an initial value. Value will be set on initial call to set', 'warn', 'attribute');}
 403
 404                     if (hasValue) {
 405                         // We'll go through set, don't want to set value in config directly
 406                         value = config.value;
 407                         delete config.value;
 408                     }
 409
 410                     config.added = true;
 411                     config.initializing = true;
 412
 413                     state.addAll(name, config);
 414
 415                     if (hasValue) {
 416                         // Go through set, so that raw values get normalized/validated
 417                         host.set(name, value);
 418                     }
 419
 420                     state.remove(name, INITIALIZING);
 421                 }
 422             }
 423
 424             return host;
 425         },
 426
 427         /**
 428          * Checks if the given attribute has been added to the host
 429          *
 430          * @method attrAdded
 431          * @param {String} name The name of the attribute to check.
 432          * @return {boolean} true if an attribute with the given name has been added, false if it hasn't. This method will return true for lazily added attributes.
 433          */
 434         attrAdded: function(name) {
 435             return !!this._state.get(name, ADDED);
 436         },
 437
 438         /**
 439          * Returns the current value of the attribute. If the attribute
 440          * has been configured with a 'getter' function, this method will delegate
 441          * to the 'getter' to obtain the value of the attribute.
 442          *
 443          * @method get
 444          *
 445          * @param {String} name The name of the attribute. If the value of the attribute is an Object,
 446          * dot notation can be used to obtain the value of a property of the object (e.g. <code>get("x.y.z")</code>)
 447          *
 448          * @return {Any} The value of the attribute
 449          */
 450         get : function(name) {
 451             return this._getAttr(name);
 452         },
 453
 454         /**
 455          * Checks whether or not the attribute is one which has been
 456          * added lazily and still requires initialization.
 457          *
 458          * @method _isLazyAttr
 459          * @private
 460          * @param {String} name The name of the attribute
 461          * @return {boolean} true if it's a lazily added attribute, false otherwise.
 462          */
 463         _isLazyAttr: function(name) {
 464             return this._state.get(name, LAZY);
 465         },
 466
 467         /**
 468          * Finishes initializing an attribute which has been lazily added.
 469          *
 470          * @method _addLazyAttr
 471          * @private
 472          * @param {Object} name The name of the attribute
 473          */
 474         _addLazyAttr: function(name, cfg) {
 475             var state = this._state,
 476                 lazyCfg = state.get(name, LAZY);
 477
 478             state.add(name, IS_LAZY_ADD, true);
 479             state.remove(name, LAZY);
 480             this.addAttr(name, lazyCfg);
 481         },
 482
 483         /**
 484          * Sets the value of an attribute.
 485          *
 486          * @method set
 487          * @chainable
 488          *
 489          * @param {String} name The name of the attribute. If the
 490          * current value of the attribute is an Object, dot notation can be used
 491          * to set the value of a property within the object (e.g. <code>set("x.y.z", 5)</code>).
 492          *
 493          * @param {Any} value The value to set the attribute to.
 494          *
 495          * @return {Object} A reference to the host object.
 496          */
 497         set : function(name, val) {
 498             return this._setAttr(name, val);
 499         },
 500
 501         /**
 502          * Allows setting of readOnly/writeOnce attributes. See <a href="#method_set">set</a> for argument details.
 503          *
 504          * @method _set
 505          * @protected
 506          * @chainable
 507          *
 508          * @param {String} name The name of the attribute.
 509          * @param {Any} val The value to set the attribute to.
 510          * @return {Object} A reference to the host object.
 511          */
 512         _set : function(name, val) {
 513             return this._setAttr(name, val, null, true);
 514         },
 515
 516         /**
 517          * Provides the common implementation for the public set and protected _set methods.
 518          *
 519          * See <a href="#method_set">set</a> for argument details.
 520          *
 521          * @method _setAttr
 522          * @protected
 523          * @chainable
 524          *
 525          * @param {String} name The name of the attribute.
 526          * @param {Any} value The value to set the attribute to.
 527          * @param {Object} opts (Optional) Optional event data to be mixed into
 528          * the event facade passed to subscribers of the attribute's change event.
 529          * This is currently a hack. There's no real need for the AttributeCore implementation
 530          * to support this parameter, but breaking it out into AttributeEvents, results in
 531          * additional function hops for the critical path.
 532          * @param {boolean} force If true, allows the caller to set values for
 533          * readOnly or writeOnce attributes which have already been set.
 534          *
 535          * @return {Object} A reference to the host object.
 536          */
 537         _setAttr : function(name, val, opts, force)  {
 538
 539             // HACK - no real reason core needs to know about opts, but
 540             // it adds fn hops if we want to break it out.
 541             // Not sure it's worth it for this critical path
 542
 543             var allowSet = true,
 544                 state = this._state,
 545                 stateProxy = this._stateProxy,
 546                 cfg,
 547                 initialSet,
 548                 strPath,
 549                 path,
 550                 currVal,
 551                 writeOnce,
 552                 initializing;
 553
 554             if (name.indexOf(DOT) !== -1) {
 555                 strPath = name;
 556                 path = name.split(DOT);
 557                 name = path.shift();
 558             }
 559
 560             if (this._isLazyAttr(name)) {
 561                 this._addLazyAttr(name);
 562             }
 563
 564             cfg = state.getAll(name, true) || {};
 565
 566             initialSet = (!(VALUE in cfg));
 567
 568             if (stateProxy && name in stateProxy && !cfg._bypassProxy) {
 569                 // TODO: Value is always set for proxy. Can we do any better? Maybe take a snapshot as the initial value for the first call to set?
 570                 initialSet = false;
 571             }
 572
 573             writeOnce = cfg.writeOnce;
 574             initializing = cfg.initializing;
 575
 576             if (!initialSet && !force) {
 577
 578                 if (writeOnce) {
 579                     Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce', 'warn', 'attribute');
 580                     allowSet = false;
 581                 }
 582
 583                 if (cfg.readOnly) {
 584                     Y.log('Set attribute:' + name + ', aborted; Attribute is readOnly', 'warn', 'attribute');
 585                     allowSet = false;
 586                 }
 587             }
 588
 589             if (!initializing && !force && writeOnce === INIT_ONLY) {
 590                 Y.log('Set attribute:' + name + ', aborted; Attribute is writeOnce: "initOnly"', 'warn', 'attribute');
 591                 allowSet = false;
 592             }
 593
 594             if (allowSet) {
 595                 // Don't need currVal if initialSet (might fail in custom getter if it always expects a non-undefined/non-null value)
 596                 if (!initialSet) {
 597                     currVal =  this.get(name);
 598                 }
 599
 600                 if (path) {
 601                    val = O.setValue(Y.clone(currVal), path, val);
 602
 603                    if (val === undefined) {
 604                        Y.log('Set attribute path:' + strPath + ', aborted; Path is invalid', 'warn', 'attribute');
 605                        allowSet = false;
 606                    }
 607                 }
 608
 609                 if (allowSet) {
 610                     if (!this._fireAttrChange || initializing) {
 611                         this._setAttrVal(name, strPath, currVal, val);
 612                     } else {
 613                         // HACK - no real reason core needs to know about _fireAttrChange, but
 614                         // it adds fn hops if we want to break it out. Not sure it's worth it for this critical path
 615                         this._fireAttrChange(name, strPath, currVal, val, opts);
 616                     }
 617                 }
 618             }
 619
 620             return this;
 621         },
 622
 623         /**
 624          * Provides the common implementation for the public get method,
 625          * allowing Attribute hosts to over-ride either method.
 626          *
 627          * See <a href="#method_get">get</a> for argument details.
 628          *
 629          * @method _getAttr
 630          * @protected
 631          * @chainable
 632          *
 633          * @param {String} name The name of the attribute.
 634          * @return {Any} The value of the attribute.
 635          */
 636         _getAttr : function(name) {
 637             var host = this, // help compression
 638                 fullName = name,
 639                 state = host._state,
 640                 path,
 641                 getter,
 642                 val,
 643                 cfg;
 644
 645             if (name.indexOf(DOT) !== -1) {
 646                 path = name.split(DOT);
 647                 name = path.shift();
 648             }
 649
 650             // On Demand - Should be rare - handles out of order valueFn references
 651             if (host._tCfgs && host._tCfgs[name]) {
 652                 cfg = {};
 653                 cfg[name] = host._tCfgs[name];
 654                 delete host._tCfgs[name];
 655                 host._addAttrs(cfg, host._tVals);
 656             }
 657
 658             // Lazy Init
 659             if (host._isLazyAttr(name)) {
 660                 host._addLazyAttr(name);
 661             }
 662
 663             val = host._getStateVal(name);
 664
 665             getter = state.get(name, GETTER);
 666
 667             if (getter && !getter.call) {
 668                 getter = this[getter];
 669             }
 670
 671             val = (getter) ? getter.call(host, val, fullName) : val;
 672             val = (path) ? O.getValue(val, path) : val;
 673
 674             return val;
 675         },
 676
 677         /**
 678          * Gets the stored value for the attribute, from either the
 679          * internal state object, or the state proxy if it exits
 680          *
 681          * @method _getStateVal
 682          * @private
 683          * @param {String} name The name of the attribute
 684          * @return {Any} The stored value of the attribute
 685          */
 686         _getStateVal : function(name) {
 687             var stateProxy = this._stateProxy;
 688             return stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY) ? stateProxy[name] : this._state.get(name, VALUE);
 689         },
 690
 691         /**
 692          * Sets the stored value for the attribute, in either the
 693          * internal state object, or the state proxy if it exits
 694          *
 695          * @method _setStateVal
 696          * @private
 697          * @param {String} name The name of the attribute
 698          * @param {Any} value The value of the attribute
 699          */
 700         _setStateVal : function(name, value) {
 701             var stateProxy = this._stateProxy;
 702             if (stateProxy && (name in stateProxy) && !this._state.get(name, BYPASS_PROXY)) {
 703                 stateProxy[name] = value;
 704             } else {
 705                 this._state.add(name, VALUE, value);
 706             }
 707         },
 708
 709         /**
 710          * Updates the stored value of the attribute in the privately held State object,
 711          * if validation and setter passes.
 712          *
 713          * @method _setAttrVal
 714          * @private
 715          * @param {String} attrName The attribute name.
 716          * @param {String} subAttrName The sub-attribute name, if setting a sub-attribute property ("x.y.z").
 717          * @param {Any} prevVal The currently stored value of the attribute.
 718          * @param {Any} newVal The value which is going to be stored.
 719          *
 720          * @return {booolean} true if the new attribute value was stored, false if not.
 721          */
 722         _setAttrVal : function(attrName, subAttrName, prevVal, newVal) {
 723
 724             var host = this,
 725                 allowSet = true,
 726                 cfg = this._state.getAll(attrName, true) || {},
 727                 validator = cfg.validator,
 728                 setter = cfg.setter,
 729                 initializing = cfg.initializing,
 730                 prevRawVal = this._getStateVal(attrName),
 731                 name = subAttrName || attrName,
 732                 retVal,
 733                 valid;
 734
 735             if (validator) {
 736                 if (!validator.call) {
 737                     // Assume string - trying to keep critical path tight, so avoiding Lang check
 738                     validator = this[validator];
 739                 }
 740                 if (validator) {
 741                     valid = validator.call(host, newVal, name);
 742
 743                     if (!valid && initializing) {
 744                         newVal = cfg.defaultValue;
 745                         valid = true; // Assume it's valid, for perf.
 746                     }
 747                 }
 748             }
 749
 750             if (!validator || valid) {
 751                 if (setter) {
 752                     if (!setter.call) {
 753                         // Assume string - trying to keep critical path tight, so avoiding Lang check
 754                         setter = this[setter];
 755                     }
 756                     if (setter) {
 757                         retVal = setter.call(host, newVal, name);
 758
 759                         if (retVal === INVALID_VALUE) {
 760                             Y.log('Attribute: ' + attrName + ', setter returned Attribute.INVALID_VALUE for value:' + newVal, 'warn', 'attribute');
 761                             allowSet = false;
 762                         } else if (retVal !== undefined){
 763                             Y.log('Attribute: ' + attrName + ', raw value: ' + newVal + ' modified by setter to:' + retVal, 'info', 'attribute');
 764                             newVal = retVal;
 765                         }
 766                     }
 767                 }
 768
 769                 if (allowSet) {
 770                     if(!subAttrName && (newVal === prevRawVal) && !Lang.isObject(newVal)) {
 771                         Y.log('Attribute: ' + attrName + ', value unchanged:' + newVal, 'warn', 'attribute');
 772                         allowSet = false;
 773                     } else {
 774                         // Store value
 775                         if (!(INIT_VALUE in cfg)) {
 776                             cfg.initValue = newVal;
 777                         }
 778                         host._setStateVal(attrName, newVal);
 779                     }
 780                 }
 781
 782             } else {
 783                 Y.log('Attribute:' + attrName + ', Validation failed for value:' + newVal, 'warn', 'attribute');
 784                 allowSet = false;
 785             }
 786
 787             return allowSet;
 788         },
 789
 790         /**
 791          * Sets multiple attribute values.
 792          *
 793          * @method setAttrs
 794          * @param {Object} attrs  An object with attributes name/value pairs.
 795          * @return {Object} A reference to the host object.
 796          * @chainable
 797          */
 798         setAttrs : function(attrs) {
 799             return this._setAttrs(attrs);
 800         },
 801
 802         /**
 803          * Implementation behind the public setAttrs method, to set multiple attribute values.
 804          *
 805          * @method _setAttrs
 806          * @protected
 807          * @param {Object} attrs  An object with attributes name/value pairs.
 808          * @return {Object} A reference to the host object.
 809          * @chainable
 810          */
 811         _setAttrs : function(attrs) {
 812             var attr;
 813             for (attr in attrs) {
 814                 if ( attrs.hasOwnProperty(attr) ) {
 815                     this.set(attr, attrs[attr]);
 816                 }
 817             }
 818             return this;
 819         },
 820
 821         /**
 822          * Gets multiple attribute values.
 823          *
 824          * @method getAttrs
 825          * @param {Array | boolean} attrs Optional. An array of attribute names. If omitted, all attribute values are
 826          * returned. If set to true, all attributes modified from their initial values are returned.
 827          * @return {Object} An object with attribute name/value pairs.
 828          */
 829         getAttrs : function(attrs) {
 830             return this._getAttrs(attrs);
 831         },
 832
 833         /**
 834          * Implementation behind the public getAttrs method, to get multiple attribute values.
 835          *
 836          * @method _getAttrs
 837          * @protected
 838          * @param {Array | boolean} attrs Optional. An array of attribute names. If omitted, all attribute values are
 839          * returned. If set to true, all attributes modified from their initial values are returned.
 840          * @return {Object} An object with attribute name/value pairs.
 841          */
 842         _getAttrs : function(attrs) {
 843             var obj = {},
 844                 attr, i, len,
 845                 modifiedOnly = (attrs === true);
 846
 847             // TODO - figure out how to get all "added"
 848             if (!attrs || modifiedOnly) {
 849                 attrs = O.keys(this._state.data);
 850             }
 851
 852             for (i = 0, len = attrs.length; i < len; i++) {
 853                 attr = attrs[i];
 854
 855                 if (!modifiedOnly || this._getStateVal(attr) != this._state.get(attr, INIT_VALUE)) {
 856                     // Go through get, to honor cloning/normalization
 857                     obj[attr] = this.get(attr);
 858                 }
 859             }
 860
 861             return obj;
 862         },
 863
 864         /**
 865          * Configures a group of attributes, and sets initial values.
 866          *
 867          * <p>
 868          * <strong>NOTE:</strong> This method does not isolate the configuration object by merging/cloning.
 869          * The caller is responsible for merging/cloning the configuration object if required.
 870          * </p>
 871          *
 872          * @method addAttrs
 873          * @chainable
 874          *
 875          * @param {Object} cfgs An object with attribute name/configuration pairs.
 876          * @param {Object} values An object with attribute name/value pairs, defining the initial values to apply.
 877          * Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
 878          * @param {boolean} lazy Whether or not to delay the intialization of these attributes until the first call to get/set.
 879          * Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration.
 880          * See <a href="#method_addAttr">addAttr</a>.
 881          *
 882          * @return {Object} A reference to the host object.
 883          */
 884         addAttrs : function(cfgs, values, lazy) {
 885             var host = this; // help compression
 886             if (cfgs) {
 887                 host._tCfgs = cfgs;
 888                 host._tVals = host._normAttrVals(values);
 889                 host._addAttrs(cfgs, host._tVals, lazy);
 890                 host._tCfgs = host._tVals = null;
 891             }
 892
 893             return host;
 894         },
 895
 896         /**
 897          * Implementation behind the public addAttrs method.
 898          *
 899          * This method is invoked directly by get if it encounters a scenario
 900          * in which an attribute's valueFn attempts to obtain the
 901          * value an attribute in the same group of attributes, which has not yet
 902          * been added (on demand initialization).
 903          *
 904          * @method _addAttrs
 905          * @private
 906          * @param {Object} cfgs An object with attribute name/configuration pairs.
 907          * @param {Object} values An object with attribute name/value pairs, defining the initial values to apply.
 908          * Values defined in the cfgs argument will be over-written by values in this argument unless defined as read only.
 909          * @param {boolean} lazy Whether or not to delay the intialization of these attributes until the first call to get/set.
 910          * Individual attributes can over-ride this behavior by defining a lazyAdd configuration property in their configuration.
 911          * See <a href="#method_addAttr">addAttr</a>.
 912          */
 913         _addAttrs : function(cfgs, values, lazy) {
 914             var host = this, // help compression
 915                 attr,
 916                 attrCfg,
 917                 value;
 918
 919             for (attr in cfgs) {
 920                 if (cfgs.hasOwnProperty(attr)) {
 921
 922                     // Not Merging. Caller is responsible for isolating configs
 923                     attrCfg = cfgs[attr];
 924                     attrCfg.defaultValue = attrCfg.value;
 925
 926                     // Handle simple, complex and user values, accounting for read-only
 927                     value = host._getAttrInitVal(attr, attrCfg, host._tVals);
 928
 929                     if (value !== undefined) {
 930                         attrCfg.value = value;
 931                     }
 932
 933                     if (host._tCfgs[attr]) {
 934                         delete host._tCfgs[attr];
 935                     }
 936
 937                     host.addAttr(attr, attrCfg, lazy);
 938                 }
 939             }
 940         },
 941
 942         /**
 943          * Utility method to protect an attribute configuration
 944          * hash, by merging the entire object and the individual
 945          * attr config objects.
 946          *
 947          * @method _protectAttrs
 948          * @protected
 949          * @param {Object} attrs A hash of attribute to configuration object pairs.
 950          * @return {Object} A protected version of the attrs argument.
 951          */
 952         _protectAttrs : function(attrs) {
 953             if (attrs) {
 954                 attrs = Y.merge(attrs);
 955                 for (var attr in attrs) {
 956                     if (attrs.hasOwnProperty(attr)) {
 957                         attrs[attr] = Y.merge(attrs[attr]);
 958                     }
 959                 }
 960             }
 961             return attrs;
 962         },
 963
 964         /**
 965          * Utility method to normalize attribute values. The base implementation
 966          * simply merges the hash to protect the original.
 967          *
 968          * @method _normAttrVals
 969          * @param {Object} valueHash An object with attribute name/value pairs
 970          *
 971          * @return {Object}
 972          *
 973          * @private
 974          */
 975         _normAttrVals : function(valueHash) {
 976             return (valueHash) ? Y.merge(valueHash) : null;
 977         },
 978
 979         /**
 980          * Returns the initial value of the given attribute from
 981          * either the default configuration provided, or the
 982          * over-ridden value if it exists in the set of initValues
 983          * provided and the attribute is not read-only.
 984          *
 985          * @param {String} attr The name of the attribute
 986          * @param {Object} cfg The attribute configuration object
 987          * @param {Object} initValues The object with simple and complex attribute name/value pairs returned from _normAttrVals
 988          *
 989          * @return {Any} The initial value of the attribute.
 990          *
 991          * @method _getAttrInitVal
 992          * @private
 993          */
 994         _getAttrInitVal : function(attr, cfg, initValues) {
 995             var val, valFn;
 996             // init value is provided by the user if it exists, else, provided by the config
 997             if (!cfg.readOnly && initValues && initValues.hasOwnProperty(attr)) {
 998                 val = initValues[attr];
 999             } else {
1000                 val = cfg.value;
1001                 valFn = cfg.valueFn;
1002
1003                 if (valFn) {
1004                     if (!valFn.call) {
1005                         valFn = this[valFn];
1006                     }
1007                     if (valFn) {
1008                         val = valFn.call(this, attr);
1009                     }
1010                 }
1011             }
1012
1013             Y.log('initValue for ' + attr + ':' + val, 'info', 'attribute');
1014
1015             return val;
1016         },
1017
1018         /**
1019          * Utility method to set up initial attributes defined during construction, either through the constructor.ATTRS property, or explicitly passed in.
1020          *
1021          * @method _initAttrs
1022          * @protected
1023          * @param attrs {Object} The attributes to add during construction (passed through to <a href="#method_addAttrs">addAttrs</a>). These can also be defined on the constructor being augmented with Attribute by defining the ATTRS property on the constructor.
1024          * @param values {Object} The initial attribute values to apply (passed through to <a href="#method_addAttrs">addAttrs</a>). These are not merged/cloned. The caller is responsible for isolating user provided values if required.
1025          * @param lazy {boolean} Whether or not to add attributes lazily (passed through to <a href="#method_addAttrs">addAttrs</a>).
1026          */
1027         _initAttrs : function(attrs, values, lazy) {
1028             // ATTRS support for Node, which is not Base based
1029             attrs = attrs || this.constructor.ATTRS;
1030
1031             var Base = Y.Base,
1032                 BaseCore = Y.BaseCore,
1033                 baseInst = (Base && Y.instanceOf(this, Base)),
1034                 baseCoreInst = (!baseInst && BaseCore && Y.instanceOf(this, BaseCore));
1035
1036             if ( attrs && !baseInst && !baseCoreInst) {
1037                 this.addAttrs(this._protectAttrs(attrs), values, lazy);
1038             }
1039         }
1040     };
1041
1042     Y.AttributeCore = AttributeCore;
1043
1044
1045 }, '3.7.2', {"requires": ["oop"]});