# ask-nicely

> Easily create command-line applications by configuring commands, options and parameters that are supermagically parsed.

Latest version **4.0.4** (published 2020-01-24) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install ask-nicely
pnpm add ask-nicely
yarn add ask-nicely
bun add ask-nicely
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 4.0.4 |
| Published | 2020-01-24 |
| First published | 2015-11-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4.1.0 |
| Dependencies | 0 |
| Unpacked size | 35.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Wybe Minnebo |
| Maintainers | wvbe |
| Keywords | argument, argv, command, option, parameter, parsing, shell, terminal |

## Links

- npm: https://www.npmjs.com/package/ask-nicely
- Repository: https://github.com/wvbe/ask-nicely
- Issues: https://github.com/wvbe/ask-nicely/issues
- npm.io page: https://npm.io/package/ask-nicely

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 4.0.4 (latest) — 2020-01-24
- 4.0.3 — 2020-01-24
- 4.0.2 — 2020-01-24
- 4.0.1 — 2020-01-16
- 3.0.4 — 2020-01-09
- 3.0.3 — 2020-01-09
- 3.0.2 — 2018-08-15
- 3.0.1 — 2017-06-30
- 3.0.0 — 2017-06-26
- 2.0.0 — 2017-06-23
- 2.0.0-rc1 — 2017-06-22
- 1.1.1 — 2017-04-03
- 1.1.0 — 2016-05-31
- 1.0.0 — 2015-11-02

## README

# ASK-NICELY
Easily create command-line applications by configuring commands, options and parameters that are supermagically parsed.

Ask Nicely is different from parsers like `minimist` because it interprets input based on what's configured, rather
than syntax alone.

## Example
An elaborate example can be found in `examples/application.annotated.js`. The following code is a functioning
command-line application (that merely dumps whatever `Request` object was parsed from input):

```js
import { Command } from 'ask-nicely';

const root = new Command();

root.addOption('alpha', 'a');

root.addCommand('subcommand', request => {
		console.log(request));
		return { somethingWasDone: true };
	})
	.addOption('beta', 'b', 'Beta is the second letter of the greek alphabet', true)
	.addParameter('gamma');

root.execute(process.argv.slice(2))
	.then(result => console.log(result))
	.catch(error => console.log(error));
```

Parsing input (`process.argv` in this example) would yield the following `Request` object in the relevant controller
and precontrollers:

```js
// node examples/application.microscopic.js -a
{
    command:    { /* the root command */ },
    options:    { alpha: true }
}

// node examples/application.microscopic.js subcommand paramValue --beta optValue
{
    command:    { /* the subcommand */ },
    parameters: { gamma: 'paramValue' },
    options:    { alpha: undefined, beta: 'optValue' }
}
```

## Advanced use
The Command methods `addOption` and `addParameter` either take a couple of strings and booleans, or an `Option` or
`Parameter` instance respectively. Creating the instance of `Option` or `Parameter` first allows you to configure it
with more advanced behaviour.

There are different kinds of `Options` and `Parameters`; for example, `--user.name wvbe` would create an object
(`req.options.user = { name: 'wvbe' }`) if you configure it as a `DeepOption`. These extending Option and Parameter
classes are exposed on `AskNicely` and it's instances.

```js
import { Option } from 'ask-nicely';

root.addOption(new Option('delta')
    .setShort('d')
    .setResolver(input => database.find('users', input))
    .addValidator(user => {
        if (user.username === 'wvbe')
            throw new Error('Get this sucka outta here');
    })
);
```

The resolver transforms flat text `input` into something different and is handled asynchronously if it returns a
`Promise`. The validator in the example would throw a custom error if the resolved `user` object happens to have my
username.

## Important classes
- Command
- Option
    - MultiOption (like `--emails one@hotmail.com two@hotmail.com`)
    - DeepOption (like `--config.username wvbe`)
    - IsolatedOption (like `--help`, prevents further input parsing)
- Parameter
    - DeepParameter (as seen in `git config`)
- Request (user input is assigned to this object)
- InputError (thrown if a mistake was made by the end-user rather than a programmer)

## Important methods
- Command, Option and Parameter classes (`NamedSyntaxPart`)
    - `constructor(name)`
    - `addAlias(alias)`
    - `setDescription(description)`
- Option and Parameter classes (`VariableSyntaxPart`)
    - `isRequired(required)`
    - `addValidator(validator)`
    - `setResolver(resolver)`
- Parameter classes
    - `setDefault(arbitrary)`
