[pwl6.git] / src / yuu / yf.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 () {
    "use strict";

    /** yf - yuu foundation

        A collection of tools for functional programming and the kind
        of sequence (array) manipulations usually associated with
        functional programming.

        yf doesn't depend on yuu specifically, but may use standard
        features not yet widely supported provided by yuu/pre.
     */

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

    function isString (s) {
        /** Check if a value is a string */
        return Object.prototype.toString.call(s) === "[object String]";
    }

    function I (x) { return x; }

    function K (x) { return function () { return x; }; }

    /** Get the minimum or maximum of two objects

        The default JavaScript Math.min and Math.max are unsuitable as
        generic functions. They don't work on strings. Because they
        support a variable numbers of arguments they don't work
        correctly when passed directly to higher-order functions that
        pass "bonus" arguments such as Array.prototype.reduce.

        These functions work on any objects comparable with < and >,
        and only consider two arguments.
    */
    function min (a, b) { return b < a ? b : a; }
    function max (a, b) { return b > a ? b : a; }
    function clamp(x, lo, hi) { return max(lo, min(hi, x)); }

    /** Get a property from the this object by name */
    function getter (key) { return this[key]; }

    /** Set a property value on the this object by name */
    function setter (key, value) { this[key] = value; }

    function unbind (f) {
        /** Factor out the special 'this' argument from a function

            unbind(f)(a, b, c) is equivalent to f.call(a, b, c), and
            you may store the return value for later use without
            storing the original function.
        */

        // return f.call.bind(f) is ~15% slower than this closure on
        // Chrome 31 and negligibly slower on Firefox 25.
        return function () {
            return f.call.apply(f, arguments);
        };
    }

    /** Unbound versions of useful functions */
    var slice = unbind(Array.prototype.slice);

    function contains (seq, o) {
        return Array.prototype.indexOf.call(seq, o) !== -1;
    }

    function lacks (seq, o) {
        return !contains(seq, o);
    }

    /** The first element of a sequence */
    function head (a) { return a[0]; }

    /** All but the first element of a sequence */
    function tail (a) { return slice(a, 1); }

    /** The last element of a sequence */
    function last (a) { return a[a.length - 1]; }

    /** All but the last element of a sequence */
    function most (a) { return slice(a, 0, -1); }

    /** The length of a sequence */
    function len (seq) { return seq.length; }

    /** Note that yf's argument order is slightly different from
        JavaScript's normal order (but the same as most other
        languages with functional elements).

        This is irrelevant for `fold` and `filter`, but `each` and
        `map` can take multiple sequences to allow callback functions
        with arbitrary arity.

        Because of this difference, there is no final `thisArg` as in
        e.g. the standard Array's forEach. Instead the `this` of
        the original call is forwarded. For example,
            someArray.forEach(callback, thisArg)
        becomes
            yf.each.call(thisArg, callback, someArray)
    */

    function foldl (callback, seq, value) {
        /** Like Array's reduce, but with no extra arguments

            This traverses the sequence in indexed order, low-to-high,
            and calls the provided function with the accumulated value
            and the sequence item.
        */
        var i = 0;
        if (arguments.length === 2)
            value = seq[i++];
        for (; i < seq.length; ++i)
            value = callback.call(this, value, seq[i]);
        return value;
    }

    function foldr (callback, seq, value) {
        /** Like foldl, but reversed.

            This traverses the sequence in indexed order, high-to-low,
            and calls the provided function with the sequence item and
            the accumulated value.
        */
        var i = seq.length - 1;
        if (arguments.length === 2)
            value = seq[i--];
        for (; i >= 0; --i)
            value = callback.call(this, seq[i], value);
        return value;
    }

    function call (f, x) { return f.call(this, x); }

    function compose () {
        /** Create a function by composing multiple functions

            compose(f, g, h)(x, y, z) is equivalent to f(g(h(x, y, z))).
        */
        var inner = last(arguments);
        var funcs = most(arguments);
        return function () {
            return foldr.call(this, call, funcs, inner.apply(this, arguments));
        };
    }

    // Generating specialized functions for plucking the nth argument
    // and passing it to a callback is 100-120x faster than the
    // generic one in V8.
    //
    // So generate specialized functions for small argc, and only
    // resort to the generic approach when there's many sequences.
    var CALLS = [];

    /* jshint -W054*/ /* Function constructor is a form of eval */
    for (var args = []; args.length < 32;
         args.push(", seqs[" + args.length + "][i]"))
        CALLS[args.length] = new Function(
            "callback", "i", "seqs",
            "return callback.call(this" + args.join("") + ");");

    function lookup (prop) {
        /** Return a function that gets a particular property */

        // Building this as a closure is ~2-5x faster than writing
        // a function lookup(prop, o) and binding it.
        return function (s) { return s[prop]; };
    }

    function callx (callback, i, seqs) {
        return callback.apply(this, seqs.map(lookup(i)));
    }

    function calln (argc) {
        return CALLS[argc] || callx;
    }

    function argv (f) {
        /** Provide a variadic-like version of f

            Arguments passed to the function including and after the
            final named one are collected and passed as a single
            sequence (not necessarily Array) value.
        */
        var length = f.length;
        switch (length) {
        case 0: throw new Error("don't use argv for 0-ary functions");
        case 1: return function () { return f.call(this, arguments); };
        default:
            return function () {
                var args = slice(arguments, 0, length - 1);
                args.push(slice(arguments, length - 1));
                return f.apply(this, args);
            };
        }
    }

    var each = argv(function (callback, seqs) {
        /** Call a function on the given sequences' elements

            If one sequence is longer than the others, `undefined`
            will be passed for that sequence's argument.

            For example, each(f, [a, b, c], [x, y]) is equivalent to
                f(a, x);
                f(b, y);
                f(c, undefined);

            If you want to pass a thisArg to the callback, use
            each.call(thisArg, callback, ...).
        */
        var length = Math.max.apply(Math, seqs.map(len));
        var fn = calln(seqs.length);
        for (var i = 0; i < length; ++i)
            fn.call(this, callback, i, seqs);
    });

    var eachr = argv(function (callback, seqs) {
        /** Call a function on the given sequences' elements, backwards
            
            If one sequence is longer than the others, `undefined` will be
            passed for that sequence's argument.

            For example, each(f, [a, b, c], [x, y]) is equivalent to
                f(c, undefined);
                f(b, y);
                f(a, x);

            If you want to pass a thisArg to the callback, use
            eachr.call(thisArg, callback, ...).
        */
        var length = Math.max.apply(Math, seqs.map(len));
        var fn = calln(seqs.length);
        for (var i = length - 1; i >= 0; --i)
            fn.call(this, callback, i, seqs);
    });

    function pusher (a) {
        // Ridiculously faster than a.push.bind(a). :(
        return function (o) { a.push(o); };
    }

    function map () {
        /** Build an array by applying a function to sequences

            Similar to Array.prototype.map, but allows passing multiple
            sequences to call functions of any arity, as with each.

            If you want to pass a thisArg to the callback, use
            map.call(thisArg, callback, ...).
        */
        var a = [];
        arguments[0] = compose(pusher(a), arguments[0]);
        each.apply(this, arguments);
        return a;
    }

    function mapr () {
        /** Build an array by applying a function to sequences backwards

            As eachr is to each, so mapr is to map.
        */
        var a = [];
        arguments[0] = compose(pusher(a), arguments[0]);
        eachr.apply(this, arguments);
        return a;
    }

    function filter (callback, seq) {
        /** Build an array without the elements that fail the predicate

            Like Array.prototype.filter, but if null is passed for the
            predicate, any false-y values will be removed.
        */
        var a = [];
        callback = callback || I;
        function _ (o) { if (callback.call(this, o)) a.push(o); }
        each.call(this, _, seq);
        return a;
    }

    function packed (f) {
        /** Pack arguments to a function into an Array

            packed(f)([a, b, c]) is equivalent to f(a, b, c).
        */
        return function (args) { return f.apply(this, args); };
    }

    function argcd () {
        /** Create a function that dispatches based on argument count

            Pass a list of functions with varying argument lengths, e.g.
                var f = argcd(function () { ... },
                              function (a, b) { ... },
                              function (a, b, c) { ... });

            This can be used for function overloading, clearer
            defaults for positional parameters, or significantly more
            evil things.

            The functions can also be accessed directly by their
            argument count, e.g. f[0], f[2], f[3] above.

            If no matching argument count is found for a call, a
            TypeError is raised.
        */
        if (arguments.length === 1)
            throw new Error("don't use argcd for one function");
        var table = (function table () {
            return table[arguments.length].apply(this, arguments);
        });
        for (var i = 0; i < arguments.length; ++i)
            table[arguments[i].length] = arguments[i];
        return table;
    }

    var irange = argcd(
        /** Call the provided callback counting as it goes
            
            irange(x) counts from [0, x), by 1.
            
            irange(x, y) counts from [x, y), by 1.
            
            irange(x, y, s) counts from [x, y), by s.
        */
        function (callback, stop) {
            return irange.call(this, callback, 0, stop, 1);
        },
        function (callback, start, stop) {
            return irange.call(this, callback, start, stop, 1);
        },
        function (callback, start, stop, step) {
            var length = Math.max(Math.ceil((stop - start) / step), 0);
            for (var i = 0; i < length; ++i)
                callback.call(this, start + step * i);
        }
    );

    function capture1 (ifunc) {
        /** Build an array from the values of an iterating function

            The elements added to the array are the first arguments
            the iterating function passes.
        */
        return function () {
            var a = [];
            var args = slice(arguments);
            args.unshift(pusher(a));
            ifunc.apply(this, args);
            return a;
        };
    }

    /** Generate an Array from range of numbers, as irange */
    var range = capture1(irange);

    function ipairs (callback, o) {
        /** Call the provided callback with each key and value of the object */
        each.call(this, function (k) { callback.call(this, k, o[k]); },
                  Object.keys(o));
    }

    function iprototypeChain (callback, o) {
        /** Traverse an object and its prototype chain */
        do {
            callback.call(this, o);
        } while ((o = Object.getPrototypeOf(o)));
    }

    function allKeys (o) {
        /** Get *ALL* property names. Even unowned non-enumerable ones. */
        var props = [];
        iprototypeChain(compose(packed(props.push).bind(props),
                                Object.getOwnPropertyNames),
                        o);
        return props.sort().filter(function (p, i, a) {
            return p !== a[i - 1];
        });
    }

    var some = argv(function (callback, seqs) {
        callback = callback || I;
        var length = Math.max.apply(Math, seqs.map(len));
        var fn = calln(seqs.length);
        for (var i = 0; i < length; ++i)
            if (fn.call(this, callback, i, seqs))
                return true;
        return false;
    });

    var eachrUntil = argv(function (callback, seqs) { // Reverse of `some`
        callback = callback || I;
        var length = Math.max.apply(Math, seqs.map(len));
        var fn = calln(seqs.length);
        for (var i = length - 1; i >= 0; --i)
            if (fn.call(this, callback, i, seqs))
                return true;
        return false;
    });

    function not (f) {
        /** Build a function equivalent to !f(...) */
        return function () { return !f.apply(this, arguments); };
    }

    function every () {
        arguments[0] = not(arguments[0] || I);
        return !some.apply(this, arguments);
    }

    function none () {
        return !some.apply(this, arguments);
    }

    function repeat (o, n) {
        return (new Array(n)).fill(o);
    }

    function arrayify (o) {
        /** Equivalent to [].concat(o) but faster */
        return Array.isArray(o) ? o : [o];
    }

    function stash (key, value, a) {
        each(function (o) { o[key] = value; }, a);
    }

    function without (seq, o) {
        if (arguments.length === 2)
            return filter(function (a) { return a !== o; }, seq);
        var os = slice(arguments, 1);
        return filter(lacks.bind(null, os), seq);
    }

    function construct (ctr, args) {
        args = slice(args);
        args.unshift(ctr);
        return new (Function.prototype.bind.apply(ctr, args))();
    }

    function new_ (ctr) {
        return function () { return construct(ctr, arguments); };
    }

    function counter (start) {
        var i = +(start || 0);
        return function () { return i++; };
    }

    function volatile (f) {
        return { valueOf: f };
    }

    function transform (callback, seq) {
        irange.call(this, function (i) {
            seq[i] = callback.call(this, seq[i]);
        }, seq.length);
    }

    function mapValues (callback, o) {
        var r = {};
        for (var k in o)
            r[k] = callback.call(this, o[k]);
        return r;
    }

    function insertBefore (seq, o, before) {
        var idx = seq.lastIndexOf(before);
        if (idx === -1)
            seq.push(o);
        else
            seq.splice(idx, 0, o);
        return seq;
    }

    function seqEqual (a, b) {
        if (a.length !== b.length)
            return false;
        for (var i = 0; i < a.length; ++i)
            if (a[i] !== b[i])
                return false;
        return true;
    }

    function debounce (callback, wait) {
        wait = wait || 100;
        var this_ = null;
        var args = null;
        var id = null;

        function _ () {
            callback.apply(this_, args);
            this_ = null;
            args = null;
            id = null;
        }

        return function () {
            if (id !== null && this_ !== this)
                _();
            clearTimeout(id);
            this_ = this;
            args = arguments;
            id = setTimeout(_, wait);
        };
    }

    function pluck (prop, seq) {
        return map(lookup(prop), seq);
    }

    Object.assign(this, {
        allKeys: allKeys,
        argcd: argcd,
        argv: argv,
        arrayify: arrayify,
        clamp: clamp,
        compose: compose,
        construct: construct,
        contains: contains,
        counter: counter,
        debounce: debounce,
        each: each,
        eachUntil: some,
        eachr: eachr,
        eachrUntil: eachrUntil,
        every: every,
        filter: filter,
        foldl: foldl,
        foldr: foldr,
        getter: getter,
        head: head,
        I: I,
        insertBefore: insertBefore,
        ipairs: ipairs,
        irange: irange,
        isFunction: isFunction,
        isString: isString,
        K: K,
        lacks: lacks,
        last: last,
        len: len,
        lookup: lookup,
        map: map,
        mapr: mapr,
        mapValues: mapValues,
        max: max,
        min: min,
        most: most,
        new_: new_,
        none: none,
        pluck: pluck,
        range: range,
        repeat: repeat,
        seqEqual: seqEqual,
        setter: setter,
        slice: slice,
        some: some,
        stash: stash,
        tail: tail,
        transform: transform,
        unbind: unbind,
        volatile: volatile,
        without: without,

        VERSION: 0
    });

}).call(typeof exports !== "undefined" ? exports : (this.yf = {}));