You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Hilbish/readline
TorchedSammy 8d40179a73
fix(readline): dont do anything if length of input rune slice is 0
2 months ago
..
completers chore: bring readline in repo for easier maintenance 11 months ago
examples chore: bring readline in repo for easier maintenance 11 months ago
raw chore: bring readline in repo for easier maintenance 11 months ago
CHANGES.md chore: bring readline in repo for easier maintenance 11 months ago
LICENSE chore: bring readline in repo for easier maintenance 11 months ago
README.md chore: bring readline in repo for easier maintenance 11 months ago
codes.go fix(readline): use invert for completion highlight instead of hardcoded colors 10 months ago
comp-grid.go fix(readline): grip completion menu fixes 2 months ago
comp-group.go fix: percentages in completion entries causing a problem in the completion menus 7 months ago
comp-list.go fix: percentages in completion entries causing a problem in the completion menus 7 months ago
comp-map.go fix: percentages in completion entries causing a problem in the completion menus 7 months ago
cursor.go fix(readline): make forward delete work properly 11 months ago
editor.go chore: bring readline in repo for easier maintenance 11 months ago
editor_plan9.go chore: bring readline in repo for easier maintenance 11 months ago
editor_unix.go chore: bring readline in repo for easier maintenance 11 months ago
editor_windows.go chore: bring readline in repo for easier maintenance 11 months ago
errors.go chore: bring readline in repo for easier maintenance 11 months ago
events.go feat: add inline hint text and change what were hints previously to info (closes #126) 11 months ago
go.mod chore: bring readline in repo for easier maintenance 11 months ago
go.sum chore: bring readline in repo for easier maintenance 11 months ago
godoc.go chore: bring readline in repo for easier maintenance 11 months ago
hint.go feat: add inline hint text and change what were hints previously to info (closes #126) 11 months ago
history.go fix: provide correct command when navigating history (#214) 2 months ago
info.go feat: add inline hint text and change what were hints previously to info (closes #126) 11 months ago
instance.go fix: provide correct command when navigating history (#214) 2 months ago
line.go feat(hilbish.editor): add getLine function to get contents of line 7 months ago
line_test.go chore: bring readline in repo for easier maintenance 11 months ago
prompt.go fix(readline): correct function to count len of prompt to accomodate east asian characters 5 months ago
raw_bsd.go chore: bring readline in repo for easier maintenance 11 months ago
raw_linux.go chore: bring readline in repo for easier maintenance 11 months ago
raw_plan9.go chore: bring readline in repo for easier maintenance 11 months ago
raw_solaris.go chore: bring readline in repo for easier maintenance 11 months ago
raw_unix.go chore: bring readline in repo for easier maintenance 11 months ago
raw_windows.go chore: bring readline in repo for easier maintenance 11 months ago
readline.go fix(readline): dont do anything if length of input rune slice is 0 2 months ago
register.go feat: add hilbish.editor interface 9 months ago
syntax.go chore: bring readline in repo for easier maintenance 11 months ago
tab-virtual.go fix(readline): use uniseg to calculate width of virtual tab entry (closes #209) 3 months ago
tab.go fix: don't refetch tab completion on refresh if its already open (closes #163) 8 months ago
tabfind.go fix: print err don't panic and in the case of regex compile failing on menu find 8 months ago
term.go chore: bring readline in repo for easier maintenance 11 months ago
timer.go feat(hilbish.editor): add getLine function to get contents of line 7 months ago
tokenise.go chore: bring readline in repo for easier maintenance 11 months ago
tui-effects.go chore: bring readline in repo for easier maintenance 11 months ago
undo.go chore: bring readline in repo for easier maintenance 11 months ago
update.go fix(readline): take into account newlines when calculating amount of lines taken up by input 4 months ago
vim.go fix(readline): put cursor at end of text when exiting editor 4 months ago
vimdelete.go feat: add inline hint text and change what were hints previously to info (closes #126) 11 months ago
wrap.go chore: bring readline in repo for easier maintenance 11 months ago

README.md

Readline - Console library in Go

Demo 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

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 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 !