From 7876104ee7e73c190b67e90a87fe5a44f40c4af6 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Sat, 9 Aug 2014 17:17:39 -0700
Subject: * filter.c (filter_init): Expose the trie-lookup-begin, trie-value-at
 and trie-lookup-feed-char functions as intrinsics.

* txr.1: Document exposed functions.
---
 ChangeLog |  7 +++++++
 filter.c  |  3 +++
 txr.1     | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 17f33500..dfdb84fe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2014-08-09  Kaz Kylheku  <kaz@kylheku.com>
+
+	* filter.c (filter_init): Expose the trie-lookup-begin,
+	trie-value-at and trie-lookup-feed-char functions as intrinsics.
+
+	* txr.1: Document exposed functions.
+
 2014-08-08  Kaz Kylheku  <kaz@kylheku.com>
 
 	Bugfix: ret operator does not generate functions
diff --git a/filter.c b/filter.c
index fa841856..28d1d48a 100644
--- a/filter.c
+++ b/filter.c
@@ -724,6 +724,9 @@ void filter_init(void)
   reg_fun(intern(lit("trie-add"), user_package), func_n3(trie_add));
   reg_fun(intern(lit("trie-compress"), user_package),
           func_n1(trie_compress_intrinsic));
+  reg_fun(intern(lit("trie-lookup-begin"), user_package), func_n1(trie_lookup_begin));
+  reg_fun(intern(lit("trie-value-at"), user_package), func_n1(trie_value_at));
+  reg_fun(intern(lit("trie-lookup-feed-char"), user_package), func_n2(trie_lookup_feed_char));
   reg_fun(intern(lit("filter-string-tree"), user_package), func_n2(filter_string_tree));
   reg_fun(intern(lit("filter-equal"), user_package), func_n4(filter_equal));
   reg_fun(intern(lit("url-encode"), user_package), func_n2o(url_encode, 1));
diff --git a/txr.1 b/txr.1
index b178b42f..6956d497 100644
--- a/txr.1
+++ b/txr.1
@@ -14938,6 +14938,64 @@ while at the same time still modifying the internals of <trie>.
 Consequently, the program should not retain the input object <trie>,
 but use the returned object in its place.
 
+.SS Function trie-lookup-begin
+
+.TP
+Syntax:
+
+  (trie-lookup-begin <trie>)
+
+.TP
+Description:
+
+The trie-lookup-begin function returns a context object for performing
+an open-coded lookup traversal of a trie. The <trie> argument
+is expected to be a trie that was created by the make-trie function.
+
+.SS Function trie-lookup-feed-char
+
+.TP
+Syntax:
+
+  (trie-lookup-feed-char <trie-context> <char>)
+
+.TP
+Description:
+
+The trie-lookup-feed-char function performs a one character step in a trie
+lookup. The <trie-context> argument must be a trie contxt returned
+by trie-lookup-begin, or by some previous call to trie-lookup-feed-char.
+The <char> argument is the character to search for.
+
+If the lookup is successful (the match through the trie can continue
+with the given character) then a new trie context object is returned.
+The old trie context remains valid.
+
+If the lookup is unsuccessful, nil is returned.
+
+Note: determining whether a given string is stored in a trie can be
+performed looking up every character of the string successively
+with trie-lookup-feed-char, using the newly returned context
+for each successive operation. If every character is found, it means
+that either that exact string is found in the trie, or a prefix.
+The ambiguity can be resolved by testing whether the trie has a value
+at the last node using tree-value-at. For instance, if "catalog"
+is inserted into an empty trie with value "foo", then "cat" will look up
+successfully, being a prefix of "catalog"; however, the value at "cat" is nil.
+
+.SS Function tree-value-at
+
+.TP
+Syntax:
+
+  (trie-value-at <trie-context>)
+
+.TP
+Description:
+
+The trie-value-at function returns the value stored at the node in
+in the trie given by <trie-context>. Nodes which have not been given
+a value hold the value nil.
 
 .SS Function filter-string-tree
 
-- 
cgit v1.2.3