[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: Switch to \ExpandArgs/\UseName for #735 (547f13df)
Joseph Wright
joseph.wright at morningstar2.co.uk
Thu Jan 6 14:54:19 CET 2022
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/547f13dfcdc8049b72ee7b6de372758830e7ca68
>---------------------------------------------------------------
commit 547f13dfcdc8049b72ee7b6de372758830e7ca68
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date: Thu Jan 6 13:54:19 2022 +0000
Switch to \ExpandArgs/\UseName for #735
>---------------------------------------------------------------
547f13dfcdc8049b72ee7b6de372758830e7ca68
base/changes.txt | 5 +++++
base/doc/ltnews35.tex | 13 +++++++------
base/doc/usrguide3.tex | 44 +++++++++++++++++++++++++-----------------
base/ltexpl.dtx | 33 ++++++++++++++++---------------
base/testfiles/github-0735.lvt | 12 ++++++------
5 files changed, 61 insertions(+), 46 deletions(-)
diff --git a/base/changes.txt b/base/changes.txt
index b373ddc7..8bb024b0 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,11 @@ completeness or accuracy and it contains some references to files that
are not part of the distribution.
================================================================================
+2022-01-06 Joseph Wright <Joseph.Wright-project.org>
+
+ * ltexpl.dtx (section{Document-level command names for expl3 functions}):
+ Adjust document-level names for \exp_args:Nc and the like
+
2021-12-31 Phelype Oleinik <phelype.oleinik at latex-project.org>
* ltcmd.dtx (subsubsection{Showing the definition of a command}):
diff --git a/base/doc/ltnews35.tex b/base/doc/ltnews35.tex
index 15ae20f7..cbdc24ee 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -243,18 +243,18 @@ document-level commands with \cs{NewDocumentCommand} or
\cs{NewCommandCopy}, etc.\ the L3 programming layer may not be active,
and even if it is, mixing CamelCase syntax with L3 programming syntax
is not really a good approach. We have therefore added the commands
-\cs{ExpandNc}, \cs{ExpandNcc}, and \cs{ExpandNNc} to assist in such
+\cs{UseName} and \cs{ExpandArgs} to assist in such
situations, e.g.,
\begin{verbatim}
\NewDocumentCommand\newcopyedit{mO{red}}
{\newcounter{todo#1}%
- \ExpandNc\NewDocumentCommand{#1}{s m}%
+ \ExpandArgs{c}\NewDocumentCommand{#1}{s m}%
{\stepcounter{todo#1}%
\IfBooleanTF {##1}%
{\todo[color=#2!10]%
- {\Expandc{thetodo#1}: ##2}}%
+ {\UseName{thetodo#1}: ##2}}%
{\todo[inline,color=#2!10]%
- {\Expandc{thetodo#1}: ##2}}%
+ {\UseName{thetodo#1}: ##2}}%
}%
}
\end{verbatim}
@@ -262,9 +262,10 @@ which provides a declaration mechanism for copyedit commands, so that
\verb=\newcopyedit{FMi}[blue]= then defines \cs{FMi} (and the
necessary counter).
-The commands \cs{ExpandNcc} and \cs{ExpandNNc} can be useful in
+The command \cs{ExpandArgs} can be useful with the argument \texttt{cc} or
+\texttt{Nc} in
combination with \cs{NewCommandCopy} if the old or new command name
-or both need constructing. Finally, there is \cs{Expandc} which
+or both need constructing. Finally, there is \cs{UseName} which
takes its argument and turns it into a command (i.e., a CamelCase
version of \cs{@nameuse} (\LaTeXe) or \cs{use:c} (L3 programming
layer)) which was also used in the example above.
diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index 377b24e3..f04a007c 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -241,7 +241,7 @@ defined.
\end{itemize}
If the \meta{cmd} can't be provided as a single token but needs
-\enquote{constructing}, you can use \cs{ExpandNc} as explained in
+\enquote{constructing}, you can use \cs{ExpandArgs} as explained in
Section~\ref{sec:preconstructing-csnames} which also gives an example
in which this is needed.
@@ -774,8 +774,8 @@ that would be of limited value.
If the \meta{cmd} or \meta{existing-cmd} can't be provided as a single
-token but need \enquote{constructing}, you can use \cs{ExpandNc},
-\cs{ExpandNNc}, or \cs{ExpandNcc} as explained in
+token but need \enquote{constructing}, you can use \cs{ExpandArgs}
+as explained in
Section~\ref{sec:preconstructing-csnames}.
@@ -798,10 +798,8 @@ about the argument signature.
\label{sec:preconstructing-csnames}
\begin{decl}
- |\Expandc| \arg{string} \\
- |\ExpandNc| \arg{cmd} \arg{string} \\
- |\ExpandNcc| \arg{cmd} \arg{string} \arg{string} \\
- |\ExpandNNc| \arg{cmd} \arg{cmd\textsubscript{2}} \arg{string}
+ |\UseName| \arg{string} \\
+ |\ExpandArgs| \arg{cmd} \arg{spec} \arg{arg1} \arg{args2}
\end{decl}
When declaring new commands with \cs{NewDocumentCommand} or
@@ -810,22 +808,28 @@ When declaring new commands with \cs{NewDocumentCommand} or
layer has \cs{exp_args:N...} for this, but there is no mechanism for
it if \cs{ExplSyntaxOn} is not active (and mixing programming and user
interface level commands is not a good approach anyhow). We therefore
-offer a few of these commands also with CamelCase names.
-
-All four commands first turn the \meta{string} argument(s) into
-csnames and then execute \meta{cmd}, or in case of \cs{Expandc}
-execute the generated csname.
+offer a mechanism to access this ability using CamelCase naming.
+
+\cs{UseName} turns the \meta{string} directly into a csname and
+then executes it: this is equivalent to the long-standing
+\LaTeXe{} internal command \tn{@nameuse}, or the L3 programming
+equivalent \cs{use:c}. \cs{ExpandArgs} takes a \meta{spec} which
+describes how to expand the \meta{args}, carries out these
+operations then executes the \meta{cmd}. The \meta{spec} uses
+the descriptions offered by the L3 programming layer, and the
+relevant \cs{exp_args:N...} function must exist. Common cases will
+have a \meta{spec} of \texttt{c} or \texttt{cc}: see below.
As an example, the following declaration provides a method to generate
copyedit commands:
\begin{verbatim}
\NewDocumentCommand\newcopyedit{mO{red}}
{\newcounter{todo#1}%
- \ExpandNc\NewDocumentCommand{#1}{s m}%
+ \ExpandArgs{c}\NewDocumentCommand{#1}{s m}%
{\stepcounter{todo#1}%
\IfBooleanTF {##1}%
- {\todo[color=#2!10]{\Expandc{thetodo#1}: ##2}}%
- {\todo[inline,color=#2!10]{\Expandc{thetodo#1}: ##2}}%
+ {\todo[color=#2!10]{\UseName{thetodo#1}: ##2}}%
+ {\todo[inline,color=#2!10]{\UseName{thetodo#1}: ##2}}%
}%
}
\end{verbatim}
@@ -833,9 +837,13 @@ Given that declaration you can then write
\verb/\newcopyedit{note}[blue]/ which defines the command \cs{note}
and corresponding counter for you.
-
-
-
+A second example is to copy a command by string name using
+\cs{NewCommandCopy}: here we might need to construct both command
+names.
+\begin{verbatim}
+\NewDocumentCommand\savebyname{m}
+ {\ExpandArgs{cc}\NewCommandCopy{saved#1}{#1}}
+\end{verbatim}
\section{Expandable floating point (and other) calculations}
diff --git a/base/ltexpl.dtx b/base/ltexpl.dtx
index eb1dd78b..05993f53 100644
--- a/base/ltexpl.dtx
+++ b/base/ltexpl.dtx
@@ -33,7 +33,7 @@
%<*driver>
% \fi
\ProvidesFile{ltexpl.dtx}
- [2021/12/07 v1.3d LaTeX Kernel (expl3-dependent code)]
+ [2022/01/06 v1.3e LaTeX Kernel (expl3-dependent code)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltexpl.dtx}
@@ -462,10 +462,8 @@
% \end{macrocode}
%
%
-% \DescribeMacro\Expandc
-% \DescribeMacro\ExpandNc
-% \DescribeMacro\ExpandNcc
-% \DescribeMacro\ExpandNNc
+% \DescribeMacro\UseName
+% \DescribeMacro\ExpandArgs
% When declaring new commands with \cs{NewDocumentCommand} or
% \cs{NewCommandCopy} or similar, it is sometimes necessary to
% ``construct'' the csname. As a general mechanism the L3
@@ -474,23 +472,28 @@
% therefore offer a few of these commands also with CamelCase names.
%
%
-% \begin{macro}{\Expandc,\ExpandNc,\ExpandNcc,\ExpandNNc}
+% \begin{macro}{\UseName,\ExpandArgs}
% A document wrapper for changing arguments to cs names for use
% with \cs{NewDocumentCommand} and similar functions.
%
% \changes{v1.3d}{2021/12/28}{Added document level names for \cs{exp\_args:Nc} and the like (gh/735)}
+% \changes{v1.3e}{2022/01/06}{Adjust document level names for \cs{exp\_args:Nc} and the like (gh/735)}
% \begin{macrocode}
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2022/06/01}%
-%<latexrelease> {\Expandc}{Some pre-expansion commands}%
+%<latexrelease> {\ExpandArgs}{Some pre-expansion commands}%
\ExplSyntaxOn
-\cs_new_eq:NN \Expandc \use:c
+\cs_new_eq:NN \UseName \use:c
% \end{macrocode}
%
% \begin{macrocode}
-\cs_new_eq:NN \ExpandNc \exp_args:Nc
-\cs_new_eq:NN \ExpandNcc \exp_args:Ncc
-\cs_new_eq:NN \ExpandNNc \exp_args:NNc
+\cs_new:Npn \ExpandArgs #1
+ {
+ \cs_if_exist_use:cF { exp_args:N #1 }
+ { \msg_expandable_error:nnn { kernel } { unknown-arg-expansion } {#1} }
+ }
+\msg_new:nnn { kernel } { unknown-arg-expansion }
+ { Unknopwn~arg~expansion~"#1" }
\ExplSyntaxOff
% \end{macrocode}
% \end{macro}
@@ -499,13 +502,11 @@
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
-%<latexrelease> {\Expandc}{Some pre-expansion commands}%
+%<latexrelease> {\ExpandArgs}{Some pre-expansion commands}%
%<latexrelease>
-%<latexrelease>\let\Expandc\@undefined
-%<latexrelease>\let\ExpandNc\@undefined
-%<latexrelease>\let\ExpandNcc\@undefined
-%<latexrelease>\let\ExpandNNc\@undefined
+%<latexrelease>\let\UseName\@undefined
+%<latexrelease>\let\ExpandArgs\@undefined
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
%
diff --git a/base/testfiles/github-0735.lvt b/base/testfiles/github-0735.lvt
index 247aed99..56195177 100644
--- a/base/testfiles/github-0735.lvt
+++ b/base/testfiles/github-0735.lvt
@@ -7,20 +7,20 @@
\TEST { pre-expansion one argument}
{
- \ExpandNc \NewDocumentCommand{foo}{om}{???}
+ \ExpandArgs{c} \NewDocumentCommand{foo}{om}{???}
\ShowCommand\foo
- \ExpandNc \ShowCommand {foo}
- \ExpandNc \NewCommandCopy {baz} \foo
+ \ExpandArgs{c} \ShowCommand {foo}
+ \ExpandArgs{c} \NewCommandCopy {baz} \foo
\ShowCommand\baz
- \Expandc {typeout}{Ok?}
+ \UseName {typeout}{Ok?}
}
\TEST { pre-expansion two arguments}
{
\NewDocumentCommand\foo {om}{???}
- \ExpandNcc \NewCommandCopy {baz} {foo}
+ \ExpandArgs{cc} \NewCommandCopy {baz} {foo}
\ShowCommand\baz
- \ExpandNNc \RenewCommandCopy \baz {foo}
+ \ExpandArgs{Nc} \RenewCommandCopy \baz {foo}
\ShowCommand\baz
}
More information about the latex3-commits
mailing list.