* match.c (require_s): New variable.

(v_require): New static function.
(syms_init): Initialize require_s.
(dir_tables_init): Add new entries into v_directive_table
and h_directive_table for new require directive.

* match.h (require_s): Declared.

* txr.1: Added do and require directives to the directive summary
section. Documented new require directive.
Fixed int-str documentation to clarify that the radix is
optional.

4 files changed, 55 insertions, 4 deletions

diff --git a/ChangeLog b/ChangeLog
index a2bec990..dde2893f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,20 @@
 2013-06-11  Kaz Kylheku  <kaz@kylheku.com>
 
+	* match.c (require_s): New variable.
+	(v_require): New static function.
+	(syms_init): Initialize require_s.
+	(dir_tables_init): Add new entries into v_directive_table
+	and h_directive_table for new require directive.
+
+	* match.h (require_s): Declared.
+
+	* txr.1: Added do and require directives to the directive summary
+	section. Documented new require directive.
+	Fixed int-str documentation to clarify that the radix is
+	optional.
+
+2013-06-11  Kaz Kylheku  <kaz@kylheku.com>
+
 	* eval.c (eval_init): tok-str acquires new parameter
 
 	* lib.c (tok_str): New parameter, keep_sep.
diff --git a/match.c b/match.c
index 410bd05a..612276bb 100644
--- a/match.c
+++ b/match.c
@@ -55,6 +55,7 @@ val decline_k, next_spec_k, repeat_spec_k;
 val mingap_k, maxgap_k, gap_k, mintimes_k, maxtimes_k, times_k;
 val lines_k, chars_k;
 val text_s, choose_s, gather_s, do_s, mod_s, modlast_s, fuzz_s, load_s;
+val require_s;
 val longest_k, shortest_k, greedy_k;
 val vars_k, resolve_k;
 val append_k, into_k, var_k, list_k, string_k, env_k, counter_k;
@@ -3483,6 +3484,17 @@ static val v_do(match_files_ctx *c)
   return next_spec_k;
 }
 
+static val v_require(match_files_ctx *c)
+{
+  spec_bind (specline, first_spec, c->spec);
+  val args = rest(first_spec);
+  uw_set_match_context(cons(c->spec, c->bindings));
+  if (!eval_progn(args, make_env(c->bindings, nil, nil), specline))
+    return nil;
+  return next_spec_k;
+}
+
+
 static val v_load(match_files_ctx *c)
 {
   uses_or2;
@@ -3764,6 +3776,7 @@ static void syms_init(void)
   gather_s = intern(lit("gather"), user_package);
   do_s = intern(lit("do"), user_package);
   load_s = intern(lit("load"), user_package);
+  require_s = intern(lit("require"), user_package);
   longest_k = intern(lit("longest"), keyword_package);
   shortest_k = intern(lit("shortest"), keyword_package);
   greedy_k = intern(lit("greedy"), keyword_package);
@@ -3826,6 +3839,7 @@ static void dir_tables_init(void)
   sethash(v_directive_table, filter_s, cptr((mem_t *) v_filter));
   sethash(v_directive_table, eof_s, cptr((mem_t *) v_eof));
   sethash(v_directive_table, do_s, cptr((mem_t *) v_do));
+  sethash(v_directive_table, require_s, cptr((mem_t *) v_require));
   sethash(v_directive_table, load_s, cptr((mem_t *) v_load));
 
   sethash(h_directive_table, text_s, cptr((mem_t *) h_text));
@@ -3851,6 +3865,7 @@ static void dir_tables_init(void)
   sethash(h_directive_table, define_s, cptr((mem_t *) h_define));
   sethash(h_directive_table, eol_s, cptr((mem_t *) h_eol));
   sethash(h_directive_table, do_s, cptr((mem_t *) h_do));
+  sethash(h_directive_table, require_s, cptr((mem_t *) hv_trampoline));
 }
 
 void match_init(void)
diff --git a/match.h b/match.h
index 9a69374e..83e1e0ad 100644
--- a/match.h
+++ b/match.h
@@ -24,7 +24,7 @@
  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  */
 
-extern val text_s, choose_s, gather_s, do_s;
+extern val text_s, choose_s, gather_s, do_s, require_s;
 extern val load_s, mod_s, modlast_s, counter_k;
 val format_field(val string_or_list, val modifier, val filter, val eval_fun);
 val match_filter(val name, val arg, val other_args);
diff --git a/txr.1 b/txr.1
index 73493413..45dad773 100644
--- a/txr.1
+++ b/txr.1
@@ -1374,6 +1374,16 @@ filter or chain or filters, updating them with the filtered values.
 .IP @(load)
 The load directive loads another TXR file and interprets its contents.
 
+.IP @(do)
+The do directive is used to evaluate TXR Lisp expressions, discarding their
+result values. See the TXR LISP section far below.
+
+.IP @(require)
+The require directive is similar to the do directive: it evaluates one or more
+TXR Lisp expressions.  If the result of the rightmost expression is nil,
+then require triggers a match failure.  See the TXR LISP section far below.
+
+
 .PP
 
 .SH INPUT SCANNING AND DATA MANIPULATION
@@ -4643,7 +4653,7 @@ definitions are in error:
 
 The TXR language contains an embedded Lisp dialect called TXR Lisp.
 
-This language is exposed in TXR in two ways.
+This language is exposed in TXR in three ways.
 
 Firstly, in any situation that calls for an expression, a Lisp compound
 expression can be used, if it is preceded by the @ symbol. The Lisp expression
@@ -4656,6 +4666,11 @@ forms, such that their value is thrown away. This is useful for evaluating some
 Lisp code for the sake of its side effect, such as defining a variable,
 updating a hash table, et cetera.
 
+Thirdly, the @(require) directive can be used to evaluate Lisp expressions
+as part of the matching logic of the TXR pattern language. The return value
+of the rightmost expression is examined. If it is nil, then the @(require)
+directive triggers a match failure. Otherwise, matching proceeds.
+
 Examples:
 
 Bind variable a to the integer 4:
@@ -4673,6 +4688,11 @@ Define several Lisp functions using @(do):
           (t (or (eq (first list) item)
                  (occurs item (rest list)))))))
 
+Trigger a failure unless previously bound variable "answer" is greater
+than 42:
+
+@(require (> (str-int answer) 42)
+
 .SS Overview
 
 TXR Lisp is a small and simple dialect, like Scheme, but much more similar to
@@ -8866,7 +8886,7 @@ Thus (max a b c) is (max (max a b) c).
 .TP
 Syntax:
 
-  (int-str <string> <radix>)
+  (int-str <string> [<radix>])
   (flo-str <string>)
   (num-str <string>)
 
@@ -8879,7 +8899,8 @@ returned.  Trailing material which does not contribute to the number
 is ignored.
 
 The int-str function converts a string of digits in the specified
-radix to an integer value. For radices above 10, letters of the alphabet
+radix to an integer value. If the radix isn't specified, it defaults to 10.
+For radices above 10, letters of the alphabet
 are used for digits: A represent a digit whose value is 10, B represents 11 and
 so forth until Z.  For values of radix above 36, the returned value is
 unspecified. Upper and lower case letters are recognized.