args-and-envs v0.4.3

args-and-envs

Command line and environment variable parser for all node apps.

This package was specifically written for the needs of Kubernetes-hosted applications. On Kubernetes, it isn't always easy setting a command line option, especially if the value of said command line option needs to come from a secret. This allows you to provide environment variable substitutes for command line options, and treats them as equivalents.

Installation

npm install --save ags-and-envs

Usage

  import parse from 'args-and-envs';

  // these are the command line arguments and environment variables we want
  // to parse for.
  let optionsDef = [
    { name: 'xfile',
      arg: ['--xfile', '-x'],
      env: 'FILE',
      required: false
    }
  ];

  // these are options for the parser.
  let parserOptions = {
    validator: {
      file: value => {value.length < 16;}
    }
  };

  let parser = new Parser(optionsDef, parserOptions);

  parser.parse();

  console.log(parser.errors);
  console.log(parser.argv);
  console.log(global.argv);

  // the xfile argument itself
  console.log(global.argv.xfile);

The first paramter is an array containing information about the expected command line options. The second is a set of options for how the options should be parsed.

Command Line Options

The command line options object has these details:

A note about lists

With the list type, the argument can appear multiple times in the command line. The parse will return an array of the values in that argument. For example a a script that takes multiple files with a command line like:

  $> script.js --file=text1.txt --file=text2.txt --file=text2

would parse to

  { file: ['text1.txt', 'text2.txt'. 'text3.txt'] }

With environment variables, of course, the list can only have one element in it because of the limitations of environment variables.

Lists can only get values from command line arguments or environment variables. Not both. Like all other parameters, if a command line argument exists, the environment variable is ignored.

Parser options

None of the parser options are required.

handler

The handler can be a function or an object. The function is called for all parameters; the object is a set of key=function pairs that are only called for individual functions. If this is an Array, it'll run the handlers in the array order.

handler functions

handler = (name, value, args) { ... }

• name - the name of the argument
• value - the value of the argument
• args - the entire set of arguments

handler object

handler = {
  name1: function(value1, args) { ... },
  name2: function(value2, args) { ... }
}

• name_x - the name of the argument
• value_x - the value of the argument
• args - the entire set of arguments

There is no need to define every needed parameter name. Any parameters not provided here will get the default handling.

Parse errors

If the command line cannot be parsed, it'll return a list of error objects with the following data:

Development

This package was specifically written for apps that run in Kubernetes, so future changes will mainly focus on features that would be useful to developers writing Kubernetes applications.

Specifically, array types are prioritized and usage guide generators are deprioritized.