============================================================================= Zeta ============================================================================= ----------------------------------------------------------------------------- Functional tools for JavaScript ----------------------------------------------------------------------------- :Author: Roman Neuhauser :Contact: neuhauser@sigpipe.cz :Copyright: This document is in the public domain. .. contents:: Introduction ============ Zeta is an `open-source`_ functional JavaScript library. It comprises a set of algorithms, operators, and higher-order functions (functions which return and/or accept functions as arguments). A programming language in which functions are values like JavaScript is actually a metaprogramming language. Exploiting this feature and treating code as data enables major reductions in code volume and complexity. Zeta is published under the `MIT license`_ which means you are free and welcome to use it in any way. .. _STL: http://www.sgi.com/tech/stl/ .. _open-source: http://opensource.org/docs/definition.php .. _MIT license: http://opensource.org/licenses/mit-license.php Use === The library is distributed as a single file, ``zeta.js``. This file contains a single function :: $$IMPORT_ZETA_INTO$$($$IMPORT_SCOPE$$) which creates the library proper. The function takes an object, the scope into which Zeta is to be imported. ``$$IMPORT_ZETA_INTO$$`` protects Zeta from other code and vice versa as much as possible, and gives you the freedom to import the library into any scope. To import Zeta into the current scope: :: $$IMPORT_ZETA_INTO$$(this); When the above runs in the global scope in a browser, it is equivalent to :: $$IMPORT_ZETA_INTO$$(window); Wehn Zeta is injected into the global scope, its functions can be called by unadorned names. An example showing this (and the import mechanism) in the SpiderMonkey_ shell: :: % js js> load("zeta.js"); js> sum // not yet typein:2: ReferenceError: sum is not defined js> $$IMPORT_ZETA_INTO$$(this); js> sum(map(Number, ["10.2", "20.3", "30.5"])) 61 js> To put Zeta in a namespace: :: % js js> load("zeta.js"); js> $$IMPORT_ZETA_INTO$$(Z = {}); js> Z.sum(Z.map(Number, ["10.2", "20.3", "30.5"])); 61 js> sum // does not leak typein:4: ReferenceError: sum is not defined js> The above creates a global "namespace" ``Z`` and puts all Zeta functions in it. Namespacing may clutter the resulting code considerably and is not recommended, but may be the only way to get Zeta into legacy code, which is why this provision exists. Prerequisities ============== * JavaScript 1.5+ Zeta is developed and tested on FreeBSD 9 with SpiderMonkey_ 1.7, Firefox_ 3.5, and Arora_ 0.10. .. _SpiderMonkey: http://www.mozilla.org/js/spidermonkey/ .. _Firefox: http://www.firefox.org/ .. _Arora: http://www.arora-browser.org/ Downloads ========= Repository ++++++++++ The latest source can be checked out from the Mercurial_ repository_, which is also available for anonymous browsing_. .. _Mercurial: http://selenic.com/mercurial/ .. _repository: https://hg.sigpipe.cz/ .. _browsing: http://hg.sigpipe.cz/ Official tarballs +++++++++++++++++ Zeta source releases are distributed as bzip2ed tarballs created with either Tim Kientzle's bsdtar_ or GNU tar, Julian Seward's bzip2_ in all cases. Your operating system should include compatible extraction tools. All Zeta releases can be found in the `download directory`_. .. _bsdtar: http://people.freebsd.org/~kientzle/libarchive/ .. _bzip2: http://www.bzip.org/ .. _download directory: http://codex.sigpipe.cz/zeta/dist/ Build and Installation ====================== Build +++++ The build mechanism requires a subset of the POSIX shell environment with a few commmon extensions, and works at least on FreeBSD, GNU/Linux and Cygwin. The build product is of course completely system-agnostic. Zeta source code is distributed among several files (all in the `src`_ directory). You can use individual files (but note that `base.js`_ is needed by all other files), or create a single file (``zeta.js``) containing all of Zeta by running ``make`` in the top directory. Repository checkouts require Docutils_ to build HTML documentation. .. _Docutils: http://docutils.sourceforge.net/ .. _base.js: src/base.js Install +++++++ Just copy ``zeta.js`` into a convenient location. Web servers (and even more so *non-web* uses of JavaScript/ECMA-262) are an area too volatile to warrant a vendor-provided installation mechanism. This task is left as an excercise for the user's software configuration management process. Zeta can (and should) be seen as a static library, and this position is therefore fully justified. Test suite ========== Zeta's test suite can be exercised by running ``make check`` in the top directory, or by loading `tests/browser.html`_ in one of supported browsers. .. _tests/browser.html: tests/browser.html Runtime overhead ================ You can either run ``make time`` on the command line, or access `tests/time.html`_ in a browser. Beware, the results cannot be taken literally! As a prominent example, ``bind`` has trivial overhead which is nice but quite uninteresting, much more important is the overhead of the functions ``bind`` returns, and this tool measures the former. However, Zeta is mostly implemented using Zeta, so ``bind``'s "real" overhead shows up in other functions' results. My results suggest that arora-0.10.2 (webkit-532.4) is about 7x as fast as Firefox-3.5.5, and that is several times as fast as SpiderMonkey-1.7 (Firefox-3.0). .. _tests/time.html: tests/time.html Reference ========= `Zeta Library Reference`_ describes public functions. The complete source code can be found in the `src`_ directory. .. _Zeta Library Reference: docs/reference.rest .. _src: src/ Examples ======== See `Zeta Usage Examples`_. .. _`Zeta Usage Examples`: docs/examples.rest Releases ======== Release types +++++++++++++ Zeta releases fall into one of the following four categories: * snapshots * bugfix releases * new functionality * backward-incompatible change Release versioning ++++++++++++++++++ Each release is tagged with a version number string with the following structure (ABNF_): :: version-string = compat-cnt "." newfun-cnt "." bugfix-cnt [rel-candidate] compat-cnt = counter newfun-cnt = counter bugfix-cnt = counter rel-candidate = "." snapshot counter ; "snap" snapshot = %x73.6e.61.70 ; counter is a positive integer (includes 0) counter = 1 * DIGIT For each release of any type the appropriate counter is incremented by at least one and counters to the right of it are reset to 0 (the release-candidate part is removed altogether), while counters to the left of it are left at their current values. Version string of the first nonsnapshot Zeta release is ``0.0.0``, while "0.0.0.snap135" is the version string of a pre-0.0.0 snapshot. Note that there may be gaps between. This handling is consistent with the way FreeBSD's `pkg_version -t`_ interprets version strings. .. _ABNF: http://tools.ietf.org/html/rfc4234 .. _pkg_version -t: http://www.freebsd.org/cgi/man.cgi?query=pkg_version .. target-notes:: .. section-numbering:: .. vim: ft=rst sts=2 sw=2 tw=80