1339dc4a2f | ||
---|---|---|
.. | ||
completers | ||
examples | ||
raw | ||
CHANGES.md | ||
LICENSE | ||
README.md | ||
codes.go | ||
comp-grid.go | ||
comp-group.go | ||
comp-list.go | ||
comp-map.go | ||
cursor.go | ||
editor.go | ||
editor_plan9.go | ||
editor_unix.go | ||
editor_windows.go | ||
errors.go | ||
events.go | ||
go.mod | ||
go.sum | ||
godoc.go | ||
hint.go | ||
history.go | ||
info.go | ||
instance.go | ||
line.go | ||
line_test.go | ||
prompt.go | ||
raw_bsd.go | ||
raw_linux.go | ||
raw_plan9.go | ||
raw_solaris.go | ||
raw_unix.go | ||
raw_windows.go | ||
readline.go | ||
register.go | ||
syntax.go | ||
tab-virtual.go | ||
tab.go | ||
tabfind.go | ||
term.go | ||
timer.go | ||
tokenise.go | ||
tui-effects.go | ||
undo.go | ||
update.go | ||
vim.go | ||
vimdelete.go | ||
wrap.go |
README.md
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
andMap
) - 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
Prompt system
Completion Engine
Hint Formatter & Syntax Highlighter
Command History
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.
Version Information
-
The version string will be based on Semantic Versioning. ie version numbers will be formatted
(major).(minor).(patch)
- for example2.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. Howeverminor
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 aminor
ormajor
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 !