%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \iffalse %%%%
% %
% Copyright (c) 2016 - Michiel Helvensteijn (www.mhelvens.net) %
% %
% This work may be distributed and/or modified under the conditions %
% of the LaTeX Project Public License, either version 1.3 of this %
% license or (at your option) any later version. The latest version %
% of this license is in http://www.latex-project.org/lppl.txt %
% and version 1.3 or later is part of all distributions of LaTeX %
% version 2005/12/01 or later. %
% %
% This work has the LPPL maintenance status `maintained'. %
% %
% The Current Maintainer of this work is Michiel Helvensteijn. %
% %
% This work consists of the files withargs.tex and withargs.sty. %
% %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \fi %%%%
\documentclass[a4paper]{withargs-packagedoc}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Setup %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\moretexcs{
withargs,foo,bar,bas,expectedResult,
actualResult,MyPost,A,uniquecsname,NewPost,
cs_generate_variant:Nn,
withargs:nn,withargs:cn
}
% Ugly hack, because of the unfortunate deprecation of 'n' to 'c' conversion,
% plus the fact that kernel errors, even non-fatal ones, cannot be redirected.
% Will think of a better solution at some point, but not now.
\ExplSyntaxOn
\let\__withargs_docs_old_kernel_msg_error:nnnnnn\__kernel_msg_error:nnnnnn
\def\__kernel_msg_error:nnnnnn#1#2{
\str_if_eq:nnTF { #1/#2 } { kernel/deprecated-variant }{
\__kernel_msg_warning:nnnnnn{#1}{#2}
}{
\__withargs_docs_old_kernel_msg_error:nnnnnn{#1}{#2}
}
}
\ExplSyntaxOff
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Global Changes %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\changes{0.0.1}{2013/10/01}
{initial version}
\changes{0.0.2}{2013/10/11}
{renamed package to \texttt{withargs}}
\changes{0.1.0}{2015/09/07}
{adjusted code to new version of expl3}
\changes{0.2.0}{2016/12/19}
{adjusted code to new version of expl3}
\changes{0.3.1}{2019/11/04}
{adjusted code to new version of expl3}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document} %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\maketitle
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction} %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
An example is worth a thousand words:
\begin{latex-example-show}
\withargs [!] [Hello] [world] { #2 #3#1 }
\end{latex-example-show}
A quick explanation: we're passing three pieces of \LaTeX\ code in the form
of optional arguments to the final argument, which forms the output. We're
defining a new anonymous macro and invoking it right away.
Up to seven optional arguments are supported.
\subsection{Why is this useful?} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
One of the main use-cases for this package is to insert the expanded
result of a computation into the middle of a big
blob of code that \emph{shouldn't} be expanded. This is possible because
argument substitution bypasses the expansion process:
\begin{latex-example-show}
\def \expectedResult {\bar}
\def \actualResult {\bas}
\withargs (oo) [\actualResult] [\expectedResult] {
\texttt{\detokenize{
The \foo variable resulted in `#1' instead of `#2'!
}}
}
\end{latex-example-show}
`|(oo)|' indicates that both arguments should be expanded `once'.
Any optional \LaTeX3 style argument specification between parentheses
may be specified to control expansion.
\needspace{10\baselineskip}
You can define your own commands accepting `templates'
with \TeX-style parameters:
\begin{latex-example-show}
\newcommand{\NewPost}[4]{
% #1: author % #2: title
% #3: content % #4: template
\withargs (xnn) [#1] [#2] [#3] {#4}
}
\def\MyPost{ \NewPost{Author}{Title}
{Boy, do I have some important stuff to say!} }
\begin{tabular}{p{3.5cm}p{3.5cm}p{3.5cm}}
\MyPost{\textbf{#2\hfill#1}\vskip1mm\hrule\vskip1mm\textit{#3}} &
\MyPost{\fbox{#1: ``#2''}\par#3\vskip1mm\hrule} &
\MyPost{#2: #3\hfill\textit{(#1)}}
\end{tabular}
\end{latex-example-show}
Generally, if speed is not a concern, |\withargs| can be used
to make \LaTeX\ code more readable in a variety of situations.
%\vskip-.4\baselineskip
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Document Level Commands} %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\vskip-.5\baselineskip
\def\mystrut{\rule{0pt}{4mm}}
\describemacro{\withargs}{
\texttt{\bfseries(}%
\(\overbrace{\mystrut\hbox{\meta{argument specification}}}^x\)%
\texttt{\bfseries)}
\(\overbrace{\mystrut\hbox{\oarg{1} \oarg{2} \oarg{3} \oarg{4} \oarg{5} \oarg{6} \oarg{7}}}^x\)
\marg{body}
}
Leaves \meta{body} in the output with |#1|\ldots|#7| replaced
by optional arguments \meta{1}\ldots\!\meta{7}.
An optional \LaTeX3 style \meta{argument specification} between parentheses
can be provided, in which case the arguments undergo expansion as specified
before being placed in the \meta{body}.
%%
Here is an example demonstrating the possible expansion types:
\begin{latex-example-show}
\def\foo{\bar} \def\s{s} \def\bar{ba\s} \def\bas{FOO-BAR-BAS}
\withargs (n o f x c v )
[\foo][\foo][\foo][\foo][\foo][\foo] {
\begin{tabular}{llll}
n: & \texttt{\detokenize{#1}} & % no expansion
o: & \texttt{\detokenize{#2}} \\ % expand once
f: & \texttt{\detokenize{#3}} & % expand until unexpandable
x: & \texttt{\detokenize{#4}} \\ % exhaustive expansion
c: & \texttt{\detokenize{#5}} & % \csname conversion
v: & \texttt{\detokenize{#6}} % `c', then `o'
\end{tabular}
}
\end{latex-example-show}
Note that all spaces in the \meta{argument specification} are ignored.
For details about \LaTeX3 argument specifications, have a look at the
following documentation:
\begin{center}
\url{http://www.ctan.org/pkg/expl3}
\end{center}
\describemacro{\uniquecsname}{}\vskip-2\baselineskip
Perhaps a bit misleading, |\uniquecsname| is not actually defined as a command,
but |\withargs| recognizes it as a special marker. If an optional |\withargs|
argument consists entirely of |\uniquecsname|, it is replaced by a
command sequence name which is guaranteed to be unique\ldots unless
you look at the source code (Section~\ref{sec:implementation})
and intentionally replicate the naming scheme.
\begin{latex-example-show}
\withargs (ccc) [\uniquecsname][\uniquecsname][\uniquecsname] {
\def#1{A} \let\A#1
\def#2{B}
\def#3{C}
#3#2#1%
}%
(\A)
\end{latex-example-show}
\vskip5mm
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\LaTeX3 Functions} %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The \LaTeX3 functions underlying the functionality of |\withargs| are
also available as is.
\describeanymacro{\texttt{\textbackslash withargs:\smash{\(\overbrace{\mystrut\hbox{nnnnnnnn}\!}^x\,\)}n}}{
\(\overbrace{\mystrut\hbox{\marg{1} \marg{2} \marg{3} \marg{4} \marg{5} \marg{6} \marg{7} \marg{8}}}^x\)
\marg{body}
}
These functions do pretty much the same thing as the main |\withargs| macro,
except that the argument specification is embedded in the function name
as per \LaTeX3 coding convention, so a parameter slot is freed up for
custom use. They are slightly faster than |\withargs|, as there is no
need to gather optional arguments or do any error checking.
The downside is that the |\uniquecsname| marker doesn't work for these.
To use a specific expansion scheme, you have to define a variant:
\begin{latex-example-show}
\ExplSyntaxOn
\cs_generate_variant:Nn \withargs:nn {cn}
\withargs:cn {LaTeX} {#1}
\ExplSyntaxOff
\end{latex-example-show}
Read the \LaTeX3 documentation for details.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document} %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%