unified-args

Interface for creating CLIs around unified processors. Wrapper around the engine to configure it with command-line arguments. Should be required and configured in an executable script, on its own, as it handles the whole process.

Installation

npm:

npm install unified-args

Usage

This example creates a CLI for remark, loading remark- plugins, searching for markdown files, and loading configuration and ignore files.

cli (executable: chmod +x cli):

#!/usr/bin/env node
'use strict';

var start = require('unified-args');
var extensions = require('markdown-extensions');
var remark = require('remark');
var pack = require('remark/package.json');

var name = pack.name;

start({
  'processor': remark,
  'name': name,
  'description': pack.description,
  'version': pack.version,
  'pluginPrefix': name,
  'extensions': extensions,
  'packageField': name + 'Config',
  'rcName': '.' + name + 'rc',
  'ignoreName': '.' + name + 'ignore'
});

API
- start(configuration)
CLI
Diagnostics
Debugging
License

API

`start(configuration)`

Create a CLI for a unified processor.

`configuration`

All options are required.

processor (Processor) — Processor to transform files (engine: processor).
name (string) — Name of executable.
description (string) — Description of executable.
version (string) — Version of executable.
extensions (Array.<string>) — Default file extensions to include. (engine: extensions).
ignoreName (string) — Name of ignore files to load. (engine: ignoreName).
rcName (string) — Name of configuration files to load. (engine: rcName).
packageField (string) — Property at which configuration can be found in package.json files. (engine: packageField).
pluginPrefix (string) — Prefix to use when searching for plug-ins (engine: pluginPrefix);
presetPrefix (string) — Prefix to use when searching for presets from config files (engine: presetPrefix).

CLI

CLIs created with unified-args, such as the example above, creates an interface similar to the below (run cli --help for accurate information):

Usage: remark [options] [path | glob ...]

  Markdown processor powered by plugins

Options:

  -h  --help                output usage information
  -v  --version             output version number
  -o  --output [path]       specify output location
  -r  --rc-path <path>      specify configuration file
  -i  --ignore-path <path>  specify ignore file
  -s  --setting <settings>  specify settings
  -e  --ext <extensions>    specify extensions
  -u  --use <plugins>       use plugins
  -p  --preset <presets>    use presets
  -w  --watch               watch for changes and reprocess
  -q  --quiet               output only warnings and errors
  -S  --silent              output only errors
  -f  --frail               exit with 1 on warnings
  -t  --tree                specify input and output as syntax tree
      --file-path <path>    specify path to process as
      --tree-in             specify input as syntax tree
      --tree-out            output syntax tree
      --[no-]stdout         specify writing to stdout (on by default)
      --[no-]color          specify color in report (on by default)
      --[no-]config         search for configuration files (on by default)
      --[no-]ignore         search for ignore files (on by default)

Examples:

  # Process `input.md`
  $ remark input.md -o output.md

  # Pipe
  $ remark < input.md > output.md

  # Rewrite all applicable files
  $ remark . -o

All non-options are seen as input and can be:

Paths (cli README.txt) and globs (cli *.txt) pointing to files to load.
Paths (cli test) and globs (cli fixtures/{in,out}) pointing to directories. These are searched for files with known extensions which are not ignored by patterns in ignore files. The default behaviour is to exclude files in node_modules and hidden directories (those starting with a dot: .).

Default: none;
Engine: globs.

`--help`

cli --help

Output short usage information.

Default: off;
Alias: -h.

`--version`

cli --version

Output version number.

Default: off;
Alias: -v.

`--output [path]`

cli . --output
cli . --output doc
cli input.txt --output doc/output.text

Whether to write successfully processed files, and where to. Can be set from configuration files.

If output is not given, files are not written to the file-system;
If output is given without path, input files are overwritten when successful;
If output is given with path and it points to an existing directory, files are written to that directory;
If output is given with path, the parent directory of that path exists, and one file is processed, the file is written to the given path.

Default: off;
Alias: -o;
Engine: output.

`--rc-path <path>`

cli . --rc-path config.json

File-path to a JSON configuration file to load, regardless of --config.

Note: Be careful not to pass a file which is also detected.

Note: Do not pass package.json files or .js files.

Default: none;
Alias: -r;
Engine: rcPath.

`--ignore-path <path>`

cli . --ignore-path .gitignore

File-path to an ignore file to load, regardless of --ignore.

Default: none;
Alias: -i;
Engine: ignorePath.

