コミット: 5f71b353eed4fe90eb7402e101dc43d89779e053 - groff-pdfmark (hg)

Reference Documentation: PDF Publishing with GNU Troff

コミットメタ情報

• リビジョン: 5f71b353eed4fe90eb7402e101dc43d89779e053 (tree)
• 日時: 2024-10-19 03:02:11
• 作者: Keith Marshall <keith@user...>
• コミッター: Keith Marshall

ログメッセージ

Strip delimited argument escape sequences from sanitized text.

* tmac/sanitize.tmac (sanitize:esc-s, sanitize:esc-v): New macros;
each of these is implemented, internally, as an alias for...
(sanitize:esc-delimited): ...this new generic handler macro.
(sanitize:scan.delimiter.push, sanitize:scan.delimiter.pop): New
helper macros; they are used by...
(sanitize:esc-delimited): ...this, to save, and subsequently restore,
effective escape sequence delimiter context, in...
(sanitize:scan.delimiter.stack): ...this new string.
(sanitize:esc-generic): Refactored; it now uses...
(sanitize:skip-handler): ...this new string; it defines a template,
used for redirection of control to one, or other of...
(sanitize:skip-(, sanitize:skip-[): ...these, as appropriate.

変更サマリ

• modified: tmac/sanitize.tmac

差分

diff -r 1dd113b9870c -r 5f71b353eed4 tmac/sanitize.tmac
--- a/tmac/sanitize.tmac	Thu Oct 10 20:38:50 2024 +0100
+++ b/tmac/sanitize.tmac	Fri Oct 18 19:02:11 2024 +0100
@@ -477,6 +477,63 @@
 .   length sanitize:residual.length \\*[sanitize:residual]
 ..
 .
+.\" Removal of Entire Escape Sequences from Sanitized Text
+.\" ------------------------------------------------------
+.\"
+.\" There are three classes of escape sequence which may be designated
+.\" as candidates for complete removal from any sanitized text string:
+.\" those with arguments of explicit length, those with arguments of
+.\" arbitrary length, demarcated by brackets, and those with arguments
+.\" of arbitrary length, demarcated by matching, arbitrarily chosen
+.\" quoting characters.
+.\"
+.\" Typical of those in the first two classes are "\f...", and "\F...",
+.\" these are processed by the sanitize:esc-generic handler macro:
+.\"
+.de sanitize:esc-generic als
+.als sanitize:esc-f sanitize:esc-generic
+.als sanitize:esc-F sanitize:esc-generic
+.
+.\" Conversely, the third class of these escape sequences is typified
+.\" by those such as "\s'...'", and "\v'...'"; these are processed by
+.\" the alternative sanitize:esc-delimited handler macro:
+.\"
+.de sanitize:esc-delimited als
+.als sanitize:esc-s sanitize:esc-delimited
+.als sanitize:esc-v sanitize:esc-delimited
+.
+.\" The formal implementation of sanitize:esc-generic follows here;
+.\" that of sanitize:esc-delimited may be found further below.
+.\"
+.am sanitize:esc-generic
+.\" Usage (internal): .sanitize:esc-X
+.\"
+.\" (X represents any legitimate single-character escape sequence id).
+.\"
+.\" Handler for skipping "\X" sequences, in text which is to be sanitized;
+.\" this will automatically detect sequences conforming to any of the forms
+.\" "\Xc", "\X(cc", or "\X[...]", and will handle each appropriately.  The
+.\" implementation is generic, and may be aliased to handle any specific
+.\" escape sequences, which exhibit similar semantics.
+.\"
+.\" At least one additional argument character is consumed; this may extend
+.\" to further argument characters, when a skip handler is associated with
+.\" this initial argument character.
+.\"
+.   sanitize:scan.execute
+.   if d \\*[sanitize:skip-handler] .\\*[sanitize:skip-handler]
+..
+.\" For escape sequences of the "\Xc" form, the above handler has already
+.\" consumed the the entire sequence, by calling the sanitize:scan.execute
+.\" macro; however, the "\X(cc", and "\X[...]" forms require the additional
+.\" services provided by the pair of sub-handlers designated by names which
+.\" match this sanitize:skip-handler template:
+.\"
+.ds sanitize:skip-handler "sanitize:skip-\E*[sanitize:scan.char]\"
+.
+.\" The first of the sanitize:skip-handler service macros provides the
+.\" support required to handle "\X(cc" escape sequences.
+.\"
 .de sanitize:skip-(
 .\" Usage (internal): .sanitize:skip-(
 .\"
@@ -486,6 +543,9 @@
 .   nr sanitize:residual.length -2
 .   substring sanitize:residual 2
 ..
+.\" Conversely, the second sanitize:skip-handler macro provides the support
+.\" required for handling "\X[...]" escape sequences.
+.\"
 .de sanitize:skip-[
 .\" Usage (internal): .sanitize:skip-[
 .\"
@@ -508,26 +568,134 @@
 .      el .nr sanitize:skip.count 0
 .   \}
 ..
-.de sanitize:esc-generic
-.\" Usage (internal): .sanitize:esc-X
-.\"
-.\" (X represents any legitimate single-character escape sequence id).
+.
+.\" The implementation of the alternative sanitize:esc-delimited handler
+.\" macro, as used for escape sequences such as "\s'...'", and "\v'...'",
+.\" follows here.
 .\"
-.\" Handler for skipping "\X" sequences, in text which is to be sanitized;
-.\" this will automatically detect sequences conforming to any of the forms
-.\" "\Xc", "\X(cc", or "\X[...]", and will handle each appropriately.  The
-.\" implementation is generic, and may be aliased to handle any specific
-.\" escape sequences, which exhibit similar semantics.
+.am sanitize:esc-delimited
+.\" Usage (internal, as alias): .sanitize:esc-X
 .\"
-.   sanitize:scan.execute
-.   if d sanitize:skip-\\*[sanitize:scan.char] \
-.      sanitize:skip-\\*[sanitize:scan.char]
+.\" (X represents any legitimate single-character escape sequence id.)
+.\"
+.\" Handler for skipping escape sequences of the "\X'arg...' form, in
+.\" which the sequence accepts an argument bounded by a quoting pair of
+.\" arbitrary, but matching delimiter characters.  Nesting of similar
+.\" sequences is supported, within the quoted argument, regardless of
+.\" whether the nested sequence arguments are quoted by the same, or
+.\" by distinct delimiter characters.
+.\"
+.\" Begin by backing up the current input character, acquiring the next,
+.\" and pushing it on to the pending delimiter stack.
+.\"
+.   as sanitize:hold \\*[sanitize:scan.char]
+.   sanitize:scan.delimiter.push
+.
+.\" Initiate an iterative look-ahead loop, backing up, acquiring, and
+.\" analysing successive input characters, until the matching delimiter
+.\" is detected.
+.\"
+.   while \\n[sanitize:residual.length] \{\
+.      as sanitize:hold \\*[sanitize:scan.char]
+.      sanitize:scan.execute
+.      if '\\*[sanitize:scan.char]'\\*[sanitize:scan.delimiter]' \{\
+.
+.      \" Found the closing delimiter; discard the entire sequence,
+.      \" scanned up to this point, pop the pending delimiter stack,
+.      \" and return to the top level scan of any residual input.
+.      \"
+.         sanitize:scan.delimiter.pop
+.         return
+.      \}
+.      if '\\*[sanitize:scan.char]'^[' \{\
+.
+.      \" An embedded escape sequence has been encountered, within
+.      \" the scope of the delimiters; process it, before resuming
+.      \" the look-ahead cycle.
+.      \"
+.         as sanitize:hold "^[\"
+.         sanitize:scan.execute
+.         if d \\*[sanitize:esc-handler] .\\*[sanitize:esc-handler]
+.      \}
+.   \}
+.\" If here, no closing delimiter has been found; restore the entire
+.\" sequence, comprising all backed up content, followed by the last
+.\" scanned input character, and return it.
+.\"
+.   as sanitize:result \\*[sanitize:hold]\\*[sanitize:scan.char]
 ..
-.\" Map the generic handler to specific escape sequences, as required.
+.\" Augment the base handler, by defining the delimiter stack, its
+.\" associated sanitize:scan.delimiter.push, and the complementary
+.\" sanitize:scan.delimiter.pop helper macros.
 .\"
-.als sanitize:esc-f sanitize:esc-generic
-.als sanitize:esc-F sanitize:esc-generic
+.\" Both the sanitize:scan.delimiter.push, and its complementary
+.\" sanitize:scan.delimiter.pop macros assume that the associated
+.\" sanitize:scan.delimiter.stack string pre-exists; to avoid any
+.\" groff warning, ensure that it does, albeit initially empty.
 .\"
+.ds sanitize:scan.delimiter.stack "\" empty string
+.
+.de sanitize:scan.delimiter.push
+.\" Usage (internal): .sanitize:scan.delimiter.push [delimiter list ...]
+.\"
+.\" Acquire the next available token, from the scanned input text, and
+.\" push it on to the pending delimiter stack, whence it represents the
+.\" active delimiter for the current level of escape sequence quoting.
+.\"
+.\" Called by the sanitize:esc-delimited macro, WITHOUT arguments, it
+.\" subsequently calls itself, recursively, WITH arguments representing
+.\" the entire updated stack content, as a space-separated list of all
+.\" pending delimiter tokens; the first argument represents the most
+.\" recently pushed, and also the currently pending delimiter.
+.\"
+.   ie \\n[.$] .ds sanitize:scan.delimiter.stack \\$*
+.   el \{\
+.   \" This is the normal macro entry point; acquire the next delimiter
+.   \" token, and then recurse to push it on to the delimiter stack.
+.   \"
+.      sanitize:scan.execute
+.      \\$0 \\*[sanitize:scan.char] \\*[sanitize:scan.delimiter.stack]
+.
+.   \" Ultimately, assign this new delimiter token as "active".
+.   \"
+.      ds sanitize:scan.delimiter \\*[sanitize:scan.char]
+.   \}
+..
+.de sanitize:scan.delimiter.pop
+.\" Usage (internal): .sanitize:scan.delimiter.pop [delimiter list ...]
+.\"
+.\" Complements the sanitize:scan.delimiter.push macro; this discards
+.\" the most recently active delimiter token from the top of the stack,
+.\" and make the next entry, if any, the new "active" delimiter.
+.\"
+.\" If there is nothing on the stack, this becomes a no-op.
+.\"
+.   if '\\*[sanitize:scan.delimiter.stack]'' .return
+.
+.\" Like sanitize:scan.delimiter.push, sanitize:scan.delimiter.pop is
+.\" called by sanitize:esc-delimited, WITHOUT arguments; it then calls
+.\" itself, recursively, WITH arguments representing the stack content,
+.\" prior to removal of its unwanted top entry.
+.\"
+.   ie \\n[.$] \{\
+.   \" This is the recursive re-entry; the first argument represents
+.   \" the unwanted top stack entry, so shift it out of the way, and
+.   \" reassign the stack, to represent only any remaining entries.
+.   \"
+.      shift
+.      ds sanitize:scan.delimiter.stack "\\$*\"
+.
+.   \" Additionally, assign the new top-of-stack entry, as the new
+.   \" actively pending delimiter token.
+.   \"
+.      ds sanitize:scan.delimiter \\$1
+.   \}
+.\" Alternatively, when called normally, without arguments, simply
+.\" recurse, passing the current stack contents as arguments.
+.\"
+.   el .\\$0 \\*[sanitize:scan.delimiter.stack]
+..
+.
 .\" Local Variables:
 .\" mode: nroff
 .\" End: