README
executed
Frustration-free CLI package for Node.js
Plans
- Testing via
mocha
- Blank option with flag setup
- Access to inbuilt functions
Installation
npm install executed --save
Setup
Firstly, create a js
file specifically for setting up executed
and your options/flags. While this file can live anywhere in your project, bin/index.js
is recommended.
You should then add #!/usr/bin/env node
to the top of your bin/index.js
file. This will tell the command line to run this file using node
.
Below this line, you should then import executed
, this can be accomplished with the line var executed = require("executed")
. You should also add your program's information, use executed.setInfo(name, version)
to achieve this.
Your bin/index.js
should look like this.
#!/usr/bin/env node
var executed = require("executed")
executed.setInfo("example", "1.0")
You should then add information to your package.json
to specify that you want to add a command with your package. If you placed your executed
file in bin/index.js
, adding the following to package.json
will suffice (changing example
to your desired command name).
"bin": {
"example": "./bin/index.js"
}
Adding an option
The option is the main part of the command when ran, it specifies what the user wishes to achieve. For example in the command example help
, help
would be the option of the command. Adding an option is as simple as this.
executed.setOption("version", "Display the program's version number", false, function(flags) {
console.log("Version v1.0")
})
setOption
's arguments can be broken down like this, executed.setOption(name = string, description = string, input = boolean, callback = function)
callback
is the callback function that is ran when the option is called. The function is fed one guaranteed argument, flags
, a dictionary with the flags used and their input, and another argument input
that is only fed when the option requires an input specified through the input
argument (more below).
An example of the flags
dictionary can be seen here, {verbose: undefined, output: file.txt}
. If the flag doesn't require an input, the value of the flag will simply be undefined
.
With an input
An option's input is the text that is specified alongside the option when the command is ran. For example in the command example build index.x
, index.x
would be the input.
The input
argument, as seen above, is a boolean that specifies if the option requires an input. Specifying true
will mean that the callback function is fed a second argument with the input.
executed.setOption("read", "Read a file", true, function(flags, input) {
var contents = read(input)
console.log(result)
})
Adding a flag
Flags are additional options that the user can specify alongside the main option. For example the flag --verbose
would display more detailed information about the task being ran. Adding flags are very similar to adding options, minus the callback.
executed.setFlag("verbose", "v", "Display additional information", false)
setFlag
's argument can be broken down like this, executed.setFlag(name = string, short = string, description = string, input = boolean)
The short
argument is the short form of the flag, you can call the flag using either the short or long form. However, short forms can be used on the same -
like so, example version -va
. This command can be broken down into --verbose
and -all
.
With an input
A flag's input is similar to an option's input, it's text that is used alongside the flag. However for the text to be considered a flag's input, it must be used directly next to the flag. For example in example build --output test test.x
, test
would be considered --output
's input, and test.x
is build's input.
To set a flag to require an input, simply set the input
argument as true
.
executed.setFlag("output", "o", "Output result to a file", true)
Parsing
Once information, options and flags have all been setup, the final line executed.parse()
should be ran. While parse
requires no arguments and instead uses process.argv
by default, an array can be used as the only argument to parse the array instead.
Examples
Detecting flags
executed.setOption("version", "Display the program's version number", false, function(flags) {
if ("verbose" in flags) {
console.log("example v0.1 published on 18/7/17")
} else {
console.log("example v0.1")
}
})
The command example version -v
would then output example v0.1 published on 18/7/17
.
With an input
executed.setOption("read", "Read a file", true, function(flags, input) {
var contents = read(input)
console.log(result)
if ("output" in flags) {
write(flags["output"], result)
}
})
The command example read file.txt -o clone.txt
would write the contents of file.txt
to the command line and the file clone.txt
.
Help
An automatic help option is built in to all executed
CLIs, this automatically lists the commands and flags alongside their descriptions. However, if you want to build your own custom help option, it can be fully overwritten with setOption
.