Composable Command Line Applications
Reginn helps you conquer the world of command line applications functionally.
Reginn empowers you with simple functions to implement complex command-line applications with expressive code and ease. By sandboxing side effects into tightly-controlled areas of your application, your code will become easy to read, reason about, and test.
Reginn was built to eliminate the crutch on monolithic imperative APIs to work with the command line.
Leading alternatives—such as commander.js—are both largely unmaintained and feature large imperative classes, which are bad for reusability. Commander introduces many new syntaxes that you have to learn and all are based around the way you format strings. As you know, that is a recipe for disaster. Commander also forces the intermixing of where you declare your application’s intent and where side effects exist that leads to poor separation of concerns and testability.
Reginn is laser-focused to create small, testable functions that allow you to build you command line applications with assurances not found elsewhere. Reginn introduces zero new syntaxes to your application and no new concepts, since you already know functions.
npm install --save reginn
# Do awesome things!
We're going to walk through the process of creating a small application that reads an input file, and writes it somewhere else. Easy.
The end result we're looking for is an application we can use like this
node ./cli.js build -i path/to/file -o new/path/to/file
# without abbreviation
node ./cli.js build --input path/to/file --output new/path/to/file
Let's break it down into a few pieces first to see what it is we're trying to achieve. We're going to work right to left, as this is how function composition works.
First we want to define how our application can process -o new/path/to/file
The code to do this is
import { flag, alias } from 'reginn'
const outputFlag = flag(alias('output', 'o'))
Remember that we're dealing with function composition. Here we are describing
that we want to create a Flag
with an alias of output
and an abbreviation of
o
.
Let's break that down a little further.
First we create a new Alias
. An alias is a low-level type designed
to associate other types with a name and optionally an abbreviation to that
name. We do that here by calling alias('output', 'o')
.
Secondly we wrap that alias inside of Reginn's flag()
function. This creates
our second type introduced here: Flag
. A Flag is mechanism for
creating options that change or define the behavior of your applications.
Can you guess how we are going to create the next piece of our API?
We want to enable this: -i path/to/file
const inputFlag = flag(alias('input', 'i'))
Exactly like the outputFlag
above!
Next we want to be able to describe the command build
that accepts these
flags. We are going to introduce a new type.
import { command } from 'reginn'
const buildCommand = command(alias('build'), inputFlag, outputFlag)
Here we're introducing a new type Command
. Commands are composed
of an Alias
and any number of Flag
s.
Commands are a very special type and is where we branch our code to sandbox our side effects.
Here we are going to perform our applications sole purpose. Reginn has a few
functions to create side-effects but here we are going to use a Promise
.
import { readFile, writeFile } from 'fs'
import { asPromise } from 'reginn'
asPromise(buildCommand).then(({ args, options }) => {
// lets read our input file
readFile(options.input, 'utf8', (err, content) => {
if (err) throw err
// and lets write it to our output file
writeFile(options.output, content, 'utf8', (err) => {
if (err) throw err
})
})
})
Calling asPromise
with a Command
as the sole argument returns to us a
Promise that will resolve when the command has been matched. The resolved promise
will have access to an object with args
and options
.
args
here is an array of strings, representing all non-Flag parameters given to
our application.
options
here is a hash of flags we are explicitly handling, and have been matched.
For example:
node ./cli.js build notAFlag --input file.js --output output.js --unhandledFlag
The resulting args
will be [ 'notAFlag' ]
and options
will be
{
input: "file.js",
output: "output.js"
}
So lets recap what we've done so far. We've learned how to create flags to give options to our application, build commands that can make use of those flags, and lastly how to do something with all that.
The last thing we need to do is run it!
The code to do so is
import { run } from 'reginn'
run(buildCommand)
This is all we need to implement the API we set out to describe. Here is the entire application.
import { command, flag, alias, run, asPromise } from 'reginn'
const outputFlag = flag(alias('output', 'o'))
const inputFlag = flag(alias('input', 'i'))
const buildCommand = command(alias('build'), inputFlag, outputFlag)
asPromise(buildCommand).then(({ args, options }) => {
// lets read our input file
readFile(options.input, 'utf8', (err, content) => {
if (err) throw err
// and lets write it to our output file
writeFile(options.output, content, 'utf8', (err) => {
if (err) throw err
})
})
})
run(buildCommand)
At this point I hope you now understand the core concepts of what Reginn is trying to do, and what it is capable of. Thank you for taking the time to read this and please open an issue for suggestions and comments!
All of the types used by Reginn are simple objects exposed by functions of the same lowercased name, which are described above.
An alias is used to associate other types to a usable value for a user of your command line applications. An Alias is a fundamental type, that can not be composed of other types.
type Alias = {
type: 'alias',
value: [string, string]
};
Example:
import { alias } from 'reginn'
alias('name')
alias('name', 'aliasToName')
A Description is just what you'd expect. It adds descriptive information to
a parent type. Acceptable parent types are Flag
and Command
.
Example:
import { desc } from 'reginn'
desc('This is what this is about')
A Type is created to distinguish how to parse the input of a Flag.
type Type = {
type: 'type',
value: 'string' | 'boolean'
};
Example:
import { type } from 'reginn'
type('boolean')
A Flag is a mid-level type which can be composed of Type
and Alias
. A flag
is used to associate options to part of your command.
type Flag = {
type: 'flag',
flagType: 'string' | 'boolean',
alias: Array<[string, string]>
};
Example:
import { flag, type, alias } from 'reginn'
flag(type('boolean'), alias('example'))
A Command is a very special type which allows us to compose many options together to create a public facing API, and also as a place to sandbox our side-effects.
A Command is typically composed of types Alias
and Flag
, but for subcommands,
can be composed with other Command
types. In the case of matching a command
that has subcommands, the parent's handler will receive an instance of type App
.
asPromise(commandWithSubCommands).then((app: App) => {
run(app) // run your sub application
})
//or simply
asPromise(commandWithSubCommands).then(run)
The reason that subcommands are handled in this way, is because executing commands is a side-effect! Furthermore, it is possible to provide extra logic to be performed before calling the subcommmands like composing with another App.
type Command = {
type: 'command',
command?: Array<Command>,
flag?: CommandFlags,
alias?: Array<[string, string]>,
handler?: Handler
};
type CommandFlags = {
alias?: Array< { [name: string]: string } >,
string?: string[],
boolean?: string[]
};
type Handler = (input: HandlerOption) => any;
type HandlerOption = {
args: string,
options: Object
};
Example:
import { command, flag, alias } from 'reginn'
run
command(flag(alias('only'), alias('test'))
An App
is a collection of any number of Commands, Flags, and also other Apps to
create a container for many commands and flags for you application.
A large application can be composed or any
number of smaller applications e.g. app(app(), app(), app())
, where app's
are composed of commands and flags.
A note on composing many applications: A deep merge is performed from left to right on each containing application. What this means, is if there is a overlap of commands between the applications, the one defined on the application to the right will override the application to the left.
export type App = {
type: 'app',
command: Array<Command>,
flag?: CommandFlags,
args?: Array<string> // only present for subcommand apps
options?: Object // only present for subcommand appss
}
**Example: **
import { app, command, alias } from 'reginn'
const gitApp = app(command(alias('git')))
const hgApp = app(command(alias('hg')))
const vcsApp = app(gitApp, hgApp)
run()
is the function which gets your application off of it's feet by
processing arguments, and executing command handlers. Calling run with an array
of strings allows for you to explicitly define what is parsed by the application
which is immensely useful for testing.
import { run } from 'reginn'
run(application)
Handlers are the mechanisms for performing side-effects from commands.
import { asPromise } from 'reginn'
asPromise(command).then(({ args, options }) => {
// do stuff
})
The Stream
type being referred to here is a most.js Stream.
import { asStream } from 'reginn'
asStream(command).observe(({ args, options }) => {
// do stuff
})
import { withCallback } from 'reginn'
withCallback(commad, ({ args, options }) => {
// do stuff
})
help
is a function that takes a name of you application and adds a new command,
you guessed it, named help
. This allows your users to call node cli.js help
and print out how to use your application.
example
import { help } from 'reginn'
help('myApp', ....)
node ./myapp.js help
myApp
COMMANDS:
command1 - this is command1
FLAGS:
option1 - this is option1