Documented interactive listener.

1 files changed, 343 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 5b173c78..7a8653a7 100644
--- a/txr.1
+++ b/txr.1
@@ -436,6 +436,12 @@ standard error device (but the if the situations occur, they still fail the
 query). This option does not suppress error generation during the parsing
 of the query, only during its execution.
 
+.coIP -i
+If this option is present, then \*(TX will enter into an interactive
+interpretation mode after processing all options, and the input query
+if one is present. See the INTERACTIVE LISTENER section for a
+description of this mode.
+
 .coIP -d
 .coIP --debugger
 Invoke the interactive \*(TX debugger. See the DEBUGGER section.
@@ -33160,6 +33166,343 @@ Parser error messages are directed to the
 .code *stderr*
 stream.
 
+.SH* INTERACTIVE LISTENER
+
+.SS* Overview
+
+On some target platforms, \*(TX provides an interactive listener, which is
+invoked using the
+.code -i
+command line option. The interactive listener provides features like visual
+editing of the command line, tab completion on \*(TL symbols, and history
+recall.
+
+.SS* Basic Operation
+
+The interactive listener prints a numbered prompt, and then accepts input
+characters from the terminal. Characters are either interpreted as editing
+commands or other special characters, or else are inserted into the
+editing buffer. The number in the prompt increments with every command.
+The first command line is numbered 1, the second one 2 and so forth.
+
+The carriage return character generated by the Enter key indicates that a
+complete line has been entered, and it is to be interpreted. The listener
+parses the line as a \*(TL expression, evaluates it, and prints the resulting
+value. If the evaluation of the line throws an exception, the listener
+intercepts the exception and prints information about it preceded by
+two asterisks and a space. These asterisks distinguish an exception from a
+result value.
+
+If an empty line is entered, or a line containing only spaces and tabs,
+the prompt is repeated without incrementing the number.
+
+.SS* Ways to Quit
+
+Pressing Ctrl-D in a completely empty command line terminates the listener.
+Another way to quit is to enter the
+.code :quit
+keyword symbol. When a command line evaluates to this symbol,
+the listener will terminate:
+
+.cblk
+  1> (+ 2 2)
+  4
+  2> :quit
+  os-shell $
+.cble
+
+Another way to terminate is to evaluate a call to the
+.code exit
+function. This method allows a termination status to be specified:
+
+.cblk
+  1> (exit 1)
+  os-shell $
+.cble
+
+Raising a fatal signal with the
+.code raise
+function is another way to quit:
+
+.cblk
+  1> (raise sig-abrt)
+  Aborted (core dumped)
+  os-shell $
+.cble
+
+.SS* Interrupting Evaluation
+
+Ctrl-C typed while editing a command line is interpreted as an editing command
+which causes that command line to be canceled. The listener prints the string
+.str ** intr
+and repeats the same prompt.
+
+If a command line is submitted for evaluation, the evaluation might take
+a long time or block for input. In these situations, typing Ctrl-C will issue
+an interrupt signal. The listener has installed a handler for this signal which
+generates an exception of type
+.code error
+which is caught by the listener. The exception's message is the string
+.str intr
+so that the listener ends up printing
+.str intr **
+like in the case of the Ctrl-C editing command. In this situation, though new
+command line prompt is issued with an incremented number, and the exception
+is recorded as a value.
+
+.SS* Listener Variables
+
+.coNP Variables @, *0 @, *1 @, *2 @, ... @ *99
+.desc
+The listener provides useful variables which allow commands to reference
+the results of previous commands. As noted previously, the commands
+are enumerated with an incrementing number. Each command's number, modulo 100,
+corresponds to one of the variables
+.codn *0 ,
+.codn *1 ,
+.codn *2 ,
+.codn ... ,
+.codn *99 .
+Thus, up to the previous hundred results can be referenced:
+
+.cblk
+  ...
+  99> (+ 2 2)  ;; stored in *99
+  4
+  100> (* 3 2) ;; stored in *0
+  6
+  101> (+ *99 *0) ;; i.e. (+ 4 6)
+  10
+.cble
+
+.coNP Variable @ *n
+.desc
+The listener variable
+.code *n
+evaluates to the current command line number: the number of the command in
+which the variable occurs:
+
+.cblk
+  5> *n
+  5
+  6> (* 2 *n)
+  12
+.cble
+
+.coNP Variable @ *v
+.desc
+The listener variable
+.code *v
+evaluates to the current variable number: the command number modulo 100:
+
+.cblk
+  103> *v
+  3
+  104> *v
+  4
+.cble
+
+.coNP Variable @ *r
+.desc
+The listener variable
+.code *r
+evaluates to a hash table which associates variable numbers with command
+results:
+
+.cblk
+  213> 42
+  42
+  214> [*r 13]
+  42
+.cble
+
+The result hash allows relative addressing. For instance the expression
+.code [*r (mod (pred *v) 100)]
+refers to the result of the previous command.
+
+.SS* Exceptions
+
+The interactive listener catches all exceptions. Each caught exception is
+associated with the command's variable number, and stored as a value
+in the appropriate listener variable as well as the
+.code *r
+result hash. Exceptions are turned into values by creating a cons cell
+whose
+.code car
+is the exception symbol and whose
+.code cdr
+holds the exception's arguments.
+
+For each caught exception, a message
+is printed beginning with the sequence
+.strn "** " .
+Exactly how the message appears depends on the type and content of
+the exception.
+
+.SS* Editing
+
+.NP* Move Left and Right
+
+Moving within the line is achieved using the left and right arrow keys.  In
+addition, Ctrl-B ("back") and Ctrl-F ("forward") perform this movement.
+
+.NP* Jump to Beginning and End of Line
+
+The Ctrl-A command moves to the beginning of the line. ("A" is the beginning
+of the alphabet). The Ctrl-E ("end") command jumps to the end of the line,
+such that the last character of the line is to the left of the cursor
+position.
+
+.NP* Character Swap
+
+The Ctrl-T (twiddle) command exchanges the character under the cursor with the
+previous character.
+
+.NP* Delete Character Left
+
+The Backspace key erases the character to the left of the cursor, and moves the
+cursor to the position which that character occupied.
+
+It doesn't matter whether this key generates ASCII
+characters 8 (BS) or 127 (DEL): either one is acceptable. The Ctrl-H command
+also performs the same action, since it corresponds to ASCII BS.
+
+.NP* Delete Character Right
+
+The Ctrl-D command is overloaded with two meanings. If the line is empty, it is
+a quit indication. Otherwise, it deletes the character under the cursor
+without changing the cursor position.
+
+.NP* Delete Word Left
+
+The Ctrl-W ("word") command deletes the word to the left of the cursor
+position. More precisely, this command first deletes any consecutive whitespace
+characters (spaces or tabs) to the left of the cursor. Then, it deletes
+consecutive non-whitespace characters. Material under the cursor or to the
+right remains.
+
+.NP* Delete to Beginning of Line
+
+The Ctrl-U ("undo typing") command is a "super backspace" operation: it deletes
+all characters to the left of the cursor position. The cursor is moved to
+the leftmost position.
+
+.NP* Delete to End of Line
+
+The Ctrl-K ("kill") command deletes the character under the cursor position
+and all subsequent characters. The cursor position doesn't change.
+
+.NP* Verbatim Character Insert
+
+The Ctrl-V ("verbatim") command places the listener's input editor into
+a mode in which the next character is interpreted literally and inserted
+into the line, even if that character is a special character such as Enter,
+or a command character.
+
+.NP* Clear Screen and Refresh
+
+The Ctrl-L command clears the screen and re-draws the line being edited.
+This is useful when the display is disturbed by the output of some
+background process, or serial line noise.
+
+.NP* Suspend to Background
+
+The Ctrl-Z ("Zzzz... (sleep)") command causes \*(TX to be placed into the
+background in a suspended, and control returned to the system shell.
+This feature depends on the use of a POSIX job control shell.
+
+Bringing the suspended \*(TX back into the foreground is achieved with a shell
+command such as the
+.code fg
+command in GNU Bash.
+
+When \*(TX is resumed, the interactive listener will re-display the edited
+line and restore the previous cursor position.
+
+.NP* History Recall
+
+The most recent one hundred lines submitted to the interactive listener are
+remembered in a history.  This history is available for recall, making it
+convenient to repair mistakes, or compose new lines which are based on
+previous lines.  Note that the the history suppresses consecutive duplicate
+lines.
+
+If the up arrow is used while editing a line, the contents of the line are
+placed into a temporary save area.  The line display is then updated to
+show the most recent line of history.  Using the up arrow key additional times
+will recall successively less recent lines.
+
+The down arrow key navigates in the opposite direction: from older lines to
+newer lines. When the down arrow key is invoked on the most recent history line,
+then the current line is restored from the temporary save area.
+
+Instead of the up and down arrow keys, the commands Ctrl-P ("previous")
+and Ctrl-N ("next") may be used.
+
+If the Enter key is pressed while a recalled history line is showing, then that
+line will be submitted as if it were a newly composed line.  The originally
+edited line which had been placed in the save area is discarded.
+
+When a recalled line is showing, it may be edited. There are two important
+behaviors to note here. If a recalled history line is edited, and then the
+up/down arrow keys or a navigation command is used to show a different
+history line, or to restore the original current line, then the edit is made
+permanent: the edited line replaces its original version in the same
+position in the history.  This feature allows corrections to be made to the
+history.  However, if a recalled line is edited and submitted without
+navigating to another line, then it is submitted as a newly composed line,
+without replacing the original in the history.
+
+Each submitted line is entered into the history, if it is different
+from the most recent line already in history. This is true whether it
+is a freshly composed line, a recalled history line, or an edited
+history line.
+
+.NP* History Persistence
+
+The history is maintained in a text file called
+.code .txr_history
+in the user's home directory. Whenever the interactive listener terminates,
+this file is overwritten with the history contents stored in the listener's
+memory.  The next time the listener starts, it first re-loads the history from
+this file, making the commands of a previous session available for recall.
+
+The home directory is determined from the
+contents of the
+.code HOME
+environment variable. If this variable doesn't exist, or the user doesn't
+have permissions to write to this directory or to an existing history file
+in that directory, then the history isn't saved.
+
+.NP* Symbolic Completion
+
+If the Tab key is pressed while editing a line, it is interpreted as a
+request for completion. This only happens if the cursor is at the end
+of the line (to the right of the rightmost character); completion in
+the middle of a line is not supported.
+
+When completion is invoked with the Tab key, the listener looks at a few of the
+trailing characters of the line in order to determine the applicable list of
+completions. Completions are determined from among the \*(TL symbols which have
+global variable, function, macro and symbolic macro bindings.  Symbols which
+have operator binding are also taken into consideration.  If a
+package-qualified symbol is completed, then completion is restricted to that
+package. Keyword symbol completion is restricted to the contents of the keyword
+package.
+
+If no completions are found, then the BEL character is sent to the terminal
+to generate a beep or a visual alert indication. The listener returns to
+editing mode.
+
+If completions are found, listener enters into completion selection mode.
+The first available completion is placed into the line as if it had been typed
+in.  The other completions may be viewed one by one using the Tab key.
+When the completions are exhausted, the original uncompleted line is shown
+again, and Tab can continue to be used to cycle through the completions again.
+In completion mode, the ESC key acts as a command to cancel completion mode
+and return to editing the original uncompleted line. Any other input causes the
+the listener to keep the currently shown completion, and return to edit mode.
+
 .SH* DEBUGGER
 \*(TX has a simple, crude, built-in debugger. The debugger is invoked by adding
 the