/*

Copyright (c) 2009, Yahoo! Inc. All rights reserved.

Code licensed under the BSD License:

http://developer.yahoo.net/yui/license.txt

version: 3.0.0b1

build: 1163

*/

YUI.add('attribute', function(Y) {

    /**

     * The State class maintains state for a collection of named items, with 

     * a varying number of properties defined.

     *

     * It avoids the need to create a separate class for the item, and separate instances 

     * of these classes for each item, by storing the state in a 2 level hash table, 

     * improving performance when the number of items is likely to be large.

     *

     * @constructor

     * @class State

     */

    Y.State = function() { 

        /**

         * Hash of attributes

         * @property data

         */

        this.data = {};

    };

    Y.State.prototype = {

        /**

         * Adds a property to an item.

         *

         * @method add

         * @param name {String} The name of the item.

         * @param key {String} The name of the property.

         * @param val {Any} The value of the property.

         */

        add : function(name, key, val) {

            var d = this.data;

            d[key] = d[key] || {};

            d[key][name] = val;

        },

        /**

         * Adds multiple properties to an item.

         *

         * @method addAll

         * @param name {String} The name of the item.

         * @param o {Object} A hash of property/value pairs.

         */

        addAll: function(name, o) {

            var key;

            for (key in o) {

                if (o.hasOwnProperty(key)) {

                    this.add(name, key, o[key]);

                }

            }

        },

        /**

         * Removes a property from an item.

         *

         * @method remove

         * @param name {String} The name of the item.

         * @param key {String} The property to remove.

         */

        remove: function(name, key) {

            var d = this.data;

            if (d[key] && (name in d[key])) {

                delete d[key][name];

            }

        },

        /**

         * Removes multiple properties from an item, or remove the item completely.

         *

         * @method removeAll

         * @param name {String} The name of the item.

         * @param o {Object|Array} Collection of properties to delete. If not provided, the entire item is removed.

         */

        removeAll: function(name, o) {

            var d = this.data;

            Y.each(o || d, function(v, k) {

                if(Y.Lang.isString(k)) {

                    this.remove(name, k);

                } else {

                    this.remove(name, v);

                }

            }, this);

        },

        /**

         * For a given item, returns the value of the property requested, or undefined if not found.

         *

         * @method get

         * @param name {String} The name of the item

         * @param key {String} Optional. The property value to retrieve.

         * @return {Any} The value of the supplied property.

         */

        get: function(name, key) {

            var d = this.data;

            return (d[key] && name in d[key]) ?  d[key][name] : undefined;

        },

        /**

         * For the given item, returns a disposable object with all of the

         * item's property/value pairs.

         *

         * @method getAll

         * @param name {String} The name of the item

         * @return {Object} An object with property/value pairs for the item.

         */

        getAll : function(name) {

            var d = this.data, o;

            Y.each(d, function(v, k) {

                if (name in d[k]) {

                    o = o || {};

                    o[k] = v[name];

                }

            }, this);

            return o;

        }

    };

    /**

     * The attribute module provides an augmentable Attribute implementation, which 

     * adds configurable attributes and attribute change events to the class being 

     * augmented. It also provides a State class, which is used internally by Attribute,

     * but can also be used independently to provide a name/property/value data structure to

     * store state.

     *

     * @module attribute

     */

    var O = Y.Object,

        EventTarget = Y.EventTarget,

        DOT = ".",

        CHANGE = "Change",

        // Externally configurable props

        GETTER = "getter",

        SETTER = "setter",

        READ_ONLY = "readOnly",

        WRITE_ONCE = "writeOnce",

        VALIDATOR = "validator",

        VALUE = "value",

        VALUE_FN = "valueFn",

        BROADCAST = "broadcast",

        LAZY_ADD = "lazyAdd",

        // Used for internal state management

        ADDED = "added",

        INITIALIZING = "initializing",

        INIT_VALUE = "initValue",

        PUBLISHED = "published",

        DEF_VALUE = "defaultValue",

        LAZY = "lazy",

        IS_LAZY_ADD = "isLazyAdd",

        INVALID_VALUE,

        MODIFIABLE = {};

        // Properties which can be changed after the attribute has been added.

        MODIFIABLE[READ_ONLY] = 1;

        MODIFIABLE[WRITE_ONCE] = 1;

        MODIFIABLE[GETTER] = 1;

        MODIFIABLE[BROADCAST] = 1;

    /**

     * <p>

     * Attribute provides configurable attribute support along with attribute change events. It is designed to be 

     * augmented onto a host class, and provides the host with the ability to configure attributes to store and retrieve state, 

     * along with attribute change events.

     * </p>

     * <p>For example, attributes added to the host can be configured:</p>

     * <ul>

     *     <li>As read only.</li>

     *     <li>As write once.</li>

     *     <li>With a setter function, which can be used to manipulate

     *     values passed to Attribute's <a href="#method_set">set</a> method, before they are stored.</li>

     *     <li>With a getter function, which can be used to manipulate stored values,

     *     before they are returned by Attribute's <a href="#method_get">get</a> method.</li>

     *     <li>With a validator function, to validate values before they are stored.</li>

     * </ul>

     *

     * <p>See the <a href="#method_addAttr">addAttr</a> method, for the complete set of configuration

     * options available for attributes</p>.

     * 

     * <p><strong>NOTE:</strong> Most implementations will be better off extending the <a href="Base.html">Base</a> class, 

     * instead of augmenting Attribute directly. Base augments Attribute and will handle the initial configuration 

     * of attributes for derived classes, accounting for values passed into the constructor.</p>

     *

     * @class Attribute

     * @uses EventTarget

     */

    function Attribute() {

        Y.log('Attribute constructor called', 'info', 'attribute');

        // Perf tweak - avoid creating event literals if not required.

        this._ATTR_E_FACADE = {};

        EventTarget.call(this, {emitFacade:true});

        this._conf = new Y.State();

    }

    /**

     * <p>The value to return from an attribute setter in order to prevent the set from going through.</p>

     * 

     * <p>You can return this value from your setter if you wish to combine validator and setter 

     * functionality into a single setter function, which either returns the massaged value to be stored or 

     * Attribute.INVALID_VALUE to prevent invalid values from being stored.</p>

     *

     * @property Attribute.INVALID_VALUE

     * @type Object

     * @static

     * @final

     */

    Attribute.INVALID_VALUE = {};

    INVALID_VALUE = Attribute.INVALID_VALUE;

    /**

     * The list of properties which can be configured for 

     * each attribute (e.g. setter, getter, writeOnce etc.).

     *

     * This property is used internally as a whitelist for faster

     * Y.mix operations.

     *

     * @property Attribute._ATTR_CFG

     * @type Array

     * @static

     * @protected

     */

    Attribute._ATTR_CFG = [SETTER, GETTER, VALIDATOR, VALUE, VALUE_FN, WRITE_ONCE, READ_ONLY, LAZY_ADD, BROADCAST];

    Attribute.prototype = {

        /**

         * <p>

         * Adds an attribute with the provided configuration to the host object.

         * </p>

         * <p>

         * The config argument object supports the following properties:

         * </p>

         * 

         * <dl>

         *    <dt>value &#60;Any&#62;</dt>

         *    <dd>The initial value to set on the attribute</dd>

         *

         *    <dt>valueFn &#60;Function&#62;</dt>

         *    <dd>A function, which will return the initial value to set on the attribute. This is useful

         *    for cases where the attribute configuration is defined statically, but needs to 

         *    reference the host instance ("this") to obtain an initial value.

         *    If defined, this precedence over the value property.</dd>

         *

         *    <dt>readOnly &#60;boolean&#62;</dt>

         *    <dd>Whether or not the attribute is read only. Attributes having readOnly set to true

         *        cannot be modified by invoking the set method.</dd>

         *

         *    <dt>writeOnce &#60;boolean&#62;</dt>

         *    <dd>Whether or not the attribute is "write once". Attributes having writeOnce set to true, 

         *        can only have their values set once, be it through the default configuration, 

         *        constructor configuration arguments, or by invoking set.</dd>

         *

         *    <dt>setter &#60;Function&#62;</dt>

         *    <dd>The setter function used to massage or normalize the value passed to the set method for the attribute. 

         *    The value returned by the setter will be the final stored value. Returning

         *    <a href="#property_Attribute.INVALID_VALUE">Attribute.INVALID_VALUE</a>, from the setter will prevent

         *    the value from being stored.</dd>

         *

         *    <dt>getter &#60;Function&#62;</dt>

         *    <dd>The getter function used to massage or normalize the value returned by the get method for the attribute.

         *    The value returned by the getter function is the value which will be returned to the user when they 

         *    invoke get.</dd>

         *

         *    <dt>validator &#60;Function&#62;</dt>

         *    <dd>The validator function invoked prior to setting the stored value. Returning

         *    false from the validator function will prevent the value from being stored.</dd>

         *    

         *    <dt>broadcast &#60;int&#62;</dt>

         *    <dd>If and how attribute change events for this attribute should be broadcast. See CustomEvent's <a href="CustomEvent.html#property_broadcast">broadcast</a> property for 

         *    valid values. By default attribute change events are not broadcast.</dd>

         *

         *    <dt>lazyAdd &#60;boolean&#62;</dt>

         *    <dd>Whether or not to delay initialization of the attribute until the first call to get/set it. 

         *    This flag can be used to over-ride lazy initialization on a per attribute basis, when adding multiple attributes through 

         *    the <a href="#method_addAttrs">addAttrs</a> method.</dd>

         *

         * </dl>

         *

         * <p>The setter, getter and validator are invoked with the value and name passed in as the first and second arguments, and with

         * the context ("this") set to the host object.</p>

         *

         * @method addAttr

         *

         * @param {String} name The name of the attribute.

         * @param {Object} config An object with attribute configuration property/value pairs, specifying the configuration for the attribute.

         *

         * <p>

         * <strong>NOTE:</strong> The configuration object is modified when adding an attribute, so if you need 

         * to protect the original values, you will need to merge the object.

         * </p>

         *

         * @param {boolean} lazy (optional) Whether or not to add this attribute lazily (on the first call to get/set). 

         *

         * @return {Object} A reference to the host object.

         *

         * @chainable

         */

        addAttr: function(name, config, lazy) {

            Y.log('Adding attribute: ' + name, 'info', 'attribute');

            var conf = this._conf;

            lazy = (LAZY_ADD in config) ? config[LAZY_ADD] : lazy;

            if (lazy && !this.attrAdded(name)) {

                Y.log('Lazy Add: ' + name, 'info', 'attribute');

                conf.add(name, LAZY, config || {});

                conf.add(name, ADDED, true);

            } else {

                if (this.attrAdded(name) && !conf.get(name, IS_LAZY_ADD)) { Y.log('Attribute: ' + name + ' already exists. Cannot add it again without removing it first', 'warn', 'attribute'); }

                if (!this.attrAdded(name) || conf.get(name, IS_LAZY_ADD)) {

                    Y.log('Non-Lazy Add: ' + name, 'info', 'attribute');

                    config = config || {};

                    var value, hasValue = (VALUE in config);

                    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');}

                    if(hasValue) {

                        // We'll go through set, don't want to set value in _conf directory

                        value = config.value;

                        delete config.value;

                    }

                    config.added = true;

                    config.initializing = true;

                    conf.addAll(name, config);

                    if (hasValue) {

                        // Go through set, so that raw values get normalized/validated

                        this.set(name, value);

                    }

                    conf.remove(name, INITIALIZING);

                }

            }

            return this;

        },

        /**

         * Checks if the given attribute has been added to the host

         *

         * @method attrAdded

         * @param {String} name The name of the attribute to check.

         * @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.

         */

        attrAdded: function(name) {

            return !!this._conf.get(name, ADDED);

        },

        /**

         * Updates the configuration of an attribute which has already been added.

         * <p>

         * The properties which can be modified through this interface are limited

         * to the following subset of attributes, which can be safely modified

         * after a value has already been set on the attribute: readOnly, writeOnce, 

         * broadcast and getter.

         * </p>

         * @method modifyAttr

         * @param {String} name The name of the attribute whose configuration is to be updated.

         * @param {Object} config An object with configuration property/value pairs, specifying the configuration properties to modify.

         */

        modifyAttr: function(name, config) {

            if (this.attrAdded(name)) {

                if (this._isLazyAttr(name)) {

                    this._addLazyAttr(name);

                }

                var prop, conf = this._conf;

                for (prop in config) {

                    if (MODIFIABLE[prop] && config.hasOwnProperty(prop)) {

                        conf.add(name, prop, config[prop]);

                        // If we reconfigured broadcast, need to republish

                        if (prop === BROADCAST) {

                            conf.remove(name, PUBLISHED);

                        }

                    }

                }

            }

            if (!this.attrAdded(name)) {Y.log('Attribute modifyAttr:' + name + ' has not been added. Use addAttr to add the attribute', 'warn', 'attribute');}

        },

        /**

         * Removes an attribute from the host object

         *

         * @method removeAttr

         * @param {String} name The name of the attribute to be removed.

         */

        removeAttr: function(name) {

            this._conf.removeAll(name);

        },

        /**

         * Returns the current value of the attribute. If the attribute

         * has been configured with a 'getter' function, this method will delegate

         * to the 'getter' to obtain the value of the attribute.