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 and fish
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

Availability

Exoskeleton has not yet been published as a binary, though work is ongoing to fix this.

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.

Related Projects

The following Scala One libraries are dependencies of Exoskeleton:

No other Scala One libraries are dependents of Exoskeleton.

Status

Exoskeleton is classified as fledgling. For reference, Scala One projects are categorized into one of the following five stability levels:

embryonic: for experimental or demonstrative purposes only, without any guarantees of longevity
fledgling: of proven utility, seeking contributions, but liable to significant redesigns
maturescent: major design decisions broady settled, seeking probatory adoption and refinement
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

Projects at any stability level, even embryonic projects, are still ready to be used, but caution should be taken if there is a mismatch between the project's stability level and the importance of your own project.

Exoskeleton is designed to be small. Its entire source code currently consists of 341 lines of code.

Building

Exoskeleton can be built on Linux or Mac OS with Fury, however the approach to building is currently in a state of flux, and is likely to change.

Contributing

Contributors to Exoskeleton are welcome and encouraged. New contributors may like to look for issues marked beginner.

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 unless there is a good reason to keep them private. While it can be tempting to repsond to such questions, private answers cannot be shared with a wider audience, and it can result in duplication of effort.

Author

Exoskeleton was designed and developed by Jon Pretty, and commercial support and training is available from Propensive OÜ.

Name

Exoskeleton is a library for interacting with shells, which are their exterior skeletons—or Exoskeletons.

propensive / exoskeleton 0.1