Deployed on 2009-09-03

Rakefile

@@ -14,6 +14,8 @@ exclude = {
   "lib/os/popen" => true
 }
 
+CHECKOUT_BRANCH = 'master'
+
 DEFAULT_LAYOUT_TEMPLATE = '_layouts/default-template.html'
 DEFAULT_LAYOUT = '_layouts/default.html'
 
@@ -22,10 +24,10 @@ task :default => [:build]
 task :all => [:checkout, :build, :runserver]
 
 task :checkout do
-  puts "Checking out 'docs' from master"
+  puts "Checking out 'docs' from #{CHECKOUT_BRANCH}"
   rm_rf 'docs', :verbose => false
-  `git checkout master docs`
-  `git checkout master README.md`
+  `git checkout #{CHECKOUT_BRANCH} docs`
+  `git checkout #{CHECKOUT_BRANCH} README.md`
   `mv README.md docs/index.md`
 end
 

_layouts/default.html

@@ -1,6 +1,10 @@
 ---
 github_url: "http://github.com/tlrobinson/narwhal"
 articles:
+- name: browser deployment
+  link: "/browser-deployment.html"
+- name: engines
+  link: "/engines.html"
 - name: introduction
   link: "/index.html"
 - name: lib / binary
@@ -9,6 +13,8 @@
   link: "/lib/file.html"
 - name: modules
   link: "/modules.html"
+- name: narwhal / json
+  link: "/narwhal/json.html"
 - name: narwhal
   link: "/narwhal.html"
 - name: packages howto

_posts/2009-07-29-hello-0.1.md

