Readline - Console library in Go
This project is actually the merging of an original project (github.com/lmorg/readline) and one of its forks (github.com/maxlandon/readline): both introductions are thus here given, in chronological order.
This project began a few years prior to this git commit history as an API for murex, an alternative UNIX shell, because I wasn't satisfied with the state of existing Go packages for readline (at that time they were either bugger and/or poorly maintained, or lacked features I desired). The state of things for readline in Go may have changed since then however own package had also matured and grown to include many more features that has arisen during the development of murex. So it seemed only fair to give back to the community considering it was other peoples readline libraries that allowed me rapidly prototype murex during it's early stages of development.
This project started out of the wish to make an enhanced console for a security tool (Sliver, see below). There are already several readline libraries available in Go (github.com/chzyer/readline, and github.com/lmorg/readline), but being stricter readline implementations, their completion
This project is not an integrated REPL/command-line application, which means it does not automatically understand nor executes any commands.
However, having been developed in a project using the CLI github.com/jessevdk/go-flags library,
it also includes some default utilities (completers) that are made to work with this library, which I humbly but highly recommend.
Please see the Wiki (or the
examples/ directory) for information on how to use these utilities.
A summarized list of features supported by this library is the following:
Input & Editing
- Vim / Emacs input and editing modes.
- Optional, live-refresh Vim status.
- Vim modes (Insert, Normal, Replace, Delete) with visual prompt Vim status indicator
- line editing using
viin the example - enabled by pressing
- Vim registers (one default, 10 numbered, and 26 lettered)
- Vim iterations
- Most default keybindings you might find in Emacs-like readline. Some are still missing though
- 3 types of completion categories (
- Stackable, combinable completions (completion groups of any type & size can be proposed simultaneously).
- Controlable completion group sizes (if size is greater than completions, the completions will roll automatically)
- Virtual insertion of the current candidate, like in Z-shell.
Listcompletion groups, ability to have alternative candidates (used for displaying
-s(short) options, with descriptions)
- Completions working anywhere in the input line (your cursor can be anywhere)
- Completions are searchable with Ctrl-F, like in lmorg's library.
Prompt system & Colors
- 1-line and 2-line prompts, both being customizable.
- Functions for refreshing the prompt, with optional behavior settings.
- Optional colors (can be disabled).
Hints & Syntax highlighting
- A hint line can be printed below the input line, with any type of information. See utilities for a default one.
- The Hint system is now refreshed depending on the cursor position as well, like completions.
- A syntax highlighting system. A default one is also available.
- Ability to have 2 different history sources (I used this for clients connected to a server, used by a single user).
- History is searchable like completions.
- Default history is an in-memory list.
- Quick history navigation with Up/Down arrow keys in Emacs mode, and j/k keys in Vim mode.
- Default Tab completer, Hint formatter and Syntax highlighter provided, using github.com/jessevdk/go-flags
command parser to build themselves. These are in the
completers/directory. Please look at the Wiki page for how to use them. Also feel free to use them as an inspiration source to make your owns.
- Colors mercilessly copied from github.com/evilsocket/islazy/
- Also in the
completersdirectory, completion functions for environment variables (using Go's std lib for getting them), and dir/file path completions.
Installation & Usage
As usual with Go, installation:
go get github.com/maxlandon/readline
Please see either the
examples directory, or the Wiki for detailed instructions on how to use this library.
The complete documentation for this library can be found in the repo's Wiki. Below is the Table of Contents:
Hint Formatter & Syntax Highlighter
Command & Completion utilities
Project Status & Support
Being alone working on this project and having only one lifetime (anyone able to solve this please call me), I can engage myself over the following:
- Support for any issue opened.
- Answering any questions related.
- Being available for any blame you'd like to make for my humble but passioned work. I don't mind, I need to go up.
The version string will be based on Semantic Versioning. ie version numbers will be formatted
(major).(minor).(patch)- for example
majorreleases will have breaking changes. Be sure to read CHANGES.md for upgrade instructions
minorreleases will contain new APIs or introduce new user facing features which may affect useability from an end user perspective. However
minorreleases will not break backwards compatibility at the source code level and nor will it break existing expected user-facing behavior. These changes will be documented in CHANGES.md too
patchreleases will be bug fixes and such like. Where the code has changed but both API endpoints and user experience will remain the same (except where expected user experience was broken due to a bug, then that would be bumped to either a
majordepending on the significance of the bug and the significance of the change to the user experience)
Any updates to documentation, comments within code or the example code will not result in a version bump because they will not affect the output of the go compiler. However if this concerns you then I recommend pinning your project to the git commit hash rather than a
readline library is distributed under the Apache License (Version 2.0, January 2004) (http://www.apache.org/licenses/).
All the example code and documentation in
/completers is public domain.