base.rst

Ajax下日志框架

    on each element. Uses a fast-path for length differences.


:mochidef:`bind(func, self[, arg, ...])`:

    Return a copy of ``func`` bound to ``self``. This means whenever
    and however the returned function is called, ``this`` will always
    reference the given ``self``. ``func`` may be either a function
    object, or a string. If it is a string, then ``self[func]`` will
    be used, making these two statements equivalent::
        
        bind("method", self);
        bind(self.method, self);

    Calling :mochiref:`bind(func, self)` on an already bound function will
    return a new function that is bound to the new ``self``! If
    ``self`` is ``undefined``, then the previous ``self`` is used.
    If ``self`` is ``null``, then the ``this`` object is used
    (which may or may not be the global object). To force binding
    to the global object, you should pass it explicitly.

    Additional arguments, if given, will be partially applied to
    the function. These three expressions are equivalent and
    return equally efficient functions (:mochiref:`bind` and
    :mochiref:`partial` share the same code path):

    - :mochiref:`bind(oldfunc, self, arg1, arg2)`
    - :mochiref:`bind(partial(oldfunc, arg1, arg2), self)`
    - :mochiref:`partial(bind(oldfunc, self), arg1, arg2)`


:mochidef:`bindMethods(self)`:

    Replace all functions ``meth`` on ``self`` with 
    :mochiref:`bind(meth, self)`.  This emulates
    Python's bound instance methods, where there is no
    need to worry about preserving ``this`` when the
    method is used as a callback.


:mochidef:`clone(obj)`:

    Return a new object using ``obj`` as its prototype. Use this
    if you want to return a mutable object (e.g. instance state),
    but don't want the user to mutate it. If they do, it won't
    have any effect on the original ``obj``.
    
    Note that this is a shallow clone, so mutable properties will
    have to be cloned separately if you want to "protect" them.


:mochidef:`compare(a, b)`:

    Compare two objects in a sensible manner. Currently this is:
    
    1.  ``undefined`` and ``null`` compare equal to each other
    2.  ``undefined`` and ``null`` are less than anything else
    3.  If JavaScript says ``a == b``, then we trust it
    4.  comparators registered with registerComparator are
        used to find a good comparator. Built-in comparators
        are currently available for ``Array``-like and ``Date``-like
        objects.
    5.  Otherwise hope that the built-in comparison operators
        do something useful, which should work for numbers
        and strings.
    6.  If neither ``a < b`` or ``a > b``, then throw a ``TypeError``

    Returns what one would expect from a comparison function:

    +-----------+---------------+
    | Value     | Condition     |
    +-----------+---------------+
    | ``0``     | ``a == b``    |
    +-----------+---------------+
    | ``1``     | ``a > b``     |
    +-----------+---------------+
    | ``-1``    | ``a < b``     |
    +-----------+---------------+


:mochidef:`concat(lst[, ...])`:

    Concatenates all given ``Array``-like arguments and returns
    a new ``Array``::

        var lst = concat(["1","3","5"], ["2","4","6"]);
        assert( lst.toString() == "1,3,5,2,4,6" );


:mochidef:`counter(n=1)`:

    Returns a function that will return a number one greater than
    the previous returned value, starting at ``n``. For example::

        nextId = counter()
        assert( nextId() == 1 )
        assert( nextId() == 2 )

    For an iterator with this behavior, see
    :mochiref:`MochiKit.Iter.count`.


:mochidef:`extend(self, obj, skip=0)`:

    Mutate the array ``self`` by extending it with an ``Array``-like
    ``obj``, starting from index ``skip``. If ``null`` is given
    as the initial array, a new one will be created.

    This mutates *and returns* ``self``, be warned.


:mochidef:`evalJSON(aJSONString)`:

    Unserialize a JSON [1]_ represenation of an object.
    
    Note that this uses the ``eval`` function of the interpreter, and
    therefore trusts the contents of ``aJSONString`` to be safe.
    This is acceptable when the JSON and JavaScript application
    originate from the same server, but in other scenarios it may not be the
    appropriate security model. Currently, a validating JSON parser is beyond
    the scope of MochiKit, but there is one available from json.org [1]_.


