[latex3-commits] [git/LaTeX3-latex3-latex3] master: Document \peek_analysis_map_inline:n in the right place (b7a37074c)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : master
Link       : https://github.com/latex3/latex3/commit/b7a37074cce73660ff29017bf1c29549dc80fba1

>---------------------------------------------------------------

commit b7a37074cce73660ff29017bf1c29549dc80fba1
Author: Bruno Le Floch <bruno at le-floch.fr>
Date:   Thu Jul 16 18:58:45 2020 +0200

    Document \peek_analysis_map_inline:n in the right place


>---------------------------------------------------------------

b7a37074cce73660ff29017bf1c29549dc80fba1
 l3kernel/CHANGELOG.md      |  3 +++
 l3kernel/l3tl-analysis.dtx | 45 +++++++++------------------------
 l3kernel/l3token.dtx       | 63 +++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 74 insertions(+), 37 deletions(-)

diff --git a/l3kernel/CHANGELOG.md b/l3kernel/CHANGELOG.md
index dbeb92795..3eab183c7 100644
--- a/l3kernel/CHANGELOG.md
+++ b/l3kernel/CHANGELOG.md
@@ -7,6 +7,9 @@ this project uses date-based 'snapshot' version identifiers.
 
 ## [Unreleased]
 
+### Added
+- `\peek_analysis_map_inlione:n`
+
 ### Unchanged
 - Extend `\text_expand:n` to cover `\@protected at testopt`
 - Extend `\text_purify:n` to cover `\@protected at testopt`
diff --git a/l3kernel/l3tl-analysis.dtx b/l3kernel/l3tl-analysis.dtx
index c864770a3..d992eb60e 100644
--- a/l3kernel/l3tl-analysis.dtx
+++ b/l3kernel/l3tl-analysis.dtx
@@ -54,21 +54,24 @@
 %
 % This module provides functions that are particularly useful in the
 % \pkg{l3regex} module for mapping through a token list one \meta{token}
-% at a time (including begin-group/end-group tokens).  The token list is
-% either given as an argument or found in the input stream.  In both
-% cases the user provides \meta{inline code} that receives three
-% arguments for each \meta{token}:
+% at a time (including begin-group/end-group tokens).  For
+% \cs{tl_analysis_map_inline:Nn} or \cs{tl_analysis_map_inline:nn}, the
+% token list is given as an argument; the analogous function
+% \cs{peek_analysis_map_inline:n} documented in \pkg{l3token} finds
+% tokens in the input stream instead.  In both cases the user provides
+% \meta{inline code} that receives three arguments for each
+% \meta{token}:
 % \begin{itemize}
 %   \item \meta{tokens}, which both \texttt{o}-expand and
 %     \texttt{x}-expand to the \meta{token}. The detailed form of
-%     \meta{token} may change in later releases.
+%     \meta{tokens} may change in later releases.
 %   \item \meta{char code}, a decimal representation of the character
 %     code of the \meta{token}, $-1$ if it is a control sequence.
 %   \item \meta{catcode}, a capital hexadecimal digit which denotes the
-%     category code of the \meta{token} (0: control sequence, 1:
-%     begin-group, 2: end-group, 3: math shift, 4: alignment tab, 6:
-%     parameter, 7: superscript, 8: subscript, A: space, B: letter,
-%     C:other, D:active).  This can be converted to an integer by
+%     category code of the \meta{token} (0:~control sequence,
+%     1:~begin-group, 2:~end-group, 3:~math shift, 4:~alignment tab,
+%     6:~parameter, 7:~superscript, 8:~subscript, A:~space, B:~letter,
+%     C:~other, D:~active).  This can be converted to an integer by
 %     writing |"|\meta{catcode}.
 % \end{itemize}
 % In addition, there is a debugging function \cs{tl_analysis_show:n},
@@ -96,30 +99,6 @@
 %   made by the \meta{inline function} remain in effect after the loop.
 % \end{function}
 %
-% \begin{function}[added = 2020-07-14]{\peek_analysis_map_inline:n}
-%   \begin{syntax}
-%     \cs{peek_analysis_map_inline:n} \Arg{inline function}
-%   \end{syntax}
-%   Applies the \meta{inline function} to each individual \meta{token}
-%   in the input stream that follows.  The \meta{inline function}
-%   receives three arguments as explained above.  As all other mappings
-%   the mapping is done at the current group level, \emph{i.e.}~any
-%   local assignments made by the \meta{inline function} remain in
-%   effect after the loop.  The tokens are removed from the input
-%   stream.  The loop can be stopped by \cs{peek_analysis_map_break:}.
-%   Within the code, \cs{l_peek_token} is set equal (as a token, not a
-%   token list) to the token under consideration.
-% \end{function}
-%
-% \begin{function}[added = 2020-07-14]{\peek_analysis_map_break:, \peek_analysis_map_break:n}
-%   \begin{syntax}
-%     \cs{peek_analysis_map_inline:n} |{| \dots{} \cs{peek_analysis_map_break:n} \Arg{code} |}|
-%   \end{syntax}
-%   Stops the \cs{peek_analysis_map_inline:n} loop from seeking more
-%   tokens, and inserts \meta{code} in the input stream (empty for
-%   \cs{peek_analysis_map_break:}).
-% \end{function}
-%
 % \end{documentation}
 %
 % \begin{implementation}
