summaryrefslogtreecommitdiff
path: root/Master/texmf-dist
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-06-12 16:14:46 +0000
committerKarl Berry <karl@freefriends.org>2016-06-12 16:14:46 +0000
commitd5e9bf23cf171fa8b3dd00240390287e15c26b80 (patch)
tree511eeef9ee1a2496bfb0e2533d025b2cbac799f3 /Master/texmf-dist
parent417c2c0a5d5d82e53235d9aa529a30c06acee3cb (diff)
getargs (21may16)
git-svn-id: svn://tug.org/texlive/trunk@41415 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist')
-rw-r--r--Master/texmf-dist/doc/latex/getargs/README13
-rw-r--r--Master/texmf-dist/doc/latex/getargs/getargs.pdfbin0 -> 402698 bytes
-rw-r--r--Master/texmf-dist/doc/latex/getargs/getargs.tex250
-rw-r--r--Master/texmf-dist/tex/latex/getargs/getargs.sty56
4 files changed, 319 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/getargs/README b/Master/texmf-dist/doc/latex/getargs/README
new file mode 100644
index 00000000000..243be70c7cb
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/getargs/README
@@ -0,0 +1,13 @@
+THE getargs PACKAGE
+
+This short package provides a flexible list-parsing macro with the
+ability to configure the parsing character, as well as the macro names
+in which the parsed list items are placed. The name of the parsing
+macro is \getargs.
+
+It is a significant improvement over similarly named macros in my
+stringstrings and readarray packages. It is my intent to eventually
+have the parsers of those other packages point to this package, to
+achieve a measure of uniformity.
+
+Steven B. Segletes
diff --git a/Master/texmf-dist/doc/latex/getargs/getargs.pdf b/Master/texmf-dist/doc/latex/getargs/getargs.pdf
new file mode 100644
index 00000000000..4ae4516ddd9
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/getargs/getargs.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/getargs/getargs.tex b/Master/texmf-dist/doc/latex/getargs/getargs.tex
new file mode 100644
index 00000000000..a0c4054e86a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/getargs/getargs.tex
@@ -0,0 +1,250 @@
+\documentclass{article}
+\usepackage{verbatimbox,getargs}
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+\def\gtrgpk{\textsf{getargs}}
+\reversemarginpar
+\marginparwidth 1.6in
+\newcommand\margtt[1]{\marginpar{\hfill\ttfamily#1}}
+\newcommand\margcmd[1]{\marginpar{\hfill\ttfamily\char'134#1}}
+\newcommand\cmd[1]{\texttt{\small\char'134#1}}
+\usepackage{parskip}%\parindent 0in\parskip 1em
+\parskip 1.8ex plus 2pt
+\begin{document}
+\begin{myverbbox}[\small]{\gtrg}\getargs\end{myverbbox}
+\begin{myverbbox}[\small]{\gtrginv}\getargs{<argument-list to parse using parse-character>}\end{myverbbox}
+\begin{myverbbox}[\small]{\setpc}\setparsechar\end{myverbbox}
+\begin{myverbbox}[\small]{\setpcinv}\setparsechar{<parse-character>}\end{myverbbox}
+\begin{myverbbox}[\small]{\setpcrn}\setparserootname\end{myverbbox}
+\begin{myverbbox}[\small]{\setpcrninv}\setparserootname[<root-name>]\end{myverbbox}
+\begin{center}
+\LARGE The {\gtrgpk} Package\\
+\rule{0em}{.7em}\small Provides the \verb|\getargs| list parsing macro
+and associated configurations\\
+\rule{0em}{2.7em}\large Steven B. Segletes\\
+steven.b.segletes.civ@mail.mil\\
+\rule{0em}{1.7em}\today\\
+\getargsversionnumber%
+\end{center}
+This is the 3rd incarnation of the \gtrg{} macro in some form or another.
+The first was in the \textsf{stringstrings} package, but it is slow, can only
+ parse an expanable list with space delimiters, and brings all the baggage
+ of my bloated \textsf{stringstrings} package with it.
+An much more efficient form was reformulated in my \textsf{readarray} package,
+ under the name \gtrg\texttt{\small C}, but like its predecessor, it can
+ only parse with space delimiters.
+So here, I reintroduce the \gtrg{} macro, both efficient and capable of parsing
+ based on any delimiter character desired.
+In addition, it allows for the root-name of the parsed-argument list to be customized.
+It is my intent to eventually have the parsers of those other packages point
+ to this package, to achieve uniformity.
+
+This package is very short, providing three user macros plus one diagnostic macro.
+The macro \setpc{}\margcmd{setparsechar}, invoked as
+
+\setpcinv,
+
+\noindent provides the means to designate the delimiter character by which
+ the parser breaks the argument list into pieces.
+Because of the popularity of the csv format, the parsing delimiter character
+ is set to a comma (\texttt{,}), when the package is initially invoked.
+The parsing delimiter character can also be set to a space with
+ \setpc\texttt{\small\{ \}}.
+If the parsing delimiter is not a space, however, then leading and trailing
+ spaces in the parsed argument list are retained
+(note that, in the standard \LaTeX{} fashion, multiple adjacent spaces are
+ parsed as a single input space).%
+\footnote{The current parse character is stored in
+ \cmd{\small getargsparsechar}, for reference only.
+However, a new parse character can only be set
+ with an invocation of \setpc{}.}
+
+The primary user macro of this package is \gtrg{}\margcmd{getargs}, which
+ is used to parse a delimited argument list. The invocation syntax is
+
+\gtrginv
+
+\noindent
+Like prior formulations of the \gtrg{} macro, the result of the parsing are
+ twofold:
+\begin{enumerate}
+ \item The number of items parsed from the argument-list is stored, via
+ \cmd{xdef}, in the macro named, by default, \cmd{narg}.
+ \item The actual tokens of the parsed argument-list are placed in a series
+ of macros, which are, by default, named \cmd{argi}, \cmd{argii},
+ \cmd{argiii}, \cmd{argiv}, \ldots, in roman-numeral naming fashion.
+\end{enumerate}
+The root name of the macros into which the parsed argument-list are placed
+ can itself be designated by the user, using the \setpcrn%
+ \margcmd{setparserootname} macro.
+This macro is invoked as
+
+\setpcrninv
+
+The default root-name employed is ``arg'', if the optional argument is not
+ specified.
+When the root-name of the \gtrg{} parser is changed, not only are the
+ subsequently parsed arguments stored in new macro names \cmd{<root-name>i},
+ \cmd{<root-name>ii}, \cmd{<root-name>iii}, \textit{etc.}, but the
+ total number of arguments parsed is no longer stored in \cmd{narg}, but now
+ in \cmd{n<root-name>}.
+
+The final macro provided is the \cmd{showargs}\margcmd{showargs}
+ diagnostic macro.
+It can be invoked with or without the \texttt{\small[x]} optional argument,
+ which determines whether the parsed argument list is presented as tokens
+ (the default, via \cmd{detokenize}\footnote{%
+Dont forget that \LaTeX{}'s \cmd{\footnotesize detokenize} always presents macro names
+ with a trailing space, regardless of whether that space actually exists
+ in the parsed argument.})
+ or, if it is presented in expanded form,
+ when the \texttt{\small[x]} optional argument is employed.
+\textbf{Be forewarned that not all parsed tokens will present without error in
+ expanded form.}
+If the parsing separates a macro from its arguments, or if it separates some
+ types of opening and closing delimiters (paired \texttt{\$}, for example),
+ then errors will be generated, not from the parsing, but from an attempt to
+ \cmd{showargs} the result in expanded \texttt{[x]} form.
+
+The \cmd{showargs} invocation will first list the number of items most
+ recently parsed from the input list associated with the current
+ \texttt{<root-name>}.
+It will provide that root-name of the parsed items and whether or not the
+ parsed items that follow are presented as raw tokens or in expanded form.
+Finally, it will sequentially list the parsed items between vertical
+ dividing rules, in a line breakable way.
+
+This version of \gtrg{} and \cmd{showargs} will overwrite any existing
+ version that is already loaded (for example, from the
+ \textsf{stringstrings} package), without providing warning or error.
+If that is the intent of the user, then make sure the \gtrgpk{} package
+ is loaded after the other conflicting packages.
+
+\clearpage\section*{Examples}
+
+\begin{itemize}
+
+\item \textbf{The difference between expanded and raw-token \cmd{showargs}}
+
+\begin{verbnobox}[\small]
+\def\myname{Steven Segletes}
+\getargs{Signed/dated as follows, \myname, \today}
+\showargs[x]\par
+\showargs
+\end{verbnobox}
+\def\myname{Steven Segletes}
+\getargs{Signed/dated as follows, \myname, \today}
+\showargs[x]\par
+\showargs
+
+When presented in expanded form, the macros are fleshed out with their
+ expansions.
+However, one can see that the original tokens remain in the tokenized
+ presentation of \cmd{argii} and \cmd{argiii}.
+
+\item \textbf{The behavior of leading/trailing spaces (with a non-space parse
+ character)}
+
+\begin{verbnobox}[\small]
+\getargs{A, A, A , A }
+\showargs
+\end{verbnobox}
+\getargs{A, A, A , A }
+\showargs
+
+Note above, in the expression of \cmd{argiv}, that multiple spaces in the
+ input are parsed, according to the \LaTeX{} standard, as single spaces.
+Thus, \cmd{argiii} and \cmd{argiv} are functionally identical.
+
+\item \textbf{Changing the parsing character}
+
+\begin{verbnobox}[\small]
+\setparsechar{&}
+\getargs {y&\frac{x}{y}&(x_0-y_0)^3}
+$\showargs[x]$
+\end{verbnobox}
+
+\setparsechar{&}
+\getargs {y&\frac{x}{y}&(x_0-y_0)^3}
+$\showargs[x]$
+
+Note that the parsing of math expressions did not take place in math mode.
+However, as long as they are presented in math mode, all is well.
+
+The changed parsing character will remain \texttt{\&} until subsequently
+ changed (or until the group ends, if it was changed within a group).
+
+\clearpage\item \textbf{Space as the parsing character}
+
+\begin{verbnobox}[\small]
+\setparsechar{ }
+\getargs{A B C D}\showargs
+\end{verbnobox}
+
+\setparsechar{ }
+\getargs{A B C D}\showargs
+
+When a space-character is used as the parsing character, one can see above that
+ multiple leading/trailing spaces are absorbed in the parsing, so that \cmd{argiii}
+ is left as a simple ``C'', despite being surrounded by multiple spaces.
+
+
+\item \textbf{Parsed macros are not expanded at time of parsing}
+
+\begin{verbnobox}[\small]
+\setparsechar{&}
+\def\A{Alpha $\alpha$}
+\getargs {parameter (1)& &parameter {\A}}
+\argiii{} VS. \def\A{Beta $\beta$}\argiii
+\end{verbnobox}
+
+\setparsechar{&}
+\def\A{Alpha $\alpha$}
+\getargs {parameter (1)& &parameter {\A}}
+\argiii{} VS. \def\A{Beta $\beta$}\argiii
+
+Because \cmd{argiii} is stored as this: ``\texttt{\small\detokenize\expandafter{\argiii}}'',
+it follows that after \cmd{A} is redefined, the redefinition carries over into
+ the expansion of \cmd{argiii}.
+
+\item \textbf{Nested parsing}
+
+\begin{verbnobox}[\small]
+\setparserootname[ROW]
+\setparsechar{\\}
+\getargs {A_{11} & A_{12} & A_{13}\\ A_{21} & A_{22} & A_{23}}
+\setparsechar{&}
+\setparserootname[ROWiCOL]
+\expandafter\getargs\expandafter{\ROWi}
+\setparserootname[ROWiiCOL]
+\expandafter\getargs\expandafter{\ROWii}
+$(\ROWiCOLi) (\ROWiCOLii) (\ROWiCOLiii)$\\
+$(\ROWiiCOLi) (\ROWiiCOLii) (\ROWiiCOLiii)$
+\end{verbnobox}
+
+\setparserootname[ROW]
+\setparsechar{\\}
+\getargs {A_{11} & A_{12} & A_{13}\\ A_{21} & A_{22} & A_{23}}
+\setparsechar{&}
+\setparserootname[ROWiCOL]
+\expandafter\getargs\expandafter{\ROWi}
+\setparserootname[ROWiiCOL]
+\expandafter\getargs\expandafter{\ROWii}
+$(\ROWiCOLi) (\ROWiCOLii) (\ROWiCOLiii)$\\
+$(\ROWiiCOLi) (\ROWiiCOLii) (\ROWiiCOLiii)$
+
+Above, I perform all the tasks manually, but it is not hard to set it in
+ a loop based on the respective values of \cmd{nROW} (\nROW), \cmd{nROWiCOL}
+ (\nROWiCOL), and \cmd{nROWiiCOL} (\nROWiiCOL).
+This is a powerful way to retieve and store all the elements of a matrix in
+ a structured way.
+Note that \cmd{ROWi} and \cmd{ROWii} each had to be expanded exactly once
+ in order to be digested as input to \gtrg.
+
+\end{itemize}
+
+
+\section*{Source Code}
+
+\verbfilebox[\footnotesize]{getargs.sty}\theverbbox
+\end{document}
diff --git a/Master/texmf-dist/tex/latex/getargs/getargs.sty b/Master/texmf-dist/tex/latex/getargs/getargs.sty
new file mode 100644
index 00000000000..be28d6257b2
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/getargs/getargs.sty
@@ -0,0 +1,56 @@
+\def\getargsversionnumber{v1.01}
+\ProvidesPackage{getargs}
+[2016/05/20 \getargsversionnumber\
+ Macro to parse an argument list, using user-specified parsing character]
+% CREATED BY Steven B. Segletes <steven.b.segletes.civ@mail.mil>
+% THIS PACKAGE IS RELEASED IN ACCORDANCE WITH THE LaTeX PUBLIC PROJECT LICENSE
+% LPPL v1.3c (http://ctan.org/license/lppl1.3) OR ITS SUCCESSORS
+
+% V1.00-Initial release
+\newcounter{getarg@ctr}
+\let\getargs\relax
+\newcommand\getargs{}
+
+\newcommand\setparsechar[1]{%
+ \def\getargparsechar{#1}%
+ \renewcommand{\getargs}[1]{%
+ \setcounter{getarg@ctr}{0}%
+ \parse@args##1#1\relax\relax%
+ }%
+ \def\parse@args##1#1##2\relax{%
+ \stepcounter{getarg@ctr}%
+ \expandafter\gdef\csname\getarg@root\romannumeral\value{getarg@ctr}\endcsname{##1}%
+ \ifx\relax##2\relax%
+ \expandafter\xdef\csname n\getarg@root\endcsname{\thegetarg@ctr}\else%
+ \parse@args##2\relax\fi%
+ }%
+}
+
+\newcommand\setparserootname[1][arg]{\def\getarg@root{#1}}
+
+\let\showargs\relax
+\newcommand\showargs[1][t]{%
+ \fboxrule=.7pt\relax\fboxsep=\dimexpr-.5pt-\fboxrule\relax%
+ \csname n\getarg@root\endcsname{} \textbackslash\getarg@root\ldots{} items %
+ \if x#1(expanded)\else (tokens)\fi%
+ : \showargs@help{#1}{1}{\csname n\getarg@root\endcsname}\unskip\fbox{\strut}.%
+}
+
+\newcommand\showargs@help[3]{%
+ \setcounter{getarg@ctr}{#2}%
+ \if x#1%
+ \fbox{\strut}\csname\getarg@root\romannumeral\value{getarg@ctr}\endcsname%
+ \hskip0pt\relax%
+ \else
+ \fbox{\strut}%
+ \expandafter\detokenize\expandafter\expandafter\expandafter{%
+ \csname\getarg@root\romannumeral\value{getarg@ctr}\endcsname}\hskip0pt\relax%
+ \fi
+ \ifnum\value{getarg@ctr}<#3\relax\stepcounter{getarg@ctr}%
+ \showargs@help{#1}{\thegetarg@ctr}{#3}%
+ \fi%
+}
+
+\setparserootname
+\setparsechar{,}
+\endinput