@@ -19,5 +19,5 @@ Check out the [quick start guide](http://narwhaljs.org/quick-start.html) for ins
 * 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 [platforms](http://narwhaljs.org/platforms.html).
+* 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.

docs/.gitignore

@@ -0,0 +1 @@
+*.html

docs/engines.md

@@ -0,0 +1,32 @@
+
+Engines
+=======
+
+Narwhal is a standard library and tools for multiple JavaScript engines; each engine has its own library.  Use `tusk engine {name}` to select an engine, or edit `narwhal.conf`.  The following engines are presently in development:
+
+* `rhino`: is the default and most complete engine, based on Mozilla Rhino for Java, used for out-of-the-box functionality.
+* `k7`: is a `v8` based engine, in development by Sébastien Pierre.
+* `helma`: is based on Rhino with extensions, being developed by Hannes Wallnöefer.
+* `xulrunner`: is in development for Firefox extensions and XULRunner applications on the Spidermonkey engine by Irakli Gozalishvili, Christoph Dorn, and Zach Carter.
+* `jaxer`: is an engine based on Mozilla SpiderMonkey, for deploying web pages with both server and client side scripts, being developed by Nathan L Smith.
+* `v8cgi`: is based on the work of Ondrej Zara, and has not been updated in a long while.
+* `default`: is a catchall engine that implements modules that can be shared among engines.
+* `browser`: will eventually be available for client side loading of modules with various techniques.
+* `secure`: will eventually be available for dependency injection sandboxed module systems within some other engines.
+
+
+Creating new Engine Adapters
+----------------------------
+
+We have a template for new engines at `engines/template` that you can copy to `engines/{name}` and fill in the blanks.  These consist of:
+
+1. An executable (shell script or binary) at `engines/{name}/bin/narwhal-{name}` that executes the interpreter engine of choice and causes it to load a bootstrap script.  This script will be loaded by `bin/narwhal` with the environment variable `NARWHAL_HOME` set to the Narwhal project directory and `NARWHAL_ENGINE_HOME` set to the engine directory.  This script will be run if `NARWHAL_ENGINE` is set to your engine name.  You can set `NARWHAL_DEFAULT_ENGINE` or `NARWHAL_ENGINE` in a `narwhal.conf` in your Narwhal project directory (template provided).
+
+2. A "thunk", at `engines/{name}/bootstrap.js` that evaluates `narwhal.js` and passes the returned function a preliminary `system` object with a few required properties (`global`, `evalGlobal`, `engine`, `engines`, `print`, `evaluate`, `prefix`, `fs.read`, and `fs.isFile`). This should be enough to get to an interactive console.
+
+3. Engine implementations for core modules, such as `file` and `system` located in `engines/{name}/lib/`.  You can implement `file-engine` instead of `file` if you implement the subset of the ServerJS file API used by `lib/file.js` (and similar for `io`, `os`, `binary`, etc). The next steps are:
+
+    * system: You must implement `system.args` to be able to pass command line options to Narwhal.
+
+    * file: To enable the package system you must implement `list`, `canonical`, `mtime`, `isDirectory`, `isFile`.
+

docs/index.md

@@ -4,9 +4,9 @@ Narwhal
 A general purpose JavaScript platform
 -------------------------------------
 
-Narwhal is a cross-platform, multi-interpreter, general purpose JavaScript platform. It aims to provide a solid foundation for building JavaScript applications, primarily outside the web browser. Narwhal includes a package manager, module system, and standard library for multiple JavaScript interpreters. Currently Narwhal's [Rhino](http://www.mozilla.org/rhino/) support is the most complete, but [other platforms](platforms.html) are available too.
+Narwhal is a cross-platform, multi-interpreter, general purpose JavaScript platform. It aims to provide a solid foundation for building JavaScript applications, primarily outside the web browser. Narwhal includes a package manager, module system, and standard library for multiple JavaScript interpreters. Currently Narwhal's [Rhino](http://www.mozilla.org/rhino/) support is the most complete, but [other engines](engines.html) are available too.
 
-Narwhal's standard library conforms to the [ServerJS standard](https://wiki.mozilla.org/ServerJS). It is designed to work with multiple JavaScript interpreters, and to be easy to add support for new interpreters. Wherever possible, it is implemented in pure JavaScript to maximize reuse of code among platforms.
+Narwhal's standard library conforms to the [ServerJS standard](https://wiki.mozilla.org/ServerJS). It is designed to work with multiple JavaScript interpreters, and to be easy to add support for new interpreters. Wherever possible, it is implemented in pure JavaScript to maximize reuse of code among engines.
 
 Combined with [Jack](http://jackjs.org/), a [Rack](http://rack.rubyforge.org/)-like [JSGI](http://jackjs.org/jsgi-spec.html) compatible library, Narwhal provides a platform for creating server-side JavaScript web applications and frameworks such as [Nitro](http://www.nitrojs.org/).
 
@@ -37,7 +37,7 @@ Documentation
 * [How to Build Packages](packages-howto.html)
 * [Modules](modules.html)
 * [Virtual Environments / Seas](sea.html)
-* [How to Build Platforms](platforms.html)
+* [How to Build Engines](engines.html)
 * [How Narwhal Works](narwhal.html)
 
 

docs/lib/binary.md

@@ -1,12 +1,12 @@
-All platforms must support two types for interacting with binary data: ByteArray and ByteString.  The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds.  The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1.  These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString.  (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.)
+All engines must support two types for interacting with binary data: ByteArray and ByteString.  The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds.  The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1.  These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString.  (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.)
 
 # Philosophy
 
 This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information.  The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data.  Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]).  This goes against most mentioned [[ServerJS/Binary|prior art]].
 
 This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array.  Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list).  This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation).
 
-This proposal also reflects both group sentiment and a pragmatic point about properties.  This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs.  However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified.  (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]).
+This proposal also reflects both group sentiment and a pragmatic point about properties.  This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs.  However, given that all engines support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified.  (See comments by Kris Zyp about the implementability of properties in all engines, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]).
 
 The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points.  This behavior may be specified further in the future.
 

docs/lib/binary.wiki

