getargs (21may16)

git-svn-id: svn://tug.org/texlive/trunk@41415 c570f23f-e606-0410-a88d-b1316a301751

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
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