rawrg v0.1.2

Rawrg

Lightweight and easy-to-use utility library for splitting command line strings and parsing command line arguments.

Written in TypeScript and transpiled to JavaScript. Comes as an ES6 or CommonJS module, or a browser-ready minified IIFE.

Examples

# npm
$ npm install rawrg --save-dev

# yarn
$ yarn add rawrg --dev

// ES6
import * as rawrg from 'rawrg';

// CommonJS
var rawrg = require('rawrg');

var commandLine = 'my-tool run --pretty -o "my file.txt"; my-tool load "my file.txt"';
var commands = rawrg.split(commandLine);

// [
//   ["my-tool", "run", "--pretty", "-o", "my file.txt"],
//   ["my-tool", "load", "my file.txt"]
// ]

var acceptedOptions = [
  'help h?',
  'pretty',
  'output o!',
];
var parsedCommand = rawrg.parse(commands[0], acceptedOptions);

// {
//   "args": ["my-tool", "run"],
//   "opts": {
//     "pretty": true,
//     "output": "my file.txt"
//   }
// }

API

rawrg.split(commandLine: string): string[][]

Splits a raw string of user input from a command line into commands and arguments, using semicolons to delimit command and whitespace to delimit arguments.

Delimiters can be escaped by wrapping them in single or double quotes. Quotes can in turn be escaped with backslashes.

split() is intended to closely match how Windows splits command line input into arguments.

rawrg.parse(args: string[], optdefs: string[]): ParseResult

Parses an array of command line arguments and an array of options declarations and returns a ParseResult object containing positional arguments and options.

parse() follows common conventions and is able to recognize long options (--some-option), stacked short options (-abc) and the -- argument/option separator.

parse() also recognizes different ways of setting option arguments (provided the option takes an argument):

• implicitly as the next argument (--some-option 123 or -a 123)
• explicitly with an equals sign (--some-option=123 or -a=123)
• immediately after a short argument (-a123)

If any unknown options (i.e. options not defined in the array of optdefs passed to the function) are encountered during parsing, they will listed in the result object under the properties unknown.shorts and unknown.longs.

Option declarations

Options declarations (or optdefs for short) are strings that define an option's name and type (whether it takes no arguments, an optional argument or a required argument), as well as an optional single-character short alias. Optdefs should be structured as follows:

• With or without short alias:
  • some-option
  • option-with-short-alias a
• With or without an optional/required argument:
  • boolean-option
  • option-with-optional-arg?
  • option-with-required-arg!
• With short alias and with or without an optional/required argument:
  • boolean-with-short b
  • optional-with-short o?
  • required-with-short r!

ParseResult

ParseResult is the object returned by parse() and contains the positional arguments and options found when parsing.

If any unknown options are encountered during parsing, they will be listed under the unknown property, which means that you can check for any unknown options simply by doing 'unknown' in result.

interface ParseResult {
  args: string[];
  opts: {
    [name: string]: string | true | undefined;
  };
  unknown?: {
    shorts: {
      [shortName: string]: string | true | undefined;
    };
    longs: {
      [longName: string]: string | true | undefined;
    };
  };
}

Testing

# npm
$ npm test

# yarn
$ yarn test

Building

# npm
$ npm run build

# yarn
$ yarn build

Building requires Java to be installed on your machine as Google Closure Compiler is used as a minifier.

License

Licensed under Apache 2.0.

Contributing

Please do! If you have any suggestions, bug reports/fixes or improvements, either add a new issue or submit a pull request. All that I request is that you try to adhere to the coding style that is already in place and that you do not break anything.