streams: force-off indent mode.

The fourth indent mode indent-foff (force off) is introduced.

* buf.c (buf_print): Turn on data mode indentation if
the current mode is not indent-foff, rather than when it
is indent-off.

* lib.c (obj_print_impl): The unconditional set_indent_mode
calls are replaced with test_neq_set_indent_mode so we only
set the mode if it is not forced off.

* stream.c (formatv): For the ! directive, turn on data
mode identation is not indent-foff, rather than when it is
indent-off.
(put_string, put_char, width_check): Recognize ident-foff as
indentation off.
(test_neq_set_indent_mode): New function.
(stream_init): Register test-neq-set-indent-mode function
and indent-foff variable.

* stream.h (indent_mode): New enum constant, indent_foff.
(test_neq_set_indent_mode): Declared.

* struct.c (struct_inst_print): Turn on data mode indentation
if the current mode is not indent-foff, rather than when it is
indent-off.

* txr.1: Documented.

1 files changed, 59 insertions, 18 deletions

diff --git a/txr.1 b/txr.1
index 2a9afa9b..14e5ba62 100644
--- a/txr.1
+++ b/txr.1
@@ -46953,31 +46953,55 @@ function does not interact with indentation. The column position tracking
 will be incorrect if byte and character output are mixed, affecting
 the placement of indentation.
 
-Indentation mode takes on three numeric values, given by the three
+Indentation mode takes on four numeric values, given by the four
 variables
 .codn indent-off ,
 .codn indent-data ,
+.code indent-code
 and
-.codn indent-code .
-As far as stream output is concerned, the code and data modes behave
+.codn indent-foff .
+As far as stream output is concerned, the code and data modes
+represented by
+.code indent-code
+and
+.code indent-data
+behave
 the same way: both represent the "indentation turned on" state.
 The difference between them influences the behavior of the
 .code width-check
-function. This function isn't used by any stream output routines.
-It is used by the object printing functions like
+function. This function isn't used by any lower-level stream output
+routines. It is used by the object printing functions like
 .code print
 and
 .code pprint
 to break up long lines.
+The
+.code indent-off
+and
+.code intent-foff
+modes are also treated the same way by lower level stream output,
+indicating "indentation turned off". The modes are distinguished
+by
+.code print
+and
+.code pprint
+in the following way:
+.code indent-off
+is a "soft" disable which allows these object-printing routines
+to temporarily turn on indentation while traversing aggregate objects.
+Whereas the
+.code indent-foff
+("force off") value is a "hard" disable: the object-printing routines will not
+enable indentation and will not break up long lines.
 
-.coNP Variables @, indent-off @ indent-data and @ indent-code
+.coNP Variables @, indent-off @, indent-data @ indent-code and @ indent-foff
 .desc
 These variables hold integer values representing output stream
 indentation modes. The value of
 .code indent-off
 is zero.
 
-.coNP Functions @, get-indent-mode @ set-indent-mode and @ test-set-indent-mode
+.coNP Functions @ get-indent-mode and @ set-indent-mode
 .synb
 .mets (get-indent-mode << stream )
 .mets (set-indent-mode < stream << new-mode )
@@ -46989,7 +47013,6 @@ The
 .code get-indent-mode
 retrieves the current indent mode of
 .metn stream .
-
 The
 .code set-indent-mode
 function sets the indent mode of
@@ -46998,6 +47021,23 @@ to
 .meta new-mode
 and returns the previous mode.
 
+Note: it is encouraged to save and restore the indentation mode,
+and in a way that is exception safe.
+If a block of code sets up indentation on a stream such as
+.code *stdout*
+and is terminated by an exception, the indentation will remain in
+effect and affect subsequent output. The
+.code with-resources
+macro or
+.code unwind-protect
+operator may be used.
+
+.coNP Functions @ test-set-indent-mode and @ test-neq-set-indent-mode
+.synb
+.mets (test-set-indent-mode < stream < compare-mode << new-mode )
+.mets (test-neq-set-indent-mode < stream < compare-mode << new-mode )
+.syne
+.desc
 The
 .code test-set-indent-mode
 function sets the indent mode of
@@ -47009,16 +47049,17 @@ its current mode is equal to
 .metn compare-mode .
 Whether or not it changes the mode, it returns the previous mode.
 
-Note: it is encouraged to save and restore the indentation mode,
-and in a way that is exception safe.
-If a block of code sets up indentation on a stream such as
-.code *stdout*
-and is terminated by an exception, the indentation will remain in
-effect and affect subsequent output. The
-.code with-resources
-macro or
-.code unwind-protect
-operator may be used.
+The
+.code test-neq-set-indent-mode
+only differs in that it sets
+.meta stream
+to
+.meta new-mode
+if, and only if,
+the current mode is
+.B not
+equal to
+.metn compare-mode .
 
 .coNP Functions @, get-indent @ set-indent and @ inc-indent
 .synb