Skip to content

Commit

Permalink
Added configuration attributes for customizing flag help message output.
Browse files Browse the repository at this point in the history
  • Loading branch information
coreybutler committed May 4, 2020
1 parent f1b1f70 commit 115eb46
Show file tree
Hide file tree
Showing 9 changed files with 1,623 additions and 18 deletions.
46 changes: 43 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ See the [Installation Guide](#installation) when you're ready to get started.

There is a complete working example of a CLI app (with a mini tutorial) in the examples directory.

_This example imports the library for Node. Simply swap the Node import for the appropriate browser import if you're building a web utility. Everything else is the same for both Node and browser environments._
_This example imports the library for Node. Simply swap the Node import for the appropriate browser import if you're building a web utility. Everything else is the same for both Node and browser environments._

```javascript
import { Shell, Command } from '@author.io/node-shell'
Expand Down Expand Up @@ -604,9 +604,49 @@ Done!
### Customized Help/Usage Messages
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.
**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.
<details>
<summary>Example</summary>
<br/>
```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:
_Example:_
```sh
Flags:
-name ['nm'] Required. Specify a name. Options: Mr
Awesome, Mrs Awesome, Rad Dev. Can be
used multiple times. (Default Rad Dev)
```
</details>
<br/>
**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/node-shell'
Expand Down
2 changes: 1 addition & 1 deletion examples/cli/index.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
#!/usr/bin/env node --experimental-modules
#!/usr/bin/env node --experimental-modules -r source-map-support/register

import fs from 'fs'
import path from 'path'
Expand Down
5 changes: 4 additions & 1 deletion examples/cli/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,8 @@
"engines": {
"node": "^12.0.0"
},
"dependencies": {}
"dependencies": {},
"devDependencies": {
"@author.io/node-shell-debug": "^1.5.0"
}
}
Loading

0 comments on commit 115eb46

Please sign in to comment.