README
blargs
(think the expression "BLARG" munged with "args")
Check the changelog for notes on what has been done between releases.
Versatile argument parser with command-line test utility
While it is not my general goal to re-create something that has been exhaustively developed and engineered, I often find myself needing features that are not consistently available from a single source. blargs is an attempt to create a simple, reliable, performant and consistent argument parser that can be used as-is or wrapped by other utilities.
While this project is vastly different in implementation, I would like to give a shout-out to some projects I have used over the years that influenced some of the features I have added:
Check This
# can also be used in your project
npm install -g blargs
# test using the command-line test utility
blargs "is this" -a --test
# => [ { a: true, test: true }, [ 'is this' ], null ]
echo '"is this" -a --test' | blargs
# => [ { a: true, test: true }, [ 'is this' ], null ]
Wondering what that output means and how the hell it's useful? Read about programmatic usage and see the examples.
Quick Contents
Tool Features
- Treats command-line arguments as a context-free grammar (an un-opinionated language)
- Handles strings and arrays of arguments
- Performs quite well
- Returns an ES6 destructurable iterable (compatible with ES5 by array index) which ensures all keys on named-arguments object are valid (see below)
- Comes with a useful command-line argument testing utility so you don't need to write your own just to see how it will break down your arguments
Language Features
- negateable booleans (-no-x,--no-xarg)
- multiple boolean short-hand args (-abcd, -no-abcd)
- (recursive) subarg notation support
- (recursive) next-argument handling
- multiples of same argument support
Booleans
# standard single argument declarations
-a # a -> true
-a true # a -> true
-a=true # a -> true
-no-a # a -> false
-a false # a -> false
-a=false # a -> false
# multiple short-hand argument booleans in single statement
-abcd # a, b, c and d -> true
-no-abcd # a, b, c and d -> false
# full argument flag
--arg # arg -> true
--no-arg # arg -> false
--arg=true # arg -> true
--arg=false # arg -> false
Assignment
# standard single argument assignment methods
-a value # NOTE that positional arguments after short-hand are assigned
-a=value
-a "value with spaces"
-a 'value with spaces'
-a="value with spaces"
-a='value with spaces'
--arg=value
--arg="value with spaces"
--arg='value with spaces'
Positionals
# positional arguments can be anywhere except after single short-hand boolean
arg1 arg2 -a # cannot place positional argument here
arg1 arg2 -abc arg3 # can place positional argument here
Subargs
# subargs must be assigned but may be nested (spaces inside bracket not required)
-a [ arg -abc --arg=value ]
-a=[ arg -abc --arg=value ]
--arg=[ arg -abc --arg=value ]
# nested example
-a [ arg -abc --arg=[ nested -abc ] ]
Next-Argument
Sometimes it is useful to specify multiple ordered commands. These next-arguments can be nested inside subargs and next-arguments can be nested inside subargs.
# if -- is encountered the previous command is considered "complete"
--arg=value -- -abc --arg
# you can nest next-arguments in subargs
--arg=[ arg -- -abc --arg ] -- -abc --arg
# you can nest subargs in next-arguments
--arg=value -- -abc --arg=[ arg -abc ]
Programmatic Usage
Internally (and soon, hopefully to be publicly available) blargs is wrapped by an argument validator and sanitizer (another project of mine). However, there are plenty of reasons you may want to use blargs by itself.
Let me take a second to describe how to use it and then I will explain why it returns what it does.
Including the project is a snap, npm install --save blargs (if you install from github you will need to npm install && npm run prepublish to generate the executable code since it uses Babel to transpile).
In your project you could then:
import blargs from 'blargs';
// or in ES5
// var blargs = require('blargs');
// designed first for ES6 to cleanly separate the return values
// by their context and meaning
let [ args, positionals, next ] = blargs();
// in ES5 the equivalent would be
var ret = blargs();
var args = ret[0];
var positionals = ret[1];
var next = ret[2];
Note that blargs() accepts nothing, or an array of arguments, or a string to be parsed as arguments. When you call it without arguments, it automatically uses those provided by Node.
// same as passing it process.argv.slice(2)
blargs();
blargs(['-a','-b','--arg="spaces are dope"']);
blargs('-a -b --arg="spaces are dope"');
Assigned values are included as named keys on the first return value (always an object even if it has no keys). Because we keep positional arguments and next-arguments sub-expressions out of the initial return value you can safely assume that any keys are valid.
// assuming args of -abc
args.a === true;
args.b === true;
args.c === true;
Object.keys(args) // safely use all keys, no reserved words to avoid
// we can also use non-alpha short-hand characters although some are
// ill-advised especially since some characters can't actually be used
// on the command-line (at least not bash)...
[ args ] = blargs('-abc -0 -$#@');
args['0'] === true;
args.a === true;
args.b === true;
args.c === true;
args['