started adding examples...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>

README.md

@@ -65,6 +65,7 @@ This code is an evolution of that parser.
 		- [Nested parsers](#nested-parsers)
 		- [Stopping](#stopping)
 		- [Error reporting](#error-reporting)
+		- [Handling the result](#handling-the-result)
 		- [Calling the script](#calling-the-script)
 	- [Advanced docs](#advanced-docs)
 	- [More...](#more)
@@ -73,12 +74,12 @@ This code is an evolution of that parser.
 
 ## Architecture
 
-```
-	Parser(..) -> <parser> -> <parsed>
-```
-
 This module provides the following workflow:
 
+```
+Parser(..) -> <parser> -> <parsed>
+```
+
 - define/declare a parser (parse grammar)
 	```
 	Parser(<spec>)
@@ -98,9 +99,9 @@ This module provides the following workflow:
 	<parser>(...)
 		-> <parsed>
 	```
-	- option handlers defined in `<spec>` are called while parsing,
-	- the appropriate `<callback>`s are called after the `<parser>` is done,
-	- everything is run in the context of the `<parsed>` object so any
+	- option handlers (defined in `<spec>`) are called while parsing,
+	- the appropriate `<callback>`'s are called after the `<parser>` is done,
+	- everything is run in the _context_ of the `<parsed>` object so any
 	  data set on it is accessible after parsing is done for further
 	  reference.
 
@@ -142,14 +143,21 @@ var parser = argv.Parser({
 	})
 
 // run the parser...
-__filename == require.main
-	&& parser(process.argv)
+__filename == require.main.filename
+	&& parser()
 ```
 
 This will already create a script that can respond to `-help` and freinds.
 
 ```shell
 $ ./script.js --help 
+Usage: script.js [OPTIONS]
+
+Options:
+        -h,  --help             - print this message and exit
+        -v,  --version          - show script.js verion and exit
+        -q,  --quiet            - quiet mode
+        -                       - stop processing arguments after this point
 ```
 
 ## Options in more detail
@@ -220,10 +228,10 @@ present in the command-line.
 		// NOTE: of no attr is specified in arg option name is used.
 		arg: '| required_option_given',
 
+		// NOTE: by default required options/commands are sorted above normal
+		//		options but bellow -help/-version/-quiet/...
+		//		(by default at priority 80)
 		required: true,
-
-		// keep this near the top of the options list in -help...
-		priority: 80,
 	},
 
 
@@ -244,6 +252,9 @@ present in the command-line.
 		arg: 'VALUE | default',
 
 		default: 'some value',
+
+		// keep this near the top of the options list in -help...
+		priority: 80,
 	},
 
 
@@ -379,9 +390,6 @@ There are three ways to stop and/or report errors:
 		'-critical-error': {
 			handler: function(){
 				throw 'something went really wrong.' } },
-
-	// and to close things off ;)
-	})
 	```
 
 Note that [`<parser>.then(..)`](./ADVANCED.md#parserthen) will not be triggered 
@@ -389,6 +397,36 @@ in any of these cases.
 
 Also see: [`<parser>.printError(..)`](./ADVANCED.md#parserprint--parserprinterror)
 
+```javascript
+// and to close things off for the <spec> ;)
+})
+```
+
+### Handling the result
+
+The `<parser>` will call different sets of callbacks on different stop conditions:
+
+- [`<parser>.then(..)`](./ADVANCED.md#parserthen) for normal exit
+	```javascript
+	.then(function(unhandled, root_value, rest){
+		console.log('finished normally.')
+	})
+	```
+
+- [`<parser>.stop(..)`](./ADVANCED.md#parserstop) when parser is stopped
+	```javascript
+	.stop(function(arg, rest){
+		console.log(`stopped at ${arg}.`)
+	})
+	```
+
+- [`<parser>.stop(..)`](./ADVANCED.md#parserstop) when an error is detected
+	```javascript
+	.error(function(reason, arg, rest){
+		console.log(`something went wrong when parsing ${arg}.`)
+	})
+	```
+
 
 ### Calling the script
 

argv.js

@@ -496,14 +496,15 @@ object.Constructor('Parser', {
 	//footer: 'Written by $AUTHOR ($VERSION / $LICENSE).',
 	footer: undefined,
 
+	// NOTE: this supports but does not requires the 'colors' module...
 	// XXX should wrap long lines...
 	alignColumns: function(a, b, ...rest){
 		var opts_width = this.helpColumnOffset || 4
 		var prefix = this.helpColumnPrefix || ''
 		b = [b, ...rest].join('\n'+ ('\t'.repeat(opts_width+1) + ' '.repeat(prefix.length)))
 		return b ?
-			(a.strip.length < opts_width*8 ?
-				[a +'\t'.repeat(opts_width - Math.floor(a.strip.length/8))+ prefix + b]
+			((a.strip || a).length < opts_width*8 ?
+				[a +'\t'.repeat(opts_width - Math.floor((a.strip || a).length/8))+ prefix + b]
 				: [a, '\t'.repeat(opts_width)+ prefix + b])
 			: [a] },
 	expandTextVars: function(text){

examples/bare.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+// compatible with both node's and RequireJS' require(..)
+var argv = require('../argv')
+
+var parser = argv.Parser({
+		// option definitions...
+		// ...
+	})
+	.then(function(){
+		// things to do after the options are handled...
+		// ...
+	})
+
+// run the parser...
+__filename == require.main.filename
+	&& parser(process.argv)
+
+// vim:set ts=4 sw=4 spell :