NAME

Fugu::REPL - a line editor for an operator prompt

SYNOPSIS

    use Fugu::REPL;
    my $repl = Fugu::REPL->new(
        prompt   => 'fugu> ',
        commands => { help => 'show this help', quit => 'end the session' },
        complete => sub ($word, $line) { return @candidates },
        watch    => [$reply_pipe],
    );
    while (defined(my $line = $repl->read_line)) {
        $repl->show($output);
    }
    exit 1 if $repl->event eq 'watch';

DESCRIPTION

Fugu::REPL reads one operator command line from a terminal. It edits the line with a fixed emacs-style key subset, completes a word, keeps a session history in memory, and filters untrusted bytes before it shows them.

The module stands alone. It uses core Perl only, it loads no other "Fugu::" module, and it never logs: every failure is a return value. It operates inside the "stdio tty" promises of pledge(2): it opens no file, creates no process, and reaches no network. The escape sequences are the fixed ANSI set, because a terminfo read needs the "rpath" promise.

The editor holds the terminal in raw mode only while it reads. restore() puts the terminal back on every exit path, and the destructor calls it.

This document is the interface contract of the module. The FuguPass and FuguTTX specifications cite it, so a change here coordinates with both.

THE KEY SUBSET

The editor implements one fixed set of keys.

    Enter               accept the line
    Tab                 complete the word before the cursor,
                        and cycle through the candidates
    Shift-Tab           cycle back through the candidates
    Ctrl-A, Home        go to the start of the line
    Ctrl-E, End         go to the end of the line
    Ctrl-B, Left        go back one character
    Ctrl-F, Right       go forward one character
    Ctrl-P, Up          recall the previous history line
    Ctrl-N, Down        recall the next history line
    Backspace, Ctrl-H   delete the character before the cursor
    Ctrl-D              delete the character under the cursor,
                        or end the input on an empty line
    Ctrl-K              delete to the end of the line
    Ctrl-U              delete the whole line
    Ctrl-W              delete the word before the cursor
    Ctrl-L              draw the line again
    Ctrl-C              clear the line and report an interrupt

An unknown escape sequence does nothing. The editor never inserts the bytes of a sequence into the line.

COMPLETION

The "complete" callback receives the word before the cursor and the whole line. It returns the candidate list.

The module completes a command name from the command table when the cursor is in the first word of the command language. It calls the callback otherwise. One candidate replaces the word. Several candidates extend the word to the common prefix. When no extension remains, "Tab" shows the list once, selects the first candidate, and starts a cycle. Each further "Tab" selects the next candidate, and "Shift-Tab" selects the previous one. The cycle wraps, and every other key ends it.

The callback runs in the caller's process, at the prompt. A callback that blocks blocks the prompt.

RETURN VALUES

read_line() returns the line, or "undef" at an end of file, on a watch event, and on an interrupt. confirm() returns 1 or 0. event() returns "line", "eof", "watch", "interrupt", or "undef" before the first read. ready_handle() returns a handle after a watch event and "undef" otherwise.

EXAMPLES

This example runs a session that a peer on a reply pipe can end:

    my $repl = Fugu::REPL->new(
        commands => { help => 'show this help', quit => 'end the session' },
        watch    => [$reply],
    );
    while (1) {
        my $line = $repl->read_line;
        if (!defined $line) {
            next if $repl->event eq 'interrupt';
            last;
        }
        last if $line eq 'quit';
        $repl->show( handle_command($line) );
    }

This example gates a dangerous step:

    apply_change() if $repl->confirm('Apply the change?');

ERRORS

new() and the watch() accessor die on a programming error: a "complete" argument that is not a code reference, or a watch handle with no descriptor. Every other failure is a return value, and event() names it.

SEE ALSO

pledge(2), termios(4), Fugu::CLI, Fugu::Signal

AUTHORS

Dick Olsson <hi@senzilla.io>

CAVEATS

The editor counts a UTF-8 sequence as one character for the cursor. A double-width character therefore draws one column short.

A line that grows past the terminal width wraps, and the redraw then trails the wrapped part. An operator command line is short in practice.

A candidate list can be longer than the terminal. The module shows the whole list and draws the prompt again; it has no page mode.

A signal that interrupts a blocked read reports the event "interrupt". The caller checks its own signal flags and decides whether to read again.