Hilbish/readline

Readline - Console library in Go

This demo GIF has been made with a Sliver project client.

Introduction

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.

lmorg

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.

maxlandon

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

Features Summary

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 $EDITOR (vi in the example - enabled by pressing [ESC] followed by [v])
• 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

Completion engine

• 3 types of completion categories (Grid, List and Map)
• 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.
• In List completion groups, ability to have alternative candidates (used for displaying --long and -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.

Command history

• 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.

Utilities

• 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/ tui/ package.
• Also in the completers directory, 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.

Documentation

The complete documentation for this library can be found in the repo's Wiki. Below is the Table of Contents:

Getting started

• Embedding readline in a project
• Input Modes

Prompt system

• Setting the Prompts
• Prompt Refresh

Completion Engine

• Completion Groups
• Completion Search

Hint Formatter & Syntax Highlighter

• Live Refresh Demonstration

Command History

• Main & Alternative Sources
• Navigation & Search

Command & Completion utilities

• Interfacing with the go-flags library
• Declaring go-flags commands
• Colors/Effects Usage

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.

Version Information

• The version string will be based on Semantic Versioning. ie version numbers will be formatted (major).(minor).(patch) - for example 2.0.1

• major releases will have breaking changes. Be sure to read CHANGES.md for upgrade instructions

• minor releases will contain new APIs or introduce new user facing features which may affect useability from an end user perspective. However minor releases 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

• patch releases 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 minor or major depending 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 patch release

License Information

The 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 /examples, /completers is public domain.

Warmest Thanks

• The Sliver implant framework project, which I used as a basis to make, test and refine this library. as well as all the GIFs and documentation pictures !
• evilsocket for his TUI library !