diff --git a/README.md b/README.md index 9232301..6991fd4 100644 --- a/README.md +++ b/README.md @@ -137,11 +137,11 @@ var parser = exports.parser = argv.Parser({ // option definitions... - // ... + ... }) .then(function(){ // things to do after the options are handled... - // ... + ... }) // run the parser... @@ -217,6 +217,33 @@ for example: ``` +If nested parsers are defined the default `-h` and `--help` will behave differently, +the former will print the normal help while `--help` will also print help for each +of the nested parsers/commands. + +To disable this behavior set `'extendedHelp'` to `false`: +```javascript + argv.Parser({ + ... + + extendedHelp: false, + + ... + }) +``` + +To explicitly separate `-h` and `--help` either define custom handlers or +alias `--help` directly to `extendedHelp`: +```javascript + argv.Parser({ + ... + + '-help': 'extendedHelp', + + ... + }) +``` + ### Basic options These, if encountered, simply assign a value to an attribute on the parsed object. @@ -345,7 +372,7 @@ above applies here too. ```javascript '@command': { - // ... + ... }, // Since options and commands are identical, aliases from one to the @@ -362,7 +389,7 @@ by the parser '-active': { doc: 'basic active option', handler: function(args, key, value){ - // ... + ... } }, ``` @@ -370,7 +397,7 @@ And for quick-n-dirty hacking stuff together, a shorthand (_not for production u ```javascript '-s': '-shorthand-active', '-shorthand-active': function(args, key, value){ - // ... + ... }, ``` @@ -393,7 +420,7 @@ Pattern option/command keys enable partial input key matching. '-prefix-*': { doc: 'Pattern option', handler: function(rest, key){ - // ... + ... } }, ``` @@ -411,9 +438,9 @@ An options/command handler can also be a full fledged parser. ```javascript '@nested': argv.Parser({ - // ... + ... }).then(function(){ - // ... + ... }), // and for fun, import the bare parser... diff --git a/argv.js b/argv.js index 3b6a6a3..dc8a039 100644 --- a/argv.js +++ b/argv.js @@ -394,6 +394,7 @@ object.Constructor('Parser', { return Parser(Object.assign({}, update(e, { splitOptions: false, + '-h': undefined, '-help': undefined, '-*': undefined, '@*': undefined, @@ -698,9 +699,10 @@ object.Constructor('Parser', { usage: '$SCRIPTNAME $REQUIRED [OPTIONS]', doc: undefined, examples: undefined, - //footer: undefined, footer: 'Written by: $AUTHOR\nVersion: $VERSION / License: $LICENSE', + helpExtendedCommandHeader: 'Command: $COMMAND', + // NOTE: this supports but does not requires the 'colors' module... // XXX should wrap long lines... alignColumns: function(a, b, ...rest){ @@ -768,20 +770,38 @@ object.Constructor('Parser', { .replace(/\$SCRIPTNAME/g, this.scriptName || 'SCRIPT') }, // - // --help - // --help= + // -h + // -h= // // Supported options: // noUsage - do not print usage info // noFooter - do not print help footer // + // By default, if this is triggered via --help this will defer to + // .extendedHelp if any of the options is a nested parser. + // To disable this behavior set .extendedHelp to false + // To explicitly separate -h from --help set '-help' to 'extendedHelp' + // // NOTE: the options are for internal use mostly... // NOTE: this will set .quiet to false... - '-h': '-help', - '-help': { + // + // XXX would be nice to make this print help for '-h' and '--help' + // separately in extended mode... + '-help': '-h', + '-h': { doc: 'print this message and exit', priority: 90, handler: function(argv, key, value){ + // extended help... + if(this.extendedHelp + && key.slice(1) == 'help' + && this['-help'] == '-h'){ + for(var n in this){ + // only print if extended help available... + if(this[n] instanceof Parser){ + return this.extendedHelp.handler.call(this, ...arguments) } } } + + // normal help... var options = {} if(value){ for(var opt of value.split(/\s*,\s*/g)){ @@ -928,12 +948,14 @@ object.Constructor('Parser', { .flat() .join('\n'))) return module.STOP }}, - // XXX might also be a good idea to do this as --help and the do the - // short version as -h... - '-help-all': { - // XXX should this be hidden??? - //doc: 'print help for all nested commands supporting customization', - doc: false, + // Extended help... + // + // To make this explicit add an alias to it: + // '-help': 'extendedHelp', + // + extendedHelp: { + doc: 'print base and configurable command help then exit', + priority: 90, handler: function(argv, key, value){ var options = {} if(value){ @@ -941,18 +963,22 @@ object.Constructor('Parser', { options[opt] = true } } // main help... - var res = this.handle('-help', argv, '-help', 'noFooter') + var res = this.handle('-h', argv, '-h', 'noFooter') // print help for nested parsers... for(var n in this){ - if(this[n] instanceof Parser){ + // doc... + if(this[n] instanceof Parser + && this[n].doc !== false){ this.print([ '', '', - 'Command: '+ n.slice(1), + (this.helpExtendedCommandHeader + ?? 'Command: $COMMAND') + .replace(/\$COMMAND/g, n.slice(1)), '', ].join('\n')) - this.handle(n, ['-help=noFooter'], n.slice(1)) } } + this.handle(n, ['-h=noFooter'], n.slice(1)) } } // footer... options.noFooter @@ -966,7 +992,7 @@ object.Constructor('Parser', { '-?': { doc: false, handler: function(){ - return this.handle('-help', ...arguments) } }, + return this.handle('-h', ...arguments) } }, // Version... diff --git a/package.json b/package.json index b21da5d..28d80bf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "ig-argv", - "version": "2.16.5", + "version": "2.16.7", "description": "simple argv parser", "main": "argv.js", "scripts": {