summaryrefslogtreecommitdiff
path: root/obsolete/macros/latex/contrib/getargs/getargs.tex
blob: a0c4054e86a1f99e90c171d0600bf76aaf0b034a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
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}