Added docs, Changelog, Readme updates, version bump to v0.10.0

CHANGELOG.md

@@ -1,3 +1,10 @@
+# v0.10.0
+
+**BREAKING CHANGES**
+
+* Added tests to CommandGroup to ensure callbacks were getting called with the correct arguments, they weren't.
+* Added nesting CommandGroup test to ensure creation of trees was possible.
+
 # v0.9.0
 
 * Fixed help exiting - bad exitOnHelp default.

README.md

@@ -40,12 +40,10 @@ Quick Example:
 
 ```javascript
 var Cli = require('admiral-cli'),
-    CliCommand = require('admiral-cli').Command,
-    CliInvalidInputError = require('admiral-cli').InvalidInputError,
-    CliConfigError = require('admiral-cli').ConfigError;
 
 var cli = new Cli();
 cli
+    // Command Groups are for fixed options, like 'commit' and 'checkout' in git
     .commandGroup({
         name: 'cmd',
         description: 'Commands are single words, no - or --s, and are one of the following:',
@@ -67,6 +65,7 @@ cli
         },
         required: true
     })
+    // Flags are for true/false switches
     .flag({
         name: 'flagName',
         description: 'Flags are single phrases, set as a boolean',
@@ -79,6 +78,7 @@ cli
         shortFlag: '-n',
         longFlag: '--notPassed'
     })
+    // Options are two parts, a key and a user supplied value.
     .option({
         name: 'optName',
         description: 'Options are two parts, a key and a user supplied value',
@@ -95,10 +95,11 @@ try {
 }
 catch (error) {
     console.error(error);
-    if (error instanceof CliInvalidInputError) {
+    if (error instanceof Cli.InvalidInputError) {
+        // User input something wrong, will display help by default.
         process.exit(2);
     }
-    else if (error instanceof CliConfigError) {
+    else if (error instanceof Cli.ConfigError) {
         console.error('Doh, configured something wrong.', error);
         process.exit(1);
     }
@@ -156,15 +157,60 @@ for `push` (and other top level commands like `commit` and `pull`), then another
 | `description` | String (null)   | Description of this Command Group, used for help text.                                                    |
 | `commands`    | Commands[] ([]) | The set of possible Commands                                                                              |
 | `required`    | Boolean (true)  | This command is required, one of the Commands must be passed.                                             |
-| `callback`    | Function (null) | A callback to call when a command from this command group is parsed, function([Command Group], [Command]) |
+| `callback`    | Function (null) | A callback to call when a command from this command group is parsed, function([Cli], [Command]) |
 
 #### Command Options:
 
 | Option        | Type (default)  | Description                                                                                               |
 |---------------|-----------------|-----------------------------------------------------------------------------------------------------------|
 | `name`        | String (null)   | Name of the Command, used when parsing, so `push` or `commit` from the example above.                     |
 | `description` | String (null)   | Description of this Command, used for help text.                                                          |
-| `callback`    | Function (null) | A callback to call when a command from this command group is parsed, function([Command Group], [Command]) |
+| `callback`    | Function (null) | A callback to call when a command from this command group is parsed, function([Cli], [Command]) |
+
+Creating a tree structure for command routing isn't hard, just add more `CommandGroup`s to the first argument (the base Cli) in the callback
+
+```javascript
+var cli = new Cli();
+
+var finalResult;
+cli
+    .commandGroup({
+        name: 'cmd1',
+        description: 'main route for the program',
+        commands: [
+            new Command({
+                name: 'test1',
+                description: 'The first command option',
+                callback: function(cli, command) {
+                    // Append additional subgroups when this one is chosen.
+                    cli.commandGroup({
+                        name: 'test1Sub',
+                        description: 'the sub command to test1',
+                        commands: [
+                            new Command({
+                                name: 'foo',
+                                description: 'Foo should equal bar',
+                                callback: function(cli, command) {
+                                    finalResult = 'bar';
+                                }
+                            })
+                        ],
+                        required: true
+                    });
+                }
+            }),
+            new Command({
+                name: 'test2',
+                description: 'The second command option'
+            })
+        ],
+        required: true
+    });
+
+// Calling with: `node ./my-script.sh test1 foo` will set `finalResult` to 'bar'
+// The script will also be able to be called with `node ./my-script.sh test2`
+```
+
 
 ### Flag
 A flag is a single phrase that is set as a boolean and can be passed in any order. Flags that aren't passed are set as false.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "admiral-cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A Command Line Framework (CLI) framework for Node.js. Admiral has features like other CLI frameworks, but adds validation and some callbacks in key places. Less configuration, stronger validation.",
   "main": "main",
   "scripts": {

test/CommandTest.js

@@ -135,18 +135,26 @@ describe("Commands", function () {
 											finalResult = 'bar';
 										}
 									})
-								]
+								],
+								required: true
 							});
 						}
 					}),
 					new Command({
 						name: 'test2',
-						description: 'The second command option'
+						description: 'The second command option',
+						callback: function(cli, command) {
+							finalResult = 'hello';
+						}
 					})
 				],
 				required: true
 			});
 
+		cli.parse(['node', 'cli-test.js', 'test2']);
+		assert.equal(cli.params.cmd1, 'test2');
+		assert.equal(finalResult, 'hello');
+
 		cli.parse(['node', 'cli-test.js', 'test1', 'foo']);
 		assert.equal(cli.params.cmd1, 'test1');
 		assert.equal(cli.params.test1Sub, 'foo');