diff --git a/l3kernel/l3token.dtx b/l3kernel/l3token.dtx
index 676c55747..ac2a1ea9f 100644
--- a/l3kernel/l3token.dtx
+++ b/l3kernel/l3token.dtx
@@ -758,10 +758,12 @@
 %
 % There is often a need to look ahead at the next token in the input
 % stream while leaving it in place. This is handled using the
-% \enquote{peek} functions. The generic \cs{peek_after:Nw} is
-% provided along with a family of predefined tests for common cases.
-% As peeking ahead does \emph{not} skip spaces the predefined tests
-% include both a space-respecting and space-skipping version.
+% \enquote{peek} functions. The generic \cs{peek_after:Nw} is provided
+% along with a family of predefined tests for common cases.  As peeking
+% ahead does \emph{not} skip spaces the predefined tests include both a
+% space-respecting and space-skipping version.  In addition, using
+% \cs{peek_analysis_map_inline:n}, one can map through the following
+% tokens in the input stream and repeatedly perform some tests.
 %
 % \begin{function}{\peek_after:Nw}
 %   \begin{syntax}
@@ -980,6 +982,59 @@
 %   (as appropriate to the result of the test).
 % \end{function}
 %
+% \begin{function}[added = 2020-07-16]{\peek_analysis_map_inline:n}
+%   \begin{syntax}
+%     \cs{peek_analysis_map_inline:n} \Arg{inline function}
+%   \end{syntax}
+%   Repeatedly removes one \meta{token} from the input stream and
+%   applies the \meta{inline function} to it, until
+%   \cs{peek_analysis_map_break:} is called.  The \meta{inline function}
+%   receives three arguments for each \meta{token} in the input stream:
+%   \begin{itemize}
+%   \item \meta{tokens}, which both \texttt{o}-expand and
+%     \texttt{x}-expand to the \meta{token}. The detailed form of
+%     \meta{tokens} may change in later releases.
+%   \item \meta{char code}, a decimal representation of the character
+%     code of the \meta{token}, $-1$ if it is a control sequence.
+%   \item \meta{catcode}, a capital hexadecimal digit which denotes the
+%     category code of the \meta{token} (0:~control sequence,
+%     1:~begin-group, 2:~end-group, 3:~math shift, 4:~alignment tab,
+%     6:~parameter, 7:~superscript, 8:~subscript, A:~space, B:~letter,
+%     C:~other, D:~active).  This can be converted to an integer by
+%     writing |"|\meta{catcode}.
+%   \end{itemize}
+%   These arguments are the same as for \cs{tl_analysis_map_inline:nn}
+%   defined in \pkg{l3tl-analysis}.  The \meta{char code} and
+%   \meta{catcode} do not take the meaning of a control sequence or
+%   active character into account: for instance, upon encountering the
+%   token \cs{c_group_begin_token} in the input stream,
+%   \cs{peek_analysis_map_inline:n} calls the \meta{inline function}
+%   with |#1| being \cs{exp_not:n} |{| \cs{c_group_begin_token} |}|
+%   (with the current implementation),
+%   |#2|~being~$-1$, and
+%   |#3|~being~$0$, as for any other control sequence.  In contrast,
+%   upon encountering an explicit begin-group token~|{|, % ^^A |}|
+%   the \meta{inline function} is called with arguments
+%   \cs{exp_after:wN} |{| \cs{if_false:} |}| \cs{fi:}, $123$ and~$1$.
+%
+%   The mapping is done at the current group level, \emph{i.e.}~any
+%   local assignments made by the \meta{inline function} remain in
+%   effect after the loop.  Within the code, \cs{l_peek_token} is set
+%   equal (as a token, not a token list) to the token under
+%   consideration.
+% \end{function}
+%
+% \begin{function}[added = 2020-07-16]
+%   {\peek_analysis_map_break:, \peek_analysis_map_break:n}
+%   \begin{syntax}
+%     \cs{peek_analysis_map_inline:n}
+%       |{| \dots{} \cs{peek_analysis_map_break:n} \Arg{code} |}|
+%   \end{syntax}
+%   Stops the \cs{peek_analysis_map_inline:n} loop from seeking more
+%   tokens, and inserts \meta{code} in the input stream (empty for
+%   \cs{peek_analysis_map_break:}).
+% \end{function}
+%
 % \section{Description of all possible tokens}
 % \label{sec:l3token:all-tokens}
 %