japhb / Terminal-LineEditor

Generalized terminal line editing for Raku
Artistic License 2.0
7 stars 3 forks source link

Actions Status

NAME

Terminal::LineEditor - Generalized terminal line editing

SYNOPSIS

### PREP

use Terminal::LineEditor;
use Terminal::LineEditor::RawTerminalInput;

# Create a basic CLI text input object
my $cli = Terminal::LineEditor::CLIInput.new;

### BASICS

# Preload some input history
$cli.load-history($history-file);
$cli.add-history('synthetic input', 'more synthetic input');

# Prompt for input, supporting common edit commands,
# scrolling the field to stay on one line
my $input = $cli.prompt('Please enter your thoughts: ');

# Prompt for a password, masking with asterisks (suppresses history)
my $pass  = $cli.prompt('Password: ', mask => '*');

# Prompt defaults to empty
my $stuff = $cli.prompt;

# Review and save history
.say for $cli.history;
$cli.save-history($history-file);

### TYPICAL USE

loop {
    # Get user's input
    my $in = $cli.prompt("My prompt >");

    # Exit loop if user indicated finished
    last without $in;

    # Add line to history if it is non-empty
    $cli.add-history($in) if $in.trim;

    # Do something with the input line; here we just echo it
    say $in;
}

DESCRIPTION

Terminal::LineEditor is a terminal line editing package similar to Linenoise or Readline, but not a drop-in replacement for either of them. Terminal::LineEditor has a few key design differences:

Use with Rakudo REPL

A PR for Rakudo has been created to allow Terminal::LineEditor to be used as the REPL line editor when Rakudo is used in interactive mode. If your Rakudo build includes this PR, you can set the following in your environment to use Terminal::LineEditor by default:

export RAKUDO_LINE_EDITOR=LineEditor

If the environment variable is not specified, but Terminal::LineEditor is the only line editing module installed, Rakudo will auto-detect and enable it.

Default Keymap

The latest version of the default keymap is specified in Terminal::LineEditor::KeyMappable.default-keymap(), but the below represents the currently implemented, commonly used keys:

Commonly Used Keys
KEY FUNCTION NOTES
Ctrl-A move-to-start
Ctrl-B move-char-back
Ctrl-C abort-input
Ctrl-D abort-or-delete Abort if empty, or delete-char-forward
Ctrl-E move-to-end
Ctrl-F move-char-forward
Ctrl-H delete-char-back
Ctrl-J finish LF (Line Feed)
Ctrl-K delete-to-end
Ctrl-L refresh-all
Ctrl-M finish CR (Carriage Return)
Ctrl-N history-next
Ctrl-P history-prev
Ctrl-T swap-chars
Ctrl-U delete-to-start
Ctrl-V literal-next
Ctrl-W delete-word-back
Ctrl-Y yank
Ctrl-Z suspend
Ctrl-_ undo Ctrl-Shift-<hyphen> on some keyboards
Backspace delete-char-back
CursorLeft move-char-back
CursorRight move-char-forward
CursorHome move-to-start
CursorEnd move-to-end
CursorUp history-prev
CursorDown history-next
Alt-b move-word-back
Alt-c tclc-word Readline treats this as Capitalize
Alt-d delete-word-forward
Alt-f move-word-forward
Alt-l lowercase-word
Alt-t swap-words
Alt-u uppercase-word
Alt-< history-start Alt-Shift-<comma> on some keyboards
Alt-> history-end Alt-Shift-<period> on some keyboards

All bindable edit functions are defined in the Terminal::LineEditor::SingleLineTextInput role (in each corresponding method beginning with edit-) or is one of the following special actions:

Special Actions
ACTION MEANING
abort-input Throw away input so far and return an undefined Str
abort-or-delete abort-input if empty, otherwise delete-char-forward
finish Accept and return current input line
literal-next Insert a literal control character into the buffer
suspend Suspend the program with SIGTSTP, wait for SIGCONT
history-start Switch input to first line in history
history-prev Switch input to previous line in history
history-next Switch input to next line in history
history-end Switch input to last line in history (the partial input)

Architecture

Terminal::LineEditor is built up in layers, starting from the most abstract:

Edge Cases

There are a few edge cases for which Terminal::LineEditor chose one of several possible behaviors. Here's the reasoning for each of these otherwise arbitrary decisions:

Unmapped Functionality

Some of the functionality supported by lower layers of Terminal::LineEditor is not exposed in the default keymap of Terminal::LineEditor::KeyMappable. This is generally because no commonly-agreed shell keys map to this functionality.

For example, Terminal::LineEditor::SingleLineTextBuffer can treat replace as an atomic operation, but basic POSIX shells generally don't; they instead expect the user to delete and insert as separate operations.

That said, if I've missed a commonly-supported key sequence for any of the unmapped functionality, please open an issue for this repository with a link to the relevant docs so I can expand the default keymap.

AUTHOR

Geoffrey Broadwell gjb@sonic.net

COPYRIGHT AND LICENSE

Copyright 2021-2024 Geoffrey Broadwell

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.