-
Notifications
You must be signed in to change notification settings - Fork 0
Public API
GNU C getopt style options are fully supported by Bebopt.
Both long and short options may receive arguments in both implicit and explicit forms.
- explicit:
--help=<ARG>, -h=<ARG>
- implicit:
--help <ARG>, -h <ARG>
Flag options may only receive an argument in the explicit form: <FLAG>=<ARG>
, which produces an error, since the value of a flag is determined by how many times it appears on the command-line, and so cannot be set using an argument.
Passing an argument to a flag in the implicit form (e.g. <FLAG> <ARG>
) has no effect and does not produce an error. The flag simply ignores the argument and Bebopt treats said argument as a positional argument; an example of a positional arg would be the name of a file passed to the cat
program (e.g. cat FILENAME
).
Information regarding some less obvious points about option definitions.
An option's callback gets called when said option or one of its aliases appears on the command-line. Any arguments to said option will be available in said option's callback as its first parameter.
The value of this parameter depends on the said option's type:
- a number denoting the times said option was passed to the program (flags)
- a string containing the argument, if any, passed to the option.
After an option's callback returns, the return value is stored in the after
field under the option's name in the resulting hash that .parse produces.
There are, so far, 3 types of options:
- Boolean flags
- options with optional arguments
- options with required arguments
An option's type is determined by the opcode, if any, that appears at the end of its name.
No opcode is necessary. All options are flags by default.
If the option is found with an argument, your program will exit non-zero and print out an error message.
Appending ::
to the end of an option's name denotes that it accepts an optional argument.
If the option is found without any arguments, the parameter passed to the option's callback will be undefined
.
Appending :
to the end of an option's name denotes that it accepts a required argument.
If the option is found without any arguments, your program will exit non-zero and print out an error message.
Sets the usage-string printed by printHelp to string
; it is the first thing printed by printHelp
var argv = new Bebopt
.usage('hello')
.define('h', '\tprint this message and exit', function() {
this.printHelp();
process.exit(0);
}).parse(['-h']);
hello
-h print this message and exit
Parses args
, or process.argv
if args
is undefined.
The hash returned by .parse
is of the form:
{
<Option Name>: {
before: <Option Arg>,
after: <Value Returned By Option's Callback>
}
}
var argv = new Bebopt
.usage('hello')
.define('h:', '\tfoo', function(){}) // `-h' takes a required arg
.parse([
'-h',
'bar'
]);
console.log(argv);
// the callback didn't return anything: making `after' undefined.
{ h: { before: 'bar', after: undefined }}
var argv = new Bebopt
.usage('hello')
.define('h:', '\tfoo', function(){ return true; })
.parse([
'-h',
'bar'
]);
console.log(argv);
// the callback returned `true'.
{ h: { before: 'bar', after: true }}
defines an option named name
.
The following name
suffixes have special meanings:
-
:
→ option accepts a required argument -
::
→ option accepts an optional argument -
<no suffix>
→ option does not accept any arguments; defaults to true when present, and false when absent.
The help-text
and callback
args can be passed in any order, so long as they come after name
.
Short options are limited to single character names. (e.g. h
, v
)
.define('h', 'foobar', function(){}); // defines `-h'
Long options are limited to multi-character names. (e.g. help
, version
)
.define('help', 'foobar', function(){}); // defines `--help'
define aliases for an immediately preceding option definition.
calling .alias
without prefacing it with an option defintion will raise an exception.
var argv = new Bebopt
.usage('hello')
.define('h', '\tfoo', function(){})
.alias('help')
.parse(['--help'])
hello
foo
Public functions intended to only be used within option callbacks.
prints program usage, followed by the help text for each option defined.
see usage for an example.
If given a single argument, log will print the output of util.inspect(ARG)
to stdout; when multiple arguments are present, log prints the even ones to stdout using process.stdout.write()
, and then inspects the odd ones as expected.
var argv = new Bebopt
.usage('hello')
.define('i', 'blah', function(i) {
this.log(i);
})
.parse(['-i']);
1 // boolean flag `-i' appeared one time