* stream.c (stream_init): Register get-indent-mode, set-indent-mode,

test-set-indent-mode, get-indent, set-indent, inc-indent
and width-check intrinsic functions. Register indent-off,
indent-data and indent-code variables.

* txr.1: Documented stream output indentation API.

3 files changed, 163 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index aa7075e3..40f10b3b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
 2015-08-05  Kaz Kylheku  <kaz@kylheku.com>
 
+	* stream.c (stream_init): Register get-indent-mode, set-indent-mode,
+	test-set-indent-mode, get-indent, set-indent, inc-indent
+	and width-check intrinsic functions. Register indent-off,
+	indent-data and indent-code variables.
+
+	* txr.1: Documented stream output indentation API.
+
+2015-08-05  Kaz Kylheku  <kaz@kylheku.com>
+
 	* stream.c (width_check): Just use the public
 	put_char function; no need to manipulate column
 	or call put_indent.
diff --git a/stream.c b/stream.c
index 514b7140..a5bf5909 100644
--- a/stream.c
+++ b/stream.c
@@ -3302,6 +3302,17 @@ void stream_init(void)
   reg_fun(intern(lit("open-files*"), user_package), func_n2o(open_files_star, 1));
   reg_fun(intern(lit("abs-path-p"), user_package), func_n1(abs_path_p));
 
+  reg_fun(intern(lit("get-indent-mode"), user_package), func_n1(get_indent_mode));
+  reg_fun(intern(lit("test-set-indent-mode"), user_package), func_n3(test_set_indent_mode));
+  reg_fun(intern(lit("set-indent-mode"), user_package), func_n2(set_indent_mode));
+  reg_fun(intern(lit("get-indent"), user_package), func_n1(get_indent));
+  reg_fun(intern(lit("set-indent"), user_package), func_n2(set_indent));
+  reg_fun(intern(lit("inc-indent"), user_package), func_n2(inc_indent));
+  reg_fun(intern(lit("width-check"), user_package), func_n2(width_check));
+  reg_varl(intern(lit("indent-off"), user_package), num_fast(indent_off));
+  reg_varl(intern(lit("indent-data"), user_package), num_fast(indent_data));
+  reg_varl(intern(lit("indent-code"), user_package), num_fast(indent_code));
+
   fill_stream_ops(&null_ops);
   fill_stream_ops(&stdio_ops);
   fill_stream_ops(&tail_ops);
diff --git a/txr.1 b/txr.1
index 78893dc8..4319540d 100644
--- a/txr.1
+++ b/txr.1
@@ -27703,7 +27703,7 @@ if
 supports a byte write operation. The byte
 value is specified as an integer value in the range 0 to 255.
 
-All these runctions return
+All these functions return
 .codn t .
 On failure, they do not return, but throw exceptions of type
 .codn file-error .
@@ -28114,6 +28114,148 @@ is not present, then an exception of type
 .code syntax-error
 is thrown.
 
+.SS* Stream Output Indentation
+\*(TL streams provide support for establishing hanging indentations
+in text output. Each stream which supports output has a built-in state variable
+called indentation mode, and another variable indicating the current
+indentation amount. When indentation mode is enabled, then prior to the
+first character of every line, the stream prepends the indentation: space
+characters equal in number to the current indentation value.
+This logic is implemented by the
+.code put-char
+and
+.code put-string
+functions, and all functions based on these. The
+.code put-byte
+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
+variables
+.codn indent-off ,
+.codn indent-data ,
+and
+.codn indent-code .
+As far as stream output is concerned, the code and data modes 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
+.code print
+and
+.code pprint
+to break up long lines.
+
+.coNP Variables @, indent-off @ indent-data and @ indent-code
+.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
+.synb
+.mets (get-indent-mode << stream )
+.mets (set-indent-mode < stream << new-mode )
+.mets (test-set-indent-mode < stream < compare-mode << new-mode )
+.syne
+.desc
+These functions retrieve and manipulate the stream indent mode.
+The
+.code get-indent-mode
+retrieves the current indent mode of
+.metn stream .
+
+The
+.code set-indent-mode
+function sets the indent mode of
+.meta stream
+to
+.meta new-mode
+and returns the previous mode.
+
+The
+.code test-set-indent-mode
+function sets the indent mode of
+.meta stream
+to
+.meta new-mode
+if, and only if,
+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.
+
+.coNP Functions @, get-indent @, set-indent and @ inc-indent
+.synb
+.mets (get-indent << stream )
+.mets (set-indent < stream << new-indent )
+.mets (inc-indent < stream << indent-delta )
+.syne
+.desc
+These functions manipulate the indentation value of the stream.
+The indentation takes effect the next time a character is output
+following a newline character.
+
+The
+.code get-indent
+function retrieves the current indentation amount.
+
+The
+.code set-indent
+function sets
+.metn stream 's
+indentation to the value
+.meta new-indent
+and returns the previous value.
+Negative values are clamped to zero.
+
+The
+.code inc-indent
+function sets
+.metn stream 's
+indentation relative to the current printing column position,
+and returns the old value.
+The indentation is calculated by adding
+.meta indent-delta
+to the current column position.
+If a negative indentation results, it is clamped to zero.
+
+.coNP Function @ width-check
+.synb
+.mets (width-check < stream << alt-char )
+.syne
+.desc
+The
+.code width-check
+function examines the state of the stream, taking into consideration
+the current printing column position, the indentation state, and
+indentation amount. It makes a decision either to introduce a line
+break by printing a newline character, or else to print the
+.meta alt-char
+character.
+
+If a decision is made not to emit a line break, but
+.meta alt-char
+is
+.codn nil ,
+then the function has no effect at all.
+
+The return value is always
+.codn t .
+
 .SS* Filesystem Access
 
 .coNP Function @ open-directory