@undercut/cli

A command line utility for lazy data processing in a shell using operations from Undercut and any valid JavaScript expression including loading your custom libraries.

• Based on existing JS protocols and language features
• Balanced API: not too imperative, not too functional
• Composability and extensibility by design
• Custom operations in a couple of lines
• Pure ES Modules with Node 14 loader compliance
• Lazy evaluation when possible
• No external dependencies
• TypeScript in JSDoc

Please visit undercut.js.org for broader overview and documentation.

Installation

npm install --global @undercut/cli
# or
yarn global add @undercut/cli

You may also install it locally.

Usage

The name of the installed command is undercut. You may also import the run function from the @undercut/cli to call it programmatically.

undercut [...options] [...operations]

List of available operations.

You're building a Push Line where the source is stdin and the target is stdout. Operations should be single quoted (prevents parsing by the shell) and separated by spaces. You can use everything that is available in the global context of Node.js. There're predefined variables with imports from Undercut packages: pull, push, and utils.

undercut 'map(s => parseInt(s, 10))' 'filter(utils.isNumberValue)'

If your expression starts with a call to a push function, you may omit the "push." prefix there:

undercut 'composeOperations([push.sortStrings(utils.desc)])'
          ^                  ^--- but not here
          |--- skip prefix here

Any valid JavaScript expression resulting into a PushOperation works:

undercut 'observer => observer' # Does nothing useful, but works.

Examples

Pipe data like you usually do in a shell:

$ cat strings.txt | undercut 'map(s => s.trim())' 'filter(s => s.length > 10)'
Hello world!
A very long string...

Use an Iterable as a source instead of stdin:

$ undercut -s 'pull.range(0, 5)' 'map(Math.sqrt)' 'sum()'
6.146264369941973

Import an installed npm package and use it:

$ undercut -i 'pad::left-pad' -s 'range(0, 3)' 'map(x => pad(x, 3))'
000
001
002

Enter text data from keyboard by skipping a source. Results will be printed to stdout after you signal the end of input with Ctrl + D:

$ undercut 'map(s => s.toUpperCase(s))'
Tom
Sam
# Ctrl + D to finish the input.
TOM
SAM

Options

-i, --import=SPECIFIER

Import a Node.js module to use it in expressions. The specifier has the format name::id. Module will be loaded by this id and accessible under this name.

$ undercut -i 'pad::left-pad' -s 'range(0, 3)' 'map(x => pad(x, 3, 0))'
000
001
002

A specifier is translated into something like this:

const name = require("id");

So, the name should be a valid JS identifier, and the id should allow Node to load the module (like a path to a .js file or a name of npm package).

You may omit the name if your id is a valid identifier:

// -i 'chalk'
const chalk = require("chalk");

Or use a destructuring expression:

// -i '{green,blue}::chalk'
const {green,blue} = require("chalk");

-s, --source=EXPRESSION

Specify a JavaScript expression of an Iterable to read input values from. In this case stdin will be ignored.

You can skip the "pull." prefix for a function from the pull package.

$ undercut -s 'range(0, 5)' 'sum()'
10

--help

Shows help information.

--version

Prints package's version.

License

Licensed under the MIT License, see LICENSE for more information.