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

minor tweaks...

Browse Source 
Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
This commit is contained in:
Alex A. Naanou 2020-07-29 23:26:31 +03:00
parent be48c11535
commit 870411ecef
1 changed files with 95 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
README.md
View File

@ -117,12 +117,12 @@ Let us populate the option definitions splitting the job into sections...
```javascript ```javascript
var parser = argv.Parser({ var parser = argv.Parser({
// doc sections... // doc sections...
varsion: '0.0.1', 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).',
license: 'BSD-3-Clause', license: 'BSD-3-Clause',
``` ```
@ -134,79 +134,79 @@ If no value is given `true` is assigned to indicate that the option/command is
present in the command-line. present in the command-line.
```javascript ```javascript
'-bool': { '-bool': {
doc: 'if given set .bool to true' }, doc: 'if given set .bool to true' },
// option with a value... // option with a value...
'-value': { '-value': {
doc: 'set .x to X', doc: 'set .x to X',
// 'X' (VALUE) is used for -help while 'x' (key) is where the // 'X' (VALUE) is used for -help while 'x' (key) is where the
// value will be written... // value will be written...
arg: 'X | x', arg: 'X | x',
// the value is optional by default but we can make it required... // the value is optional by default but we can make it required...
valueRequired: true, valueRequired: true,
}, },
// setup an alias -r -> -required // setup an alias -r -> -required
'-r': '-required', '-r': '-required',
// a required option... // a required option...
'-required': { '-required': {
doc: 'set .required_option_given to true' doc: 'set .required_option_given to true'
// NOTE: we can omit the VALUE part to not require a value... // NOTE: we can omit the VALUE part to not require a value...
// NOTE: of no attr is specified in arg option name is used. // NOTE: of no attr is specified in arg option name is used.
arg: '| required_option_given', arg: '| required_option_given',
required: true, required: true,
// keep this near the top of the options list in -help... // keep this near the top of the options list in -help...
priority: 80, priority: 80,
}, },
'-int': { '-int': {
doc: 'pass an integer value', doc: 'pass an integer value',
// NOTE: if not key is given the VALUE name is used as a key, so the // NOTE: if not key is given the VALUE name is used as a key, so the
// value here is assigned to .INT... // value here is assigned to .INT...
arg: 'INT', arg: 'INT',
// convert the input value to int... // convert the input value to int...
type: 'int', type: 'int',
}, },
'-default': { '-default': {
doc: 'option with default value', doc: 'option with default value',
arg: 'VALUE | default', arg: 'VALUE | default',
default: 'some value', default: 'some value',
}, },
'-home': { '-home': {
doc: 'set home path', doc: 'set home path',
arg: 'HOME | home', arg: 'HOME | home',
// get the default value from the environment variable $HOME... // get the default value from the environment variable $HOME...
env: 'HOME', env: 'HOME',
}, },
// collecting values... // collecting values...
'-p': '-push', '-p': '-push',
'-push': { '-push': {
doc: 'push elements to a .list', doc: 'push elements to a .list',
arg: 'ELEM | list', arg: 'ELEM | list',
// this will add each argument to a -push option to a list... // this will add each argument to a -push option to a list...
collect: 'list', collect: 'list',
}, },
``` ```
@ -217,13 +217,13 @@ that determines how it is parsed, otherwise they are identical and everything
above applies here too. above applies here too.
```javascript ```javascript
'@command': { '@command': {
// ... // ...
}, },
// Since options and commands are identical, aliases from one to the // Since options and commands are identical, aliases from one to the
// other work as expected... // other work as expected...
'-c': '@command', '-c': '@command',
``` ```
@ -232,19 +232,19 @@ above applies here too.
These define `.handler`s which are executed when the option is encountered These define `.handler`s which are executed when the option is encountered
by the parser by the parser
```javascript ```javascript
'-active': { '-active': {
doc: 'basic active option', doc: 'basic active option',
handler: function(args, key, value){ handler: function(args, key, value){
// ... // ...
} }, } },
``` ```
And for quick-n-dirty hacking stuff together, a shorthand (_not for production use_): And for quick-n-dirty hacking stuff together, a shorthand (_not for production use_):
```javascript ```javascript
'-s': '-shorthand-active', '-s': '-shorthand-active',
'-shorthand-active': function(args, key, value){ '-shorthand-active': function(args, key, value){
// ... // ...
}, },
``` ```
@ -253,11 +253,11 @@ And for quick-n-dirty hacking stuff together, a shorthand (_not for production u
An options/command handler can also be a full fledged parser. An options/command handler can also be a full fledged parser.
```javascript ```javascript
'@nested': argv.Parser({ '@nested': argv.Parser({
// ... // ...
}).then(function(){ }).then(function(){
// ... // ...
}), }),
``` ```
This can be useful when there is a need to define a sub-context with it's own This can be useful when there is a need to define a sub-context with it's own
@ -280,16 +280,16 @@ To stop option processing either return `STOP` or `THEN` from the handler.
- `THEN` is the normal case, stop processing and trigger [`<parser>.then(..)`](./ADVANCED.md#parserthen): - `THEN` is the normal case, stop processing and trigger [`<parser>.then(..)`](./ADVANCED.md#parserthen):
```javascript ```javascript
'-then': { '-then': {
handler: function(){ handler: function(){
return argv.THEN } }, return argv.THEN } },
``` ```
- `STOP` will stop processing and trigger [`<parser>.stop(..)`](./ADVANCED.md#parserstop): - `STOP` will stop processing and trigger [`<parser>.stop(..)`](./ADVANCED.md#parserstop):
```javascript ```javascript
'-stop': { '-stop': {
handler: function(){ handler: function(){
return argv.STOP } }, return argv.STOP } },
``` ```
@ -299,18 +299,18 @@ There are three ways to stop and/or report errors:
- Simply `throw` a `ParserError(..)` instance: - Simply `throw` a `ParserError(..)` instance:
```javascript ```javascript
'-error': { '-error': {
handler: function(){ handler: function(){
throw argv.ParserError('something went wrong.') } }, throw argv.ParserError('something went wrong.') } },
``` ```
Here processing will stop and the error will be reported automatically Here processing will stop and the error will be reported automatically
before [`<parser>.error(..)`](./ADVANCED.md#parsererror-1) is triggered. before [`<parser>.error(..)`](./ADVANCED.md#parsererror-1) is triggered.
- _Silently_ `return` a `ParserError(..)` instance: - _Silently_ `return` a `ParserError(..)` instance:
```javascript ```javascript
'-silent-error': { '-silent-error': {
handler: function(){ handler: function(){
return argv.ParserError('something went wrong.') } }, return argv.ParserError('something went wrong.') } },
``` ```
This will _not_ report the error but will stop processing and trigger This will _not_ report the error but will stop processing and trigger
[`<parser>.error(..)`](./ADVANCED.md#parsererror-1), so the user can either [`<parser>.error(..)`](./ADVANCED.md#parsererror-1), so the user can either
@ -318,12 +318,12 @@ There are three ways to stop and/or report errors:
- For a critical error simply `throw` any other JavaScript error/exception: - For a critical error simply `throw` any other JavaScript error/exception:
```javascript ```javascript
'-critical-error': { '-critical-error': {
handler: function(){ handler: function(){
throw 'something went really wrong.' } }, throw 'something went really wrong.' } },
// and to close things off ;) // and to close things off ;)
}) })
``` ```
Note that [`<parser>.then(..)`](./ADVANCED.md#parserthen) will not be triggered Note that [`<parser>.then(..)`](./ADVANCED.md#parserthen) will not be triggered