executed v0.1.1

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.