sproutit-narwhal 0.1.106

data/docs/download.md

@@ -0,0 +1,25 @@
+
+Narwhal Downloads
+=================
+
+Download a version of Narwhal then follow the [quick start guide](http://narwhaljs.org/quick-start.html) to get running!
+
+Bleeding Edge
+-------------
+
+* [Download zip](http://github.com/tlrobinson/narwhal/zipball/master)
+* [Download tar](http://github.com/tlrobinson/narwhal/tarball/master)
+
+* Git: `git clone git://github.com/tlrobinson/narwhal.git`
+
+* [View tree](http://github.com/tlrobinson/narwhal/tree/master)
+* [View commit](http://github.com/tlrobinson/narwhal/commit/master)
+
+
+Releases
+--------
+
+<div id="releases-list">Loading...</div>
+<script type="text/javascript" charset="utf-8" src="js/releases.js"></script>
+<script type="text/javascript" charset="utf-8" src="http://github.com/api/v2/json/repos/show/tlrobinson/narwhal/tags?callback=showreleases"></script>
+

data/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`.
+

data/docs/json-tool.md

@@ -0,0 +1,121 @@
+
+JSON Tool Recipes
+=================
+
+List the module search paths:
+
+        json -e require.paths -np
+
+List the package search prefixes:
+
+        json -e system.prefixes -np
+
+List the active engine names:
+
+        json -e system.engines -np
+
+List the prefix paths of every installed package:
+
+        json -e 'require("packages").order' -n -f directory -p
+
+Visit the home page of every contributor to every installed package.  "open" is
+on Mac OS X only, but you can use "gnome-open" or "xdg-open" on Linux, or
+"kde-open" on Kubuntu specifically:
+
+        json -e 'require("packages").order'
+            -n
+            -e _.contributors
+            -A                  # flatten the array
+            -w _.url            # if they've got one
+            -e _.url            # extract it from their Author object
+            -p
+        | sort | uniq | xargs open
+
+List the contributors to Narwhal with field selection:
+
+        json -i package.json -j -f contributors -Anp
+
+Use JSONPath to list the contributors:
+
+        json -i package.json -j -$ $.contributors -Anp
+
+Enquote all of the MP3s in your collection, line by line:
+
+        find . -name '*.mp3' | json -nJp
+
+        find . -name '*.mp3' -print0 | json -n0Jp
+
+Rename all of your MP3s so that URL encoded patterns are unescaped:
+
+        find .
+            -name '*.mp3'
+            -print0             # write null-terminated lines
+        | json
+            -n                  # line by line
+            -z0                 # both read and write null-terminated lines
+            -c                  # this forces an array to
+                                # be accumulated for reprint
+            -p                  # print in escaped form
+            -e 'unescape(_)' -p # reprint unescaped
+        | xargs
+            -0                  # read null-terminated lines
+            -n 2                # one command for each adjacent pair
+            mv
+
+Convert `/etc/passwd` to JSON:
+
+        json -i /etc/passwd -nd: -NTJp
+
+Convert `/etc/passwd` to JSON with Objects instead of Arrays:
+
+        cat /etc/passwd | json
+            -n
+            -d:
+            -F name,password,uid,gid,class,change,expire,gecos,home,shell
+            -x _.uid=+_.uid
+            -x _.gid=+_.gid
+            -f name,_
+            -N
+            -O
+            -TJp
+
+Create a JSON mapping from user name to UID and format it as CSV:
+
+        cat /etc/passwd | json -nd: -f 0,2 -D, -p
+
+Create a JSON mapping from user name to UID and write it out as a single line of JSON:
+
+        json -i /etc/passwd -nd: -f 0,2 -NOJp
+
+Grab the UID of the "root" user:
+
+        json -i /etc/passwd -nd: -f0,2 -N -O -f root -p
+
+Reverse engineer a package catalog from installed packages:
+
+        json
+            -e 'require("packages").order'
+            -n # line input mode
+            -e '[_.name || _.directory.dirname().basename(), JSON.decode(_.directory.resolve("package.json").read())'
+            -N # object input mode
+            -O
+            -v '{version:1,packages:_}'
+            -TJ
+            -p
+
+Use the JSON tool as a pointless pipe buffer:
+
+        json -np
+
+Print the number '1' thrice.
+
+        json -e 1 -ppp
+
+Find the largest number from 1 to 10:
+
+        $(which jot) $(which seq) 10 | json -njNe 'Math.max.apply(this, _)' -p
+
+Put all your eggs in one basket:
+
+        json -e 'require("narwhal")' -f LEFT,RIGHT -np
+

data/docs/lib/binary.wiki

@@ -0,0 +1,242 @@
+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 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.
+
+= Specification =
+
+The "binary" top-level module must export "Binary", "ByteArray" and "ByteString".
+
+
+== ByteString ==
+
+A ByteString is an immutable, fixed-width representation of a C unsigned char (byte) array.  ByteString supports the String API, and indexing returns a byte substring of length 1.
+
+=== Constructor ===
+
+; ByteString()
+: Construct an empty byte string.
+; ByteString(byteString)
+: Copies byteString.
+; ByteString(byteArray)
+: Use the contents of byteArray.
+; ByteString(arrayOfNumbers)
+: Use the numbers in arrayOfNumbers as the bytes.
+: If any element is outside the range 0...255, an exception (''TODO'') is thrown.
+; ByteString(string, charset)
+: Convert a string. The ByteString will contain string encoded with charset.
+
+=== Constructor methods ===
+
+; join(array, delimiter)
+: Like Array.prototype.join, but for Binarys. Returns a ByteString.
+
+=== Instance properties ===
+
+; length
+: The length in bytes. Immutable.
+
+=== Instance methods (in prototype) ===
+
+; toByteArray()
+: Returns a byte for byte copy in a ByteArray.
+; toByteArray(sourceCharset, targetCharset)
+: Returns a transcoded copy in a ByteArray.
+; toByteString()
+: Returns itself, since there's no need to copy an immutable ByteString.
+; toByteString(sourceCharset, targetCharset)
+: Returns a transcoded copy.
+; toArray()
+: Returns an array containing the bytes as numbers.
+; toArray(charset)
+: Returns an array containing the decoded Unicode code points.
+; toString()
+: Returns a debug representation like "[ByteString 10]", where 10 is the length of the Array. Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included.
+; decodeToString(charset)
+: Returns the decoded ByteArray as a string.
+; indexOf(byte)
+; indexOf(byte, start)
+; indexOf(byte, start, stop)
+: Returns the index of the first occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched.
+; lastIndexOf(byte)
+; lastIndexOf(byte, start)
+; lastIndexOf(byte, start, stop)
+: Returns the index of the last occurance of byte (a Number or a single element ByteString or ByteArray) or -1 if none was found. If start and/or stop are specified, only elements between the the indexes start and stop are searched.
+; charCodeAt(offset)
+; <u>get(offset)</u>
+: Return the byte at offset as a Number.
+; byteAt(offset) ByteString
+; charAt(offset) ByteString
+: Return the byte at offset as a ByteString.
+; split(delimiter, [options])
+: Split at delimiter, which can by a Number, a ByteString, a ByteArray or an Array of the prior (containing multiple delimiters, i.e., "split at any of these delimiters"). Delimiters can have arbitrary size.
+: Options is an optional object parameter with the following optional properties:
+* ''count'' - Maximum number of elements (ignoring delimiters) to return. The last returned element may contain delimiters.
+* ''includeDelimiter'' - Whether the delimiter should be included in the result.
+: Returns an array of ByteStrings.
+; slice()
+; slice(begin)
+; slice(begin, end)
+: See [https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice Array.prototype.slice]
+
+
+; substr(start)
+:
+; substr(start, length)
+:
+; substring(first)
+:
+; substring(first, last)
+
+; [] ByteString
+: the immutable [] operator returning ByteStrings
+; toSource()
+: which would return "ByteString([])" for a null byte string
+
+ByteString does not implement toUpperCase() or toLowerCase() since they are not meaningful without the context of a charset.
+
+== ByteArray ==
+
+A ByteArray is a mutable, flexible representation of a C unsigned char (byte) array.
+
+=== Constructor ===
+
+; ByteArray()
+: New, empty ByteArray.
+; ByteArray(length)
+: New ByteArray filled with length zero bytes.
+; ByteArray(byteArray)
+: Copy byteArray.
+; ByteArray(byteString)
+: Copy contents of byteString.
+; ByteArray(arrayOfBytes)
+: Use numbers in arrayOfBytes as contents.
+: Throws an exception if any element is outside the range 0...255 (''TODO'').
+; ByteArray(string, charset)
+: Create a ByteArray from a Javascript string, the result being encoded with charset.
+
+Unlike the Array, the ByteArray is not variadic so that its initial length constructor is not ambiguous with its copy constructor.
+
+All values within the length of the array are numbers stored as bytes that default to 0 if they have not been explicitly set.  Assigning beyond the bounds of a ByteArray implicitly grows the array, just like an Array.  Retrieving a value from an index that is out of the bounds of the Array, lower than 0 or at or beyond the length, the returned value is "undefined".  Assigning an index with a value that is larger than fits in a byte will be implicitly and silently masked against 0xFF.  Negative numbers will be bit extended to a byte in two's complement form and likewise masked.
+
+=== Instance properties ===
+
+; mutable length property
+: extending a byte array fills the new entries with 0.
+
+=== Instance methods (in prototype) ===
+
+; toArray()
+: n array of the byte values
+; toArray(charset)
+: an array of the code points, decoded
+; toString()
+: A string debug representation like "[ByteArray 10]". Alternative debug representations are valid too, as long as (1) this method will never fail, (2) the length is included.
+; decodeToString(charset)
+: returns a String from its decoded bytes in a given charset.
+; toByteArray()
+: just a copy
+; toByteArray(sourceCharset, targetCharset)
+: transcoded
+; toByteString()
+: byte for byte copy
+; toByteString(sourceCharset, targetCharset)
+: transcoded
+; <u>byteAt(offset) ByteString</u>
+: Return the byte at offset as a ByteString.
+; <u>get(offset) Number</u>
+: Return the byte at offset as a Number.
+; concat(other:ByteArray|ByteString|Array)
+; pop() byte:Number
+:
+; push(...variadic Numbers...) -> count(Number)
+:
+; <u>extendRight(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u>
+: 
+; shift() byte:Number
+:
+; unshift(...variadic Numbers...) count:Number
+:
+; <u>extendLeft(...variadic Numbers / Arrays / ByteArrays / ByteStrings ...)</u>
+: 
+; reverse() in place reversal
+:
+; slice()
+:
+; sort()
+:
+; splice()
+:
+; <u>indexOf()</u>
+:
+; <u>lastIndexOf()</u>
+:
+; <u>split()</u> 
+: Returns an array of ByteArrays instead of ByteStrings.
+; <u>filter()</u>
+:
+; <u>forEach()</u>
+:
+; <u>every()</u>
+:
+; <u>some()</u>
+:
+; <u>map()</u>
+:
+; <u>reduce()</u>
+:
+; <u>reduceRight()</u>
+:
+; <u>displace(begin, end, values/ByteStrings/ByteArrays/Arrays...) -> length</u>
+: begin/end are specified like for slice. Can be used like splice but does not return the removed elements.
+; toSource()
+: Returns a string like "ByteArray([])" for a null byte-array.
+; [] Number
+: The mutable [] operator for numbers
+
+== String ==
+
+The String prototype will be extended with the following members:
+
+; toByteArray(charset)
+: Converts a string to a ByteArray encoded in charset.
+; toByteString(charset)
+: Converts a string to a ByteString encoded in charset.
+; charCodes()
+: Returns an array of Unicode code points (as numbers).
+
+== Array ==
+
+The Array prototype will be extended with the following members:
+
+; toByteArray(charset)
+: Converts an array of Unicode code points to a ByteArray encoded in charset.
+; toByteString(charset)
+: Converts an array of Unicode code points to a ByteString encoded in charset.
+
+== General Requirements ==
+
+None of the specified prototypes or augmentations to existing prototypes are enumerable.
+
+<u>Any operation that requires encoding, decoding, or transcoding among charsets may throw an error if that charset is not supported by the implementation.  All implementations MUST support "us-ascii" and "utf-8".</u>
+
+Charset strings are as defined by IANA http://www.iana.org/assignments/character-sets.
+
+<u>Charsets are case insensitive.</u>
+
+= Tests =
+
+* [http://github.com/tlrobinson/narwhal/tree/master/tests/serverjs ServerJS tests] compatible with [http://github.com/tlrobinson/narwhal/tree/master/lib/test this test framework].
+
+= Relevant Discussions =
+
+* [http://groups.google.com/group/serverjs/browse_thread/thread/f8ad81201f7b121b ByteArray and ByteString proposal]
+* [http://groups.google.com/group/serverjs/browse_thread/thread/a8d3a91af37fd355 ByteArray: byteAt method]
+* [http://groups.google.com/group/serverjs/browse_thread/thread/45190ac89d7b422a Binary/B Extension Proposals and Implementation Notes]

data/docs/lib/file.wiki

@@ -0,0 +1,325 @@
+Proposal A, Draft 5 (in development)
+
+The "file" module supports the File System API, providing an interface for path, directory, file, link, file stat, and file stream manipulation.
+
+For the purpose of this documentation, "fs" is a variable name for any object that implements the File System API, including the exports of the "file" module, and objects returned by "fs.chroot(path)".
+
+
+=== Security ===
+
+Objects implementing the File System API, including the "file" module object, are capability bearing objects that carry and mediate authority to read and write to the underlying storage.  As such, the "file" module can return other objects that implement and attenuate the File System API for sandboxing.  Furthermore, streams returned by the file system object are implicitly attenuated to only give the receiver authority to manipulate the given file, without knowledge of the path on which it resides or access to references that would permit it to manipulate other parts of the file system.
+
+
+=== Interface ===
+
+The "file" module must export the following:
+
+==== Files ====
+
+; open(path String, mode|options)
+: returns a stream object that supports an appropriate interface for the given options and mode, which include reading, writing, updating, byte, character, unbuffered, buffered, and line buffered streams.  More details follow in the [#Stream] section of this document.
+* path
+* mode: "rwa+bxc", or
+* options
+** mode String
+** charset String
+** read Boolean
+** write Boolean
+** append Boolean
+** update Boolean
+** binary Boolean
+** exclusive Boolean
+** canonical Boolean
+; read(path String, [mode|options])
+: opens, reads, and closes a file, returning its content.
+; write(path String, content String|Binary, [mode|options])
+: opens, writes, flushes, and closes a file with the given content.  If the content is a ByteArray or ByteString, the binary mode is implied.
+; copy(source String, target String)
+: reads one file and writes another in byte mode.
+; move(from String, to String)
+:
+; remove(path String)
+:
+; rename(path String, name String)
+:
+; touch(path, [mtime Date])
+:
+
+==== Directories ====
+
+('''TODO''' Should the methods in this section use "mkdir" or "makeDir" style names? [http://groups.google.com/group/serverjs/browse_thread/thread/851fea66620bae13 discussion])
+
+; list(path String) Iterator
+: returns an iterator that yields the names of the entries in a directory.  Throws an error if the directory is inaccessible or does not exist.
+; mkdir(path String)
+: Create a single directory specified by ''path''. If the directory cannot be created for any reason an exception will be thrown. This includes if the parent directories of "path" are not present.
+:
+; mktree(path String)
+: '''TODO''' Decide upon the name of this function. "mkdirs" or "mktree" or "makeTree"
+: Will create the directory specified by "path" including any missing parent directories.
+:
+; rmdir(path String) 
+: Removes a directory if it is empty. If it is not, or cannot be removed for another reason an exception will be thrown.
+:
+; rmtree(path String)
+:
+: This does its best to remove the directory "path", akin to "rm -r" on Unix or "del /s" on Windows. That is it will recursively delete all directories and files under "path".
+
+==== Links ====
+
+==== Paths ====
+
+; [new] Path(path String|Path|Array, [fs FileSystem]) Path
+: returns a Path object that closes on a File System object and a "path" representation.  The path object is a chainable shorthand for working with paths in the context of the "file" module.  "Path" objects have no more or less authority to manipulate the file system than the FileSystem object that they are attached to, as any path string is reachable by chaining operations on a path instance.  The FileSystem object defaults to the "file" module if the argument is omitted or undefined.  More details follow in the [#Path Path] section of this document.
+; path(path String|Path, fs FileSystem) Path
+: "fs.path(path)" is a shorthand for "new fs.Path(path, fs)".
+
+===== Working Path =====
+
+The current working directory is used by all routines that resolve relative paths to absolute file system paths, including "open", and "absolute".
+
+; cwd() String
+: returns the current working directory.
+; chdir(path String)
+: changes the current working directory.
+
+===== Traditional =====
+
+; join(...)
+: takes a variadic list of path Strings, joins them on the file system's path separator, and normalizes the result.
+; split(path String) Array
+: returns an array of path components.  If the path is absolute, the first component will be an indicator of the root of the file system; for file systems with drives (such as Windows), this is the drive identifier with a colon, like "c:"; on Unix, this is an empty string "".  The intent is that calling "join.apply" with the result of "split" as arguments will reconstruct the path.
+; normal(path String) 
+: removes '.' path components and simplifies '..' paths, if possible, for a given path.
+; absolute(path String)
+: returns the absolute path, starting with the root of this file system object, for the given path, resolved from the current working directory.  If the file system supports home directory aliases, absolute resolves those from the root of the file system.  The resulting path is in normal form.  On most systems, this is equivalent to expanding any user directory alias, joining the path to the current working directory, and normalizing the result.  "absolute" can be implemented in terms of "cwd", "join", and "normal".
+; canonical(path String)
+: returns the canonical path to a given abstract path.  Canonical paths are both absolute and intrinsic, such that all paths that refer to a given file (whether it exists or not) have the same corresponding canonical path.  This function must not communicate information about the true parent directories of files in chroot environments.  This function is equivalent to expanding a user directory alias, joining the given path to the current working directory, joining all symbolic links along the path, and normalizing the result.  "canonical" can be implemented in terms of "cwd", "join", "normal" and "readlink".
+; dirname(path String) String
+: returns the path of a file's containing directory, albeit the parent directory if the file is a directory.  A terminal directory separator is ignored.
+; basename(path String, [extension String]) String
+: returns the part of the path that is after the last directory separator.  If an extension is provided and is equal to the file's extension, the extension is removed from the result.
+; extension(path String) String
+: returns the extension of a file.  The extension of a file is the last dot (excluding any number of initial dots) followed by one or more non-dot characters. Returns an empty string if no valid extension exists.  [http://github.com/kriskowal/narwhal-test/blob/master/src/test/file/extension.js unit test].
+
+===== URL-like =====
+
+; resolve(...)
+: a function like "join" except that it treats each argument as as either an absolute or relative path and, as is the convention with URL's, treats everything up to the final directory separator as a location, and everything afterward as an entry in that directory, even if the entry refers to a directory in the underlying storage.  Resolve starts at the location "" and walks to the locations referenced by each path, and returns the path of the last file.  Thus, resolve(file, "") idempotently refers to the location containing a file or directory entry, and resolve(file, neighbor) always gives the path of a file in the same directory.  "resolve" is useful for finding paths in the "neighborhood" of a given file, while gracefully accepting both absolute and relative paths at each stage. [http://github.com/kriskowal/narwhal-test/blob/master/src/test/file/resolve.js unit test].
+; relative(from, to)
+: returns the relative path from one path to another using only ".." to traverse up to the two paths' common ancestor.
+
+==== Tests ====
+
+; exists(path)
+:whether a file exists at a given path: receives a path and returns whether that path, joined on the current working directory, corresponds to a file that exists.  If the file is a broken symbolic link, returns false.
+; isFile(path)
+:returns whether a path exists and that it corresponds to a file.
+; isDirectory(path)
+:returns whether a path exists and that it corresponds to a directory.
+; isLink(path)
+:returns whether a path exists and that it corresponds to a symbolic link (TODO or shortcut?).
+; isReadable(path)
+:returns whether a path exists, that it corresponds to a file, and that it can be opened for reading by "fs.open".
+; isWritable(path)
+:If a path exists, returns whether a file may be opened for writing, or entries added or removed from an  existing directory.  If the path does not exist, returns whether entries for files, directories, or links can be created at its location.
+
+==== Metadata ====
+
+; stat(path String)
+:Returns an object that contains the file's metadata, including all of the following that are applicable in the target platform's file system
+;; device Number
+:device number of the file system
+;; inode Number
+:virtual node number
+;; mode Number
+:type and permissions, numeric
+;; linkCount Number
+:number of hard links to the file
+;; uid Number
+:numeric id of the owner user
+;; rdev Number
+:the device identifier for special files
+;; size Number
+:total size in bytes
+;; blockSize Number
+:preferred block size for file system IO, in bytes
+;; blockCount Number
+:number of blocks allocated
+;; mtime Date
+:time of last modification (write)
+;; atime Date
+:time of last access (read, write, update)
+;; ctime Date
+:(TODO created vs. stat changed.  is /.time/ really the best pattern for expressing these times?)
+;; xattrs
+:extended attributes (reserved)
+;; acls
+:access control lists (reserved)
+
+; size(path String)
+:Number
+; mtime(path String)
+:Date
+; atime(path String)
+:Date
+; ctime(path String)
+:Date
+; same(pathA String, pathB String) Boolean
+:whether the two files are identical, in that they come from the same file system, same device, and have the same node and corresponding storage, such that modifying one would implicitly and atomically modify the other.
+
+==== Security ====
+
+; chroot(path String)
+: returns an object that conforms to the File System API, like the "file" module or the "system.fs" variable, that can be safely passed into a sandbox as the "file" module and "system.fs" objects.
+
+
+== Path ==
+
+; [new] Path(path String|Path|Array, [fs FileSystem]) Path
+:
+
+The prototype for the Path constructor is a String object.
+
+The path constructor accepts as its first argument either a String, Path, or Array.  If the path is an Array (as tested by Array.isArray, not merely typeof path == "array"), it must conform to the specification for values returned by "fs.split".
+
+Every path object has the members "normal", "absolute", "canonical", "dirname", "basename", "join", and "resolve".  All of these return new Path objects constructed by converting the path to a string, passing it through the likewise named method of "fs", and converting it back to a Path.  Thus, all of these methods are chainable.  In addition, "join" and "resolve" are variadic, so additional paths can be passed as arguments in either String, Path, or Array form.
+
+Every path object has "chroot", "copy", "exists", "extension", "isDirectory", "isFile", "isLink", "isReadable", "isWritable", "mkdir", "mkdirs", "move", "mtime", "open", "read", "remove", "rename", "rmdir", "rmtree", "same", "size", "split", "stat", "touch", and "write".  All of these functions convert themselves to strings and pass the results through the likewise named method of "fs".
+
+In addition, paths implement:
+
+; toString()
+:
+; to(path)
+: uses "fs.relative" to return a Path from this path to another one.
+; from(path)
+: uses "fs.relative" to return a Path to this path from another one.
+; list()
+: returns an iterator of Path objects for the contained directory entries.
+
+(TODO resolve whether it's more proper to make "Path" foundational and eliminate "fs".  Wrapping the "Path" object around a central "fs" object will be necessary for "chroot" whether we expose that level of the API or not, and having routines that work with strings on one architectural layer and paths on the next up gives the programmer an oppoertunity to program at the level that makes sense for their task.  It also, however, gives the programmer more to learn.)
+
+
+== Streams ==
+
+The "open" function mediates the construction of various kinds of streams.  As "open" is the only method with the authority to manipulate files, it constructs these types on behalf of a potentially unpriviledged caller.  Stream constructors are not directly callable in a secure sandbox, so where and how these stream types are implemented is beyond the necessary scope of this specification.  The "open" function always creates a byte level stream, and by default wraps that in a textual IO wrapper.
+
+* create a "raw" byte stream.  If "x" mode (with either "w" or "a" mode), only open if the file does not already exist.  Create the file and open the stream atomically.
+** if "r" mode, make "raw" a ByteReader
+** if "w" mode, make "raw" a ByteWriter
+** if "u" mode, make "raw" a ByteUpdater
+* if "+", seek to end.
+* if not "b" mode, return "raw".
+* return a wrapper encoded/decoded string stream around "raw" with specified buffering, line buffering, and charset.
+** if "r" mode, wrap "raw" in a TextReader
+** if "w" mode, wrap "raw" in a TextWriter
+** if "u" mode, wrap "raw" in a TextUpdater
+
+; ByteReader
+: appropriate for reading binary opaque struct records or other binary data or protocols
+; ByteWriter
+: appropriate for writing binary opaque struct records or other binary data or protocols
+; ByteUpdater
+: appropriate for a database
+; ByteReaderWriter
+: appropriate for sockets
+; TextReader
+: appropriate for standard input
+; TextWriter
+: appropriate for standard output
+; TextUpdater
+:
+; TextReaderWriter
+: appropriate for a TTY
+
+(TODO: resolve whether it is necessary for all stream types to have a common prototype, or whether it makes sense for them to be arranged in a class hierarchy.)
+
+=== *Reader, *Updater ===
+
+TextReader, ByteReader, TextUpdater, ByteUpdater, TextReaderWriter, and ByteReaderWriter have the following properties and methods:
+
+; read() *String
+: reads and returns all of the file until EOF is encountered.  Return ByteStrings for Byte* types, and Strings for Text* types.
+; read(max Number) *String
+:
+; readInto(buffer *Array, [begin Number], [end Number]) Number
+:
+; canRead() Boolean
+:
+; skip(n Number) Number
+:
+
+=== *Writer, *Updater ===
+
+TextWriter, ByteWriter, TextUpdater, ByteUpdater, TextReaderWriter, and ByteReaderWriter have the following properties and methods:
+
+; canWrite() Boolean
+:
+; flush()
+:
+
+=== ByteUpdater ===
+
+; tell() Number
+:
+; seek(position Number, whence Number)
+:
+; truncate([length Number=0])
+:
+; rewind()
+: a shortcut for seek(0)
+
+=== Text* ===
+
+TextReader, TextWriter, TextUpdater, and TextReaderWriter have the following properties and methods:
+
+; raw Byte*
+: the underlying byte stream, ByteReader for TextReaders, ByteWriter for TextWriters, and so on.
+
+=== TextReader ===
+
+; readLine() String
+: reads a line from the reader.  If EOF is encountered before any data is gathered, returns "".  Otherwise, returns the line including the "newLine".
+; readLines() Array*String
+: returns an Array of Strings accumulated by calling readLine until an empty string turns up.  Does not include the final empty string, and does include "newLine" at the end of every line.
+; next() String or throws StopIteration
+: returns the next line of input without its "newLine".  Throws StopIteration if EOF is encountered.
+; iterator() Iterator
+: returns the reader itself
+
+=== TextWriter ===
+
+; writeLine(line String)
+:
+; print(...)
+: writes a "delimiter" delimited array of Strings terminated with a "newLine"
+
+=== TextUpdater ===
+
+; tell() OpaqueCookie
+:
+; seek(position OpaqueCookie)
+:
+; truncate([position OpaqueCookie)
+:
+; rewind()
+: seeks to the beginning of the file.
+
+
+== Notes ==
+
+* Path separators, and other file-system-specific constants are not included in this specification.
+
+= Todo =
+
+* <s>random access IO</s>
+* locks
+* <s>canonical IO (non-blocking)</s>
+* comprehensive stat <s>access</s> and modification
+* temporary files and directories
+* symbolic links
+* more open options: permissions, owner, groupOwner
+* copy with metadata
+* glob
+* other [https://wiki.mozilla.org/ServerJS/API/file/Names proposed names].