package argsh

argsh

A small and simple OCaml library to easily create bash, zsh and fish autocompletion files for programs using the Stdlib.Arg library.

LICENSE

argsh is distributed under the MIT License.

How to use

Simple usage

You can output the content of a completion file to a Format.formatter simply by calling Argsh.Zsh.create format program_name specs, where specs is a value of type (string * Arg.spec * string) list. Similarly, you can use Argsh.Fish.create and Argsh.Bash.create to output respectively fish and bash completions files.

You can build a completion file by using Argsh.builder.file program_name spec file_name. What shell to complete will be determined by file_name suffix. It should be either: .zsh, .fish or .bash. The function will raise Invalid_argument otherwise.

A more advanced usage: Automating the creation of completion files

It is also possible to automate the creation of these completion file if your project use dune. One possible way to accomplish this is presented in the example folder.

We first need to create an executable. This executable (here called build_sh_completion) depends on the argsh library. It simply takes as arguments a list of files ending in .zsh, .fish or .bash, and fill them with the appropriate completion files.

You should replace the values spec and executable_name to fit your needs.

By not specifying a public_name for this executable, we guarantee that it will not be installed for the end user, and will only remain a building tool.

Please note that you still have to add argsh as a dependency to your project with this method, as argsh will be necessary at build time to create completion files. You can make this dependency optional, but some changes to the provided scripts will be needed.

To call it automatically, we then need to add a new rule, here called sh-completion. This rule specify the creation of three files, called completion.bash, completion.zsh and completion.fish, and call the build_sh_completion executable to populate them.

To call this rule explicitly and check that everything behave as expected, we can use the dune build @sh-completion command. If all things work well, we should see the files created somewhere in the _build/ folder.

To be more specific, the actual emplacement of the created file are the same as the place where the dune and build_sh_completion.ml files are located, only in the _build/ subdirectory.

Finally, we need to specify that those created file are to be installed on the user system along with the currently defined package. This is done with the install stanza.