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 seem overly complex to you.

Note that if you are building bash command line scripts with bashly, then this functionality is already integrated with it.

---

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, directories and other bash built-ins

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.

You may add any of the below keywords to add additional suggestions:

Keyword	Meaning
<alias>	Alias names
<arrayvar>	Array variable names
<binding>	Readline key binding names
<builtin>	Names of shell builtin commands
<command>	Command names
<directory>	Directory names
<disabled>	Names of disabled shell builtins
<enabled>	Names of enabled shell builtins
<export>	Names of exported shell variables
<file>	File names
<function>	Names of shell functions
<group>	Group names
<helptopic>	Help topics as accepted by the help builtin
<hostname>	Hostnames, as taken from the file specified by the HOSTFILE shell variable
<job>	Job names
<keyword>	Shell reserved words
<running>	Names of running jobs
<service>	Service names
<signal>	Signal names
<stopped>	Names of stopped jobs
<user>	User names
<variable>	Names of all shell variables

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.

---