Pargv NPM | npm.io

Pargv 2.x

Pargv is a CLI argument parsing library. While similar to Yargs or Commander it differs in that it focuses on commands. Without custom logic/help most libs lump options together where most real CLI tools require different argument and option requirements. Pargv takes aim at that issue. For this reason Pargv is likely more suited to larger CLI modules.

New (v2.1.x)

The minor version upgrade from 2.0.x to 2.1.x should be compatible with older configs. You may see deprecation warnings which will indicate the new method or property name to be used however your config should still work. The reason for the minor upgrade is a lot of refactoring was done and several new methods and properties were created. Handling of help was significantly simplified. It was just overly complex and needed to be simplified. Additionally added events see events below for details.

Tutorial Video

This is a bit dated but still largely relevant. To be safe also view docs

See >> https://www.youtube.com/watch?v=c2tg32oNC8E

Installation

You can probably do this in your sleep but for completeness...

$ npm install pargv

OR (exlude dev dependencies)

$ npm install pargv  --production

Quick Start

Import or require then new up an instance of Pargv.

Basic Example

import { Pargv } from 'pargv';

// For ES5
// const Pargv = require('pargv').Pargv;

const pargv = new Pargv(/* your options */);

pargv.command('generate <template>')
  .action((template, parsed, command) => {
    // template - the <template> sub command you defined in your command.
    // parsed - the resulting parsed object see more on this below.
    // command - the command instance that Pargv generated.
  });

const parsed = pargv.parse(); // if array of args not passed process.argv will be used.

More Examples EXAMPLES.md

Advanced Example

import { Pargv } from 'pargv';

// For ES5
// const Pargv = require('pargv').Pargv;

const pargv = new Pargv({ locale: 'en', headingDivider: '#', extendCommands: true });

// Command requires template name with optiona directory path.
pargv.command('generate <template> [directory]')

  // Creates option extension with description.
  .option('--extension, --ext [ext]', 'The template\'s extension.')

  // Option to mock force.
  .option('--force, -f', 'When present forces overwrite')

  // Adds alias for extension.
  .alias('--extension', '-e')

  // Adds description for "directory" sub command.
  .describe('directory', 'The directory path to save the template to.')

  // Note we specify --ext, we could also specify -e or --extension
  // Pargv will figure it out meaning you can use the primary or an alias
  // as your key.
  .when('--force', '--ext')

  // Sets a default value for the extension option.
  .default('--extension', '.html')

  // Ensures the value for extension is contained in our expression.
  .coerce('--extension', /^\.(html|hbs|ejs)$/, 'could set default val here as well')

  .coerce('directory', (value, command) => {
    // value is the argument value.
    // command the PargvCommand instance.
    // do something and return value.
    return value;
  })

  .action((template, parsed, command) => {
    // template - the <template> sub command you defined in your command.
    // parsed - the resulting parsed object see more on this below.
    // command - the command instance that Pargv generated.
  })
  .exec(); // the above action will be called.

More EXAMPLES.md here.

Options

Pargv options, descriptions and defaults.

Colors

For supported colors see colurs. The below colors property in options suports single string value or array of strings supported in colurs.

For example if you wanted the primary color in help to have a background you might set your options as follows:

const opts = {
  colors: {
    primary: ['bold', 'bgBlue', 'white'] // result: bold white text with blue background.
  }
}

Parse & Execute

Using our above example to call the action associated with generate we would call the exec method. Calling the exec method parses your arguments and then calls the associated action.

If you do not wish to execute the action you can simply parse and handle the result yourself.

Exec Method

pargv.exec(process.argv);

Parse Method

const parsed = pargv.parse(process.argv)

Parsed Result

Consider the following executed in your terminal and its corresponding configuration below:

$ app generate about --ext .html

const parsed = pargv.command('generate <template> --ext <ext>')
  .parse(process.argv);

The parsed result would be:

parsed = {
  $exec: 'example',
  $command: 'generate',
  $commands: [ 'about' ],
  $source: [ 'generate', 'about', '--ext', '.html' ],
  ext: '.html'
}

Convention Syntax & Types

The following section describes how Pargv parses tokens and conventions in your commands and options as well as how built in Type casting and type checks work.

Pargv Syntax

Commands and options have a handy syntax that limits the need for chained calls. For example to denote an argument as required simply wrap in . See below for more examples.

Tokens

Commands, Options & Chaining API

You can create your commands and options using Pargv's syntax or using the chaining API. Both do exactly the same and support either or as well as both. There are some features which are only available through the chaining API but we'll get to those in a moment.

// Command: login           Aliases: log, l
// Sub Command: url        (required)
// Option: username         Aliases: --user, -u
// Option: password         Aliases: --pass, -p
pargv.command('login.log.l <url> --username.user.u [username] --password.pass.p [password]');

// The below is the same as above.
pargv.command('login <url>')
  .alias('login', 'log', 'l') // or .alias('login', ['log', 'l'])
  .option('--username, --user, -u [username]')
  .option('--password, --pass, -p [password]');

Spcifying Types

When creating a command or option you can specify types for sub commands and options which take values. Pargv will then attempt to cast to these types where applicable and also do some type checking to ensure the result is the correct type. If you wish you can allow casting but disable type checking when initializing Pargv (see options).

Essentially these types are nothing more than internal coercions methods. If you choose to pass a custom coercion method then any defined types will be ignored as Pargv assumes you want to handle that manually.

The following are the current supported types:

date, boolean, array, regexp, object number, float, integer, string, json

// Creates Command: query which requires a sub command of table name.
// Option: start          Type: date
// Option: end            Type: date
// Option: max            Type: integer
pargv.command('query <tablename> --start [start:date] --end [end:date] --max [max:integer]');

Argument Conventions

Arguments can be entered in your terminal in a couple different ways for certain types and options. For example you can enter flag options as follows:

$ generate contact --ext .html

$ generate contact --ext=.html

For puposes of this example assume we have the following option flags in our config. In this case we're mocking overwriting a template after backing it up and then we want to publish our changes. Again This is just all a mock but you get the idea.

NOTE: In our example below how -fbp are all together. This is possible when prefixed with a single -.

Pargv will then breakout each flag to its own argument.

-f force -b backup -p publish

$ generate aboutus --ext .html -fbp

Becomes

const args = ['generate', 'aboutus', '--ext', '.html', '-f', '-b', '-p'];

API

Please pull source and see docs initially this readme displayed tables denoting properities and methods for class instances but it's too difficult to keep in sync see docs instead.

Events

The below events should not be confused with methods such as onLog, onError or onHelp. Those methods allow intercepting the actual log, error or help handler whereas events simply listen to the emitted events. For example if you simply wish to log to a file or something you could call .on('log', your_handler). If you wanted to intercept all log events and handle them yourself use the onLog(handler) which will prevent them from being output to the terminal. You would need to handle this yourself.

Localization

The following are the supported languages however you could certainly copy the built in locales located in node_modules/pargv/locales of your project and then extend with whatever language you prefer. It's as simple as creating a copy of en.json file then changing the values to your language. Then initialize Pargv with that locale and you're off.