README
¶
Bubbline
An input line editor for line-oriented terminal applications.
Based off the bubbletea library.
Features of the line editor
| Feature | Charm textarea ^T |
libedit ^l1 /readline [^l2] |
Bubbline (this library) |
|---|---|---|---|
| Multi-line editor with both horizontal and vertical cursor navigation. | ✅ | ✅ | ✅ |
| Secondary prompt for multi-line input. | ✅ | ✅ | ✅ |
| Resizes vertically automatically as the input grows. | ❌ | ✅ | ✅ |
| Supports history navigation and search. | ❌ | ✅ | ✅ |
| Word navigation across input lines. | ❌ | ✅ | ✅ |
| Enter key conditionally ends the input. | ❌ | ✅ | ✅ |
| Tab completion callback. | ❌ | ✅ | ✅ |
| Fancy presentation of completions with menu navigation. | ❌ | ✅ [^cp] | ✅ |
| Intelligent input interruption with Ctrl+C. | ❌ | ✅ | ✅ |
| Ctrl+Z (suspend process), Ctrl+\ (send SIGQUIT to process e.g. to get stack dump). | ❌ | ✅ | ✅ |
| Uppercase/lowercase/capitalize next word, transpose characters. | ✅ | ✅ | ✅ |
| Inline help for key bindings. | ❌ | ❌ | ✅ |
| Toggle overwrite mode. | ❌ [^p1] | ❌ | ✅ |
| Key combination to reflow the text to fit within a specific width. | ❌ | ❌ | ✅ |
| Hide/show the prompt to simplify copy-paste from terminal. | ❌ | ❌ | ✅ |
| Debug mode for troubleshooting. | ❌ | ❌ | ✅ |
| Open with external editor. | ❌ | (✅) [^ed] | ✅ |
| Bracketed paste [^bp] | ❌ [^p4] | ✅ | ❌ [^p4] |
[^l2]: GNU readline [^p1]: Pending https://github.com/charmbracelet/bubbles/pull/225 [^cp]: libedit/readline's completion menu is a single line of options with wraparound. [^bp]: https://en.wikipedia.org/wiki/Bracketed-paste [^p4]: Pending https://github.com/charmbracelet/bubbletea/pull/397 and https://github.com/charmbracelet/bubbletea/pull/397 [^ed]: Possible to configure via key binding macro.
Demo / explanation
Customizable key bindings
| Default keys | Description | Binding name |
|---|---|---|
| Ctrl+D | Terminate the input if the cursor is at the beginning of a line; delete character otherwise. | EndOfInput |
| Ctrl+C | Clear the input if non-empty, or interrupt input if already empty. | Interrupt |
| Tab | Run the AutoComplete callback if defined. |
AutoComplete |
| Alt+. | Hide/show the prompt (eases copy-paste from terminal). | HideShowPrompt |
| Ctrl+L | Clear the screen and re-display the current input. | Refresh |
| Ctrl+G | Abort the search if currently searching; no-op otherwise. | AbortSearch |
| Ctrl+R | Start searching; or previous search match if already searching. | SearchBackward |
| Alt+P | Recall previous history entry. | HistoryPrevious |
| Alt+N | Recall next history entry. | HistoryNext |
| Enter, Ctrl+M | Enter a new line; or terminate input if CheckInputComplete returns true. |
InsertNewline |
| Alt+Enter, Alt+Ctrl+M | Always complete the input; ignore input termination condition. | AlwaysComplete |
| Ctrl+O | Always insert a newline; ignore input termination condition. | AlwaysNewline |
| Ctrl+F, Right | Move one character to the right. | CharacterBackward |
| Ctrl+B, Left | Move one character to the left. | CharacterForward |
| Alt+F, Alt+Right, Ctrl+Right | Move cursor to the previous word. | WordForward |
| Alt+B, Alt+Left, Ctrl+Left | Move cursor to the next word. | WordBackward |
| Ctrl+A, Home | Move cursor to beginning of line. | LineNext |
| Ctrl+E, End | Move cursor to end of line. | LineEnd |
| Alt+<, Ctrl+Home | Move cursor to beginning of input. | MoveToBegin |
| Alt+>, Ctrl+End | Move cursor to end of input. | MoveToEnd |
| Ctrl+P, Up | Move cursor one line up, or to previous history entry if already on first line. | LinePrevious |
| Ctrl+N, Down | Move cursor one line down, or to next history entry if already on last line. | LineStart |
| Ctrl+T | Transpose the last two characters. | TransposeCharacterBackward |
| Alt+O, Insert | Toggle overwrite mode. | ToggleOverwriteMode |
| Alt+U | Make the next word uppercase. | UppercaseWordForward |
| Alt+L | Make the next word lowercase. | LowercaseWordForward |
| Alt+C | Capitalize the next word. | CapitalizeWordForward |
| Ctrl+K | Delete the line after the cursor. | DeleteAfterCursor |
| Ctrl+U | Delete the line before the cursor. | DeleteBeforeCursor |
| Backspace, Ctrl+H | Delete the character before the cursor. | DeleteCharacterBackward |
| Delete | Delete the character after the cursor. | DeleteCharacterForward |
| Ctrl+W, Alt+Backspace | Delete the word before the cursor. | DeleteWordBackward |
| Alt+D, Alt+Delete | Delete the word after the cursor. | DeleteWordForward |
| Ctrl+\ | Send SIGQUIT to process. | SignalQuit |
| Ctrl+Z | Send SIGTSTOP to process (suspend). | SignalTTYStop |
| Alt+? | Toggle display of keybindings. | MoreHelp |
| Alt+q | Reflow the current line. | ReflowLine |
| Alt+Shift+Q | Reflow the entire input. | ReflowAll |
| Alt+2, Alt+F2 | Edit with an external editor, as defined by env var EDITOR. (not enabled by default) | ExternalEdit |
| Ctrl+_, Ctrl+@ | Print debug information about the editor. (not enabled by default) | Debug |
Example use
package main
import (
"errors"
"fmt"
"io"
"log"
tea "github.com/charmbracelet/bubbletea"
"github.com/knz/bubbline"
)
func main() {
// Instantiate the widget.
m := bubbline.New()
for {
// Read a line of input using the widget.
val, err := m.GetLine()
// Handle the end of input.
if err != nil {
if err == io.EOF {
// No more input.
break
}
if errors.Is(err, bubbline.ErrInterrupted) {
// Entered Ctrl+C to cancel input.
fmt.Println("^C")
} else if errors.Is(err, bubbline.ErrTerminated) {
fmt.Println("terminated")
break
} else {
fmt.Println("error:", err)
}
continue
}
// Handle regular input.
fmt.Printf("\nYou have entered: %q\n", val)
m.AddHistory(val)
}
}
See the examples subdirectory for more examples!
Documentation
¶
Index ¶
- Variables
- type AutoCompleteFn
- type Candidate
- type Completions
- type Editor
- func (m *Editor) AddHistory(line string) error
- func (m *Editor) Close()
- func (m *Editor) GetLine() (string, error)
- func (m *Editor) LoadHistory(file string) error
- func (m *Editor) SaveHistory() error
- func (m *Editor) SetAutoSaveHistory(file string, autoSave bool)
- func (m *Editor) Update(imsg tea.Msg) (tea.Model, tea.Cmd)
- type Entry
- type Values
Constants ¶
This section is empty.
Variables ¶
var ErrInterrupted = editline.ErrInterrupted
ErrInterrupted is returned when the input was interrupted with e.g. Ctrl+C, or when SIGINT was received.
var ErrTerminated = errors.New("terminated")
ErrTerminated is returned when the input was interrupted by receiving SIGTERM.
Functions ¶
This section is empty.
Types ¶
type AutoCompleteFn ¶
type AutoCompleteFn = editline.AutoCompleteFn
AutoCompleteFn is called upon the user pressing the autocomplete key. The callback is provided the text of the input and the position of the cursor in the input. The returned msg is printed above the input box.
type Completions ¶
type Completions = editline.Completions
Completions is the return value of AutoCompleteFn. It is a combination of Values and a Candidate function that converts a display Entry into a replacement Candidate.
type Editor ¶
Editor represents an input line editor.
func (*Editor) AddHistory ¶
AddHistory adds a history entry and optionally saves the history to file.
func (*Editor) Close ¶
func (m *Editor) Close()
Close should be called when the editor is not used any more.
func (*Editor) LoadHistory ¶
LoadHistory loads the entry history from file.
func (*Editor) SaveHistory ¶
SaveHistory saves the current history to the file previously configured with SetAutoSaveHistory.
func (*Editor) SetAutoSaveHistory ¶
SetAutoSaveHistory enables/disables auto-saving of entered lines to the history.
Source Files
Directories