Completely - Bash Completions Generator

---

Completely is a command line utility and a Ruby library that lets you generate bash completion scripts from simple YAML configuration.

This tool is for you if:

1. You develop your own command line tools.
2. Your life feels empty without bash completions.
3. Bash completion scripts scare you.

---

Install

$ gem install completely

Using the completely command line

The completely command line works with a simple YAML configuration file as input, and generates a bash completions script as output.

The configuration file is built like this:

pattern:
  - --argument
  - --param
  - command

You can save a sample YAML file by running:

$ completely new

This will generate a file named completely.yaml with this content:

mygit:
- --help
- --version
- status
- init
- commit

mygit status:
- --help
- --verbose
- --branch

mygit init:
- --bare
- <directory>

mygit commit:
- <file>
- --help
- --message
- --all
- -a
- --quiet
- -q

Each pattern in this configuration file will be checked against the user's input, and if the input starts with a matching pattern, the list that follows it will be suggested as completions.

To generate the bash script, simply run:

$ completely generate

# or, to just preview it without saving:
$ completely preview

For more options (like setting input/output path), run

$ completely --help

Suggesting files and directories

You may have noticed that the sample file contains two special entries:

• <file>
• <directory>

These patterns will add the list of files and directories (when <file> is used) or just directories (when <directory> is used) to the list of suggestions.

For those interested in the technical details, any word between <...> will simply be added using the compgen -A action function, so you can in fact use any of its supported arguments.

Using the generated completion scripts

In order to enable the completions, simply source the generated script:

$ source completely.bash

You may wish to add this to your ~/.bashrc file to enable this for future sessions (just be sure to use absolute path).

Using from within Ruby code

require 'completely'

# Load from file
completions = Completely::Completions.load "input.yaml"

# Or, from a hash
input = {
  "mygit" => %w[--help --version status init commit],
  "mygit status" => %w[--help --verbose --branch]
}
completions = Completely::Completions.new input

# Generate the script
puts completions.script

# Or, generate a function that echos the script
puts completions.wrapper_function
puts completions.wrapper_function "custom_function_name"

Contributing / Support

If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.

---