unified

Project:unifiedjs/unified-args

Package:unified-args@7.1.0

  1. Dependencies:8·Dependents:4
  2. Create CLIs for unified processors
  1. unified 131
  2. cli 5
  3. processor 4
  4. engine 4

unified-args

Build Coverage Downloads Sponsors Backers Chat

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

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'
})

Table of 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
      --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:

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

--rc-path <path>

cli . --rc-path config.json

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

--ignore-path <path>

cli . --ignore-path .gitignore

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

--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 exceptions: surrounding braces must not be used: "foo": 1, "bar": "baz" is valid

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

--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 honoured, 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.

--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 behaviour is to show a success message.

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.

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 behaviour is to exit with 1 on errors.

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

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

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, organisation, or community you agree to abide by its terms.

License

MIT © Titus Wormer