`--setting <settings>`

cli input.txt --setting alpha:true
cli input.txt --setting bravo:true --setting '"charlie": "delta"'
cli input.txt --setting echo-foxtrot:-2
cli input.txt --setting 'golf: false, hotel-india: ["juliet", 1]'

Configuration for the parser and compiler of the processor. Can be set from configuration files.

The given settings are JSON, with two exceptions:

Surrounding braces must not be used: "foo": 1, "bar": "baz" is valid;
Keys do not need to be quoted: both "foo": "bar" and foo: "bar" are considered equal.

Keys are camel-cased: foo-bar: true and fooBar: true are treated the same.

Default: none;
Alias: -s;
Engine: settings.

`--use <plugin>`

cli input.txt --use man
cli input.txt --use 'lint=alpha:"bravo"'

Plug-in to load by its name or path, optionally with options, and use on every processed file. Can be set from configuration files.

To pass options, follow the plugin by an equals sign (=) and settings, which have the same in syntax as --setting <settings>.

Prefers plug-ins prefixed with the configured pluginPrefix.

Default: none;
Alias: -u;
Engine: plugins.

`--preset <presets>`

cli input.txt --preset lint-recommended
cli input.txt --preset 'minify=force:true'

Preset to load by its name or path, optionally with options. Can be set from configuration files.

To pass options, follow the plugin by an equals sign (=) and settings, which have the same in syntax as --setting <settings>.

Prefers presets prefixed with the configured presetPrefix.

Default: none;
Alias: -p;
Engine: presets.

`--ext <extensions>`

cli . --ext html
cli . --ext html,htm

Specify one or more extensions to include when searching for files.

If no extensions are given, uses the configured extensions.

Default: Configured extensions;
Alias: -e;
Engine: extensions.

`--watch`

cli . -w

Process as normal, then watch found files and reprocess when they change.

The watch is stopped when SIGINT is received (usually done by pressing CTRL-C).

If --output is given without path it is not honoured, to prevent an infinite loop. When the watch closes, a final process runs including --output.

cli . -oqw

Yields:

Watching... (press CTRL+C to exit)
Note: Ignoring `--output` until exit.

Default: off;
Alias: -w.

`--tree`

cli --tree < input.json > output.json

Treat input as a syntax tree in JSON and output the transformed syntax tree. This runs neither the parsing nor the compilation phase.

Default: off;
Alias: -t;
Engine: tree.

`--tree-in`

cli --tree-in < input.json > input.txt

Treat input as a syntax tree in JSON. This does not run the parsing phase.

Default: off;
Engine: treeIn.

`--tree-out`

cli --tree-out < input.txt > output.json

Output the transformed syntax tree. This does not run the compilation phase.

Default: off;
Engine: treeOut.

`--quiet`

cli input.txt --quiet

Ignore files without any messages in the report. The default behaviour is to show a success message.

Default: off;
Alias: -q;
Engine: quiet.

`--silent`

cli input.txt --silent

Show only fatal errors in the report. Turns --quiet on.

Default: off;
Alias: -S;
Engine: silent.

`--frail`

cli input.txt --frail

Exit with a status code of 1 if warnings or errors occur. The default behaviour is to exit with 1 on errors.

Default: off;
Alias: -f;
Engine: frail.

`--file-path <path>`

cli --file-path input.txt < input.txt > doc/output.txt

File path to process the given file on stdin(4) as, if any.

Default: none;
Engine: filePath.

`--stdout`

cli input.txt --no-stdout

Whether to write a processed file to stdout(4).

Default: off if --output or --watch are given, or if multiple files are processed;
Engine: out.

`--color`

cli input.txt --no-color

Whether to output ANSI codes in the report.

Default: whether the terminal supports colour;
Engine: color.

`--config`

cli input.txt --no-config

Whether to load configuration files.

Searches for files with the configured rcName ($rcName and $rcName.js) and looks for the configured packageField in package.json files.

Default: on;
Engine: detectConfig.

`--ignore`

cli . --no-ignore

Whether to load ignore files.

Searches for files with named ignoreName.

Default: on;
Engine: detectIgnore.

Diagnostics

CLIs created with unified-args exit with:

1 on fatal errors;
1 on warnings in --frail mode;
0 on success.

Debugging

CLIs can be debugged by setting the DEBUG environment variable to *, such as DEBUG="*" cli example.txt.

kgryte/unified-args