* eval.c (eval_init): Registered regex_parse as new

intrinsic function and std_null as new variable.

* parser.h (yylex_destroy): Existing function declared.

* parser.l (regex_parse): New function.
New lexical syntax added which returns SECRET_ESCAPE_R.

* parser.y (SECRET_ESCAPE_R): New token.
(spec): Added syntactic variant which lets us
smuggle a regex into the parser easily.

* stream.c:x (std_null): New global variable.
(null_stream_print): New static function.
(null_ops): New static structure.
(make_null_stream): New function.
(stream_init): Protect and initialize std_null.

* stream.h (std_null, make_null_stream): Declared.

* txr.1: New features documented: regex-parse, *stdnull*.

* txr.c (txr_main): Call yylex_destroy after parsing the program now
that I know about this function; this can free up some memory.

1 files changed, 35 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index c38de95c..2906a0ab 100644
--- a/txr.1
+++ b/txr.1
@@ -9357,6 +9357,8 @@ The regex compile function takes the source code of a regular expression,
 expressed as a Lisp data structure, and compiles it to a regular expression
 object.
 
+Suitable source code is produced by regex-parse.
+
 .TP
 Examples:
 
@@ -9370,6 +9372,34 @@ Examples:
   ;; #/a|b|c/
   (regex-compile '(or (or #\ea #\eb) #\ec))
 
+.SS Function regex-parse
+
+.TP
+Syntax:
+
+  (regex-parse <string> : <stream>)
+
+.TP
+Description:
+
+The regex string parses a character string which contains a regular expression
+(without any surrounding / characters) and turns it into a Lisp data structure
+(the abstract syntax tree representation of the regular expression).
+
+The regular expression syntax #/RE/ produces the same structure, but as a
+literal which is processed at the time TXR source code is read; the regex-parse
+function performs this parsing at run-time.
+
+If there are parse errors, the function returns nil.
+
+The optional <stream> argument specifies a stream to which error messages
+are sent from the parser. By default, diagnostic output goes to the *stdnull*
+stream, which discards it. If <stream> is specified as t, then the diagnostic
+output goes to the *stdout* stream.
+
+If regex-parse returns a non-nil value, that structure is then something
+which is suitable as input to regex-compile.
+
 .SH HASHING LIBRARY
 
 .SS Functions make-hash, hash
@@ -9880,7 +9910,7 @@ In general, I/O errors are usually turned into exceptions. When the description
 of error reporting is omitted from the description of a function, it can be
 assumed that it throws an error.
 
-.SS Variables *stdout*, *stddebug*, *stdin* and *stderr*
+.SS Variables *stdout*, *stddebug*, *stdin*, *stderr* and *stdnull*
 
 These variables hold predefined stream objects. The *stdin*, *stdout* and
 *stderr* streams closely correspond to the underlying operating system streams.
@@ -9890,6 +9920,10 @@ The *stddebug* stream goes to the same destination as *stdout*, but is
 a separate object which can be redirected independently, allowing debugging
 output to be separated from normal output.
 
+The *stdnull* stream is a special kind of stream called a null stream.
+This stream is not connected to any device or file.  It is similar to
+the /dev/null device on Unix, but does not involve the operating system.
+
 .SS Function format
 
 .TP