New iread function.

The read function no longer works like it used to on an
interactive terminal because of the support for .. and .
syntax on a top-level expression.

The iread function is provided which uses a modified syntax
that doesn't support these operators on a top-level
expression. The parser thus doesn't look one token ahead,
and so iread can return immediately.

* eval.c (eval_init): Register iread intrinsic function.

* parser.c (prime_parser):  Only push back the recently seen
token when priming for a regular Lisp read. Handle
the prime_interactive method by preparing a SECRET_ESCAPE_I
token.
(lisp_parse_impl): New static function, formed from previous
lisp_parse. Takes a boolean argument indicating interactive
mode.
(prime_parser_post): New function.
(lisp_parse): Now a wrapper for lisp_parse_impl which
passes a nil to indicate noninteractive read.
(iread): New function.

* parser.h (enum prime_parser): New member, prime_interactive.
(scrub_scanner, iread, prime_parser_post): Declared.

* parser.l (prime_scanner): Handle the prime_interactive case
the same way as prime_lisp.
(scrub_scanner): New function.

* parser.y (SECRET_ESCAPE_I): New token type.
(i_expr): New nonterminal symbol. Like n_expr, but doesn't
support dot or dotdot operators, except in nested
subexpressions.
(spec): Handle SECRET_ESCAPE_I by way of i_expr.
(sym_helper): Before freeing the token lexeme, call
scrub_scanner. If the token is registered as the scanner's
most recently seen token, the scanner must forget that
registration, because it is no longer valid.
(parse): Call prime_parser_post.

* txr.1: Documented iread.

1 files changed, 34 insertions, 4 deletions

diff --git a/txr.1 b/txr.1
index 90807e7d..b7e1b202 100644
--- a/txr.1
+++ b/txr.1
@@ -32070,9 +32070,10 @@ Examples of strings which are not absolute paths.
   $:\eabc
 .cble
 
-.coNP Function @ read
+.coNP Functions @ read and @ iread
 .synb
-.mets (read >> [ source >> [ error-stream >> [ error-return-value <> [ name ]]]])
+.mets (read >> [ source >> [ error-stream >> [ error-retval <> [ name ]]]])
+.mets (iread >> [ source >> [ error-stream >> [ error-retval <> [ name ]]]])
 .syne
 .desc
 The
@@ -32110,15 +32111,44 @@ is a string.
 
 If there are no parse errors, the function returns the parsed data
 structure. If there are parse errors, and the
-.meta error-return-value
+.meta error-retval
 parameter is
 present, its value is returned. If the
-.meta error-return-value
+.meta error-retval
 parameter
 is not present, then an exception of type
 .code syntax-error
 is thrown.
 
+The
+.code iread
+function ("interactive read") is similar to
+.code read
+except that it parses a modified version of the syntax. The modified
+syntax does not support the application of the dot and dotdot operators
+on a toplevel expression. For instance, if the input is
+.code a.b
+or
+.code a .. b
+then
+.code iread
+will only read the
+.code a
+token whereas
+.code read
+will read the entire expression.
+
+This modified syntax allows
+.code iread
+to return immediately when an expression is recognized, which is the
+expected behavior if the input is being read from an interactive terminal.
+By contrast,
+.code read
+waits for more input after seeing a complete expression, because of the
+possibility that the expression will be further extended by means of the dot or
+dotdot operators. An explicit end-of-input signal must be given from the
+terminal to terminate the expression.
+
 .SS* Stream Output Indentation
 \*(TL streams provide support for establishing hanging indentations
 in text output. Each stream which supports output has a built-in state variable