-
-
-
-
-
-
+
-_The `flag()` method_ is a shortcut to help developers create more maintainable and understandable code. Consider the following example that does **not** use the flag method: +The `flag()` method is a shortcut to help developers create more maintainable and understandable code. Consider the following example that does **not** use the flag method: ```javascript const cmd = new Command({ @@ -236,7 +262,309 @@ const cmd = new Command({ }) ``` -While the differences aren't extreme, it abstracts the need to know whether a flag is recognized or not (or even exists). +While the differences aren't extreme, it abstracts the need to know whether a flag is recognized or not (or even exists). If a `flag()` is executed for a non-existant flag, it will return `null`. +
+
+Understanding flag()
+-_The `flag()` method_ is a shortcut to help developers create more maintainable and understandable code. Consider the following example that does **not** use the flag method: +The `flag()` method is a shortcut to help developers create more maintainable and understandable code. Consider the following example that does **not** use the flag method: ```javascript const cmd = new Command({ @@ -236,7 +262,309 @@ const cmd = new Command({ }) ``` -While the differences aren't extreme, it abstracts the need to know whether a flag is recognized or not (or even exists). +While the differences aren't extreme, it abstracts the need to know whether a flag is recognized or not (or even exists). If a `flag()` is executed for a non-existant flag, it will return `null`. +
+
+
+## Plugins
+
+Plugins expose functions, objects, and primitives to shell handlers.
+
+_Example:_
+
+Consider an example where information is retrieved from a remote API. To do this, an HTTP request library may be necessary to make the request and parse the results. In this example, the axios library is defined as a plugin. The plugin is accessible in the metadata passed to each handler, as shown below.
+
+Understanding data
+The `data` attribute supplied to handlers in the metadata argument contains the values for known flags, and _**attempts to map unknown arguments** to configured argument names_. + +For example, + +```javascript +const shell = new Shell({ + name: 'account', + commands: [{ + name: 'create', + arguments: 'email displayName', + handler (meta) { + console.log(meta.data) + } + }] +}) + +shell.exec('create me@domain.com "John Doe" test1 test2') +``` + +_Output:_ + +```json +{ + "email": "me@domain.com", + "displayName": "John Doe", + "unknown1": "test1", + "unknown2": "test2 +} +``` + +If there is a name conflict, the output will contain an array of values. For example: + +```javascript +const shell = new Shell({ + name: 'account', + commands: [{ + name: 'create', + arguments: 'email displayName', + flags: { + email: { + alias: 'e' + } + }, + handler (meta) { + console.log(meta.data) + } + }] +}) + +shell.exec('create me@domain.com -e bob@other.com') +``` + +_Output:_ + +```json +{ + "email": ["bob@other.com", "me@domain.com"], + "displayName": "John Doe", +} +``` + +> Notice the values from the known flags are _first_. +
+
+Why would you do this?
++ Remember, the shell library can produce JSON (See the Introspection/Metadata Generation section). JSON is a string format for storing data. The output will contain a stringified version of all the handler functions. This can be used as the configuration for another instance of a shell. In other words, you can maintain a runtime-agnostic configuration. You could use _mostly_ the same configuration for the browser, Node, Deno, Vert.x, or another JavaScript runtime. However; the modules/packages like the HTTP request module may or may not work in each runtime. +
++ Plugins allow developers to write handlers that are completely "self contained". It is then possible to modify the plugin configuration for each runtime without modifying every handler in the shell. +
++ +```javascript +import axios from 'axios' + +const sh = new Shell({ + name: 'info', + plugins: { + httprequest: axios // replace this with any compatible library + }, + commands: [{ + name: 'person', + flags: { + name: { + description: 'Name of the person you want info about.', + required: true + } + }, + handler (meta) { + meta.plugins.httprequest({ + method: 'get', + url: `http://api.com/person/${meta.flag('name')}` + }).then(console.log).catch(console.error) + } + }, { + name: 'group', + flags: { + name: { + description: 'Name of the group you want info about.', + required: true + } + }, + handler (meta) { + meta.plugins.httprequest({ + method: 'get', + url: `http://api.com/group/${meta.flag('name')}` + }).then(console.log).catch(console.error) + } + }] +}) +``` + +Commands will inherit plugins from the shell and any parent commands. It is possible to "override" a plugin in any specific command. + +
+
+
+## Universal Flags
+_Common flags are automatically applied to multiple commands._
+
+Sometimes a CLI app has multiple commands/subcommands that need the same flag associated with each command/subcommand. For example, if a `--note` flag were needed on every command, it would be a pain to copy/paste the config into every single command. Common flags resolve this by automatically applying to all commands from the point where the common flag is configured (i.e. the point where inheritance/nesting begins).
+
+Override Example
+ +```javascript +const sh = new Shell({ + name: 'test', + plugins: { + test: value => { + return value + 1 + } + }, + commands: [{ + name: 'cmd', + plugins: { + test: value => { + return value + 10 + } + }, + handler(meta) { + console.log(meta.test(1)) // Outputs 11 + } + }] +}) +``` + +
+
+
+Apply a common flag to ALL commands
+To include the same flag on all commands, add a common flag to the shell. + +```javascript +const shell = new Shell({ + name: 'mycli', + commmonflags: { + note: { + alias: 'n', + description: 'Save a note about the operation.' + } + }, + commands: [{ + name: 'create', + flag: { + writable: { + alias: 'w', + description: 'Make it writable.' + } + }, + ... + }, { + name: 'read', + ... + }] +}) + +shell.exec('create --help') +shell.exec('read --help') +``` + +create output: +```sh +mycli create + +Flags: + note [-n] Save a note about the operation. + writable [-w] Make it writable. +``` + +read` output: +```sh +mycli read + +Flags: + note [-n] Save a note about the operation. +``` +
+
+
+#### Filtering Universal Flags
+
+Universal/common flags accept a special attribute named `ignore`, which will prevent the flags from being applied to specific commands. This should be used sparingly.
+
+Apply a common flag to a specific command/subcommands
+ +```javascript +const shell = new Shell({ + name: 'mycli', + commands: [{ + name: 'create', + commmonflags: { + note: { + alias: 'n', + description: 'Save a note about the operation.' + } + }, + flag: { + writable: { + alias: 'w', + description: 'Make it writable.' + } + }, + commands: [...] + ... + }, { + name: 'read', + description: 'Read a directory.', + ... + }] +}) + +shell.exec('create --help') +shell.exec('read --help') +``` + +_`create` output:_ +```sh +mycli create + +Flags: + note [-n] Save a note about the operation. + writable [-w] Make it writable. +``` + +_`read` output:_ +```sh +mycli read + + Read a directory. + +``` +
+
+ +```javascript +const shell = new Shell({ + name: 'mycli', + commmonflags: { + ignore: 'info', // This can also be an array of string. Fully qualified subcommands will also be respected. + note: { + alias: 'n', + description: 'Save a note about the operation.' + } + }, + commands: [{ + name: 'create', + handler () {} + }, { + name: 'read', + handler () {} + }, { + name: 'update', + handler () {} + }, { + name: 'delete', + handler () {} + }, { + name: 'info', + handler () {} + }] +}) +``` + +Any command, except `info`, will accepts/parse the `note` flag. + +
## Middleware
@@ -274,7 +602,9 @@ shell.useWith('demo', function (metadata, next) {
})
```
-The code above would only run when the user inputs the `demo` command (or and `demo` subcommand).
+The code above would only run when the user inputs the `demo` command (or any `demo` subcommand).
+
+#### Command-Specific Assignments
It is possible to assign middleware to more than one command at a time, and it is possible to target subcommands. For example:
@@ -290,8 +620,353 @@ shell.useWith(['demo', 'command subcommand'], function (metadata, next) {
Notice the array as the first argument of the `useWith` method. This middleware would be assigned to `demo` command, all `demo` subcommands, the `subcommand` of `command`, and all subcommands of `subcommand`. If this sounds confusing, just know that middleware is applied to commands, including nested commands.
-### Other Middleware
+Assigned middleware can also be applied directly to a `Command` class. For example,
+
+```javascript
+const cmd = new Command({
+ name: 'demo',
+ flags: {
+ a: { type: String },
+ b: { type: String }
+ },
+ handler: metadata => {
+ console.log(metadata)
+ }
+})
+
+cmd.use(function (metadata, next) {
+ console.log(`this middleware is specific to the "${cmd.name}" command`)
+ next()
+})
+```
+
+#### Command-Exclusion Assignments
+
+Sometimes middleware needs to be applied to all but a few commands. The `useExcept` method supports these needs. It is basically the opposite of `useWith`. Middleware is applied to all commands/subcommands _except_ those specified.
+
+For example:
+
+```javascript
+const shell = new Shell({
+ ...,
+ commands: [{
+ name: 'add',
+ handler (meta) {
+ ...
+ }
+ }, {
+ name: 'subtract',
+ handler (meta) {
+ ...
+ }
+ }, {
+ name: 'info',
+ handler (meta) {
+ ...
+ }
+ }]
+})
+
+shell.useExcept(['info], function (meta, next) {
+ console.log(`this middleware is only applied to some math commands`)
+ next()
+})
+```
+
+In this example, the console statement would be displayed for all commands except the `info` command (and any info subcommands).
+
+### Built-in "Middleware"
+
+Displaying help and version information is built-in (overridable).
+
+**Help**
+
+Appending `--help` to anything will display the help content for the shell/command/subcommand. This will respect any custom usage/help configurations that may be defined.
+
+**Shell Version**
+
+A `version` command is available on the shell. For example:
-One development goal of this framework is to remain as lightweight and unopinionated as possible. Another is to be as simple to use as possible. These two goals often conflict with each other (the more features you add, the heavier it becomes). In an attempt to find a comfortable balance, some additional middleware libraries are available fo those who want a little extra functionality.
+```sh
+$ cmd version
+1.0.0
+```
+
+The following common flag variations map to the version command, producing the same output:
+
+```sh
+$ cmd --version
+1.0.0
+
+$ cmd -v
+1.0.0
+```
+
+This can be overridden by creating a command called `version`, the same way any other command is created.
+
+```javascript
+const v = new Command({
+ name: 'version',
+ handler (meta) {
+ console.log(this.shell.version)
+ }
+})
+
+shell.add(v)
+```
+
+### Middleware Libraries
+
+One development goal of this framework is to remain as lightweight and unopinionated as possible. Another is to be as simple to use as possible. These two goals often conflict with each other (the more features you add, the heavier it becomes). In an attempt to find a comfortable balance, some additional middleware libraries are available for those who want a little extra functionality.
1. [@author.io/shell-middleware](https://github.com/author/shell-middleware)
+1. Submit a PR to add yours here.
+
+### Trailers
+_(Postware/Afterware)_
+
+Trailers operate just like middleware, but they execute _after_ the command handler is executed.
+
+```javascript
+const shell = new Shell({
+ name: 'mycli',
+ trailer: [
+ function () { console.log('Done!' ) }
+ ],
+ command: [{
+ name: 'dir',
+ handler () {
+ console.log('ls -l')
+ },
+ // Subcommands
+ commands: [{
+ name: 'perm',
+ description: 'Permissions',
+ handler () {
+ console.log('Display permissions for a directory.')
+ }
+ }]
+ }]
+})
+
+// Execute the "dir" command
+shell.exec('dir')
+
+// Execute the "perm" subcommand
+shell.exec('dir perm')
+```
+
+_`dir` command output:_
+```sh
+ls -l
+Done!
+```
+
+_`dir perm` subcommand output:_
+```sh
+Display permissions for a directory.
+Done!
+```
+
+### Customized Help/Usage Messages
+
+**Customizing Flag Appearance:**
+
+The `Shell` and `Command` classes can both accept several boolean attributes to customize the description of each flag within a command. Each of these is `true` by default.
+
+1. `describeDefault`: Display the default flag value.
+1. `describeOptions`: List the valid options for a flag.
+1. `describeMultipleValues`: Appends `Can be used multiple times.` to the flag description
+1. `describeRequired`: Prepends `Required.` to the flag description whenever a flag is required.
+
+Cherry-picking example
++ +```javascript +const shell = new Shell({ + name: 'mycli', + commmonflags: { + ignore: 'info', // This can also be an array of string. Fully qualified subcommands will also be respected. + note: { + alias: 'n', + description: 'Save a note about the operation.' + } + }, + commands: [{ + name: 'create', + handler () {} + }, { + name: 'read', + handler () {} + }, { + name: 'update', + handler () {} + }, { + name: 'delete', + handler () {} + }, { + name: 'info', + handler () {} + }] +}) +``` + +Any command, except `info`, will accepts/parse the `note` flag. + +
+
+ +```javascript +const c = new Command({ + name: '...', + flags: { + name: { + alias: 'nm', + required: true, + default: 'Rad Dev', + allowMultipleValues: true, + options: ['Mr Awesome', 'Mrs Awesome', 'Rad Dev'], + description: 'Specify a name.' + } + } +}) +``` + +The help message for this flag would look like: + +```sh +Flags: + -name ['nm'] Required. Specify a name. Options: Mr + Awesome, Mrs Awesome, Rad Dev. Can be + used multiple times. (Default Rad Dev) +``` +
+Example
++ +```javascript +const c = new Command({ + name: '...', + flags: { + name: { + alias: 'nm', + required: true, + default: 'Rad Dev', + allowMultipleValues: true, + options: ['Mr Awesome', 'Mrs Awesome', 'Rad Dev'], + description: 'Specify a name.' + } + } +}) +``` + +The help message for this flag would look like: + +```sh +Flags: + -name ['nm'] Required. Specify a name. Options: Mr + Awesome, Mrs Awesome, Rad Dev. Can be + used multiple times. (Default Rad Dev) +``` +
+ +**Customizing the Entire Message:** + +This library uses a vanilla dependency (i.e. no-subdependencies) called [@author.io/table](https://github.com/author/table) to format the usage and help messages of the shell. The `Table` library can be used to create your own custom screens, though most users will likely want to stick with the defaults. If you want to customize messages, the following example can be used as a starting point. The configuration options for the table can be found in the README of its repository. + +```javascript +import { Shell, Command, Table } from '@author.io/shell' + +const shell = new Shell(...) +shell.usage = '...' +shell.help = () => { + const rows = [ + ['Command', 'Alias Names'], + ['...', '...'] + ] + + const table = new Table(rows) + + return shell.usage + '\n' + table.output +} +``` + +**The `usage` and/or `help` attributes of an individual `Command` can also be set:** + +```javascript +import { Shell, Command, Table } from '@author.io/shell' + +const cmd = new Command(...) +cmd.usage = '...' +cmd.help = () => { + const rows = [ + ['Flags', 'Alias Names'], + ['...', '...'] + ] + + const table = new Table(rows) + + return cmd.usage + '\n' + table.output +} +``` + +There is also a `Formatter` class that helps combine usage/help messages internally. This class is exposed for those who want to dig into the inner workings, but it should be considered as more of an example than a supported feature. Since it is an internal class, it may change without warning (though we'll try to keep the methods consistent across releases). + +### Introspection/Metadata Generation + +A JSON metadoc can be produced from the shell: + +```javascript +console.log(shell.data) +``` + +Simple CLI utilities can also be loaded entirely from a JSON file by passing the object into the shell constructor as the only argument. The limitation is no imports or hoisted variables/methods will be recognized in a shell which is loaded this way. + +### Autocompletion/Input Hints + +This library can use a _command hinting_ feature, i.e. a shell `hint()` method to return suggestions/hints about a partial command. This feature was part of the library through the `v1.5.x` release lifecycle. In `v.1.6.0+`, this feature is no longer a part of the core library. It is now available as the [author/shell-hints plugin](https://github.com/author/shell-hints). + +Consider the following shell: + +```javascript +import HintPlugin from 'https://cdn.pika.dev/@author.io/browser-shell-hints' + +const shell = new Shell({ + name: 'mycli', + command: [{ + name: 'dir', + handler () { + console.log('ls -l') + }, + // Subcommands + commands: [{ + name: 'perm', + description: 'Permissions', + handler () { + console.log('Display permissions for a directory.') + } + }, { + name: 'payload', + description: 'Payload', + handler () { + console.log('Display payload/footprint for a directory.') + } + }] + }] +}) + +HintPlugin.apply(shell) // <-- Adds the hint method. + +// Help us figure out what we can do! +console.log(shell.hint('dir p')) +``` + +_Output:_ + +```sh +{ + commands: ['perm', 'payload'], + flags: [] +} +``` + +The hint matches "**dir p**ermission" and "**dir p**ayload", but does not match any flags. + +If no options/hints are available, `null` is returned. + +While this add-on provides input hints that could be used for suggestions/completions, it does **not** generate autocompletion files for shells like bash, zsh, fish, powershell, etc. + +> There are many variations of autocompletion for different shells, which are not available in browsers (see our Devtools extension for browser completion). + +If you wish to generate your own autocompletion capabilities, use the `shell.data` attribute to retrieve data for the shell (see prior section). For terminals, consider using the shell metadata with a module like [omlette](https://github.com/f/omelette) to produce autocompletion for your favorite terminal app. For browser-based CLI apps, consider using our devtools extension for an autocompletion experience. + +## Installation + +### Node.js + +
+
+ +```sh +npm install @author.io/shell --save +``` + +Please note, you'll need a verison of Node that supports ES Modules. In Node 12, this feature is behind the `--experimental-modules` flag. It is available in Node 13+ without a flag, but the `package.json` file must have the `"type": "module"` attribute. This feature is generally available in [Node 14.0.0](https://nodejs.org) and above. +
+
+Modern (ES Modules)
++ +```sh +npm install @author.io/shell --save +``` + +Please note, you'll need a verison of Node that supports ES Modules. In Node 12, this feature is behind the `--experimental-modules` flag. It is available in Node 13+ without a flag, but the `package.json` file must have the `"type": "module"` attribute. This feature is generally available in [Node 14.0.0](https://nodejs.org) and above. +
+
+
+ +DEPRECATED + +If you need to use the older CommonJS format (i.e. `require`), run `npm install @author.io/shell-legacy` instead.
+
+
+### Browsers
+
+**CDN**
+
+```javascript
+import { Shell, Command } from 'https://cdn.pika.dev/@author.io/shell'
+```
+
+Also available from [jsdelivr](https://www.jsdelivr.com/package/npm/@author.io/shell/index.js) and [unpkg](https://unpkg.com/@author.io/shell/index.js).
+
+### Debugging
+
+Each distribution has a corresponding `-debug` version that should be installed _alongside_ the main module (the debugging is an add-on module). For example, `npm install @author.io/shell-debug --save-dev` would install the debugging code for Node. In the browser, appending the debug library adds sourcemaps.
+
+### Related Modules
+
+1. [@author.io/table](https://github.com/author/table) - Used to generate the default usage/help messages for the shell and subcommands.
+
+**Sponsors (as of 2020)**
+
+Legacy (CommonJS/require)
++ +DEPRECATED + +
 |
+  |
+