[groff] 12/12: [troff]: Implement .it, .itc, .itm registers.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1fce75f6ba981990397e841aa227d7c049cb5d7d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Feb 11 10:37:36 2024 -0600

    [troff]: Implement .it, .itc, .itm registers.
    
    [troff]: Implement `.it`, `.itc`, and `.itm` registers.  These read-only
    (and, in the case of `.itm`, string-valued as well) registers report the
    number of lines remaining in a pending input trap, a Boolean indication
    of whether that pending input trap honors output line continuation (cf.
    the `it` and `itc` requests), and the name of the macro associated with
    the pending input trap, respectively.
    
    * src/roff/troff/env.h (class environment): Declare new member functions
      to retrieve these data.
    
    * src/roff/troff/env.cpp (environment::get_input_trap_line_count)
      (environment::get_input_trap_respects_continuation)
      (environment::get_input_trap_macro): Implement them.
    
      (environment::environment): Update constructors to initialize
      `input_trap_count` to "-1", as a hint that no input trap has ever been
      sprung in the environment.  (After one has, the count remains at zero
      and the name of the macro associated with the last trap that was
      sprung remains in `.itm`, until a new input trap is planted or
      explicitly cleared.)
    
      (environment::copy): Set the input trap line count to "-1".
    
      (do_input_trap): Update `it`/`itc` request handler.  Reset the input
      trap line count to "-1" and null out the associated macro name.  If
      the `it` or `itc` requests are given no arguments, this is the
      situation that persists.  Recast diagnostic message when attempting to
      set a nonpositive input line count.
    
      (init_env_requests): Hook up the new register names to accessor
      functions.
    
    * doc/groff.texi.in (Input Line Traps):
    * man/groff.7.man (Read-only registers):
    * man/groff_diff.7.man (New registers): Document them.
    
    * NEWS: Add item.
---
 ChangeLog              | 37 +++++++++++++++++++++++++++++++++++++
 NEWS                   |  8 ++++++++
 doc/groff.texi.in      | 11 ++++++++++-
 man/groff.7.man        | 15 +++++++++++++++
 man/groff_diff.7.man   | 21 +++++++++++++++++++++
 src/roff/troff/env.cpp | 29 ++++++++++++++++++++++++-----
 src/roff/troff/env.h   |  3 +++
 7 files changed, 118 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index bfcfa32b7..aa3bd89c9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,40 @@
+2024-02-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [troff]: Implement `.it`, `.itc`, and `.itm` registers.  These
+       read-only (and, in the case of `.itm`, string-valued as well)
+       registers report the number of lines remaining in a pending
+       input trap, a Boolean indication of whether that pending input
+       trap honors output line continuation (cf. the `it` and `itc`
+       requests), and the name of the macro associated with the pending
+       input trap, respectively.
+
+       * src/roff/troff/env.h (class environment): Declare new member
+       functions to retrieve these data.
+       * src/roff/troff/env.cpp
+       (environment::get_input_trap_line_count)
+       (environment::get_input_trap_respects_continuation)
+       (environment::get_input_trap_macro): Implement them.
+       (environment::environment): Update constructors to initialize
+       `input_trap_count` to "-1", as a hint that no input trap has
+       ever been sprung in the environment.  (After one has, the count
+       remains at zero and the name of the macro associated with the
+       last trap that was sprung remains in `.itm`, until a new input
+       trap is planted or explicitly cleared.)
+       (environment::copy): Set the input trap line count to "-1".
+       (do_input_trap): Update `it`/`itc` request handler.  Reset the
+       input trap line count to "-1" and null out the associated macro
+       name.  If the `it` or `itc` requests are given no arguments,
+       this is the situation that persists.  Recast diagnostic message
+       when attempting to set a nonpositive input line count.
+       (init_env_requests): Hook up the new register names to accessor
+       functions.
+
+       * doc/groff.texi.in (Input Line Traps):
+       * man/groff.7.man (Read-only registers):
+       * man/groff_diff.7.man (New registers): Document them.
+
+       * NEWS: Add item.
+
 2024-02-11  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [troff]: The `color`, `cp`, `linetabs`, and `vpt` requests now
