Add documentation

README.md

@@ -1,6 +1,6 @@
 # drv
 
-A Nix `.drv` file parser.
+A Nix `.drv` file parser. Can produce either an AST or a descriptive object, depending on usage.
 
 ## License
 
@@ -22,8 +22,175 @@ Be aware that by making a pull request, you agree to release your modifications
 
 ## Usage
 
-TODO
+A basic example of parsing a derivation into a descriptive object:
+
+```javascript
+'use strict';
+
+const Promise = require("bluebird");
+const fs = Promise.promisifyAll(require("fs"));
+const util = require("util");
+
+const drv = require("drv");
+
+Promise.try(() => {
+	return fs.readFileAsync("/nix/store/path/to/derivation.drv");
+}).then((contents) => {
+	let parsedContents = drv(contents.toString());
+
+	console.log(util.inspect(parsedContents, {colors: true, depth: null}));
+});
+```
+
+The default parsing method is to interpret the parsed data, in the same way that Nix would interpret it; each field in a derivation has a pre-defined meaning based on its position.
+
+The above code will therefore produce output that looks something like this:
+
+```javascript
+{ outputs:
+   [ { name: 'dev',
+       path: '/nix/store/lpwm4gcsda53g26jp6rxz4x13l8lywzg-libXdmcp-1.1.2-dev',
+       hashAlgorithm: '',
+       hash: '' },
+     /* ... snipped ... */
+     { name: 'out',
+       path: '/nix/store/3iq0cd1ll0c7hss8xxgalxqn0jm0b2mi-libXdmcp-1.1.2',
+       hashAlgorithm: '',
+       hash: '' } ],
+  inputDerivations:
+   [ { path: '/nix/store/3l3gnqvlwrmiqdma5vg3zibkabv4d6wh-pkg-config-0.29.drv',
+       inputDerivations: [ 'out' ] },
+     /* ... snipped ... */
+     { path: '/nix/store/w3qvvackybwaq6d2sw58yacsrbbrxa4b-xproto-7.0.29.drv',
+       inputDerivations: [ 'out' ] } ],
+  inputSources: [ '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ],
+  platform: 'x86_64-linux',
+  builder: '/nix/store/gabjbkwga2dhhp2wzyaxl83r8hjjfc37-bash-4.3-p48/bin/bash',
+  builderArguments:
+   [ '-e',
+     '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ],
+  environmentVariables:
+   [ { name: 'buildInputs', value: '' },
+     { name: 'builder',
+       value: '/nix/store/gabjbkwga2dhhp2wzyaxl83r8hjjfc37-bash-4.3-p48/bin/bash' },
+     /* ... snipped ... */
+     { name: 'src',
+       value: '/nix/store/djf171kmvws6891q2nzd2icdjd5bgj4r-libXdmcp-1.1.2.tar.bz2' },
+     { name: 'stdenv',
+       value: '/nix/store/985d95clq0216a6pcp3qzw4igp84ajvr-stdenv' },
+     { name: 'system', value: 'x86_64-linux' } ] }
+```
+
+Sometimes, you'll only be interested in the AST, eg. because you're writing a pretty-printer. In that case, you'll want to use the `drv.ast` method instead.
+
+For example:
+
+```javascript
+'use strict';
+
+const Promise = require("bluebird");
+const fs = Promise.promisifyAll(require("fs"));
+const util = require("util");
+
+const drv = require("drv");
+
+Promise.try(() => {
+	return fs.readFileAsync("/nix/store/path/to/derivation.drv");
+}).then((contents) => {
+	let parsedContents = drv.ast(contents.toString()); // Note that we're using `drv.ast` now, instead of just `drv`!
+
+	console.log(util.inspect(parsedContents, {colors: true, depth: null}));
+});
+```
+
+That will produce output like this:
+
+```javascript
+{ type: 'deriveTag',
+  items:
+   [ { type: 'array',
+       items:
+        [ { type: 'tuple',
+            items:
+             [ 'dev',
+               '/nix/store/lpwm4gcsda53g26jp6rxz4x13l8lywzg-libXdmcp-1.1.2-dev',
+               '',
+               '' ] },
+          /* ... snipped ... */
+          { type: 'tuple',
+            items:
+             [ 'out',
+               '/nix/store/3iq0cd1ll0c7hss8xxgalxqn0jm0b2mi-libXdmcp-1.1.2',
+               '',
+               '' ] } ] },
+     { type: 'array',
+       items:
+        [ { type: 'tuple',
+            items:
+             [ '/nix/store/3l3gnqvlwrmiqdma5vg3zibkabv4d6wh-pkg-config-0.29.drv',
+               { type: 'array', items: [ 'out' ] } ] },
+          /* ... snipped ... */
+          { type: 'tuple',
+            items:
+             [ '/nix/store/w3qvvackybwaq6d2sw58yacsrbbrxa4b-xproto-7.0.29.drv',
+               { type: 'array', items: [ 'out' ] } ] } ] },
+     { type: 'array',
+       items: [ '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ] },
+     'x86_64-linux',
+     '/nix/store/gabjbkwga2dhhp2wzyaxl83r8hjjfc37-bash-4.3-p48/bin/bash',
+     { type: 'array',
+       items:
+        [ '-e',
+          '/nix/store/zsi9kk33hj7kvjfw0zahpdsiggg58nn4-builder.sh' ] },
+     { type: 'array',
+       items:
+        [ { type: 'tuple', items: [ 'buildInputs', '' ] },
+          /* ... snipped ... */
+          { type: 'tuple',
+            items:
+             [ 'stdenv',
+               '/nix/store/985d95clq0216a6pcp3qzw4igp84ajvr-stdenv' ] },
+          { type: 'tuple', items: [ 'system', 'x86_64-linux' ] } ] } ] }
+```
 
 ## API
 
