From 1aeb1697bea252d977e57bc2015d1c21ca2c6a2a Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Sun, 19 Jul 2020 18:06:17 +0300
Subject: [PATCH] doc...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 README.md | 217 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 180 insertions(+), 37 deletions(-)

diff --git a/README.md b/README.md
index a0ca913..1029615 100644
--- a/README.md
+++ b/README.md
@@ -54,17 +54,27 @@ This code is an evolution of that parser.
 	- [Installation](#installation)
 	- [Basic usage](#basic-usage)
 	- [Configuration](#configuration)
-		- [Options, commands and aliases](#options-commands-and-aliases)
-		- [Help](#help)
-			- [Value placeholders](#value-placeholders)
-			- [Automatically defined values](#automatically-defined-values)
-			- [`.doc`](#doc)
-			- [`.usage`](#usage)
-			- [`.version`](#version)
-			- [`.license`](#license)
-			- [`.examples`](#examples)
-			- [`.footer`](#footer)
-			- [More control over help...](#more-control-over-help)
+		- [Option/command configuration](#optioncommand-configuration)
+			- [`<option>.handler(..)`](#optionhandler)
+			- [`<option>.doc`](#optiondoc)
+			- [`<option>.arg`](#optionarg)
+			- [`<option>.type`](#optiontype)
+			- [`<option>.env`](#optionenv)
+			- [`<option>.default`](#optiondefault)
+			- [`<option>.required`](#optionrequired)
+			- [`<option>.valueRequired`](#optionvaluerequired)
+		- [Built-in options](#built-in-options)
+			- [`-v` / `--version`](#-v----version)
+			- [`-h` / `--help`](#-h----help)
+				- [Value placeholders](#value-placeholders)
+				- [Automatically defined values](#automatically-defined-values)
+				- [`.doc`](#doc)
+				- [`.usage`](#usage)
+				- [`.version`](#version)
+				- [`.license`](#license)
+				- [`.examples`](#examples)
+				- [`.footer`](#footer)
+				- [More control over help...](#more-control-over-help)
 		- [Nested parsers](#nested-parsers)
 	- [Components and API](#components-and-api)
 		- [`THEN`, `STOP` and `ERROR`](#then-stop-and-error)
@@ -120,12 +130,15 @@ __filename == require.main
 ```
 
 Option definitions in a bit more detail
+
+XXX make this a set of practical options and leave the attr explanation to later...
 ```javascript
 var parser = argv.Parser({
 		// XXX config...
 
-		// basic quick-n-dirty option...
+		// alias, this tells the parser that '-b' is the same as '-basic'
 		'-b': '-basic',
+		// basic quick-n-dirty option...
 		'-basic': function(opts, key, value){
 			// ...
 		},
@@ -192,6 +205,10 @@ This will create a parser that supports the folowing:
 ```shell
 $ ./script.js --help 
 
+$ ./script.js --value 321
+
+$ ./script.js --value=321
+
 $ ./script.js command
 
 $ ./script.js nested -h
@@ -202,26 +219,152 @@ $ ./script.js -fb
 
 ## Configuration
 
-This sections lists attributes and methods designed to be set/modified in
-`<spec>` passed to `Parser(..)`.
-
-Note that these attributes are the same attributes inherited by `<parser>`
-(parser instance) and are simply merged into the new instance created by
-`Parser(..)`, this there are no restrictions on what attributes/methods
-can be overloaded in this way but care must be taken when overloading
-elements that were not designed to be overloaded.
-
-```javascript
-var parser = Parser({
-
-})
+```
+Parser(<spec>)
+	-> <parser>
 ```
 
-### Options, commands and aliases
+The `<spec>` object is "merged" int the `<parser>` instance overriding or extending 
+it's API/data.
 
-### Help 
+The `<parser>` expects/handles the following data in the `<spec>` object:
 
-`Parser` defines a default help generator via the `-h` and `-help` options.
+- the configuration attributes and methods  
+	This sections lists attributes and methods designed to be set/modified in
+	`<spec>` passed to `Parser(..)`.
+
+	Note that these attributes are the same attributes inherited by `<parser>`
+	and are simply merged into the new instance created by `Parser(..)`, this 
+	there are no restrictions on what attributes/methods can be overloaded in 
+	this way but care must be taken when overloading elements that were not 
+	designed to be overloaded.
+
+- option/command definitions  
+	The keys for these are prefixed either by `"-"` for options or by `"@"` 
+	for commands and are either _objects_, _functions_ or _parser_ instances.
+
+	The only difference between an _option_ and a _command_ is that the former 
+	are passed to the _script_ with a `"-"` or `"--"` prefix (by default) and 
+	the later are passed by name without prefixes. 
+
+	In all other regards options and commands are the same.
+
+- option/command aliases  
+	An alias is an option/command key with a _string_ value.  
+	That value _references_ a different option or command, i.e. is an 
+	option/commnad name.
+
+	Looping (referencing the original alias) or dead-end (referencing non-existant 
+	options) aliases are ignored.
+
+
+### Option/command configuration
+
+#### `<option>.handler(..)`
+
+Option handler.
+
+
+```javascript
+'-option': function(opts, key, value){
+	// handle the option...
+	// ...
+},
+```
+or
+```javascript
+'-option': {
+	handler: function(opts, key, value){
+		// handle the option...
+		// ...
+	},
+},
+```
+
+The handler gets called if the option is given or if it has a default value but was not given.
+
+`opts` contains the mutable list of arguments passed to the script starting with but not including the current argument. If the handler needs to handle it's own arguments it can modify this list in place and the _parser_ will continue from that state.
+
+One usecase for this would be and option handler that needs to handle it's arguemnts on its own.
+
+`key` is the actual normalized (`[<prefix-char>]<name-str>`) option/command triggering the `.handler(..)`. 
+
+This can be useful to identify the actual option triggering the handler when using aliases or if a single handler is used for multiple options, or when it is needed to handle a specific prefix differently (a-la `find`).
+
+`value` is the option value. A _value_ either ecplicitly passed (via `=` syntax), implicitly parsed from the `argv` via the `<option>.arg` definition or `undefined` otherwise.
+
+A handler can return one of the `THEN`, `STOP` or `ERROR` to control further parsing and/or execution.  
+(See: [`THEN`, `STOP` and `ERROR`](#then-stop-and-error) for more info.)
+
+
+#### `<option>.doc`
+
+Option/command documentation string used in `-help`.
+
+
+#### `<option>.arg`
+
+Option/command argument definition.
+
+```
+arg: '<arg-name>'
+arg: '<arg-name> | <key>'
+```
+
+If defined and no explicit value is passed to the option comand (via `=`) then the _parser_ will consume the directly next non-option if present in `argv` as a value, passing it to the `<option>.type` handler, if defined, then the `<option>.handler(..)`, if defined, or setting it to `<key>` otherwise.
+
+Sets the option/command arument name given in `-help` for the option and the key where the value will be written.
+
+The `<key>` is not used if `<option>.handler(..)` is defined.
+
+
+#### `<option>.type`
+
+Option/command argument type definition. The given type handler will be used to convert the option value before it is passed to the handler or set to the given `<key>`.
+
+Supported types:
+- `"int"`
+- `"float"`
+- `"number"`
+- `"string"`
+- `"date"`
+
+Type handlers are defined in `Parser.typeHandlers` or can be overwritten by `<spec>.typeHandlers`.
+
+
+#### `<option>.env`
+
+If set, determines the environment variable to be used as the default value for option/command.
+
+If this is set, the corresponding environment variable is non-zero and `<option>.handler(..)` is defined, the handler will be called regardless of weather the option was given by the user or not.
+
+
+#### `<option>.default`
+
+Sets the default value for option/command's value.
+
+If this is set to a value other than `undefined` and `<option>.handler(..)` is defined, the handler will be called regardless of weather the option was given by the user or not.
+
+
+#### `<option>.required`
+
+Sets weather the _parser_ should complain/err if option/command is not given.
+
+
+#### `<option>.valueRequired`
+
+Sets weather the _parser_ should complain/err if option/value value is not given.
+
+
+
+### Built-in options
+
+#### `-v` / `--version`
+
+This will output the value of `.version` and exit.
+
+
+#### `-h` / `--help`
 
 By default `-help` will output in the following format:
 ```
@@ -249,7 +392,7 @@ Examples:
 All sections are optional and will not be rendered if they contain no data.
 
 
-#### Value placeholders
+##### Value placeholders
 
 All documentation strings can contain special placeholders that 
 will get replaced with appropriate values when rendering help.
@@ -258,7 +401,7 @@ will get replaced with appropriate values when rendering help.
 - `$VERSION` replaced with `.version`,
 - `$LICENSE` replaced with `.license`.
 
-#### Automatically defined values
+##### Automatically defined values
 
 These values are set by the parser just before parsing starts:
 - `.script` - full script path, usually this is the value of `argv[0]`,
@@ -267,21 +410,21 @@ These values are set by the parser just before parsing starts:
 
 These will be overwritten when the parser is called.
 
-#### `.doc`
+##### `.doc`
 Script documentation.
 
     <spec>.doc = <string> | <function>
 
 Default value: `undefined`
 
-#### `.usage`
+##### `.usage`
 Basic usage hint.
 
     <spec>.usage = <string> | <function> | undefined
 
 Default value: `"$SCRIPTNAME [OPTIONS]"`
 
-#### `.version`
+##### `.version`
 Version number.
 
     <spec>.usage = <string> | <function> | undefined
@@ -290,14 +433,14 @@ If this is not defined `-version` will print `"0.0.0"`.
 
 Default value: `undefined`
 
-#### `.license`
+##### `.license`
 Short license information.
 
     <spec>.usage = <string> | <function> | undefined
 
 Default value: `undefined`
 
-#### `.examples`
+##### `.examples`
 
     <spec>.usage = <string> | <list> | <function> | undefined
 
@@ -310,7 +453,7 @@ Example list format:
 
 Default value: `undefined`
 
-#### `.footer`
+##### `.footer`
 Aditional information.
 
     <spec>.footer = <string> | <function> | undefined
@@ -318,7 +461,7 @@ Aditional information.
 Default value: `undefined`
 
 
-#### More control over help...
+##### More control over help...
 
 For more info on help formatting see `.help*` attributes in the [source](./argv.js).