- Option classes
    - `setDefault(arbitrary, useDefaultIfFlagMissing)`
    - `setShort(short)`
- MultipleOption class
    - `isInfinite(infinite))`
- Command classes
    - `addCommand(command|name[, controller])`
    - `addOption(option|name[, short, description, required])`
    - `addParameter(parameter|name[, description, required])`
    - `addPreController(controller)`
    - `execute(input, [request, ...arbitrary])`
    - `parse(input, [request, ...arbitrary])`
    - `setController(controller)`
    - `setNewChildClass(Class)`
- Request class
    - `constructor()`
    - `execute([...arbitrary])`

## Behaviour
- Input for `Options` or `Parameters` can contain spaces if the input is wrapped in double-quotes (`--opt "My option"`)
- `Options` and `Parameters` accumulate as you go deeper from root into subcommands. In this way, any command can add
  scope to the underlying subcommands through the `Request` object
- Precontrollers (`Command#addPrecontroller()`) are accumulated as you go deeper into subcommands as well. When a
  command is ran, all of it's ancestors precontrollers are ran too. In this way, for example, a precontroller can
  determine if the execution chain should stop for a certain combination of options (by returning `false`).
- With exception of `DeepOption`, `Option` classes with a default value will stay undefined, unless you set the second
  argument of `Option#setDefault()` to `true`.
- Arbitrary arguments to `AskNicely#interpret()` and `Request#execute()` are passed down to syntax resolvers,
  precontrollers and controllers. This allows you to pass an application/config object along.

## Release notes
- v 4.0.0
  - Fixed an issue where the most specifically defined Option (ie. on the deepest command) of the same name did not win.
- v 3.0.0
  - _Deprecate the `Root` class, any `Command` can serve as root_
  - _Refactor `Root#interpret()` to `Command#parse()`, which doesn't throw and parses more_
  - _Add `Command#execute()` which parses, executes, and throws like the previous `interpret` method would have._
- v 2.0.0
  - Expose classes as an ES6 module
  - Package using rollup and babel ES2015 preset
  - _Rename the AskNicely (root class) to Root_
  - _Do not expose the root class as a default export_
  - _Do not expose classes via an instance of ask-nicely_
- v 1.1.1
  - Fix the way InputError was exposed
- v1.1.0
  - Adding `Command#addAlias(alias)`
  - Throwing new `InputError` as opposed to regular `Error` in some cases, allows you do distinguish user errors from
    system errors.
  - Exposing `Request` and allow to use pass own instance to `AskNicely#interpret()`
  - Adding `Command#setController(controller)` and `#setNewChildClass(Class)`
  - Declaring properties on Request in constructor so you don't have to keep null-checking
  - Adding `MultiOption` class, which evaluates to an array
- v1.0.0
  - Using ECMAScript 6
  - `Option`, `Parameter` and related classes increase configurability a thousandfold
  - Moved most parsing logic to individual classes that represent a syntax part
  - `AskNicely#interpret()` is no longer synchronous because of the ability to asynchronously resolve values
  - Ditching a lot of useless methods that are not directly used for parsing or configuring, moving a lot of other
    stuff
  - Ditching `Command#isHungry()` and `Command#isGreedy()`
- v0.1.0
  - Initial release, pretty basic parsing with limited configurability

## Issues/known bugs
- There's a problem in `VariableSyntaxPart` that would fail to clone the `default` property object of a `DeepOption` of
  `DeepParameter`, resulting in changes to the `default` value that is shared with other instances of that syntax part.
  As a work-around the `default` object is stringified and parsed again, therefore it is limited to something that can
  be serialized.
- Your terminal may replace patterns (like "*") with an actual list of matching file names before the node process is
  even started. This prevents parsing those patterns in AskNicely, and may yield unexpected results. Seen in
  `gnome-terminal` using `oh-my-zsh`. Can be circumvented by enclosing input data in double quotes, although that's
  kind of shitty.

## Wishlist
- Fix aforementioned issues and known bugs.
- `DeepOption` with a default value should stay undefined if flag is not set, like rest of `Option` classes.
- Implement `isInfinite()` for other `VariableSyntaxPart` classes
- Implement `addAlias()` for all `NamedSyntaxPart` classes, maybe.
- A different way of stopping the controller chain, returning FALSE is a little crude
- Make it easy for commands to call other commands, maybe in a dependency-aware manner
- Test more edge cases, like conflicts and multiple values

## License
Copyright (c) 2015 Wybe Minnebo

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
Software.

__THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.__

---
_Source: https://npm.io/package/ask-nicely · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._