-TODO
+### drv(contents)
+
+Parses the specified `contents` and produces a descriptive object.
+
+* __contents:__ The derivation contents to parse. This must be a string; if you're reading from a file in Node.js, you'll want to `.toString()` it first.
+
+The descriptive object that's returned is structured as follows:
+
+* __outputs:__ *Array of objects.* An array of derivation outputs; these are the store objects that are built from the derivation. Each item in the array contains the following properties:
+  * __name:__ *String.* The name of the derivation output.
+  * __path:__ *String.* The store path of the derivation output.
+  * __expectedHashAlgorithm:__ *String, may be empty.* The hashing algorithm used for the expected hash.
+  * __expectedHash:__ *String, may be empty.* The hash that the output is expected to have; if not, it will be considered a build failure. The hash is stored as a hexadecimal string.
+* __inputDerivations:__ *Array of objects.* An array of input derivations; these are the derivations that are a dependency of this derivation. They must have completed building before this derivation can be built. Each item in the array contains the following properties:
+  * __path:__ The path of the input derivation, as a string. Note that this is a path to the __derivation__, and *not* to the derivation output!
+  * __wantedOutputs:__ *Array of strings.* The names of the outputs of the input derivation that are required as a dependency of this derivation. These refer to the items in the `outputs` section of the input derivation.
+* __inputSources:__ *Array of strings.* An array of input sources; these are objects in the store that are copied from elsewhere, and that do not have their own derivation. Typical examples of this include builder scripts and source tarballs. Each item is a string containing the store path.
+* __platform:__ *String.* Describes the platform this derivation is meant to be built against. The platform strings used here are the same as those used throughout Nix and `nixpkgs`.
+* __builder:__ *String.* The builder to use for building ("realizing") this derivation.
+* __builderArguments:__ *Array of strings.* The arguments to pass to the builder.
+* __environmentVariables__ *Array of objects.* An array of environment variables in key/value format. These are the environment variables that are set when the builder is executed. Each item in the array contains the following properties:
+  * __name:__ *String.* The name of the environment variable.
+  * __value:__ *String, may be empty.* The value of the environment variable. It may contain variable interpolations.
+
+### drv.ast(contents)
+
+Parses the specified `contents` and produces an AST (Abstract Syntax Tree).
+
+* __contents:__ The derivation contents to parse. This must be a string; if you're reading from a file in Node.js, you'll want to `.toString()` it first.
+
+Each AST node has the following properties:
+
+* __type:__ *String.* The type of node. Possible options are:
+  * __"deriveTag":__ The root `Derive` tag (eg. `Derive(contents)`).
+  * __"array":__ An array (eg. `[contents]`).
+  * __"tuple":__ A tuple (eg. `(contents)`).
+* __items:__ *Array.* An array of items contained within this node. Each item is either an AST node or a string literal.
+
+The root of the AST is always a `deriveTag`. String literals in the derivation are represented as string literals in the AST as well; all other syntactic constructs are represented as AST nodes.