[latex3-commits] [l3svn] r7123 - Document what nested \c and \u do in l3regex replacements

[noreply at latex-project.org]

Author: bruno
Date: 2017-04-25 05:23:27 +0200 (Tue, 25 Apr 2017)
New Revision: 7123

Modified:
   trunk/l3experimental/l3str/l3regex.dtx
Log:
Document what nested \c and \u do in l3regex replacements

(Technically this commit also makes \c identical to \u when used
inside \c or \u: previously it did \tl_to_str:c and not \tl_to_str:v.)


Modified: trunk/l3experimental/l3str/l3regex.dtx
===================================================================
--- trunk/l3experimental/l3str/l3regex.dtx	2017-04-25 02:51:59 UTC (rev 7122)
+++ trunk/l3experimental/l3str/l3regex.dtx	2017-04-25 03:23:27 UTC (rev 7123)
@@ -400,9 +400,12 @@
 % The escape sequence |\u|\Arg{tl~var~name} allows to insert the
 % contents of the token list with name \meta{tl~var~name} directly into
 % the replacement, avoiding the need to escape special characters.
-% Within the construction |\c|\Arg{text}, the |\u|~escape sequence only
-% expands its argument once, in effect performing \cs{tl_to_str:v}.
-% Submatches can be used within the argument of |\u|.  For instance,
+% Within |\c{|\ldots{}|}| and |\u{|\ldots{}|}| constructions, the |\u|
+% and |\c|~escape sequences perform \cs{tl_to_str:v}, namely extract the
+% value of the control sequence and turn it into a string.
+%
+% Matches can be used within the arguments of |\c| and |\u|.  For
+% instance,
 % \begin{verbatim}
 %   \tl_set:Nn \l_my_one_tl { first }
 %   \tl_set:Nn \l_my_two_tl { \emph{second} }
@@ -663,8 +666,6 @@
 %   \item Optimize the use of \cs{int_step_...} functions.
 %   \item Groups don't capture within regexes for csnames; optimize and
 %     document.
-%   \item Decide and document what |\c{\c{...}}| should do in the
-%     replacement text, similar questions for |\u|.
 %   \item Better \enquote{show} for anchors, properties, and catcode tests.
 %   \item Does |\K| really need a new state for itself?
 %   \item When compiling, use a boolean \texttt{in_cs} and less magic
@@ -5121,10 +5122,7 @@
 %   |\c| can be followed by a left brace, or by a letter for which we
 %   have defined a way to produce that category of characters.  The
 %   appropriate definitions for catcodes are introduced later.  For
-%   control sequences, if we are within a control sequence, convert
-%   the token list to a string, otherwise simply prevent expansion,
-%   with a weird cross-over between \cs{exp_not:n} and \cs{exp_not:N}
-%   (see this helper's description for an explanation).
+%   control sequences, call an auxiliary that starts a control sequence.
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_replacement_c:w #1#2
   {
@@ -5136,18 +5134,30 @@
       { \@@_replacement_error:NNN c #1#2 }
   }
 \cs_new_protected:cpn { @@_replacement_c_ \c_left_brace_str :w }
+  { \@@_replacement_cu_aux:Nw \@@_replacement_exp_not:N }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}[aux]{\@@_replacement_cu_aux:Nw}
+%   Start a control sequence with \cs{cs:w}, which will be protected
+%   from expansion by |#1| (either \cs{@@_replacement_exp_not:N} or
+%   \cs{exp_not:V}), or turned to a string by \cs{tl_to_str:V} if inside
+%   another csname construction |\c| or |\u|.  We use \cs{tl_to_str:V}
+%   rather than \cs{tl_to_str:N} to deal with integers and other
+%   registers.
+%    \begin{macrocode}
+\cs_new_protected:Npn \@@_replacement_cu_aux:Nw #1
   {
     \if_case:w \l_@@_replacement_csnames_int
-      \__tl_build_one:n
-        { \exp_not:n { \exp_after:wN \@@_replacement_exp_not:N \cs:w } }
+      \__tl_build_one:n { \exp_not:n { \exp_after:wN #1 \cs:w } }
     \else:
-      \__tl_build_one:n { \exp_not:n { \exp_after:wN \tl_to_str:N \cs:w } }
+      \__tl_build_one:n { \exp_not:n { \exp_after:wN \tl_to_str:V \cs:w } }
     \fi:
     \int_incr:N \l_@@_replacement_csnames_int
   }
 %    \end{macrocode}
 % \end{macro}
-% \end{macro}
 %
 % \begin{macro}[aux]{\@@_replacement_u:w}
 %   Check that |\u| is followed by a left brace. If so, start a control
@@ -5157,14 +5167,7 @@
 \cs_new_protected:Npn \@@_replacement_u:w #1#2
   {
     \str_if_eq_x:nnTF { #1#2 } { \__tl_build_one:n \c_left_brace_str }
-      {
-        \if_case:w \l_@@_replacement_csnames_int
-          \__tl_build_one:n { \exp_not:n { \exp_after:wN \exp_not:V \cs:w } }
-        \else:
-          \__tl_build_one:n { \exp_not:n { \exp_after:wN \tl_to_str:V \cs:w } }
-        \fi:
-        \int_incr:N \l_@@_replacement_csnames_int
-      }
+      { \@@_replacement_cu_aux:Nw \exp_not:V }
       { \@@_replacement_error:NNN u #1#2 }
   }
 %    \end{macrocode}