This library wraps the BSD libedit command line editor. The binding provides a high level API to enable command line editing on the Prolog user streams and low level predicates to apply the library on other streams and program the library.
While reading a line, the binding surrounds the prompt and the input
with the OSC 133 semantic prompt marks of FinalTerm: ESC]133;A
before the prompt, ESC]133;B before the input, ESC]133;C
after the line was entered and ESC]133;D where its output
ends, which is just before the next line is asked for. A term that takes
more than one line is read a line at a time; the prompt of each line
after the first is marked ESC]133;A;k=s, which says it
continues an input rather than starting one, so that a terminal can keep
the whole term together. A terminal that understands them (Epilog,
iTerm2, kitty, WezTerm, VS Code) can tell prompt, input and output
apart, which is what lets it jump between prompts, act on the output of
one command or, in Epilog, move the caret to a click in the line being
edited. A read that asks for a single character, as get_single_char/1
and the debugger do, is not marked: there is no line being edited there.
A terminal that does not know the marks ignores them; one that prints
them instead can be spared them with el_set/2
using prompt_marks(false).
user_input
is connected to a terminal. This is the high level predicate used for
most purposes. The remainder of the library interface deals with low
level predicates that allows for applying and programming libedit in
non-standard situations.
The library is registered with ProgName set to swipl
(see
el_wrap/4).
Options processed:
history or 100 if this flag is not defined.
| ProgName | is the name of the invoking
program, used when reading the editrc(5) file to determine
which settings to use. |
forall(el_setup(Input), true) after
the input stream has been wrapped, the default Prolog commands have been
added and the default user setup file has been sourced using
el_source/2. It can be used to
define and bind additional commands.$HOME/.editrcbind command with the given arguments.
The example below lists the current key bindings.
?- el_bind(user_input, ['-a']).
The predicate el_bind/2 is
typically used to bind commands defined using el_addfn/4.
Note that the C proxy function has only the last character of the
command as context to find the Prolog binding. This implies we cannot
both bind e.g., "^[?" and "?" to a Prolog function.
bind -a (see el_bind/2)
and Goal is called of the associated key-binding is
activated. Goal is called as
call(:Goal, +Input, +Char, -Continue)
where Input is the input stream providing access to the
editor, Char the activating character and Continue must be instantated
with one of the known continuation codes as defined by libedit: norm,
newline, eof, arghack, refresh, refresh_beep, cursor,
redisplay, error or fatal. In
addition, the following Continue code is provided.
The registered Goal typically used el_line/2 to fetch the input line and el_cursor/2, el_insertstr/2 and/or el_deletestr/2 to manipulate the input line.
Normally el_bind/2 is used to associate the defined command with a keyboard sequence.
el_set() and el_wset(). Currently
provided values for
Action are:
el_wsey() EL_WORDCHARS, which is
only provided in some recent versions of libedit.
ESC[200~ /
ESC[201~ before each prompt, which the default bindings
route through bracketed_paste/3. Disabling
sends the matching
ESC[?2004l sequence immediately. enable_bracketed_paste/1
manages this based on the current editor; you normally do not need to
set it directly.
This predicate fails silently of Action is not implemented. Illegal input raises in an exception.
el_get(). Currently supported Property
terms:
emacs or vi,
reflecting the current keymap selected via el_bind/2
with -e / -v.
Any other Property raises a domain_error(editline_property, _).
line(Before, After),
where Before is a string holding the text before the cursor
and After is a string holding the text after the cursor.history() from libedit. Supported actions are:
el_history() using H_GETSIZE,
which returns the number of currently saved events. The number of saved
events may be computed from first and last or
using el_history_events/2.
first is the most recent
event and
last the oldest.
history() API, retrieving a numbered event
without changing the current notion.
Num-String,
where
Num is the event number and String is the
associated string without terminating newline.| File | is a file specification for absolute_file_name/3. |
| File | is a file specification for absolute_file_name/3. |
LIBEDIT_MAJOR*10000 + LIBEDIT_MINOR*100.
The version is generated from the include file histedit.h,
which implies that the actual version of the shared library may be
different.input
in effect while the user is typing (see
decorate_prompt/2 in boot/toplevel.pl).
Erasing part of the screen paints it with the current background colour,
so libedit must switch these attributes off before it erases the rows
the line no longer uses, e.g. after unwrapping a long line or moving
from a multi-line history entry to a shorter one. See EL_ATTRS in
libedit.
The toplevel calls this each time it builds a prompt, so a theme loaded at run time is picked up. Does nothing if libedit is too old to support this.