oclif-plugin-completion
Version:
oclif plugin for generating shell completions
275 lines (182 loc) • 9.45 kB
Markdown
[](https://oclif.io)
[](https://npmjs.org/package/oclif-plugin-completion)
[](https://github.com/MunifTanjim/oclif-plugin-completion/blob/master/LICENSE)
# oclif Plugin: completion
oclif plugin for generating shell completions
<!-- toc -->
- [oclif Plugin: completion](#oclif-plugin-completion)
- [Completion Features](#completion-features)
- [Supported Shells](#supported-shells)
- [Commands](#commands)
<!-- tocstop -->
# Completion Features
Consider the following `dummy` CLI:
```sh
Usage: dummy <COMMAND> [OPTION...]
Commands:
open <ro|rw> open a dummy (as read-only or read-write)
save save a dummy
search search a dummy
Options (open):
-i, --id dummy id
-f, --file path to dummy file
-d, --dir path to dummy directory (default: ./dummies)
-v, --verbose boolean flag
Options (save):
-n, --name dummy name
-a, --age dummy age
-t, --tag dummy tag, can be multiple (a/b/c/d)
-f, --file path to dummy file
-d, --dir path to dummy directory (default: ./dummies)
-o, --overwrite boolean flag
-v, --verbose boolean flag
Options (search):
-n, --name dummy name
-a, --age dummy age
-t, --tag dummy tag, can be multiple (a/b/c/d)
-v, --verbose boolean flag
```
Running on the current directory with tree:
```sh
|- dir-one/
| |- 042.dummy-with-id-042.json
|- dir-two/
|- dummies/
| |- 109.dummy-with-id-109.json
| |- 110.dummy-with-id-110.json
| |- 111.dummy-with-id-111.json
|- file-one.txt
|- file-two.txt
```
## Features Description
**File Path completion**:
Completion will suggest the files on disk matching glob pattern.
**Directory Path completion**:
Completion will suggest the directories on disk matching glob pattern.
**Dynamic Runtime completion**:
Completion will generate the suggestion based on state of runtime environment and/or configuration.
## Features Examples
| Feature | Input | Output |
| -------------------------- | ------------------------------------ | ---------------------------- |
| File Path completion | `dummy open --file=./dir/one/<TAB>` | `042.dummy-with-id-042.json` |
| Directory Path completion | `dummy open --dir ./di<TAB>` | `dir-one dir-two` |
| Dynamic Runtime completion | `dummy open --id <TAB>` | `109 110 111` |
| Dynamic Runtime completion | `dummy open -d ./dir-one --id <TAB>` | `042` |
## Feature Support Matrix
| :+1: | :-1: | :grey_exclamation: | :bug: | :heavy_check_mark: | :heavy_minus_sign: | :x: |
| --------- | ----------- | ------------------ | ----- | ------------------ | --------------------- | --------------- |
| Supported | Unsupported | Unknown | Bug | Implemented | Partially Implemented | Not Implemented |
| oclif | Feature | Example | Bash | Zsh | Fish |
| ---------- | ---------------------------- | ---------------------------------- | ----------------------- | ----------------------- | ----------------------- |
| :+1: | Positional argument | `ro` | :grey_exclamation: :x: | :+1: :heavy_check_mark: | :grey_exclamation: :x: |
| :+1: | Basic Long | `--name john --age 42 --overwrite` | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Alternate Long | `--name=john --age=42` | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Basic Short | `-n john -a 42 -o` | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Alternative Short | `-njohn -a42` | :+1: :x: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Stacking Short | `-ov` | :grey_exclamation: :x: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Stacking Short with argument | `-ova 42` | :grey_exclamation: :x: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Options / Enum | `--tag a` | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: :bug: | Multiple | `-t c --tag d` | :+1: :heavy_minus_sign: | :+1: :heavy_minus_sign: | :+1: :heavy_minus_sign: |
| :-1: | File Path completion | `--file ...` | :+1: :heavy_minus_sign: | :+1: :x: | :+1: :heavy_minus_sign: |
| :-1: | Directory Path completion | `--dir ...` | :+1: :heavy_minus_sign: | :+1: :x: | :+1: :heavy_minus_sign: |
| :-1: | Dynamic Runtime completion | `--dir ./dummies --id 111` | :+1: :x: | :+1: :x: | :+1: :x: |
# Supported Shells
## Bash
Reference: [Bash Completion](https://github.com/scop/bash-completion)
You need to have `bash-completion` package installed on your system.
### Bash Usage
You can enable completion for Bash using various methods. A few of them are mentioned below:
**vanilla (.bashrc)**:
Add the following line in your `.bashrc` file:
```sh
eval "$(dummy completion:generate --shell bash);"
```
**vanilla (completions directory)**:
Run the following command:
```sh
dummy completion:generate --shell bash | tee ~/.local/share/bash-completion/completions/dummy
```
Depending on you system, the completion script can also be put into one of these directories:
- `${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions` (linux/macos)
- `/usr/local/share/bash-completion/completions` (macos)
- `/usr/share/bash-completion/completions` (linux)
## Zsh
Reference: [Zsh Completion System](http://zsh.sourceforge.net/Doc/Release/Completion-System.html)
### Zsh Usage
You can enable completion for Zsh using various methods. A few of them are mentioned below:
**vanilla (.zshrc)**:
Add the following line in your `.zshrc` file:
```sh
eval "$(dummy completion:generate --shell zsh); compdef _dummy dummy;"
```
**vanilla (site-functions directory)**:
Run the following command:
```sh
dummy completion:generate --shell zsh | tee "$(echo ${FPATH} | tr ':' '\n' | grep site-functions | head -n1)/_dummy"
```
The completion script can also be put into one of the directories present in `$FPATH` variable:
```sh
echo $FPATH
```
[**zinit**](https://github.com/zdharma/zinit):
Run the following commands:
```sh
dummy completion:generate --shell zsh > ~/.local/share/zsh/completions/_dummy
zinit creinstall ~/.local/share/zsh/completions
```
## Fish
Reference: [Fish Completion](https://fishshell.com/docs/current/cmds/complete.html)
### Fish Usage
Reference: [Where to put completions](https://fishshell.com/docs/current/index.html#where-to-put-completions)
You can enable completion for Fish using various methods. A few of them are mentioned below:
**vanilla (completions directory)**:
Run the following command:
```sh
dummy completion:generate --shell fish | tee ~/.config/fish/completions/dummy.fish
```
# Commands
<!-- commands -->
- [`dummy completion`](#dummy-completion)
- [`dummy completion:generate`](#dummy-completiongenerate)
- [`dummy completion:generate:alias ALIAS`](#dummy-completiongeneratealias-alias)
## `dummy completion`
Generate shell completion script
```
USAGE
$ dummy completion
OPTIONS
-s, --shell=bash|fish|zsh (required) Name of shell
DESCRIPTION
Run this command to see instructions for your shell.
EXAMPLE
$ dummy completion --shell zsh
```
_See code: [src/commands/completion/index.ts](https://github.com/MunifTanjim/oclif-plugin-completion/blob/0.6.0/src/commands/completion/index.ts)_
## `dummy completion:generate`
Generates completion script
```
USAGE
$ dummy completion:generate
OPTIONS
-s, --shell=bash|fish|zsh (required) Name of shell
DESCRIPTION
Run the "completion" command to see instructions about how to use the script generated by this command.
EXAMPLE
$ dummy completion:generate --shell zsh
```
_See code: [src/commands/completion/generate/index.ts](https://github.com/MunifTanjim/oclif-plugin-completion/blob/0.6.0/src/commands/completion/generate/index.ts)_
## `dummy completion:generate:alias ALIAS`
Generates completion script for alias
```
USAGE
$ dummy completion:generate:alias ALIAS
ARGUMENTS
ALIAS name of the alias
OPTIONS
-s, --shell=bash|fish (required) Name of shell
DESCRIPTION
This needs the completion script for the main command to be present.
Check the "completion:generate" command.
```
_See code: [src/commands/completion/generate/alias.ts](https://github.com/MunifTanjim/oclif-plugin-completion/blob/0.6.0/src/commands/completion/generate/alias.ts)_
<!-- commandsstop -->