package argsh

  1. Overview
  2. Docs
Automatic generation of zsh, fish and bash completion file for Stdlib.Arg module

Install

Dune Dependency

Authors

Maintainers

Sources

0.1.0.tar.gz
md5=2d1a6bedf3c90a1b44ff7d89e66b52ae
sha512=59a74b93bed383b40bf96d8d060d493f2b9d2aefe322afcf6d9ed4218a516a6b26907ab2f20da0e78b9703cbfb355b07b3267f0f9c6fc052eda986dbd6c67864

Description

Tags

shell arg stdlib completion

Published: 13 Dec 2023

README

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.

Dependencies (2)

  1. ocaml >= "4.13.0"
  2. dune >= "3.10"

Dev Dependencies (1)

  1. odoc with-doc

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.