@@ -1,12 +1,12 @@
-All platforms must support two types for interacting with binary data: ByteArray and ByteString.  The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds.  The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1.  These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString.  (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.)
+All engines must support two types for interacting with binary data: ByteArray and ByteString.  The ByteArray type resembles the interface of Array in that it is mutable, extensible, and indexing will return number values for the byte in the given position, zero by default, or undefined if the index is out of bounds.  The ByteString type resembles the interface of String in that it is immutable and indexing returns a ByteString of length 1.  These types are exported by the 'binary' top-level module and both types are subtypes of Binary, which is not instantiable but exists only for the convenience of referring to both ByteArray and ByteString.  (The idea of using these particular two types and their respective names originated with Jason Orendorff in the [http://groups.google.com/group/serverjs/msg/89808c05d46b92d0 Binary API Brouhaha] discussion.)
 
 = Philosophy =
 
 This proposal is not an object oriented variation on pack and unpack with notions of inherent endianness, read/write head position, or intrinsic codec or charset information.  The objects described in this proposal are merely for the storage and direct manipulation of strings and arrays of byte data.  Some object oriented conveniences are made, but the exercise of implementing pack, unpack, or an object-oriented analog thereof are left as an exercise for a future proposal of a more abstract type or a 'struct' module (as mentioned by Ionut Gabriel Stan on [http://groups.google.com/group/serverjs/msg/592442ba98c6c70e the list]).  This goes against most mentioned [[ServerJS/Binary|prior art]].
 
 This proposal also does not provide named member functions for any particular subset of the possible charsets, codecs, compression algorithms, or consistent hash digests that might operate on a byte string or array.  Instead, convenience member functions are provided for interfacing with any named charset, with the IANA charset name space, and with the possibility of eventually employing a system of modular extensions for other codecs or digests, requiring that the given module exports a specified interface. (As supported originally by Robert Schultz, Davey Waterson, Ross Boucher, and tacitly myself, Kris Kowal, on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst First proposition] thread on the mailing list).  This proposal does not address the need for stream objects to support pipelined codecs and hash digests (mentioned by Tom Robinson and Robert Schultz in the same conversation).
 
-This proposal also reflects both group sentiment and a pragmatic point about properties.  This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs.  However, given that all platforms support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified.  (See comments by Kris Zyp about the implementability of properties in all platforms, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]).
+This proposal also reflects both group sentiment and a pragmatic point about properties.  This isn't a decree that properties like "length" should be consistently used throughout the ServerJS APIs.  However, given that all engines support properties at the native level (to host String and Array objects) and that byte strings and arrays will require support at the native level, pursuing client-side interoperability is beyond the scope of this proposal and therefore properties have been specified.  (See comments by Kris Zyp about the implementability of properties in all engines, comments by Davey Waterson from Aptana about the counter-productivity of attempting to support this API in browsers, and support properties over accessor and mutator functions by Ionut Gabriel Stand and Cameron McCormack on the [http://groups.google.com/group/serverjs/browse_thread/thread/be72ef3d8146731d/06c27162b698eef5?lnk=gst mailing list]).
 
 The byte types provide functions for encoding, decoding, and transcoding, but they are all shallow interfaces that defer to a charset manager module, and may in turn use a system level charset or use a pair of pure JavaScript modules to transcode through an array or stream of canonical Unicode code points.  This behavior may be specified further in the future.
 

docs/lib/file.md

@@ -200,7 +200,7 @@ numeric id of the owner user
 * rdev Number
 the device identifier for special files
 
-* size NUmber
+* size Number
 total size in bytes
 
 * blockSize Number

docs/lib/file.wiki

@@ -140,7 +140,7 @@ The current working directory is used by all routines that resolve relative path
 :numeric id of the owner user
 ;; rdev Number
 :the device identifier for special files
-;; size NUmber
+;; size Number
 :total size in bytes
 ;; blockSize Number
 :preferred block size for file system IO, in bytes