% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(editline): BSD libedit based command line editing}

\label{sec:editline}

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.\vspace{0.7cm}

\begin{description}
    \predicate[det]{el_wrap}{0}{}
Enable using editline on the standard user streams if \verb$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 \textit{ProgName} set to \const{swipl} (see
\predref{el_wrap}{4}).

    \predicate[det]{el_wrap}{4}{+ProgName:atom, +In:stream, +Out:stream, +Error:stream}
Enable editline on the stream-triple $<$\arg{In},\arg{Out},\arg{Error}$>$. From this
moment on \arg{In} is a handle to the command line editor.

\begin{arguments}
\arg{ProgName} & is the name of the invoking program, used when reading
the \verb$editrc(5)$ file to determine which settings to use. \\
\end{arguments}

    \predicate[nondet,multifile]{el_setup}{1}{+In:stream}
This hooks is called as \verb$forall(el_setup(Input), true)$ \textit{after} the
input stream has been wrapped, the default Prolog commands have been
added and the default user setup file has been sourced using
\predref{el_source}{2}. It can be used to define and bind additional commands.

    \predicate[semidet]{el_wrapped}{1}{+In:stream}
True if \arg{In} is a stream wrapped by \predref{el_wrap}{3}.

    \predicate[det]{el_unwrap}{1}{+In:stream}
Remove the libedit wrapper for \arg{In} and the related output and error
streams.

\begin{tags}
    \tag{bug}
The wrapper creates \verb$FILE*$ handles that cannot be closed and
thus wrapping and unwrapping implies a (modest) memory leak.
\end{tags}

    \predicate[det]{el_source}{2}{+In:stream, +File}
Initialise editline by reading the contents of \arg{File}. If \arg{File} is
unbound try \verb|$HOME/.editrc|

    \predicate[det]{el_bind}{2}{+In:stream, +Args}
Invoke the libedit \const{bind} command with the given arguments. The
example below lists the current key bindings.

\begin{code}
?- el_bind(user_input, ['-a']).
\end{code}

The predicate \predref{el_bind}{2} is typically used to bind commands defined
using \predref{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., "\Shat{}[?" *and "?" to a Prolog
function.

\begin{tags}
    \tag{See also}
\verb$editrc(5)$ for more information.
\end{tags}

    \predicate[det]{el_addfn}{4}{+Input:stream, +Command, +Help, :Goal}
Add a new command to the command line editor associated with \arg{Input}.
\arg{Command} is the name of the command, \arg{Help} is the help string printed
with e.g. \verb$bind -a$ (see \predref{el_bind}{2}) and \arg{Goal} is called of the
associated key-binding is activated. \arg{Goal} is called as

\begin{code}
call(:Goal, +Input, +Char, -Continue)
\end{code}

where \arg{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: \const{norm},
\const{newline}, \const{eof}, \const{arghack}, \const{refresh}, \verb$refresh_beep$, \const{cursor},
\const{redisplay}, \const{error} or \const{fatal}. In addition, the following Continue
code is provided.

\begin{description}
    \termitem{electric}{Move, TimeOut, Continue}
Show \textit{electric caret} at \arg{Move} positions to the left of the normal
cursor positions for the given \arg{TimeOut}. \arg{Continue} as defined by
the \arg{Continue} value.
\end{description}

The registered \arg{Goal} typically used \predref{el_line}{2} to fetch the input line
and \predref{el_cursor}{2}, \predref{el_insertstr}{2} and/or \predref{el_deletestr}{2} to manipulate
the input line.

Normally \predref{el_bind}{2} is used to associate the defined command with a
keyboard sequence.

\begin{tags}
    \tag{See also}
\verb$el_set(3)$ \verb$EL_ADDFN$ for details.
\end{tags}

    \predicate[det]{el_line}{2}{+Input:stream, -Line}
Fetch the currently buffered input line. \arg{Line} is a term \verb$line(Before, After)$, where \arg{Before} is a string holding the text before the
cursor and \arg{After} is a string holding the text after the cursor.

    \predicate[det]{el_cursor}{2}{+Input:stream, +Move:integer}
\arg{Move} the cursor \arg{Move} character forwards (positive) or backwards
(negative).

    \predicate[det]{el_insertstr}{2}{+Input:stream, +Text}
Insert \arg{Text} at the cursor.

    \predicate[det]{el_deletestr}{2}{+Input:stream, +Count}
Delete \arg{Count} characters before the cursor.

    \predicate[det]{el_history}{2}{+In:stream, ?Action}
Perform a generic action on the history. This provides an incomplete
interface to \verb$history()$ from libedit. Supported actions are:

\begin{description}
    \termitem{clear}{}
Clear the history.
    \termitem{setsize}{+Integer}
Set size of history to size elements.
    \termitem{setunique}{+Boolean}
Set flag that adjacent identical event strings should not be
entered into the history.
\end{description}

    \predicate[det]{el_history_events}{2}{+In:stream, -Events:list(pair)}
Unify \arg{Events} with a list of pairs of the form \verb$Num-String$, where
\arg{Num} is the event number and \arg{String} is the associated string
without terminating newline.

    \predicate[det]{el_add_history}{2}{+In:stream, +Line:text}
Add a line to the command line history.

    \predicate[det]{el_read_history}{2}{+In:stream, +File:file}
Read the history saved using \predref{el_write_history}{2}.

\begin{arguments}
\arg{File} & is a file specification for \predref{absolute_file_name}{3}. \\
\end{arguments}

    \predicate[det]{el_write_history}{2}{+In:stream, +File:file}
Save editline history to \arg{File}. The history may be reloaded using
\predref{el_read_history}{2}.

\begin{arguments}
\arg{File} & is a file specification for \predref{absolute_file_name}{3}. \\
\end{arguments}
\end{description}