:mochidef:`filter(fn, lst)`:

    Returns a new ``Array`` composed of all elements from ``lst`` where
    ``fn(lst[i])`` returns a true value.

    If ``fn`` is ``null``, ``operator.truth`` will be used.


:mochidef:`findValue(lst, value, start=0, end=lst.length)`:

    Finds the index of ``value`` in the ``Array``-like object ``lst`` using
    :mochiref:`compare`. The search starts at the index ``start``, and ends
    at the index ``end - 1``. If ``value`` is not found in ``lst``, it will
    return ``-1``.

    For example::
    
        assert( findValue([1, 2, 3, 2, 1], 2) == 1 )
        assert( findValue([1, 2, 3, 2, 1], 2, 2) == 3 )


:mochidef:`findIdentical(lst, value, start=0, end=lst.length)`:

    Finds the index of ``value`` in the ``Array``-like object ``lst`` using
    the ``===`` operator. The search starts at the index ``start``, and ends
    at the index ``end - 1``. If ``value`` is not found in ``lst``, it will
    return ``-1``.
    
    You should use this function instead of :mochiref:`findValue` if ``lst`` may
    be comprised of objects for which no comparator is defined and all you care
    about is finding an identical object (e.g. the same instance), or if
    ``lst`` is comprised of just numbers or strings and performance is
    important.

    For example::
    
        assert( findIdentical([1, 2, 3, 2, 1], 2) == 1 )
        assert( findIdentical([1, 2, 3, 2, 1], 2, 2) == 3 )


:mochidef:`flattenArguments(arg[, ...])`:

    Given a bunch of arguments, return a single ``Array`` containing all
    of those arguments. Any ``Array`` argument will be extended in-place,
    e.g.::

        compare(flattenArguments(1, [2, 3, [4, 5]]), [1, 2, 3, 4, 5]) == 0


:mochidef:`forwardCall(name)`:

    Returns a function that forwards a method call to ``this.name(...)``


:mochidef:`isArrayLike(obj[, ...])`:

    Returns ``true`` if all given arguments are ``Array``-like (have a
    ``.length`` property and ``typeof(obj) == 'object'``)


:mochidef:`isDateLike(obj[, ...])`:

    Returns ``true`` if all given arguments are ``Date``-like (have a 
    ``.getTime()`` method)


:mochidef:`isEmpty(obj[, ...])`:

    Returns ``true`` if all the given ``Array``-like or string arguments
    are empty ``(obj.length == 0)``


:mochidef:`isNotEmpty(obj[, ...])`:

    Returns ``true`` if all the given ``Array``-like or string arguments
    are not empty ``(obj.length > 0)``


:mochidef:`isNull(obj[, ...])`:

    Returns ``true`` if all arguments are ``null``.


:mochidef:`isUndefinedOrNull(obj[, ...])`:

    Returns ``true`` if all arguments are undefined or ``null``


:mochidef:`itemgetter(name)`:

    Returns a ``function(obj)`` that returns ``obj[name]``


:mochidef:`items(obj)`:

    Return an ``Array`` of ``[propertyName, propertyValue]`` pairs for the
    given ``obj`` (in the order determined by ``for propName in obj``).


:mochidef:`keyComparator(key[, ...])`:

    A comparator factory that compares ``a[key]`` with ``b[key]``.
    e.g.::

        var lst = ["a", "bbb", "cc"];
        lst.sort(keyComparator("length"));
        assert( lst.toString() == "a,cc,bbb" );


:mochidef:`keys(obj)`:

    Return an ``Array`` of the property names of an object
    (in the order determined by ``for propName in obj``).


