flynx/argv.js
1
0
Fork 0
mirror of https://github.com/flynx/argv.js.git synced 2025-10-31 03:30:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

more tweaking docs...

Browse Source 
Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
This commit is contained in:
Alex A. Naanou 2020-07-19 21:24:19 +03:00
parent d4ff741381
commit 73e1f82c5e
2 changed files with 44 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -71,29 +71,29 @@ This code is an evolution of that parser.
- [`-h` / `--help`](#-h----help) - [`-h` / `--help`](#-h----help)
- [Value placeholders](#value-placeholders) - [Value placeholders](#value-placeholders)
- [Automatically defined values](#automatically-defined-values) - [Automatically defined values](#automatically-defined-values)
- [`.doc`](#doc) - [`<parser>.doc`](#parserdoc)
- [`.usage`](#usage) - [`<parser>.usage`](#parserusage)
- [`.version`](#version) - [`<parser>.version`](#parserversion)
- [`.license`](#license) - [`<parser>.license`](#parserlicense)
- [`.examples`](#examples) - [`<parser>.examples`](#parserexamples)
- [`.footer`](#footer) - [`<parser>.footer`](#parserfooter)
- [More control over help...](#more-control-over-help) - [More control over help...](#more-control-over-help)
- [Nested parsers](#nested-parsers) - [Nested parsers](#nested-parsers)
- [Components and API](#components-and-api) - [Components and API](#components-and-api)
- [`THEN`, `STOP` and `ERROR`](#then-stop-and-error) - [`THEN`, `STOP` and `ERROR`](#then-stop-and-error)
- [`Parser(..)`](#parser) - [`Parser(..)`](#parser)
- [`.then(..)`](#then) - [`<parser>.then(..)`](#parserthen)
- [`.stop(..)`](#stop) - [`<parser>.stop(..)`](#parserstop)
- [`.error(..)`](#error) - [`<parser>.error(..)`](#parsererror)
- [`.off(..)`](#off) - [`<parser>.off(..)`](#parseroff)
- [`<parser>(..)`](#parser-1) - [`<parser>(..)`](#parser-1)
- [Advanced parser API](#advanced-parser-api) - [Advanced parser API](#advanced-parser-api)
- [`.print(..)` / `.printError(..)`](#print--printerror) - [`<parser>.print(..)` / `<parser>.printError(..)`](#parserprint--parserprinterror)
- [`.handlerDefault(..)`](#handlerdefault) - [`<parser>.handlerDefault(..)`](#parserhandlerdefault)
- [`.handleArgumentValue(..)`](#handleargumentvalue) - [`<parser>.handleArgumentValue(..)`](#parserhandleargumentvalue)
- [`.handleErrorExit(..)`](#handleerrorexit) - [`<parser>.handleErrorExit(..)`](#parserhandleerrorexit)
- [More...](#more) - [More...](#more)
- [License](#license-1) - [License](#license)
## Installation ## Installation
@ -137,6 +137,7 @@ XXX make this a set of practical options and leave the attr explanation to later
```javascript ```javascript
var parser = argv.Parser({ var parser = argv.Parser({
// doc sections... // doc sections...
varsion: '0.0.1',
doc: 'Example script options', doc: 'Example script options',
author: 'John Smith <j.smith@some-mail.com>', author: 'John Smith <j.smith@some-mail.com>',
footer: 'Written by $AUTHOR ($VERSION / $LICENSE).', footer: 'Written by $AUTHOR ($VERSION / $LICENSE).',
@ -415,7 +416,7 @@ not given.
Stop processing further options. Stop processing further options.
This can be used to terminate nested parsers or to stop option processing This can be used to terminate nested parsers or to stop option processing
in the root parser to handle the rest of the options in `.then(..)`, in the root parser to handle the rest of the options in `<parser>.then(..)`,
for example. for example.
@ -481,7 +482,7 @@ These values are set by the parser just before parsing starts:
These will be overwritten when the parser is called. These will be overwritten when the parser is called.
##### `.doc` ##### `<parser>.doc`
Script documentation. Script documentation.
<spec>.doc = <string> | <function> <spec>.doc = <string> | <function>
@ -489,7 +490,7 @@ Script documentation.
Default value: `undefined` Default value: `undefined`
##### `.usage` ##### `<parser>.usage`
Basic usage hint. Basic usage hint.
<spec>.usage = <string> | <function> | undefined <spec>.usage = <string> | <function> | undefined
@ -497,7 +498,7 @@ Basic usage hint.
Default value: `"$SCRIPTNAME [OPTIONS]"` Default value: `"$SCRIPTNAME [OPTIONS]"`
##### `.version` ##### `<parser>.version`
Version number. Version number.
<spec>.usage = <string> | <function> | undefined <spec>.usage = <string> | <function> | undefined
@ -507,7 +508,7 @@ If this is not defined `-version` will print `"0.0.0"`.
Default value: `undefined` Default value: `undefined`
##### `.license` ##### `<parser>.license`
Short license information. Short license information.
<spec>.usage = <string> | <function> | undefined <spec>.usage = <string> | <function> | undefined
@ -515,7 +516,7 @@ Short license information.
Default value: `undefined` Default value: `undefined`
##### `.examples` ##### `<parser>.examples`
<spec>.usage = <string> | <list> | <function> | undefined <spec>.usage = <string> | <list> | <function> | undefined
@ -529,7 +530,7 @@ Example list format:
Default value: `undefined` Default value: `undefined`
##### `.footer` ##### `<parser>.footer`
Aditional information. Aditional information.
<spec>.footer = <string> | <function> | undefined <spec>.footer = <string> | <function> | undefined
@ -539,7 +540,7 @@ 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). For more info on help formatting see `<parser>.help*` attributes in the [source](./argv.js).
### Nested parsers ### Nested parsers
@ -602,10 +603,10 @@ See [lang.js](./lang.js) for more fun with argv and programming languages ;)
Values that if returned by option/command handlers can control the parse flow. Values that if returned by option/command handlers can control the parse flow.
- `THEN` &ndash; Stop parsing and call `.then(..)` callbacks. - `THEN` &ndash; Stop parsing and call `<parser>.then(..)` callbacks.
- `STOP` &ndash; Stop parsing and call `.stop(..)` callbacks, - `STOP` &ndash; Stop parsing and call `<parser>.stop(..)` callbacks,
skipping `.then(..)`. skipping `<parser>.then(..)`.
- `ERROR` &ndash; Stop parsing, call `.error(..)` callbacks and - `ERROR` &ndash; Stop parsing, call `<parser>.error(..)` callbacks and
exit with an error. exit with an error.
### `Parser(..)` ### `Parser(..)`
@ -618,7 +619,7 @@ Parser(<spec>)
See [`<parser>(..)`](#parser-1) for more info. See [`<parser>(..)`](#parser-1) for more info.
#### `.then(..)` #### `<parser>.then(..)`
Add callback to `then` "event". Add callback to `then` "event".
``` ```
@ -634,7 +635,7 @@ callback(<unhandled>, <root-value>, <rest>)
`then` is triggered when parsing is done or stopped from an option `then` is triggered when parsing is done or stopped from an option
handler by returning `THEN`. handler by returning `THEN`.
#### `.stop(..)` #### `<parser>.stop(..)`
Add callback to `stop` "event". Add callback to `stop` "event".
``` ```
@ -649,7 +650,7 @@ callback(<arg>, <rest>)
`stop` is triggered when a handler returns `STOP`. `stop` is triggered when a handler returns `STOP`.
#### `.error(..)` #### `<parser>.error(..)`
Add callback to `error` "event". Add callback to `error` "event".
``` ```
@ -665,7 +666,7 @@ callback(<reason>, <arg>, <rest>)
`error` is triggered when a handler returns `ERROR`. `error` is triggered when a handler returns `ERROR`.
#### `.off(..)` #### `<parser>.off(..)`
Remove callback from "event". Remove callback from "event".
``` ```
@ -704,11 +705,11 @@ its head.
## Advanced parser API ## Advanced parser API
### `.print(..)` / `.printError(..)` ### `<parser>.print(..)` / `<parser>.printError(..)`
Handle how `Parser(..)` prints things. Handle how `<parser>` prints things.
`.print(..)` and `.printError(..)` are very similar but handle different `<parser>.print(..)` and `<parser>.printError(..)` are very similar but handle different
cases, similar to `console.log(..)` and `console.error(..)` cases, similar to `console.log(..)` and `console.error(..)`
``` ```
<parser>.print(...) <parser>.print(...)
@ -727,20 +728,21 @@ Both support callback binding:
-> <parser> -> <parser>
``` ```
Both `.print(..)` and `.printError(..)` can safely be overloaded if the Both `<parser>.print(..)` and `<parser>.printError(..)` can safely be
callback feature is not going to be used by the user &ndash; the print overloaded if the callback feature is not going to be used by the user
callbacks are not used internally. &ndash; the print callbacks are not used internally.
For full callback support see: `extra.afterCallback(..)` in [argv.js](./argv.js).
For full callback API see: `extra.afterCallback(..)` in [argv.js](./argv.js).
### `.handlerDefault(..)` ### `<parser>.handlerDefault(..)`
Called when `<option>.handler(..)` is not defined. Called when `<option>.handler(..)` is not defined.
By default this sets option values on the _parsed_ object. By default this sets option values on the _parsed_ object.
### `.handleArgumentValue(..)` ### `<parser>.handleArgumentValue(..)`
Handle argument value conversion. Handle argument value conversion.
@ -749,7 +751,7 @@ By default this handles the `<option>.type` mechanics.
If this is set to `false` values will be set as-is. If this is set to `false` values will be set as-is.
### `.handleErrorExit(..)` ### `<parser>.handleErrorExit(..)`
Handle exit on error. Handle exit on error.

1
argv.js
View File

@ -211,6 +211,7 @@ function(name, pre, post){
// +help -> this['+help'](..) // +help -> this['+help'](..)
// //
// //
// XXX add support for ParserError exception handling...
// XXX should -help should work for any command? ..not just nested parsers? // XXX should -help should work for any command? ..not just nested parsers?
// ...should we indicate which thinks have more "-help"?? // ...should we indicate which thinks have more "-help"??
// XXX might be a good idea to use exceptions for ERROR... // XXX might be a good idea to use exceptions for ERROR...