[pwl6.git] / src / yuu / yT.js

/* Copyright 2014 Yukkuri Games
   Licensed under the terms of the GNU GPL v2 or later
   @license http://www.gnu.org/licenses/gpl-2.0.html
   @source: http://yukkurigames.com/yuu/
*/

(function (module) {
    "use strict";

    /** yT - yuu type creation

        yT is a function like `Object.create`, but with support for
        more powerful property descriptors (referred to as _extended
        property descriptors (XPDs)_). Most standard JavaScript
        property descriptors are valid XPDs, but XPDs allow shortcuts
        to specify common descriptor patterns.

        Equivalents for `Object.defineProperties` and
        `Object.defineProperty` are also provided.

        ## Extended Property Descriptors

        Any standard descriptor that has a `get` function (called an
        'accessor descriptor') or a `value` property (called a 'data
        descriptor') is also valid XPD.

        An extended descriptor that does not have either of these and
        does not meet any of the other conditions below is equivalent
        to a data descriptor with a `value` of itself, referred to as
        a 'bare value descriptor'. For example, the following two XPDs
        are equivalent:

            { x: 1 }                { x: { value: 1 } }

        (This means a useless descriptor like `{}` is interpreted as a
        data descriptor with value `undefined` by `Object.create` but
        a bare value descriptor with value `{}` by `yT`.)
        
        In addition, extended descriptors have several other formats
        which can be used to generate different kinds of idomatic
        accessors:

         * `alias` - This property is a synonym for a different property.
            Reads and writes to it will be mapped to reads and writes
            to the aliased property. 
                { firstChild: { alias: "children[0]" } }
            is equivalent to
                { firstChild: {
                    get: function () { return this.children[0]; },
                    set: function (v) { this.children[0] = v; }
                } }

         * `proxy` - This property is a synonym for a method call
            on a different object.
                { start: { proxy: "engine.start" } }
            is equivalent to
                { start: { value: function () {
                    return this.engine.start.apply(this.engine, arguments);
                } } }

            Using `alias` rather than `proxy` would result in the
            wrong (non-engine) `this` argument being passed to the
            `start` method.

         * `aliasSynthetic` - Aliases don't work if one of the
            properties in the lookup chain is a temporary variable.
            For example, aliasing `x` to `position[0]` is no good if
            `position` itself has a getter like `transform.slice(12)`
            because the assignment to the returned value will have
            no effect.

            `aliasSynthetic` can be used to capture the temporary,
            assign to it, and then assign the whole temporary back.
                { x: { aliasSynthetic: "position[0]" } }
            Generates the same `get` as `alias`, but `set` is
                function (v) {
                    var t = this.position;
                    t[0] = v;
                    this.position = t;
                }

            `aliasSynthetic` assumes the next-to-last value is the
            temporary, e.g. in `a.b.c.d`, `a.b.c` is the temporary.
            If rather e.g. `a.b` is the temporary, you can separate
            the `alias` and `synthetic` parts:
                { x: { alias: "a.b.c.d", synthetic: "a.b" } }

         * `swizzle` - Swizzling lets you treat separate properties
            as one array property. For example if you have a color
            class with individual r, g, and b properties,
                { rgb: { swizzle: ["r", "g", "b"] } }
            is equivalent to
                { rgb: {
                    get: function () { return [this.r, this.g, this.b] },
                    set: function (v) {
                        this.r = v[0];
                        this.g = v[1];
                        this.b = v[2];
                    }
                } }

        Any descriptor may also have the `chainable` property set,
        which generates a chainable setter function. Chainable data
        descriptors are writable by default.
            { x: { value: 0, chainable: true } }
        is equivalent to
            { x: { value: 0, writable: true },
              setX: { value: function (v) { this.x = v; return this; } }
            }

        ## Example
        
        An example of a simple 2D Point class using XPDs:

            var Point = yT(Object, {
                constructor: function (x, y) {
                    this.x = x || 0;
                    this.y = y || 0;
                },

                0: { alias: "x" },
                1: { alias: "y" },
                xy: { swizzle: "xy" },
                yx: { swizzle: "yx" },

                angle: {
                    chainable: true,
                    get: function () {
                        return Math.atan2(this.y, this.x);
                    },
                    set: function (angle) {
                        var magnitude = this.magnitude;
                        this.x = Math.cos(angle) * magnitude;
                        this.y = Math.sin(angle) * magnitude;
                    }
                },

                magnitude: {
                    chainable: true,
                    get: function () {
                        return Math.sqrt(this.x * this.x + this.y * this.y);
                    },
                    set: function (magnitude) {
                        var angle = this.angle;
                        this.x = Math.cos(angle) * magnitude;
                        this.y = Math.sin(angle) * magnitude;
                    }
                },

                length: 2
            });

            var p = new Point(3, 0);
            p[0] === 3; // true
            p.y = 4; p[1] == 4; // true
            p.magnitude = 1; // normalize
            p.xy = p.yx; // transpose

            new Point().setMagnitude(m).setAngle(a);
                // construct a point from an angle and magnitude in a
                // single step.
     */

    /* jshint -W054 */ // Function constructors are the whole point here.

    function isFunction (o) {
        /** Check if a value is a function */
        return Object.prototype.toString.call(o) === '[object Function]';
    }

    function update (dst, src) {
        /** Copy every enumerable key and its value from src to dst */
        for (var k in src)
            dst[k] = src[k];
        return dst;
    }

    function rooted (path) {
        if (typeof path === "number")
            return "[" + path + "]";
        else if (path[0] !== "." && path[0] !== "[")
            return "." + path;
        else
            return path;
    }

    function chainableName (name) {
        return "set" + name[0].toUpperCase() + name.substring(1);
    }

    function chainableSetter (name) {
        return new Function(
            "value",
            "this" + rooted(name) + " = value; " + "return this;");
    }

    function alias (path, readonly) {
        path = rooted(path);
        return readonly
            ? { get: new Function("return this" + path + ";") }
            : { get: new Function("return this" + path + ";"),
                set: new Function("v", "return this" + path + " = v;") };
    }

    function proxy (path) {
        path = rooted(path);
        var prop = path.substr(0, path.lastIndexOf("."));
        return {
            value: new Function(
                "return this" + path + ".apply(this" + prop + ", arguments);")
        };
    }

    function swizzle (props) {
        props = Array.prototype.map.call(props, function (p) {
            return "this" + rooted(p);
        });
        var assignments = props.map(function (p, i) {
            return p + " = x[" + i + "];";
        });
        return {
            get: new Function("return [" + props.join(", ") + "];"),
            set: new Function("x", assignments.join("\n"))
        };
    }

    function aliasSynthetic (path) {
        var idx = Math.max(path.lastIndexOf("."), path.lastIndexOf("["));
        return synthetic(path.substring(0, idx), path);
    }

    function synthetic (synthPath, path) {
        synthPath = rooted(synthPath);
        path = rooted(path).substring(synthPath.length);
        return {
            get: new Function("return this" + synthPath + path + ";"),
            set: new Function("v",
                              ["var t = this" + synthPath + ";",
                               "t" + path + " = v; ",
                               "this" + synthPath + " = t;",
                               ].join("\n"))
        };
    }

    function isAccessorDescriptor (pd) {
        /** Check if `pd` is a descriptor describing an accessor */
        return pd && typeof pd === "object" && isFunction(pd.get);
    }

    function isDataDescriptor (pd) {
        /** Check if `pd` is a descriptor describing data */
        return pd && typeof pd === "object" && ("value" in pd);
    }
    
    function isDescriptor (pd) {
        /** Check if `pd` is any kind of descriptor */
        return isDataDescriptor(pd) || isAccessorDescriptor(pd);
    }

    function createDescriptors (name, xpd, pds) {
        if (xpd.alias !== undefined) {
            if (xpd.synthetic !== undefined)
                pds[name] = update(xpd, synthetic(xpd.alias, xpd.synthetic));
            else
                pds[name] = update(xpd, alias(xpd.alias, xpd.readonly));
        } else if (xpd.proxy !== undefined) {
            pds[name] = update(xpd, proxy(xpd.proxy));
        } else if (xpd.swizzle !== undefined) {
            pds[name] = update(xpd, swizzle(xpd.swizzle));
        } else if (xpd.aliasSynthetic !== undefined) {
            pds[name] = update(xpd, aliasSynthetic(xpd.aliasSynthetic));
        }

        pds[name] = isDescriptor(xpd) ? xpd : { value: xpd };
        if (xpd.chainable) {
            pds[chainableName(name)] = { value: chainableSetter(name) };
            if (isDataDescriptor(pds[name]) && !("writable" in pds[name]))
                pds[name].writable = true;
        }
    }

    function xpdsToPds (xpds) {
        var pds = {};
        Object.keys(xpds).forEach(function (k) {
            createDescriptors(k, xpds[k], pds);
        });
        return pds;
    }

    function T (parent, xpds) {
        /** Create a new class described by XPDs

            This function is similar to `Object.create` but supports
            extended property descriptors as described above.

            yT(parent, map of extended descriptors)
            yT(map of extended descriptors)
                // The parent is assumed to be Object

            This returns a _function_ which acts as a constructor for
            the provided type. If there is a property descriptor named
            `constructor` it is returned; otherwise a new function
            that calls the parent's.

            `parent` may be either the parent constructor or a
            prototype.
        */
        if (!xpds) {
            xpds = parent;
            parent = Object;
        }
        parent = isFunction(parent) && parent.prototype || parent;
        var pds = xpdsToPds(xpds);
        var ctor = pds.constructor && pds.constructor.value;
        if (!ctor || ctor === {}.constructor) {
            ctor = parent
                ? function () { parent.constructor.apply(this, arguments); }
                : function () { };
            pds.constructor = { value: ctor };
        }
        ctor.prototype = Object.create(parent, pds);
        return ctor;
    }

    T.defineProperties = function (o, xpds) {
        /** Add properties described by XPDs to an object

            This function is similar to`Object.defineProperties`,
            but supports the same features as `yT`.
        */
        return Object.defineProperties(o, xpdsToPds(xpds));
    };

    T.defineProperty = function (o, name, xpd) {
        /** Add a property described by an XPD to an object

            This function is similar to`Object.defineProperty`,
            but supports the same features as `yT`.
        */
        var xpds = {};
        xpds[name] = xpd;
        return T.defineProperties(o, xpds);
    };

    T.getPropertyDescriptor = function (o, name) {
        /** Look up a descriptor from `o`'s prototype chain */
        var v = null;
        while (!v && o) {
            v = Object.getOwnPropertyDescriptor(o, name);
            o = Object.getPrototypeOf(o);
        }
        return v;
    };

    T.isAccessorDescriptor = isAccessorDescriptor;
    T.isDataDescriptor = isDataDescriptor;
    T.isDescriptor = isDescriptor;

    if (module)
        module.exports = T;
    else
        this.yT = T;
}).call(typeof exports === "undefined" ? this : exports,
        typeof exports === "undefined" ? null : module);