Support max length and depth for object printing.

* hash.c (hash_print_op): Implement max length.

* lib.c (lazy_str_put, out_lazy_str): Take struct strm_base *
parameter and implement max length.
(out_quasi_str_sym): Don't use obj_print_impl for symbol's
name string; just put_string. The use of obj_print_impl causes
symbols appearing as variables in quasiliterals to be
truncated when max length is imposed.
(out_quasi_str): Implement max length.
(obj_print_impl): Implement max length and depth. Note that
there is now always a non-null ctx pointer.
(obj_print): Always set up context pointer for obj_print_impl.
Context now has pointer to low-level stream structure, where
we can access max_length and max_depth. It also carries the
recursion depth.

* lib.h (lazy_str_put): Declaration updated.

* stream.c (strm_base_init): Add initializers for max_length
and max_depth.
(put_string): Pass stream structure to lazy_str_put.
(set_max_length, set_max_depth): New functions.
(stream_init): set-max-length and set-max-depth intrinsics
registered.

* stream.h (struct strm_ctx): New members depth and strm.
(struct strm_base): New members max_length and max_depth.
(set_max_length, set_max_depth): Declared.

* txr.1: Documented.

1 files changed, 154 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 51ded597..031837c2 100644
--- a/txr.1
+++ b/txr.1
@@ -47207,6 +47207,160 @@ and
 in the same way so that application-defined output integrates
 with the formatting algorithm.
 
+.SS* Stream Output Limitation
+
+Streams have two properties which are used by the The \*(TL object printer to
+optionally truncate the output generated by aggregate objects.
+
+A stream can specify a maximum length for aggregate objects via the
+.code set-max-length
+function. Using the
+.code set-max-depth
+function, the maximum depth can also be specified.
+
+This feature is
+useful when diagnostic output is being produced, and the objects involved are
+so large that the diagnostic output overwhelms the output device or the user,
+so as to become uninformative. Output limiting also prevents the printer's
+non-termination on infinite, lazy structures.
+
+It is recommended that functions which operate on streams passed in as
+parameters save and restore these parameters, if they need to manipulate them,
+for instance using
+.codn with-resources :
+
+.verb
+  (defun output-function (arg stream)
+    ;; temporarily impose maximum width and depth
+    (with-resources ((ml (set-max-length stream 42)
+                         (set-max-length stream ml))
+                     (mw (set-max-depth stream 12)
+                         (set-max-depth stream mw)))
+      (prinl arg stream)
+      ...))
+.brev
+
+.coNP Function @ set-max-length
+.synb
+.mets (set-max-length < stream << value )
+.syne
+.desc
+The
+.code set-max-length
+function establishes the maximum length for aggregate object printing.
+It affects the printing of lists, vectors, hash tables, strings
+as well as quasiliterals and quasiword list literals (QLLs).
+
+The default value is 0 and this value means that no limit is imposed.
+Otherwise, the value must be a positive integer.
+
+When the list, vector or hash table object being printed has more
+elements than the maximum length, then elements are printed only up to
+the maximum count, and then the remaining elements are summarized by
+printing the
+.code ...
+(three dots) character sequence as if it were an additional element.
+This sequence is an invalid token; it cannot be read as input.
+
+When a character string is printed, any positive value of
+the maximum length which is less than 15 is considered to be 15.
+The maximum length specifies the number of characters of the
+a string which are output.
+
+If a string which exceeds the maximum length is being printed
+with read-print consistency, as by the
+.code print
+function, then only a prefix of the string is printed, limited
+to the maximum number of characters.  Then, the literal syntax is
+closed using the character sequence
+.code \e...\(dq
+(backslash, dot, dot, dot, double quote)
+whose leading invalid escape sequence
+.code \e.
+(backslash, dot) ensures that the truncated object is not readable.
+
+If a string which exceeds the maximum length is being printed
+without read-print consistency, as by the
+.code pprint
+function, then only a prefix of the string is printed, limited
+to the maximum number of characters. Then the
+character sequence
+.code ...
+is emitted.
+
+Quasiliterals are treated using a combination of behaviors.  Elements of a
+quasiliteral are literal sequence of text, and embedded variables and
+expressions.  The maximum length specifies both the maximum number of elements
+in the quasiliteral, and the maximum number of characters in any element which
+is a sequence of text. When either limit is exceeded, the quasiliteral
+is immediately terminated with the sequence
+.code \e...`
+(escaped dot, dot, dot, backtick). The maximum limit is applied to
+the units of text cumulatively, rather than individually. As in the case of
+string literals, smaller limit values than 15 are treated as 15,
+but only for the cumulative text length limit. For limiting the number of
+elements, the count is used as-is.
+
+When a QLL is printed, the space-separated elements
+of the literal are individually subject to the maximum length limit as if
+they were independent quasiliterals. Furthermore, the sequence of these
+elements is subject to the maximum length. If there are more elements in the
+QLL, then the sequence
+.code \e...`
+(escaped dot, dot, dot, backtick) is emitted and thus the QLL ends.
+
+The
+.code set-max-length
+function returns the previous value.
+
+.coNP Function @ set-max-depth
+.synb
+.mets (set-max-depth < stream << value )
+.syne
+.desc
+The
+.code set-max-length
+function establishes the maximum depth for the printing of nested
+objects. It affects the printing of lists, vectors, hash tables
+and structures.  The default value is 0 and this value means that no limit is
+imposed.  Otherwise, the value must be a positive integer.
+
+The depth of an object not enclosed in any object is zero. The depth of the
+element of an aggregate is one greater than the depth of the aggregate itself.
+For instance, given the list
+.code "(1 (2 3))"
+the list itself has depth 0, the atom
+.code 1
+has depth 1, as does the sublist
+.codn "(2 3)" ,
+and the
+.code 2
+and
+.code 3
+atoms have depth 2.
+
+When an object is printed whose depth exceeds the maximum depth, then three dot
+character sequence
+.code ...
+is printed instead of that object. This notation is an invalid token; it cannot be
+read as input.
+
+Additionally, when a vector, list, hash table or structure is printed which itself
+doesn't exceed the maximum depth, but whose elements do exceed, then that object
+is summarized, respectively, as
+.codn "(...)" ,
+.codn "#(...)" ,
+.code "H#(...)"
+and
+.codn "S#(...)" ,
+rather than repeating the
+.code ...
+sequence for each of its elements.
+
+The
+.code set-max-depth
+function returns the previous value.
+
 .SS* Coprocesses
 .coNP Functions @ open-command and @ open-process
 .synb