argpa v1.0.2

argpa

WARNING: this is a work in progress, the API might change significantly in future versions.

Middleweight arg parsing library.

npm install argpa

Usage

const Argpa = require('argpa')

const cmd = new Argpa()
const argv = '-a -b c'.split(' ')
const { alpha, beta } = cmd.parse(argv, {
  boolean: ['alpha'],
  string: ['beta'],
  alias: {
    alpha: 'a',
    beta: 'b'
  }
})
console.log(alpha) // prints true
console.log(beta)  // prints 'c'

API

The module exports a class, the constructor for it is

const cmd = new Argpa(flags, help, teardown)

All three arguments are optional.

flags defines the general flags that should be available to all commands and subcommands. Defaults to []

help defines a helper function to run with --help in complex CLIs. It can be invoked with any command or subcommand, and it gets passed the commandName as argument. It's called by cmd.run Defaults to function (commandName) { return commandName }

teardown defines a function that gets run at the end of cmd.run()as

finally {
  await this.teardown()
}

It defaults to the noop function () {}

cmd.add(commandName, fn)

This method introduces a command with an associated function. When invoked via cmd.run, the function will be passed the flags and arguments that follow the command, for example

command subcommand -flag argument

will invoke the command command subcommand by calling its associated function and passing to it ['-flag', 'argument']. You can parse that argument array inside the function, using cmd.parse

const x = await cmd.run(argv = argv = process.argv.splice(2))

This async method is probably going to be the starting point of the CLI, it will parse the argument array and select the correct command between the ones added. It also launches the help function if the array contains --help.

const result = cmd.parse(argv = process.argv.splice(2), opts = {})

This method is the main parser of the library. It parses the provided array of arguments and return an object that contains a key/value entry for each flag/argument, plus a _ entry for an array of positional arguments, and a -- entry for an array of arguments passed down using --. The opts object can have the following properties:

{
  boolean: [],
  string: [],
  alias: {},
  default: {},
  validate: true 
}

boolean is an array of the flags you want to have a boolean value. Boolean flags will be true by default, unless prepended with no-, in which case they will be false

string is an array of the flags you want to have a string value.

alias is a key/value pairing of flags and their aliases.

default is a key/value pairing of flags and their default values.

validate will make the parser throw an error if an unknown flag is called.

The arguments of list flags, like --numbers=1,2,3, will automatically be parsed as strings, in this case 1,2,3

Summary

If you don't need subcommands, you just construct your parser with const cmd = new Argpa(...) and use cmd.parseto parse the provided arguments.

If you need something more complex

• construct your parser with const cmd = new Argpa(...)
• use cmd.add to add commands & subcommands and associate them to functions
• use cmd.parse inside those functions to define specialized parsers for the flags&arguments of those commands
• launch the parser with cmd.run