README

unified-args

Interface for creating CLIs around unified processors. Wrapper around unifiedjs/unified-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.com, the website for unified provides a good overview about what unified can do.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

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
import {args} from 'unified-args'
import extensions from 'markdown-extensions'
import {remark} from 'remark'

args({
  processor: remark,
  name: 'remark',
  description:
    'Markdown processor powered by plugins part of the unified collective',
  version: '14.0.0',
  pluginPrefix: 'remark',
  extensions,
  packageField: 'remarkConfig',
  rcName: '.remarkrc',
  ignoreName: '.remarkignore'
})

API
- args(configuration)
CLI
Diagnostics
Debugging
Contribute
License

API

This package exports the following identifiers: args. There is no default export.

`args(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)

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.

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 (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.

Default: none
Alias: -i
Engine: 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).

Default: dir
Engine: ignorePathResolveFrom

`--ignore-pattern <globs>`

cli . --ignore-pattern docs/*.md

Additional patterns to use to ignore files.

Default: none
Engine: ignorePatterns

`--silently-ignore`

cli **/*.md --silently-ignore

Skip given files which are ignored by ignore files, instead of warning about them.

Default: off
Engine: silentlyIgnore

`--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".

Default: none
Alias: -s
Engine: settings

`--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 # only last one is used

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.

Default: none, which uses vfile-reporter.
Engine: reporter and reporterOptions.

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'
cli input.txt --use ./plugin.js

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.

Default: Configured extensions
Alias: -e
Engine: 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.

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

`--inspect`

cli --inspect < input.txt

Output the transformed syntax tree, formatted with unist-util-inspect. This does not run the compilation phase.

Default: off
Engine: inspect

`--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.

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.

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 could be processed
Engine: out

`--color`

cli input.txt --no-color

Whether to output ANSI color codes in the report.

Default: whether the terminal supports color
Engine: color

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.

Default: on
Engine: detectConfig

`--ignore`

cli . --no-ignore

Whether to load ignore files.

Searches for files 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 warnings otherwise
0 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.

Usage no npm install needed!

README

unified-args

Install

Use

Contents

API

args(configuration)

configuration

CLI

--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>

Note

--use <plugin>

--ext <extensions>

--watch

--tree

--tree-in

--tree-out

--inspect

--quiet

Note

--silent

Note

--frail

--file-path <path>

--stdout

--color

Note

--config

--ignore

Diagnostics

Debugging

Contribute

License

`args(configuration)`

`configuration`

`--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`