bash-completion is awesome. It enhances the user experience by completing paths, file names, commands, flags, etc. Ironically enough, having to use Bash to add it to one's program puts some off from using it.

nodecliac's approach is different. Rather than directly using Bash, nodecliac provides a layer of abstraction. It lets one easily map a program's commands with their flags in an auto-completion map (.acmap) file. Merely write the program's .acmap and let nodecliac handle the rest. That's it.

If Bash is needed, .acmap files are flexible enough to run shell code to generate matches. Better yet, write the necessary completion logic in a familiar language like Perl , Python, Ruby , etc., and use Bash as glue code to tie it all together.

In all, this project aims to 1 minimize the effort needed to add bash-completion so more programs support it, 2 provide a uniform bash-completion experience, and 3 to ultimately build a collection of community made completion packages for all to enjoy.

Say you have a program called tojson with the following interface.

tojson -h | --help | --version
tojson make --source=<file>
tojson format --source=<file>

Simple enough. There is the base command tojson, two sub-commands make/format, and their respective flags.

Make a folder named tojson. Inside the folder create the file tojson.acmap with the following content:

( acmap syntax is used to map commands/flag)

tojson = [
	-h
	--help
	--version
]
tojson.make = [
	--source=
]
tojson.format = [
	--source=
]

However, because the program's interface is so simple let's make use of shorthand syntax.

tojson = -h|--help|--version
tojson.make = --source=
tojson.format = --source=

make and format result in the same so delimiting them can reduce things.

tojson = -h|--help|--version
tojson.make,
tojson.format = --source=

Going a step further, commands can be grouped for even more terseness.

tojson = -h|--help|--version
tojson.{make,format} = --source=

All work and leave tojson.acmap compact yet still readable.

From here nodecliac takes over via built in commands (i.e. make, add) like so:

$ nodecliac make --source path/to/tojson.acmap && nodecliac add path/to/tojson

The make command compiles the acmap to an acdef file (the actual file used by nodecliac when providing completions). The add command adds the program's completion package to the registry (where completion packages get stored).

With everything in place, nodecliac can now provide Bash completions for the program tojson.

$ tojson ❚[TAB]
format    make

$ tojson -❚[TAB]
-h    --help    --version

Although the used example is meant to serve as a quick nodecliac introduction, a proper completion package creation guide exists. Additionally, pre-made completion packages for several programs of varying complexity are available for reference.

For more in-depth information regarding acmap syntax, nodecliac CLI/commands, .etc — check out the full documentation.