unified-args
Advanced tools
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.
unifiedjs.github.io, the website for unified provides a good
overview about what unified can do. Make sure to visit it and try its
introductionary Guides.
npm:
npm install unified-args
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'
});
start(configuration)Create a CLI for a unified processor.
configurationAll options are required.
processor (Processor)
— Processor to transform files
(engine: processor)name (string)
— Name of executabledescription (string)
— Description of executableversion (string)
— Version of executableextensions (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)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
--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:
cli README.txt) and globs (cli *.txt) pointing
to files to loadcli 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: .) unless explicitly
givenfiles--helpcli --help
Output short usage information.
-h--versioncli --version
Output version number.
-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.
path, input files are overwritten when
successfulpath and it points to an existing directory,
files are written to that directory (intermediate directories are not
created)path, the parent directory of that path
exists, and one file is processed, the file is written to the given
path-ooutput--rc-path <path>cli . --rc-path config.json
File-path to a JSON configuration file to load, regardless
of --config.
-rrcPath--ignore-path <path>cli . --ignore-path .gitignore
File-path to an ignore file to load, regardless of
--ignore.
-iignorePath--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:
"foo": 1, "bar": "baz"
is valid"foo": "bar" and
foo: "bar" are considered equalTop-level keys are camel-cased: foo-bar: true and fooBar: true are treated
the same.
-ssettings--use <plugin>cli input.txt --use man
cli input.txt --use 'toc=max-depth:3'
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>.
Plug-ins prefixed with the configured pluginPrefix are
preferred over modules without prefix.
-uplugins--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.
extensions-eextensions--watchcli . -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 honoured,
to prevent an infinite loop. When the watch closes, a final process
runs including --output.
-w--treecli --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.
-ttree--tree-incli --tree-in < input.json > input.txt
Treat input as a syntax tree in JSON. This does not run the parsing phase.
treeIn--tree-outcli --tree-out < input.txt > output.json
Output the transformed syntax tree. This does not run the compilation phase.
treeOut--quietcli input.txt --quiet
Ignore files without any messages in the report. The default behaviour is to show a success message.
-qquiet--silentcli input.txt --silent
Show only fatal errors in the report. Turns --quiet on.
-Ssilent--frailcli 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.
-ffrail--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.
filePath--stdoutcli input.txt --no-stdout
Whether to write a processed file to stdout(4).
--colorcli input.txt --no-color
Whether to output ANSI color codes in the report.
color--configcli 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.
detectConfig--ignorecli . --no-ignore
Whether to load ignore files.
Searches for files named $ignoreName.
detectIgnoreCLIs created with unified-args exit with:
1 on fatal errors1 on warnings in --frail mode, 0 on warnings otherwise0 on successCLIs can be debugged by setting the DEBUG environment
variable to *, such as DEBUG="*" cli example.txt.
FAQs
create CLIs for unified processors
We found that unified-args demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.