sproutit-narwhal 0.1.106

data/docs/packages-howto.md

@@ -0,0 +1,32 @@
+
+How to make Packages
+====================
+
+A package consists of a directory of modules conforming to the ServerJS [Securable Modules](https://wiki.mozilla.org/ServerJS/Modules/SecurableModules) specification, and a "package.json" file in the root of the package containing the location of the modules, depedencies, and other metadata.
+
+A package directory might have the following files and directories:
+
+* `package.json` for package metadata like dependencies and overrides for the conventional directory names.
+* `local.json` for overrides on `package.json` provided by the user.
+* `bin` for executables.
+* `lib` for all object code, including JavaScript modules, and C extensions.
+* `src` for all buildable source code, including C and Java source code.
+* `jars` for Java class trees and archives.
+* `packages/{name}` for installed sub-packages.
+* `engines/{engine}` for engine-specific packages.
+
+`package.json` and `local.json` may contain the following attributes:
+
+* `name` - the name of the package.  The package system will only load one package with a given name.  The name defaults to the name of the parent directory.
+* `author` - the original author of the package.  The author may be a String including an optional `(` URL in parentheses `)` and optional `<` email address in angle brackets `>`.  Alternately, it may be an Object with any of `name`, `email`, and `url` attributes.  The package reader normalizes authors to the latter Object form.
+* `maintainer` - the package maintainer for the project as a String or Object just as the author attribute.
+* `contributors` - may be an Array of additional author Strings.
+* `url` - the URL of the project website.
+* `license` - the name of the license as a String, with an optional URL in parentheses, or an Object with `name` and `url` attributes.
+* `description` - a String describing the package.  Most package descriptions end with a period/full stop.
+* `keywords` - an Array of String keywords to assist users searching for the package with `tusk search` or `tusk apropos`.
+* `lib` - a path or array of paths to top-level module directories provided in this package.  Defaults to `["lib"]`.
+* `jars` - for Rhino engines, a path or array of paths to directories to add to the Java CLASSPATH (uses a Java URLClassLoader, so accepts `.jar` paths and directory paths ending with `/`).
+* `packages` - a path or array of paths to directories containing additional packages, defaults to `["packages"]`.
+* `engines` - a path or array of paths to directories containing engine-specific packages, defaults to `["engines"]`.  These engine packages will be loaded if and in the prioritized order they appear in the `system.engines` array, and with higher priority that those in this package's generic `js` path so that they can override engine-specific modules.
+

data/docs/packages.md

@@ -0,0 +1,30 @@
+
+Available Packages
+==================
+
+You can download and install packages using the `tusk` application that comes with Narwhal.  Check out `tusk help` for details.  These are some of the packages:
+
+* `jack`: the webserver and web application/framework agnostic interface, similar to Ruby's Rack and Python's WSGI. Narwhal was conceived while building Jack, and was later extracted into it's own project.
+
+[http://github.com/tlrobinson/jack](http://github.com/tlrobinson/jack)
+
+* `chiron`: a system of interoperable JavaScript modules, including a type system, base types, general-purpose functions, events, encoding, decoding, hashing, and caching.
+
+[http://github.com/kriskowal/chiron](http://github.com/kriskowal/chiron)
+  
+* `nitro`: a web application framework built on top of Jack.
+
+[http://github.com/gmosx/nitro](http://github.com/gmosx/nitro)
+
+And others including:
+
+* Narcissus
+* Wiki Creole
+* Browser
+* Inspec
+* Kupo
+* Bespin Server Prototype
+* Bespin PubSub
+* Nitro Templates
+* Google App Engine Utilities
+

data/docs/posts/2009-07-29-hello-0.1.md

@@ -0,0 +1,19 @@
+Hello 0.1
+=========
+
+Today we're announcing [Narwhal](http://narwhaljs.org/) 0.1 and [Jack](http://jackjs.org/) 0.1.
+
+### Download
+
+* Narwhal 0.1: [tar](http://github.com/tlrobinson/narwhal/tarball/0.1), [zip](http://github.com/tlrobinson/narwhal/zipball/0.1)
+* Jack 0.1: [tar](http://github.com/tlrobinson/jack/tarball/0.1), [zip](http://github.com/tlrobinson/jack/zipball/0.1)
+
+Check out the [quick start guide](http://narwhaljs.org/quick-start.html) for instructions on getting up and running with Narwhal and Jack.
+
+### Release Notes
+
+* Complete [securable modules](https://wiki.mozilla.org/ServerJS/Modules/SecurableModules) implementation, in JavaScript, with hooks for native module loading.
+* Various modules, including `file`, `binary`, `os`, `system`, `args`, and many others.
+* The "tusk" package manager, currently using [Github](http://github.com/) as a package repository.
+* Full support for the Rhino interpreter, and partial support for numerous other [engines](http://narwhaljs.org/engines.html).
+* Full support for Mac OS X, Linux, and other Unixes. Preliminary support for Windows.

data/docs/quick-start.md

@@ -0,0 +1,69 @@
+
+Narwhal Quick Start
+===================
+
+Download Narwhal.
+
+* download and extract the [zip](http://github.com/tlrobinson/narwhal/zipball/master) or [tar](http://github.com/tlrobinson/narwhal/tarball/master) archive, or
+* `git clone git://github.com/tlrobinson/narwhal.git`
+
+Put Narwhal on your PATH environment variable.
+
+* `export PATH=$PATH:~/narwhal/bin`, or
+* `source narwhal/bin/activate`
+
+Run `narwhal` or `js` (they are equivalent).
+
+* `js narwhal/examples/hello`
+
+Look at the options for Narwhal.
+
+* `js --help`
+
+And for Tusk, the package manager and virtual environment tool.
+
+* `tusk help`
+
+
+My First Web Server
+===================
+
+Create a project "hello-web".
+
+    tusk init hello-web
+    cd hello-web
+
+Enter your project as a "virtual environment" using `activate` or `sea` so that its libraries, binaries, and packages get automatically installed when you run Narwhal.
+
+    source bin/activate
+
+or
+
+    bin/sea
+
+Install some packages you will need, like Jack, the JSGI standard library for interoperable web services.
+
+    tusk install jack
+
+Tusk gets downloaded and installed at "hello-web/packages/jack".
+
+Create your "jackconfig.js". This is a trivial JSGI compatible application, wrapped in the `ContentLength` middleware to automatically set the "Content-Length" header.
+
+    exports.app = function(env) {
+        var text = "Hello, Web!";
+        return {
+            status : 200,
+            headers : { "Content-Type" : "text/plain", "Content-Length" : String(text.length) },
+            body : [text]
+        };
+    };
+
+Run it!
+
+    jackup
+
+`jackup` looks for a file called `jackconfig.js` in the current directory, or you can specify a path to a Jack application.
+
+Open [http://localhost:8080/](http://localhost:8080/) in your web browser.
+
+Next, take a look at the introduction to [modules](modules.html), for a primer on using and making modules in Narwhal.

data/docs/sea.md

@@ -0,0 +1,49 @@
+
+Narwhal, Tusk, and Sea
+======================
+
+Narwhal is your JavaScript interpreter.  It is executable with `narwhal` or `js`.  See `narwhal --help` for a list of its options.  It is comparable to your shell, Python or Ruby/IRB.
+
+Tusk is your package manager.  Tusk by default installs packages whereever `narwhal` is installed.  See `tusk help` for a list of options.  It is comparable to `apt` or `gem`.  You can also use `tusk` to create new "packages", application project scaffolds, or "virtual environments", which are all share a common structure.
+
+`sea` is a tool for entering a Narwhal "virtual environment".  It executes a command or reexecutes your shell inside a "virtual environment".  There is a version of `sea` that comes packed with "Narwhal", that you can use to "enter" your system `narwhal` environment, which is handy if `narwhal/bin` is not on your path.  You can also `source bin/activate`, as long as your version of bash supports the `${BASH_ARGV[0]}` notation, or if your current working directory contains `bin/activate`.
+
+You can use `narwhal`, `tusk`, and `sea` to create multiple, independent, reproducable Narwhal project installations.  Assuming that `narwhal` and `tusk` are on your path, you can use `tusk init` to create two application projects.
+
+    $ tusk init foo
+    $ tusk init bar
+    $ cd foo
+    foo$ bin/sea
+    PATH=foo/bin
+    SEALVL=1
+    foo$ tusk install jack
+    foo$ edit jackconfig.js
+    foo$ jackup
+    Loading configuration module at foo/jackconfig
+    Jack is starting up using Simple on port 8080
+    ^C
+    foo$ echo $SEA
+    foo
+    foo$ which sea
+    foo/bin/sea
+    foo$ exit
+    SEALVL=0
+    foo$ cd ../bar
+    bar$ bin/sea
+    PATH=bar/bin
+    SEALVL=1
+    ...
+
+When you are in a Sea, Narwhal loads all of the packages installed in that Sea and Tusk installs packages in your Sea.  While you can manipulate the NARWHAL_PATH and JS_PATH environment variables manually, Seas obviate the need.
+
+Each sea can also have a different JavaScript engine.  Edit `narwhal.conf` in your Sea to use a different engine.
+
+    $ js -e 'print(system.engine)'
+    rhino
+    $ cat bar/narwhal.conf
+    NARWHAL_DEFAULT_PLATFORM=v8
+    $ bar/bin/sea 'js -e "print(system.engine)"'
+    v8
+    PATH=/bin
+    SEALVL=0
+

data/engines/browser/lib/binary.js

@@ -0,0 +1,2 @@
+exports.ByteString = String;
+exports.ByteArray = Array;

data/engines/browser/lib/reactor.js

@@ -0,0 +1,21 @@
+
+var active = false;
+var pending = [];
+var run = function () {
+    var task = pending.shift();
+    if (0 === pending.length) {
+        active = false;
+    } else {
+        setTimeout(run, 0);
+    }
+    task();
+};
+
+exports.enqueue = function enqueue(task) {
+    pending.push(task);
+    if (!active) {
+        setTimeout(run, 0);
+        active = true;
+    }
+};
+

data/engines/browser/lib/system.js

@@ -0,0 +1,3 @@
+exports.print = function () {
+    system.print.apply(system, arguments);
+};

data/engines/default/lib/array.js

@@ -0,0 +1,164 @@
+// Array additions.
+
+// ES5 draft:
+// http://www.ecma-international.org/publications/files/drafts/tc39-2009-025.pdf
+
+// ES5 15.4.3.2 
+if (!Array.isArray) {
+    Array.isArray = function(obj) {
+        return Object.prototype.toString.call(obj) == "[object Array]";
+    };
+}
+
+// ES5 15.4.4.18
+if (!Array.prototype.forEach) {
+    Array.prototype.forEach =  function(block, thisObject) {
+        var len = this.length >>> 0;
+        for (var i = 0; i < len; i++) {
+            if (i in this) {
+                block.call(thisObject, this[i], i, this);
+            }
+        }
+    };
+}
+
+// ES5 15.4.4.19
+// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map
+if (!Array.prototype.map) {
+    Array.prototype.map = function(fun /*, thisp*/) {
+        var len = this.length >>> 0;
+        if (typeof fun != "function")
+          throw new TypeError();
+
+        var res = new Array(len);
+        var thisp = arguments[1];
+        for (var i = 0; i < len; i++) {
+            if (i in this)
+                res[i] = fun.call(thisp, this[i], i, this);
+        }
+
+        return res;
+    };
+}
+
+// filter
+if (!Array.prototype.filter) {
+    Array.prototype.filter = function (block /*, thisp */) {
+        var values = [];
+        var thisp = arguments[1];
+        for (var i = 0; i < this.length; i++)
+            if (block.call(thisp, this[i]))
+                values.push(this[i]);
+        return values;
+    };
+}
+
+// every
+if (!Array.prototype.every) {
+    Array.prototype.every = function (block /*, thisp */) {
+        var thisp = arguments[1];
+        for (var i = 0; i < this.length; i++)
+            if (!block.call(thisp, this[i]))
+                return false;
+        return true;
+    };
+}
+
+// some
+if (!Array.prototype.some) {
+    Array.prototype.some = function (block /*, thisp */) {
+        var thisp = arguments[1];
+        for (var i = 0; i < this.length; i++)
+            if (block.call(thisp, this[i]))
+                return true;
+        return false;
+    };
+}
+
+// reduce
+// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/reduce
+if (!Array.prototype.reduce) {
+    Array.prototype.reduce = function(fun /*, initial*/) {
+        var len = this.length >>> 0;
+        if (typeof fun != "function")
+            throw new TypeError();
+
+        // no value to return if no initial value and an empty array
+        if (len == 0 && arguments.length == 1)
+            throw new TypeError();
+
+        var i = 0;
+        if (arguments.length >= 2) {
+            var rv = arguments[1];
+        } else {
+            do {
+                if (i in this) {
+                    rv = this[i++];
+                    break;
+                }
+
+                // if array contains no values, no initial value to return
+                if (++i >= len)
+                    throw new TypeError();
+            } while (true);
+        }
+
+        for (; i < len; i++) {
+            if (i in this)
+                rv = fun.call(null, rv, this[i], i, this);
+        }
+
+        return rv;
+    };
+}
+
+// reduceRight
+// https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/reduceRight
+if (!Array.prototype.reduceRight) {
+    Array.prototype.reduceRight = function(fun /*, initial*/) {
+        var len = this.length >>> 0;
+        if (typeof fun != "function")
+            throw new TypeError();
+
+        // no value to return if no initial value, empty array
+        if (len == 0 && arguments.length == 1)
+            throw new TypeError();
+
+        var i = len - 1;
+        if (arguments.length >= 2) {
+            var rv = arguments[1];
+        } else {
+            do {
+                if (i in this) {
+                    rv = this[i--];
+                    break;
+                }
+
+                // if array contains no values, no initial value to return
+                if (--i < 0)
+                    throw new TypeError();
+            } while (true);
+        }
+
+        for (; i >= 0; i--) {
+            if (i in this)
+                rv = fun.call(null, rv, this[i], i, this);
+        }
+
+        return rv;
+    };
+}
+
+/* binary */
+
+// https://wiki.mozilla.org/ServerJS/Binary/B
+if (!Array.prototype.toByteString)
+    Array.prototype.toByteString = function(charset) {
+        return new require("binary").ByteString(this);
+    };
+
+if (!Array.prototype.toByteArray)
+    Array.prototype.toByteArray = function(charset) {
+        return new ByteArray(this);
+    };
+

data/engines/default/lib/binary-engine.js

@@ -0,0 +1,53 @@
+exports.B_LENGTH = function(bytes) {
+    return bytes.length;
+}
+
+exports.B_ALLOC = function(length) {
+    var bytes = new Array(length);
+    for (var i = 0; i < length; i++)
+        bytes[i] = 0;
+    return bytes;
+}
+
+exports.B_FILL = function(bytes, from, to, value) {
+    for (var i = from; i < to; i++)
+        bytes[i] = value;
+}
+
+exports.B_COPY = function(src, srcOffset, dst, dstOffset, length) {
+    for (var i = 0; i < length; i++)
+        dst[dstOffset+i] = src[srcOffset+i];
+}
+
+exports.B_GET = function(bytes, index) {
+    return bytes[index];
+}   
+
+exports.B_SET = function(bytes, index, value) {
+    return bytes[index] = value;
+}
+
+var DEFAULT_ENCODING = "UTF-8";
+
+exports.B_DECODE = function(bytes, offset, length, codec) {
+    var newBytes = exports.B_TRANSCODE(bytes, offset, length, codec, DEFAULT_ENCODING);
+    return exports.B_DECODE_DEFAULT(newBytes, 0, exports.B_LENGTH(newBytes));
+}
+
+exports.B_DECODE_DEFAULT = function(bytes, offset, length) {
+    throw "NYI";
+}
+
+exports.B_ENCODE = function(string, codec) {
+    var bytes = exports.B_ENCODE_DEFAULT(string);
+    return exports.B_TRANSCODE(bytes, 0, exports.B_LENGTH(bytes), DEFAULT_ENCODING, codec);
+}
+
+exports.B_ENCODE_DEFAULT = function(string) {
+    throw "NYI";
+}
+
+exports.B_TRANSCODE = function(bytes, offset, length, sourceCodec, targetCodec) {
+    throw "NYI";
+}
+