All Projects → vercel → Arg

vercel / Arg

Licence: mit
Simple argument parsing

Programming Languages

javascript
184084 projects - #8 most used programming language

Projects that are alternatives of or similar to Arg

Typin
Declarative framework for interactive CLI applications
Stars: ✭ 126 (-85.95%)
Mutual labels:  cli, command, parser
Sywac
🚫 🐭 Asynchronous, single package CLI framework for Node
Stars: ✭ 109 (-87.85%)
Mutual labels:  cli, command, parser
Jquery.terminal
jQuery Terminal Emulator - JavaScript library for creating web-based terminals with custom commands
Stars: ✭ 2,623 (+192.42%)
Mutual labels:  cli, command
Serve
a static http server anywhere you need one.
Stars: ✭ 233 (-74.02%)
Mutual labels:  cli, command
Nestjs Console
A nestjs module that provide a cli to your application.
Stars: ✭ 284 (-68.34%)
Mutual labels:  cli, command
Cbox
convert any python function to unix-style command
Stars: ✭ 154 (-82.83%)
Mutual labels:  cli, command
You Dont Need Gui
Stop relying on GUI; CLI **ROCKS**
Stars: ✭ 4,766 (+431.33%)
Mutual labels:  cli, command
Picocli
Picocli is a modern framework for building powerful, user-friendly, GraalVM-enabled command line apps with ease. It supports colors, autocompletion, subcommands, and more. In 1 source file so apps can include as source & avoid adding a dependency. Written in Java, usable from Groovy, Kotlin, Scala, etc.
Stars: ✭ 3,286 (+266.33%)
Mutual labels:  cli, parser
Swagger Cli
Swagger 2.0 and OpenAPI 3.0 command-line tool
Stars: ✭ 321 (-64.21%)
Mutual labels:  cli, parser
Tsukae
🧑‍💻📊 Show off your most used shell commands
Stars: ✭ 345 (-61.54%)
Mutual labels:  cli, command
Swaggen
OpenAPI/Swagger 3.0 Parser and Swift code generator
Stars: ✭ 385 (-57.08%)
Mutual labels:  cli, parser
Hiboot
hiboot is a high performance web and cli application framework with dependency injection support
Stars: ✭ 150 (-83.28%)
Mutual labels:  cli, command
Entrypoint
Composable CLI Argument Parser for all modern .Net platforms.
Stars: ✭ 136 (-84.84%)
Mutual labels:  cli, parser
Webpack Command
[DEPRECATED] Lightweight, modular, and opinionated webpack CLI that provides a superior experience
Stars: ✭ 218 (-75.7%)
Mutual labels:  cli, command
Simplecli
Command Line Interface Library for Arduino
Stars: ✭ 135 (-84.95%)
Mutual labels:  cli, command
Cliffy
NodeJS Framework for Interactive CLIs
Stars: ✭ 263 (-70.68%)
Mutual labels:  cli, command
Cobra
A Commander for modern Go CLI interactions
Stars: ✭ 24,437 (+2624.3%)
Mutual labels:  cli, command
Spectre.cli
An extremely opinionated command-line parser.
Stars: ✭ 121 (-86.51%)
Mutual labels:  cli, parser
Crudini
A utility for manipulating ini files
Stars: ✭ 292 (-67.45%)
Mutual labels:  cli, command
Mri
Quickly scan for CLI flags and arguments
Stars: ✭ 394 (-56.08%)
Mutual labels:  cli, parser

Arg CircleCI

arg is an unopinionated, no-frills CLI argument parser.

Installation

Use Yarn or NPM to install.

$ yarn add arg

or

$ npm install arg

Usage

arg() takes either 1 or 2 arguments:

  1. Command line specification object (see below)
  2. Parse options (Optional, defaults to {permissive: false, argv: process.argv.slice(2), stopAtPositional: false})

It returns an object with any values present on the command-line (missing options are thus missing from the resulting object). Arg performs no validation/requirement checking - we leave that up to the application.

All parameters that aren't consumed by options (commonly referred to as "extra" parameters) are added to result._, which is always an array (even if no extra parameters are passed, in which case an empty array is returned).

const arg = require('arg');

// `options` is an optional parameter
const args = arg(spec, options = {permissive: false, argv: process.argv.slice(2)});

For example:

$ node ./hello.js --verbose -vvv --port=1234 -n 'My name' foo bar --tag qux --tag=qix -- --foobar
// hello.js
const arg = require('arg');

const args = arg({
	// Types
	'--help':    Boolean,
	'--version': Boolean,
	'--verbose': arg.COUNT,   // Counts the number of times --verbose is passed
	'--port':    Number,      // --port <number> or --port=<number>
	'--name':    String,      // --name <string> or --name=<string>
	'--tag':     [String],    // --tag <string> or --tag=<string>

	// Aliases
	'-v':        '--verbose',
	'-n':        '--name',    // -n <string>; result is stored in --name
	'--label':   '--name'     // --label <string> or --label=<string>;
	                          //     result is stored in --name
});

