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.

Option

Description

Default

cast

When true Pargv tries to auto cast values to type.

True

splitArgs

when args[0] is ONLY arg and string split to array by specified char. Null to disable.

null

colorize

Whether to use colors in help/log messages.

True

displayHeader

When true help header is displayed.

True

displayFooter

When true help footer is displayed.

True

displayNone

When Arguments & Options show "none" in help otherwise hidden.

True

displayTitles

When true Arguments & Options titles displayed in help.

True

headingDivider

A string repeated for heading/footing in help.

><><

commandDivider

A string divider repeated between command help.

locale

The i18n locale to use for messages/help.

localeDir

A directory for locales if u wish to roll your own.

undefined

defaultHelp

When true commands automatically to help.

True

exitHelp

Exit after displaying help.

True

layoutWidth

The width of help text layout.

castBeforeCoerce

When true will attempt to cast to type before coerce is called.

True

extendCommands

When true known sub commands extended as properties in result.

False

extendAliases

When true option aliases extended to result.

False

extendStats

When true stats object is extended to results.

False

spreadCommands

When true commands are spread in action callback.

True

allowAnonymous

When true anonymous sub commands and options are allowed.

True

ignoreTypeErrors

When true type checking is ignored.

False

colors

Option	Description	Default
primary	The primary color in help.	blue
accent	The accent color in help.	cyan
alert	The alert, error or required color in help.	red
muted	The muted color in help.	gray

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

Argument	Description
`<value>`	denotes a required command or option.
`[value]`	denotes an optional command or option.
--option	denotes an option flag.
-o	denotes short option flag.
generate.gen.g	results in gen & g as aliases for generate command.
--extension.ext.e	results in ext & e as aliases for extension option.
`[value:float]`	value should be of type float.
`[other...]`	denotes variadic (must be last command) remaining commands pushed to single array.
-fsb	single - breaks out to '-f', '-s', '-b'
--ext=html	is the same as --ext html

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.

log	when not overridden listens to log events.
error	when not overridden listens to error events.
completion	listens to completion, returns completion results.
help	when not overridden listens to show help events.

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.

English
Spanish
French
Hindi
Italian
Japanese
Russian
Chinese (Simplified)
Chinese (Traditional)

Examples

See EXAMPLES.md

Docs

See https://origin1tech.github.io/pargv/

Change

See CHANGE.md

License

See LICENSE.md