Security News
JavaScript Leaders Demand Oracle Release the JavaScript Trademark
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
unified-args
Advanced tools
unified engine to create a command line interface from a unified processor.
--help
--version
--output [path]
--rc-path <path>
--ignore-path <path>
--ignore-path-resolve-from dir|cwd
--ignore-pattern <globs>
--silently-ignore
--setting <settings>
--report <reporter>
--use <plugin>
--ext <extensions>
--watch
--tree
--tree-in
--tree-out
--inspect
--quiet
--silent
--frail
--file-path <path>
--stdout
--color
--config
--ignore
This package wraps unified-engine
so that it can be used
to create a command line interface.
It’s what you use underneath when you use remark-cli
.
You can use this to let users process multiple files from the command line, letting them configure from the file system.
This package is ESM only. In Node.js (version 14.14+, 16.0+, or 18.0+), install with npm:
npm install unified-args
The following example creates a CLI for remark, which will search for files
in folders with a markdown extension, allows configuration from
.remarkrc
and package.json
files, ignoring files from
.remarkignore
files, and more.
Say our module example.js
looks as follows:
import {args} from 'unified-args'
import {remark} from 'remark'
args({
processor: remark,
name: 'remark',
description:
'Command line interface to inspect and change markdown files with remark',
version: '14.0.0',
pluginPrefix: 'remark',
packageField: 'remarkConfig',
rcName: '.remarkrc',
ignoreName: '.remarkignore',
extensions: [
'md',
'markdown',
'mdown',
'mkdn',
'mkd',
'mdwn',
'mkdown',
'ron'
]
})
…now running node example.js --help
yields:
Usage: remark [options] [path | glob ...]
Command line interface to inspect and change markdown files with remark
Options:
-h --help output usage information
…
This package exports the identifier args
.
There is no default export.
args(configuration)
Create a command line interface from a unified processor.
configuration
All options are required.
processor
(Processor
)
— processor to inspect and 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
)
— field where configuration can be found in package.json
s
(engine: packageField
)pluginPrefix
(string
)
— prefix to use when searching for plugins
(engine: pluginPrefix
)CLIs created with unified-args
, such as the example above, have an
interface similar to the below:
Usage: remark [options] [path | glob ...]
Command line interface to inspect and change markdown files with remark
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 passed to the cli are seen as input and can be:
readme.txt
) and globs (*.txt
) pointing to files to loadtest
) and globs (fixtures/{in,out}
) pointing to folders, which
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
folders (those starting with .
) unless explicitly givenYou can force things to be seen as input by using --
:
cli -- globs/* and/files
files
--help
cli --help
Output short usage information.
-h
--version
cli --version
Output version number.
-v
--output [path]
cli --output -- .
cli --output doc .
cli --output doc/output.text input.txt
Whether to write successfully processed files, and where to. Can be set from configuration files.
path
is not given, files are overwritten when successfulpath
points to a folder, files are written therepath
👉 Note: intermediate folders are not created.
-o
output
--rc-path <path>
cli --rc-path config.json .
File path to a configuration file to load, regardless of
--config
.
-r
rcPath
--ignore-path <path>
cli --ignore-path .gitignore .
File path to an ignore file to load, regardless of
--ignore
.
-i
ignorePath
--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
).
dir
ignorePathResolveFrom
--ignore-pattern <globs>
cli --ignore-pattern docs/*.md .
Additional patterns to use to ignore files.
ignorePatterns
--silently-ignore
cli --silently-ignore **/*.md
Skip given files which are ignored by ignore files, instead of warning about them.
silentlyIgnore
--setting <settings>
cli --setting alpha:true input.txt
cli --setting bravo:true --setting '"charlie": "delta"' input.txt
cli --setting echo-foxtrot:-2 input.txt
cli --setting 'golf: false, hotel-india: ["juliet", 1]' input.txt
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"
.
-s
settings
--report <reporter>
cli --report ./reporter.js input.txt
cli --report vfile-reporter-json input.txt
cli --report json input.txt
cli --report json=pretty:2 input.txt
cli --report 'json=pretty:"\t"' input.txt
# Only last one is used:
cli --report pretty --report json input.txt
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.
vfile-reporter
reporter
and
reporterOptions
👉 Note: the
quiet
,silent
, andcolor
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 --use remark-man input.txt
cli --use man input.txt
cli --use 'toc=max-depth:3' input.txt
cli --use ./plugin.js input.txt
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.
-u
plugins
--ext <extensions>
cli --ext html .
cli --ext html --ext htm .
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
-e
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
.
-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.
-t
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.
treeIn
--tree-out
cli --tree-out < input.txt > output.json
Output the transformed syntax tree. This does not run the compilation phase.
treeOut
--inspect
cli --inspect < input.txt
Output the transformed syntax tree, formatted with
unist-util-inspect
.
This does not run the compilation phase.
inspect
--quiet
cli --quiet input.txt
Ignore files without any messages in the report. The default behavior is to show a success message.
-q
quiet
👉 Note: this option may not work depending on the reporter given in
--report
.
--silent
cli --silent input.txt
Show only fatal errors in the report.
Turns --quiet
on.
-S
silent
👉 Note: this option may not work depending on the reporter given in
--report
.
--frail
cli --frail input.txt
Exit with a status code of 1
if warnings or errors occur.
The default behavior is to exit with 1
on errors.
-f
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.
filePath
--stdout
cli --no-stdout input.txt
Whether to write a processed file to stdout(4).
--color
cli --no-color input.txt
Whether to output ANSI color codes in the report.
color
👉 Note: This option may not work depending on the reporter given in
--report
.
--config
cli --no-config input.txt
Whether to load configuration files.
Searches for files with the configured rcName
: $rcName
and
$rcName.json
(JSON), $rcName.yml
and $rcName.yaml
(YAML), $rcName.js
(JavaScript), $rcName.cjs
(CommonJS), and $rcName.mjs
(ESM); and looks for
the configured packageField
in package.json
files.
detectConfig
--ignore
cli --no-ignore .
Whether to load ignore files.
Searches for files named $ignoreName
.
detectIgnore
CLIs 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
.
This package is fully typed with TypeScript.
It export the additional type Options
.
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.
unified-args
loads and evaluates configuration files, plugins, and presets
from the file system (often from node_modules/
).
That means code that is on your file system runs.
Make sure you trust the workspace where you run unified-args
and be careful
with packages from npm and changes made by contributors.
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.
FAQs
create CLIs for unified processors
The npm package unified-args receives a total of 142,948 weekly downloads. As such, unified-args popularity was classified as popular.
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
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Security News
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.