creating.md

Creating Completion Package

This guide uses Sublime Text 3's subl program to document completion package creation.

Summary

The process is straightforward:

• Scaffold package.
• Write .acmap file and compile to .acdef (repeat this until .acmap is complete).
• Once finished, add completion package to registry.
• Source .bashrc file to apply changes and start using.

Steps

1. Scaffold package

First let's scaffold the completion package. Navigate to ~/Desktop and run:

$ nodecliac init

It will start the builtin completion package generator — which asks a series of questions to scaffold your program's base completion package. After running nodecliac init a folder with the provided <command> name will be created. Inside it are 4 files:

<command>/
  ├── package.ini
  ├── <command>.acmap
  ├── <command>.acdef
  └── .<command>.config.acdef

Note: This is the simplest a completion package needs to be to work. Packages of more complexity may have a /placeholders and or a /hooks directory. The /placeholders directory is made and used internally by nodecliac after compiling. Therefore, never create this directory manually or store anything in this directory as it gets overwritten after every compile run. The /hooks directory is created manually and stores hook scripts. Outside of that, the manner in which additional files/folders are structured is up to you.

2. Write acmap file

Tip: Syntax grammar packages for Sublime Text 3, VSCode, and Atom are available.

Here is Sublime Text's CLI interface as of v3211:

Sublime Text build 3211

Usage: subl [arguments] [files]         Edit the given files
   or: subl [arguments] [directories]   Open the given directories

Arguments:
  --project <project>: Load the given project
  --command <command>: Run the given command
  -n or --new-window:  Open a new window
  -a or --add:         Add folders to the current window
  -w or --wait:        Wait for the files to be closed before returning
  -b or --background:  Don't activate the application
  -h or --help:        Show help (this message) and exit
  -v or --version:     Show version and exit

Filenames may be given a :line or :line:column suffix to open at a specific
location.

Now it's time to write the program's acmap. This is done by using acmap markup. Breaking it down, Sublime Text's subl command is very simple. There is only one command — the program (main/root) command subl and it has a few flags. As shown, each flag takes up its own line. Switches (flags representing either true or false) are appended a ?.

Open the generated acmap file, ~/Desktop/subl.acmap, and place the following acmap inside:

subl = [
    --project
    --command
    --new-window?
    --add?
    --wait?
    --background?
    --stay?
    --help?
    --version?
]

3. Compile .acdef

With the .acmap ready, the next thing to do is generate the .acdef file. To do so run:

$ nodecliac make --source ~/Desktop/subl/subl.acmap

This will parse subl.acmap to generate the program's acdef and config file: subl.acdef and .subl.config.acdef.

subl's completion package should look like:

subl/
  ├── package.ini
  ├── subl.acmap
  ├── subl.acdef
  └── .subl.config.acdef

4. Add to registry

This package is now complete. Let's add it to the registry so nodecliac can use it. In the package root run:

$ nodecliac add

Note: When developing a package the link and unlink commands should be used, which use symlinks instead of copying the folder every time there is change. Once package development is complete the add command should be used to copy package to the registry instead of using a symlink.

Tip: Run $ nodecliac registry to confirm package is in the registry. Output should list the name of the package.

5. Reload rcfile

Open a Terminal or $ source ~/.bashrc current one then type $ subl --TabTab to see completions.

What's Next

That was it for the subl command. Admittedly, the command is extremely simple and for that reason it's used in this guide. However, as should go without saying, the more complex a CLI program is the more its .acmap will require. Existing completion packages of varying degrees of complexity can be found here. Take a look at the yarn completion package which make use of a hook and Perl scripts.