Exoskeleton
Exoskeleton is a Scala library for to make it easy to write command-line applications which interact through tab-completion in bash
, zsh
and fish
by implementing a simple, functional API to define the execution of parameters.
Features
- unified programmatic tab-completions for
bash
,zsh
andfish
- automatic installation of completion scripts for each shell
- tab-completions can be generated programmatically on-demand
- high-level APIs for programs following common tab-completion patterns
- low-level APIs for more fine-grained control over completions
- fully functional API
- can be used with GraalVM to eliminate JVM startup time
Getting Started
Exoskeleton provides the Application
trait, akin to App
in the Scala Standard Library. In addition to a main
method, the Application
trait defines a complete
method, which should be implemented to return a sequence of tab-completions based on the current state of the command-line, which is passed in as an input parameter.
Explanation
For a shell to offer tab-completions for a command to the user, it needs to find definitions for the possible ways of completing the arguments to that command. In general, this is done by searching a sequence of possible locations for a file with a predictable name based on the command name (e.g. for cmd
, this file will be called _cmd
or cmd.fish
). These locations are usually defined in an environment variable, containing at least some default initial values, but potentially with additional paths added to it during the shell startup script, e.g. .bashrc
for bash
.
The way a completion script works will be different for every shell, because their tab-completion systems all work differently, but each shell typically provides a command for specifying command completions which will be called from the completion script. Completion scripts for most commands define a static set of completions (which may be dependent on the state of the command-line being completed).
Exoskeleton, however, defines very general completion scripts for each shell it supports, which all run the command whose parameters are being completed in “completion mode”, effectively calling the Exoskeleton application’s complete
method. The completion scripts receive a response from the Exoskeleton application, in aformat that is specific to each shell, which is transformed into calls to the completion command for that particular shell.
Generation of completion scripts
Source files may be generated by running,
java -cp exoskeleton.jar exoskeleton.Generate <shell> <command> <dir>
where shell is one of bash
, zsh
and fish
, command is the name of the command that completions are being provided for, and dir is the directory in which the script should be written.
Status
Exoskeleton is classified as fledgling. Propensive defines the following five stability levels for open-source projects:
- embryonic: for experimental or demonstrative purposes only, without guarantee of longevity
- fledgling: of proven utility, seeking contributions, but liable to significant redesigns
- maturescent: major design decisions broady settled, seeking probatory adoption and refinement of designs
- dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version
1.0
or later - adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated
Availability
Exoskeleton’s source is available on GitHub, and may be built with Fury by cloning the layer propensive/exoskeleton
.
fury layer clone -i propensive/exoskeleton
or imported into an existing layer with,
fury layer import -i propensive/exoskeleton
A binary is available on Maven Central as com.propensive:exoskeleton-core_<scala-version>:2.0.0
. This may be added to an sbt build with:
libraryDependencies += "com.propensive" %% "exoskeleton-core" % "2.0.0"
Contributing
Contributors to Exoskeleton are welcome and encouraged. New contributors may like to look for issues marked .
We suggest that all contributors read the Contributing Guide to make the process of contributing to Exoskeleton easier.
Please do not contact project maintainers privately with questions, as other users cannot then benefit from the answers.
Author
Exoskeleton was designed and developed by Jon Pretty, and commercial support and training is available from Propensive OÜ.
License
Exoskeleton is copyright © 2017-21 Jon Pretty & Propensive OÜ, and is made available under the Apache 2.0 License.