unified-args
![Chat](https://img.shields.io/badge/chat-spectrum-7b16ff.svg)
Interface for creating CLIs around unified processors.
Wrapper around unifiedjs/unified-engine
to configure it with
command-line arguments.
Should be require
d and configured in an executable script, on its own, as it
handles the whole process.
unifiedjs.com
, the website for unified provides a good overview
about what unified can do.
Install
npm:
npm install unified-args
Use
This example creates a CLI for remark, loading remark-
plugins,
searching for markdown files, and loading configuration and
ignore files.
cli
(you can make it runnable with: 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'
})
Contents
API
start(configuration)
Create a CLI for a unified processor.
configuration
All options are required.
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
-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
--report <reporter> specify reporter
--file-path <path> specify path to process as
--ignore-path-resolve-from dir|cwd resolve patterns in `ignore-path` from its directory or cwd
--ignore-pattern <globs> specify ignore patterns
--silently-ignore do not fail when given ignored files
--tree-in specify input as syntax tree
--tree-out output syntax tree
--inspect output formatted 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 behavior is to exclude files in node_modules
and hidden
directories (those starting with a dot: .
) unless explicitly given
- Default: none
- Engine:
files
--help
cli --help
Output short usage information.
--version
cli --version
Output version number.
--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 (intermediate directories are not
created) - 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
.
- Default: none
- Alias:
-r
- Engine:
rcPath
--ignore-path <path>
cli . --ignore-path .gitignore
File path to an ignore file to load, regardless of
--ignore
.
--ignore-path-resolve-from dir|cwd
cli . --ignore-path node_modules/my-config/my-ignore --ignore-path-resolve-from cwd
Resolve patterns in the ignore file from its directory (dir
, default) or the
current working directory (cwd
).
--ignore-pattern <globs>
cli . --ignore-pattern docs/*.md
Additional patterns to use to ignore files.
--silently-ignore
cli **/*.md --silently-ignore
Skip given files which are ignored by ignore files, instead of warning about
them.
--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 JSON5, with one exception: surrounding braces must
not be used. Instead, use JSON syntax without braces, such as "foo": 1, "bar": "baz"
.
--report <reporter>
cli input.txt --report ./reporter.js
cli input.txt --report vfile-reporter-json
cli input.txt --report json
cli input.txt --report json=pretty:2
cli input.txt --report 'json=pretty:"\t"'
cli input.txt --report pretty --report json
Reporter to load by its name or path, optionally with options, and use to
report metadata about every processed file.
To pass options, follow the name by an equals sign (=
) and settings, which
have the same in syntax as --setting <settings>
.
The prefix vfile-reporter-
can be omitted.
Prefixed reporters are preferred over modules without prefix.
If multiple reporters are given, the last one is used.
Note
The quiet
, silent
, and color
options may not
work with the used reporter.
If they are given, they are preferred over the same properties in reporter
settings.
--use <plugin>
cli input.txt --use man
cli input.txt --use 'toc=max-depth:3'
Plugin 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>
.
Plugins prefixed with the configured pluginPrefix
are preferred
over modules without prefix.
- Default: none
- Alias:
-u
- Engine:
plugins
--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
.
--watch
cli . -qwo
Yields:
Watching... (press CTRL+C to exit)
Note: Ignoring `--output` until exit.
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 honored, to
prevent an infinite loop.
On operating systems other than Windows, when the watch closes, a final process
runs including --output
.
--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.
--tree-out
cli --tree-out < input.txt > output.json
Output the transformed syntax tree.
This does not run the compilation phase.
--inspect
cli --inspect < input.txt
Output the transformed syntax tree, formatted with
unist-util-inspect
.
This does not run the compilation phase.
--quiet
cli input.txt --quiet
Ignore files without any messages in the report.
The default behavior is to show a success message.
- Default: off
- Alias:
-q
- Engine:
quiet
Note
This option may not work depending on the reporter given in
--report
.
Note
The quiet
, silent
, and color
options may not
work with the used reporter.
--silent
cli input.txt --silent
Show only fatal errors in the report.
Turns --quiet
on.
- Default: off
- Alias:
-S
- Engine:
silent
Note
This option may not work depending on the reporter given in
--report
.
--frail
cli input.txt --frail
Exit with a status code of 1
if warnings or errors occur.
The default behavior 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.
--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 could be processed - Engine:
out
--color
cli input.txt --no-color
Whether to output ANSI color codes in the report.
Note
This option may not work depending on the reporter given in
--report
.
--config
cli input.txt --no-config
Whether to load configuration files.
Searches for files with the configured rcName
: $rcName
(JSON),
$rcName.js
(JavaScript), $rcName.yml
(YAML), and $rcName.yaml
(YAML); and
looks for the configured packageField
in package.json
files.
--ignore
cli . --no-ignore
Whether to load ignore files.
Searches for files named $ignoreName
.
Diagnostics
CLIs created with unified-args exit with:
1
on fatal errors1
on warnings in --frail
mode, 0
on warnings otherwise0
on success
Debugging
CLIs can be debugged by setting the DEBUG
environment variable to
*
, such as DEBUG="*" cli example.txt
.
Contribute
See contributing.md
in unifiedjs/.github
for ways
to get started.
See support.md
for ways to get help.
This project has a code of conduct.
By interacting with this repository, organization, or community you agree to
abide by its terms.
License
MIT © Titus Wormer