:mochidef:`listMax(lst)`:

    Return the largest element of an ``Array``-like object, as determined
    by :mochiref:`compare`. This is a special form of :mochiref:`listMinMax`,
    specifically :mochiref:`partial(listMinMax, 1)`.


:mochidef:`listMin(lst)`:

    Return the smallest element of an ``Array``-like object, as determined
    by :mochiref:`compare`. This is a special form of :mochiref:`listMinMax`,
    specifically :mochiref:`partial(listMinMax, -1)`.


:mochidef:`listMinMax(which, lst)`:

    If ``which == -1`` then it will return the smallest
    element of the ``Array``-like ``lst``. This is also available
    as :mochiref:`listMin(lst)`.

    If ``which == 1`` then it will return the largest
    element of the ``Array``-like ``lst``. This is also available
    as :mochiref:`listMax(list)`.


:mochidef:`map(fn, lst[, ...])`:

    Return a new array composed of the results of ``fn(x)`` for every ``x``
    in ``lst``.

    If ``fn`` is ``null``, and only one sequence argument is given the
    identity function is used.
    
        :mochiref:`map(null, lst)` -> ``lst.slice()``;

    If ``fn`` is ``null``, and more than one sequence is given as arguments,
    then the ``Array`` function is used, making it equivalent to
    :mochiref:`zip`.

        :mochiref:`map(null, p, q, ...)`
            -> :mochiref:`zip(p, q, ...)`
            -> ``[[p0, q0, ...], [p1, q1, ...], ...];``


:mochidef:`merge(obj[, ...])`:

    Create a new instance of ``Object`` that contains every property
    from all given objects. If a property is defined on more than
    one of the objects, the last property is used.

    This is a special form of :mochiref:`update(self, obj[, ...])`,
    specifically, it is defined as :mochiref:`partial(update, null)`.


:mochidef:`method(self, func, ...)`:

    Alternate form of :mochiref:`bind` that takes the object before the
    function. These two calls are equivalent::

        bind("method", myobject)
        method(myobject, "method")


:mochidef:`nameFunctions(namespace)`:

    Given a ``namespace`` (object or function) with a ``NAME`` property,
    find all methods in it and give them nice ``NAME`` properties too
    (for use with :mochiref:`repr`). e.g.::

        namespace = {
            NAME: "Awesome",
            Dude: function () {}
        }
        nameFunctions(namespace);
        assert( namespace.Dude.NAME == 'Awesome.Dude' );


:mochidef:`objEqual(a, b)`:

    Return ``true`` if ``compare(a, b) == 0``
    

:mochidef:`nodeWalk(node, visitor)`:

    Non-recursive generic node walking function (e.g. for a DOM).

    The walk order for nodeWalk is breadth first, meaning that all
    siblings will be visited before any children.

    ``node``:
        The initial node to be searched.

    ``visitor``:
        The visitor function, will be called as
        ``visitor(node)``, and should return an ``Array``-like
        of nodes to be searched next (e.g. ``node.childNodes``).
        Leaf nodes may return ``null`` or ``undefined``.


:mochidef:`objMax(obj[, ...])`:

    Return the maximum object according to :mochiref:`compare` out
    of the given arguments. This is similar to :mochiref:`listMax`,
    except is uses the arguments instead of a given ``Array``-like.
        

:mochidef:`objMin(obj[, ...])`:

    Return the minimum object according to :mochiref:`compare`
    out of the given arguments. This is similar to
    :mochiref:`listMin`, except it uses the arguments instead of a
    given ``Array``-like.


:mochidef:`operator`:

    A table of JavaScript's operators for usage with :mochiref:`map`,
    :mochiref:`filter`, etc.


    Unary Logic Operators:

        +--------------------+--------------------------+-------------------+
        | Operator           | Implementation           | Description       |
        +====================+==========================+===================+
        | ``truth(a)``       | ``!!a``                  | Logical truth     |
        +--------------------+--------------------------+-------------------+
        | ``lognot(a)``      | ``!a``                   | Logical not       |
        +--------------------+--------------------------+-------------------+