summaryrefslogtreecommitdiff
path: root/obsolete/macros/latex/contrib/getargs/getargs.tex
diff options
context:
space:
mode:
Diffstat (limited to 'obsolete/macros/latex/contrib/getargs/getargs.tex')
-rw-r--r--obsolete/macros/latex/contrib/getargs/getargs.tex250
1 files changed, 250 insertions, 0 deletions
diff --git a/obsolete/macros/latex/contrib/getargs/getargs.tex b/obsolete/macros/latex/contrib/getargs/getargs.tex
new file mode 100644
index 0000000000..a0c4054e86
--- /dev/null
+++ b/obsolete/macros/latex/contrib/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}