From 602d5d7b2a3669aaac49f69dbad9653e4d38bbb1 Mon Sep 17 00:00:00 2001 From: "Alex A. Naanou" Date: Fri, 31 Jul 2020 04:30:13 +0300 Subject: [PATCH] started adding examples... Signed-off-by: Alex A. Naanou --- README.md | 68 +++++++++++++++++++++++++++++++++++++----------- argv.js | 5 ++-- examples/bare.js | 19 ++++++++++++++ 3 files changed, 75 insertions(+), 17 deletions(-) create mode 100644 examples/bare.js diff --git a/README.md b/README.md index c2b4461..46b1c27 100644 --- a/README.md +++ b/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(..) -> -> -``` - This module provides the following workflow: +``` +Parser(..) -> -> +``` + - define/declare a parser (parse grammar) ``` Parser() @@ -98,9 +99,9 @@ This module provides the following workflow: (...) -> ``` - - option handlers defined in `` are called while parsing, - - the appropriate ``s are called after the `` is done, - - everything is run in the context of the `` object so any + - option handlers (defined in ``) are called while parsing, + - the appropriate ``'s are called after the `` is done, + - everything is run in the _context_ of the `` 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 [`.then(..)`](./ADVANCED.md#parserthen) will not be triggered @@ -389,6 +397,36 @@ in any of these cases. Also see: [`.printError(..)`](./ADVANCED.md#parserprint--parserprinterror) +```javascript +// and to close things off for the ;) +}) +``` + +### Handling the result + +The `` will call different sets of callbacks on different stop conditions: + +- [`.then(..)`](./ADVANCED.md#parserthen) for normal exit + ```javascript + .then(function(unhandled, root_value, rest){ + console.log('finished normally.') + }) + ``` + +- [`.stop(..)`](./ADVANCED.md#parserstop) when parser is stopped + ```javascript + .stop(function(arg, rest){ + console.log(`stopped at ${arg}.`) + }) + ``` + +- [`.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 diff --git a/argv.js b/argv.js index 83d835d..8d2895e 100644 --- a/argv.js +++ b/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){ diff --git a/examples/bare.js b/examples/bare.js new file mode 100644 index 0000000..17f2b2b --- /dev/null +++ b/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 :