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.

 el_wrap is det

 el_wrap(+Options) is det

Enable using editline on the standard user streams if 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:

pipes(+Boolean)

Used by Epilog windows to indicate we are reading from a Windows named pipe in overlapped mode. Ignored on other platforms.

history(+Size)

Size of the history. Default is defined by the Prolog flag history or 100 if this flag is not defined.

alert_signo(+Integer)

Signal used for making thread_signal/2 work while the thread is in a blocking system call.

 enable_bracketed_paste(+Input) is det[private]

Sync bracketed paste mode with the current editor: bind ESC[200~ to bracketed_paste/3 and enable the mode in emacs, unbind and disable it in vi. In vi mode ESC leaves insert mode, so the ESC[200~ start marker cannot be dispatched as a key binding. Called from el_wrap/1 after the el_setup/1 hook, since that hook may switch editor with el_bind/2 -v or -e.

 enable_word_motion(+Input) is det[private]

Bind the xterm Ctrl+Left/Ctrl+Right escape sequences to word motion. The Epilog terminal sends ESC[1;5D and ESC[1;5C for these key combinations (see packages/xpce/src/txt/terminal.c); most xterm-compatible terminals use the same sequences. In vi mode the binding is installed in both the insert keymap and the command (alternative) keymap. Called after the el_setup/1 hooks since those may switch editor.

This complements the readline emulation, which already binds these sequences in its initialisation.

 enable_windows_eof(+Input) is det[private]

Bind ^Z to send end-of-file on Windows, matching the platform convention (compare with ^D on Unix). Routed through libedit's built-in em-delete-or-list (emacs) or vi-list-or-eof (vi), both of which return EOF on an empty line.

 el_wrap(+ProgName:atom, +In:stream, +Out:stream, +Error:stream) is det

 el_wrap(+ProgName:atom, +In:stream, +Out:stream, +Error:stream, +Options) is det

Enable editline on the stream-triple <In,Out,Error>. From this moment on In is a handle to the command line editor. Options:

pipes(true)

Windows only. Assume the I/O is using pipes rather than a console. This is used for the Epilog terminal.

Arguments:

ProgName

- is the name of the invoking program, used when reading the editrc(5) file to determine which settings to use.

 el_setup(+In:stream) is nondet[multifile]

This hooks is called as 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.

 el_wrapped(+In:stream) is semidet

True if In is a stream wrapped by el_wrap/3.

 el_unwrap(+In:stream) is det

Remove the libedit wrapper for In and the related output and error streams.

bug

- The wrapper creates FILE* handles that cannot be closed and thus wrapping and unwrapping implies a (modest) memory leak.

 el_source(+In:stream, +File) is det

Initialise editline by reading the contents of File. If File is unbound try $HOME/.editrc

 el_bind(+In:stream, +Args) is det

Invoke the libedit bind 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.

See also

- editrc(5) for more information.

 el_addfn(+Input:stream, +Command, +Help, :Goal) is det

Add a new command to the command line editor associated with Input. Command is the name of the command, Help is the help string printed with e.g. 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.

electric(Move, TimeOut, Continue)

Show electric caret at Move positions to the left of the normal cursor positions for the given TimeOut. Continue as defined by the Continue value.

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.

See also

- el_set(3) EL_ADDFN for details.

 el_set(+Input:stream, +Action) is semidet

Interface to el_set() and el_wset(). Currently provided values for Action are:

wordchars(+Text)

Set the characters considered part of a word. This feature depends on el_wsey() EL_WORDCHARS, which is only provided in some recent versions of libedit.

bracketed_paste(+Boolean)

Enable or disable bracketed paste mode. When enabled, the terminal is asked to bracket pasted text with 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(+Input:stream, ?Property) is semidet

Interface to el_get(). Currently supported Property terms:

editor(-Editor)

Editor is unified with emacs or vi, reflecting the current keymap selected via el_bind/2 with -e / -v.

bracketed_paste(-Boolean)

Whether bracketed paste mode is currently enabled; see el_set/2.

Any other Property raises a domain_error(editline_property, _).

 el_line(+Input:stream, -Line) is det

Fetch the currently buffered input line. Line is a term 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.

 el_cursor(+Input:stream, +Move:integer) is det

Move the cursor Move character forwards (positive) or backwards (negative).

 el_insertstr(+Input:stream, +Text) is det

Insert Text at the cursor.

 el_deletestr(+Input:stream, +Count) is det

Delete Count characters before the cursor.

 el_history(+In:stream, ?Action) is det

Perform a generic action on the history. This provides an incomplete interface to history() from libedit. Supported actions are:

clear

Clear the history.

setsize(+Integer)

Set size of history to size elements.

getsize(-Integer)

Unify Integer with the maximum size of the history. Note that this is not the same as 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.

setunique(+Boolean)

Set flag that adjacent identical event strings should not be entered into the history.

first(-Num, -String)

last(-Num, -String)

curr(-Num, -String)

prev(-Num, -String)

next(-Num, -String)

Retrieve an event. Num is the event number and String is the event string. Note that first is the most recent event and last the oldest.

set(Num)

Set the notion of current to Num.

prev_str(+Search, -Num, -String)

next_str(+Search, -Num, -String)

Retrieve the previous or next event whose String starts with Search.

event(+Num, -String)

True when String represents event Num. This is an extension to the history() API, retrieving a numbered event without changing the current notion.

 el_history_events(+In:stream, -Events:list(pair)) is det

Unify Events with a list of pairs of the form Num-String, where Num is the event number and String is the associated string without terminating newline.

 el_add_history(+In:stream, +Line:text) is det

Add a line to the command line history.

 el_read_history(+In:stream, +File:file) is det

Read the history saved using el_write_history/2.

Arguments:

File	- is a file specification for absolute_file_name/3.

 el_write_history(+In:stream, +File:file) is det

Save editline history to File. The history may be reloaded using el_read_history/2.

Arguments:

File	- is a file specification for absolute_file_name/3.

 el_version(-Version)

True when Version is 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.

 prolog:history(+Input, ?Action) is semidet[multifile]

Provide the plugable interface into the system command line management.

 compat_read_history(+Input, +File) is det[private]

Read the saved history. This loads both the LibEdit and old history format used by swipl-win.exe before migrating to SDL.

 bind_electric(+Input) is det[private]

Bind known close statements for electric input

 electric(+Input, +Char, -Continue) is det[private]

 complete(+Input, +Char, -Continue) is det[private]

Implementation of the registered complete editline function. The predicate is called with three arguments, the first being the input stream used to access the libedit functions and the second the activating character. The last argument tells libedit what to do. Consult el_set(3), EL_ADDFN for details.

 show_completions(+Input, +Char, -Continue) is det[private]

Editline command to show possible completions.

 common_competion(+Alternatives, -Common) is det[private]

True when Common is the common prefix of all candidate Alternatives.

 common_prefix(+Atoms, -Common) is det[private]

True when Common is the common prefix of all Atoms.

 common_prefix(+A1, +A2, -Prefix:string) is det[private]

True when Prefix is the common prefix of the atoms A1 and A2

 list_alternatives(+Alternatives)[private]

List possible completions at the current point.

To be done

- currently ignores the Comment in Text-Comment alternatives.

 isearch_history(+Input, +Char, -Continue) is det[private]

Incremental search through the history. The behavior is based on GNU readline.

 paste_quoted(+Input, +Char, -Continue) is det[private]

Paste the selection as quoted Prolog value. The quoting type depends on the quote before the caret. If there is no quote before the caret we paste as an atom.

 bracketed_paste(+Input, +Char, -Continue) is det[private]

Handler for the bracketed paste start sequence ESC[200~. Reads characters until the end sequence ESC[201~ is received and inserts the collected text literally, bypassing per-character key dispatch.

The terminal is asked to enable bracketed paste mode (ESC[?2004h) from the C layer each time a prompt is issued.

 collect_paste(+Input, +RevAcc, -RevResult) is det[private]

Read characters one at a time, accumulating them in reverse order. Stop when the reversed accumulator starts with the end sequence ESC[201~ (27,91,50,48,49,126) and return the reversed content that precedes it.

 paste_char(+Raw, -Char) is det[private]

Translate a raw character code from bracketed paste to the intended code. The tty line discipline in edit mode has INLCR set, which maps LF (10) to CR (13) before libedit reads it. We reverse that here so pasted newlines are inserted as actual newlines.