console.log(args);
/*
{
	_: ["foo", "bar", "--foobar"],
	'--port': 1234,
	'--verbose': 4,
	'--name': "My name",
	'--tag': ["qux", "qix"]
}
*/

The values for each key=>value pair is either a type (function or [function]) or a string (indicating an alias).

  • In the case of a function, the string value of the argument's value is passed to it, and the return value is used as the ultimate value.

  • In the case of an array, the only element must be a type function. Array types indicate that the argument may be passed multiple times, and as such the resulting value in the returned object is an array with all of the values that were passed using the specified flag.

  • In the case of a string, an alias is established. If a flag is passed that matches the key, then the value is substituted in its place.

Type functions are passed three arguments:

  1. The parameter value (always a string)
  2. The parameter name (e.g. --label)
  3. The previous value for the destination (useful for reduce-like operations or for supporting -v multiple times, etc.)

This means the built-in String, Number, and Boolean type constructors "just work" as type functions.

Note that Boolean and [Boolean] have special treatment - an option argument is not consumed or passed, but instead true is returned. These options are called "flags".

For custom handlers that wish to behave as flags, you may pass the function through arg.flag():

const arg = require('arg');

const argv = ['--foo', 'bar', '-ff', 'baz', '--foo', '--foo', 'qux', '-fff', 'qix'];

function myHandler(value, argName, previousValue) {
	/* `value` is always `true` */
	return 'na ' + (previousValue || 'batman!');
}

const args = arg({
	'--foo': arg.flag(myHandler),
	'-f': '--foo'
}, {
	argv
});

console.log(args);
/*
{
	_: ['bar', 'baz', 'qux', 'qix'],
	'--foo': 'na na na na na na na na batman!'
}
*/

As well, arg supplies a helper argument handler called arg.COUNT, which equivalent to a [Boolean] argument's .length property - effectively counting the number of times the boolean flag, denoted by the key, is passed on the command line.. For example, this is how you could implement ssh's multiple levels of verbosity (-vvvv being the most verbose).

const arg = require('arg');

const argv = ['-AAAA', '-BBBB'];

const args = arg({
	'-A': arg.COUNT,
	'-B': [Boolean]
}, {
	argv
});

console.log(args);
/*
{
	_: [],
	'-A': 4,
	'-B': [true, true, true, true]
}
*/

Options

If a second parameter is specified and is an object, it specifies parsing options to modify the behavior of arg().

argv

If you have already sliced or generated a number of raw arguments to be parsed (as opposed to letting arg slice them from process.argv) you may specify them in the argv option.

For example:

const args = arg(
	{
		'--foo': String
	}, {
		argv: ['hello', '--foo', 'world']
	}
);

results in:

const args = {
	_: ['hello'],
	'--foo': 'world'
};

permissive

When permissive set to true, arg will push any unknown arguments onto the "extra" argument array (result._) instead of throwing an error about an unknown flag.

For example:

const arg = require('arg');

const argv = ['--foo', 'hello', '--qux', 'qix', '--bar', '12345', 'hello again'];

const args = arg(
	{
		'--foo': String,
		'--bar': Number
	}, {
		argv,
		permissive: true
	}
);

results in:

const args = {
	_:          ['--qux', 'qix', 'hello again'],
	'--foo':    'hello',
	'--bar':    12345
}

stopAtPositional

When stopAtPositional is set to true, arg will halt parsing at the first positional argument.

For example:

const arg = require('arg');

const argv = ['--foo', 'hello', '--bar'];

const args = arg(
	{
		'--foo': Boolean,
		'--bar': Boolean
	}, {
		argv,
		stopAtPositional: true
	}
);

results in:

const args = {
	_: ['hello', '--bar'],
	'--foo': true
};

Errors

Some errors that arg throws provide a .code property in order to aid in recovering from user error, or to differentiate between user error and developer error (bug).

ARG_UNKNOWN_OPTION

If an unknown option (not defined in the spec object) is passed, an error with code ARG_UNKNOWN_OPTION will be thrown:

// cli.js
try {
  require('arg')({ '--hi': String });
} catch (err) {
  if (err.code === 'ARG_UNKNOWN_OPTION') {
    console.log(err.message);
  } else {
    throw err;
  }
}
node cli.js --extraneous true
Unknown or unexpected option: --extraneous

FAQ

A few questions and answers that have been asked before:

How do I require an argument with arg?

Do the assertion yourself, such as:

const args = arg({ '--name': String });

if (!args['--name']) throw new Error('missing required argument: --name');

License

Copyright © 2017-2019 by ZEIT, Inc. Copyright © 2020 by Vercel, Inc.

Released under the MIT License.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].