diff --git a/NEWS b/NEWS
index f66982810..c446f2d3d 100644
--- a/NEWS
+++ b/NEWS
@@ -33,6 +33,14 @@ o The device-independent output now reports unbreakable 
spaces (those
 o A new read-only, string-valued register, `.trap`, interpolates the
   name of the next vertical position trap that will be sprung.
 
+o New registers `.it`, `.itc`, and `.itm` registers are available.
+  These read-only (and, in the case of `.itm`, string-valued as well)
+  registers report the number of lines remaining in a pending input
+  trap, a Boolean indication of whether that pending input trap honors
+  output line continuation (cf. the `it` and `itc` requests), and the
+  name of the macro associated with the pending input trap,
+  respectively.
+
 o A new request, `pcolor`, reports to the standard error stream the
   current list of defined colors.  (A device's default stroke and/or
   fill colors, "default", are not listed since they are immutable and
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index a0d0520c8..5e7c3b446 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -15027,7 +15027,10 @@ error to invoke @code{dt} in the top-level diversion.
 @cindex traps, input line
 
 @DefreqList {it, [@Var{n} @Var{name}]}
-@DefreqListEndx {itc, [@Var{n} @Var{name}]}
+@DefreqItem {itc, [@Var{n} @Var{name}]}
+@DefregItem {.it}
+@DefregItem {.itc}
+@DefregListEndx {.itm}
 @cindex setting input line trap (@code{it}, @code{itc})
 @cindex input line trap, setting (@code{it}, @code{itc})
 @cindex trap, input line, setting (@code{it}, @code{itc})
@@ -15095,6 +15098,12 @@ the trap is sprung.
 ..
 @endExample
 
+The @code{.it}, @code{.itc}, and @code{.itm} registers report the number
+of lines remaining in a pending input trap, a Boolean indication of
+whether that pending input trap honors output line continuation, and the
+name of the macro associated with the pending input trap, respectively.
+All are read-only; @code{.itm} is string-valued as well.
+
 @need 500
 Let us consider in more detail the sorts of input lines that are or are
 not ``productive''.
diff --git a/man/groff.7.man b/man/groff.7.man
index 4143d82a1..a62d528ef 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -6223,6 +6223,21 @@ Previous output line was \[lq]interrupted\[rq] or 
continued with
 (Boolean-valued).
 .
 .TP
+.REG .it
+The count of lines remaining in the pending input trap.
+.
+.TP
+.REG .itc
+The pending input trap honors output line continuation
+.esc c
+(Boolean-valued).
+.
+.TP
+.REG .itm
+Name of the macro associated with the pending input trap
+(string-valued).
+.
+.TP
 .REG .j
 Adjustment mode encoded as an integer;
 see
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 97d8e662e..1e287d15d 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4182,6 +4182,27 @@ Interpolate\~1 if the most recently formatted text was 
interrupted
 .
 .
 .TP
+.B \[rs]n[.it]
+Interpolate the count of lines remaining in any pending input trap.
+.
+.
+.TP
+.B \[rs]n[.itc]
+Interpolate\~1 if the pending input trap honors the output line
+continuation escape sequence
+.RB ( \[rs]c ),
+0\~otherwise.
+.
+.
+.TP
+.B \[rs]n[.itm]
+Interpolate the name of the macro associated with the pending input
+trap.
+.
+This is a string-valued register.
+.
+.
+.TP
 .B \[rs]n[.kern]
 Interpolate\~1 if pairwise kerning is enabled,
 0\~otherwise.
diff --git a/src/roff/troff/env.cpp b/src/roff/troff/env.cpp
index 545765c8f..57f2da5a0 100644
--- a/src/roff/troff/env.cpp
+++ b/src/roff/troff/env.cpp
@@ -427,6 +427,21 @@ int environment::get_no_number_count()
   return no_number_count;
 }
 
+int environment::get_input_trap_line_count()
+{
+  return input_trap_count;
+}
+
+int environment::get_input_trap_respects_continuation()
+{
+  return continued_input_trap;
+}
+
+const char *environment::get_input_trap_macro()
+{
+  return input_trap.contents();
+}
+
 void environment::add_italic_correction()
 {
   if (current_tab) {
@@ -691,7 +706,7 @@ environment::environment(symbol nm)
   have_temporary_indent(0),
   underline_lines(0),
   underline_spaces(0),
-  input_trap_count(0),
+  input_trap_count(-1),
   continued_input_trap(false),
   line(0),
   prev_text_length(0),
@@ -784,7 +799,7 @@ environment::environment(const environment *e)
   have_temporary_indent(0),
   underline_lines(0),
   underline_spaces(0),
-  input_trap_count(0),
+  input_trap_count(-1),
   continued_input_trap(false),
   line(0),
   prev_text_length(e->prev_text_length),
@@ -865,7 +880,7 @@ void environment::copy(const environment *e)
   temporary_indent = 0;
   underline_lines = 0;
   underline_spaces = 0;
-  input_trap_count = 0;
+  input_trap_count = -1;
   continued_input_trap = false;
   prev_text_length = e->prev_text_length;
   width_total = 0;
@@ -2589,7 +2604,8 @@ void no_adjust()
 
 void do_input_trap(bool respect_continuation)
 {
-  curenv->input_trap_count = 0;
+  curenv->input_trap_count = -1;
+  curenv->input_trap = 0 /* nullptr */;
   if (respect_continuation)
     curenv->continued_input_trap = true;
   else
@@ -2598,7 +2614,7 @@ void do_input_trap(bool respect_continuation)
   if (has_arg() && get_integer(&n)) {
     if (n <= 0)
       warning(WARN_RANGE,
-             "number of lines for input trap must be greater than zero");
+             "input trap line count must be greater than zero");
     else {
       symbol s = get_name(true /* required */);
       if (!s.is_null()) {
@@ -3520,6 +3536,9 @@ void init_env_requests()
   init_hunits_env_reg(".i", get_indent);
   init_hunits_env_reg(".in", get_saved_indent);
   init_int_env_reg(".int", get_prev_line_interrupted);
+  init_int_env_reg(".it", get_input_trap_line_count);
+  init_int_env_reg(".itc", get_input_trap_respects_continuation);
+  init_string_env_reg(".itm", get_input_trap_macro);
   init_int_env_reg(".linetabs", get_line_tabs);
   init_hunits_env_reg(".lt", get_title_length);
   init_int_env_reg(".j", get_adjust_mode);
diff --git a/src/roff/troff/env.h b/src/roff/troff/env.h
index 65b9f0103..0777a3c6b 100644
--- a/src/roff/troff/env.h
+++ b/src/roff/troff/env.h
@@ -314,6 +314,9 @@ public:
   hunits get_hyphenation_space();
   hunits get_hyphenation_margin();
   int get_center_lines();
+  int get_input_trap_line_count();
+  int get_input_trap_respects_continuation();
+  const char *get_input_trap_macro();
   int get_right_justify_lines();
   int get_no_number_count();
   int get_prev_line_interrupted() { return prev_line_interrupted; }