Debian Codegraph @

texmf-dist/source/latex/keyparse/keyparse.dtx

raw
1 % \iffalse meta-comment
2 % !TEX program = pdfLaTeX
3 %<*internal>
4 \iffalse
5 %</internal>
6 %<*readme>
7 -----------------------------------------------------------------
8 ##### keyparse --- key-based parser
9 - Source repository: https://github.com/rogard/keyparse
10 - Released under the LaTeX Project Public License v1.3c or later
11 - See http://www.latex-project.org/lppl.txt
12 -----------------------------------------------------------------
13 %</readme>
14 %<*internal>
15 \fi
16 \def\nameofplainTeX{plain}
17 \ifx\fmtname\nameofplainTeX\else
18 \expandafter\begingroup
19 \fi
20 %</internal>
21 %<*install>
22 \input l3docstrip.tex
23 \keepsilent
24 \askforoverwritefalse
25 \preamble
26 -----------------------------------------------------------------------------
27 keyparse --- key-based parser
28 Released under the LaTeX Project Public License v1.3c or later
29 See http://www.latex-project.org/lppl.txt
30 ----------------------------------------------------------------------------
31
32 \endpreamble
33 \postamble
34
35 Copyright (C) 2021 by Erwann Rogard
36
37 This work may be distributed and/or modified under the
38 conditions of the LaTeX Project Public License (LPPL), either
39 version 1.3c of this license or (at your option) any later
40 version. The latest version of this license is in the file:
41
42 http://www.latex-project.org/lppl.txt
43
44 This work is "maintained" (as per LPPL maintenance status) by
45 Erwann Rogard.
46
47 This work consists of the file keyparse.dtx and the derived files:
48 keyparse.sty, and keyparse.pdf.
49
50 \endpostamble
51 \generate{
52 \file{\jobname.sty}{\from{\jobname.dtx}{package}}
53 }
54 %</install>
55 %<install> \endbatchfile
56 %<*internal>
57 \generate{
58 \file{\jobname.ins}{\from{\jobname.dtx}{install}}
59 }
60 \nopreamble\nopostamble
61 \generate{
62 \file{README.md}{\from{\jobname.dtx}{readme}}
63 }
64 \ifx\fmtname\nameofplainTeX
65 \expandafter\endbatchfile
66 \else
67 \expandafter\endgroup
68 \fi
69 %</internal>
70 %<package> \NeedsTeXFormat{LaTeX2e}[2021-06-01]
71 %<package> \RequirePackage{expl3, xparse, l3keys2e}[2021-06-01]
72 %<package> \ProvidesExplPackage
73 %<package> {keyparse} % Package name
74 %<package> {2021-08-18} % Release date
75 %<package> {1.1} % Release version
76 %<package> {keyparse --- key-based parser } % Description
77 %<*driver>
78 \documentclass[show-notes]{l3doc}
79 \EnableCrossrefs
80 \CodelineIndex
81 \RecordChanges
82 %^^A\documentclass[full, show-notes]{l3doc}
83 %^^A \listfiles
84 \usepackage{amsmath, bookmark, enumitem, mathtools, microtype, tcolorbox, xparse}
85 \usepackage[french, german, english]{babel}
86 \usepackage[T1]{fontenc}
87 \usepackage[bibencoding=auto, backend=biber, sorting=ynt]{biblatex}
88 \begin{filecontents*}{\jobname.bib}
89 @manual{interface3,
90 title = {The \LaTeX3 interfaces},
91 author = {The \LaTeX3 Project Team},
92 year = {2019},
93 note = {\url{https://ctan.math.washington.edu/tex-archive/macros/latex/contrib/l3kernel/expl3.pdf}},
94 annote = {} }
95 @manual{xparse,
96 title = {The \pkg{xparse} package},
97 author = {The \LaTeX3 Project Team},
98 year = {2019},
99 note = {\url{https://ctan.math.illinois.edu/macros/latex/contrib/l3packages/xparse.pdf}},
100 annote = {} }
101 @misc{a-188053,
102 author = {@{}sean-allred},
103 title = {``How to create lambda expressions?''},
104 year = {2014},
105 note = {\url{https://tex.stackexchange.com/a/188053/112708}}}
106 \end{filecontents*}
107 \addbibresource{\jobname.bib}
108 \ExplSyntaxOn
109 %^^A *** Sectioning
110 \tl_gset:Nn \partname {Part}%^^A allows to test w/o babel
111 \makeatletter
112 \newcommand*{\docsetnameref}
113 {\def\@currentlabelname}%https://tex.stackexchange.com/questions/537751
114 \makeatother
115 \newcounter{cscounter}
116 \ProvideDocumentCommand
117 \DocPhantomSection{sO{subsection}D<>{}mo}
118 {\leavevmode
119 \refstepcounter{cscounter}
120 \IfBooleanF{#1}{\addcontentsline{toc}{#2}{#4}}
121 \IfValueT{#5}
122 {\docsetnameref{#3#4}\label{#5}}}
123 % ^^A *** Msg
124 \msg_new:nnn{__keyparse_doc}{unknown}{~#1:#2~unknown}
125 % ^^A *** Expressions
126 \ProvideDocumentCommand{\pkgpattpair}{mm}{\texttt{>\{#1\}\{#2\}}}
127 \ProvideDocumentCommand{\pkgrule}{}{\texttt{$\rightarrow$}}
128 % ^^A *** L3 package
129 \ProvideDocumentCommand{\docplaceh}{mO{1}}{\texttt{\prg_replicate:nn{#2}{\#}#1}}
130 % ^^A *** Lists
131 \newlist{arab-inl}{enumerate*}{1}
132 \setlist[arab-inl]{label=\arabic*)}
133 \newlist{colon-inl}{itemize*}{1}
134 \setlist[colon-inl]
135 { %^^Abefore=\noindent,
136 label={},
137 itemjoin={{; }},
138 after={{.}}}
139 \newlist{descr}{description}{1}
140 \setlist[descr]{nosep, align=right, itemindent=0pt, font=\sffamily\tiny}
141 \ExplSyntaxOff
142 %^^A *** listing
143 \tcbuselibrary{listings, breakable}
144 \newtcblisting[auto counter]
145 {listing}[2][]{
146 noparskip,
147 breakable,
148 colback=white,
149 colframe=black,
150 opacitybacktitle=.8,%
151 fonttitle=\bfseries,
152 title={Listing~\thetcbcounter. #1},
153 arc=0pt,
154 outer arc=0pt,
155 boxrule=1pt,
156 listing and text,
157 #2}
158 \newtcblisting
159 {internal}
160 {text only,
161 breakable,
162 colback=white,
163 fontupper=\sffamily,
164 arc=1pt,
165 outer arc=1pt,
166 boxrule=0pt,
167 halign=left,
168 fontupper=\small\sffamily,
169 left=0pt,
170 top=0pt,
171 bottom=0pt}
172 \usepackage{keyparse}
173 \usepackage{hyperref} %^^A comes last
174 \begin{document}
175 \DocInput{\jobname.dtx}
176 \end{document}
177 %</driver>
178 % \fi
179 %
180 % \GetFileInfo{\jobname.sty}
181 % \title{The \pkg{keyparse} package\thanks{^^A
182 % This file describes version \fileversion, last revised \filedate.^^A
183 % }^^A
184 % }
185 % \author{Erwann Rogard\thanks{first.lastname at gmail.com}}
186 %
187 % \date{Released \filedate}
188 % \begin{documentation}
189 %
190 % \maketitle
191 %
192 % \begin{abstract}
193 % This \LaTeX package provides an interface to define and evaluate key-based replacement rules\cite{interface3}.
194 % It can be used to parse the argument specification of a document command\cite{xparse}.
195 % \end{abstract}
196 %
197 % \tableofcontents
198 %
199 % \part{Usage}\label{part:usage}
200 %
201 % \section{Document command}
202 % \begin{function}{KeyparseKeys}
203 % \begin{syntax}
204 % \cs{KeyparseKeys}\Arg{rule}
205 % \end{syntax}
206 % \begin{descr}
207 % \item[Expands~to] The keys associated with \meta{rule}
208 % \end{descr}
209 % \end{function}
210 %
211 % \begin{function}{KeyparseEval}
212 % \begin{syntax}
213 % \cs{KeyparseEval}
214 % \end{syntax}
215 % \begin{descr}
216 % \item[Adapts] \nameref{cs:keyparse:eval}
217 % \end{descr}
218 % \end{function}
219 %
220 % \section{Programming}
221 % \DocPhantomSection*{\cs{keyparse_set:nnnnn}}[cs:keyparse:rule]
222 % \begin{function}{\keyparse_set:nnnnn}
223 % \begin{syntax}
224 % \cs{keyparse_set:nnnnn}\Arg{rule}\Arg{key}\Arg{signature}\Arg{replacement}\Arg{recurse}
225 % \end{syntax}
226 % \begin{descr}
227 % \item[Requires]
228 % \begin{colon-inl}
229 % \item \meta{rule} is a token~list
230 % \item \meta{key}\meta{signature} is a valid \enquote{weird} argument specifier\cite[Naming functions and variables]{interface3}
231 % \item \meta{replacement} and \meta{recurse} are in terms of \meta{signature}
232 % \end{colon-inl}
233 % \item[Semantics] As shown under {\sffamily\tiny{}Expands~to} for \nameref{cs:keyparse:eval}
234 % \item[Tip] Using |{|\meta{token}|}| as \meta{replacement}, one can iterate over the result of \nameref{cs:keyparse:eval} using \cs[no-index]{tl_map_function:nN}.
235 % Using \meta{token}, instead, merges the \meta{tokens}'s.
236 % \end{descr}
237 % \end{function}
238 %
239 % \DocPhantomSection*{\cs{keyparse_eval:nn}}[cs:keyparse:eval]
240 % \begin{function}[EXP]{\keyparse_eval:nn}
241 % \begin{syntax}
242 % \cs{keyparse_eval:nn}\Arg{rule}|{|\meta{key}\meta{args}|}|
243 % \end{syntax}
244 % \end{function}
245 % \begin{descr}
246 % \item[Requires] \meta{args} is compatible with \meta{signature} for that \meta{rule} and \meta{key}
247 % \item[Expands~to] \meta{replacement}\nameref{cs:keyparse:eval}\Arg{rule}\Arg{recurse}
248 % \end{descr}
249 %
250 % \subsection*{Other}
251 % \begin{function}[EXP]{\keyparse_argspec_e:n}
252 % \cs{keyparse_argspec_e:n}\Arg{token list}
253 % \end{function}
254 %
255 % \section{Rule}
256 % Hereafter are rules defined with \nameref{cs:keyparse:rule}.
257 %
258 % \DocPhantomSection{\textsf{argspec}}[keyparse:argspec]
259 % \DescribeEnv{argspec}
260 % \begin{descr}
261 % \item[Keys] \KeyparseKeys{argspec}
262 % \item[Requires] \meta{key_i}\meta{arg_i} is a valid document-command argument specifier\cite{xparse}
263 % \item[Rule i] \meta{key_i}\meta{arg_i}\pkgrule|{|\meta{key_i}\meta{arg_i}|}|
264 % \end{descr}
265 %
266 % \DocPhantomSection{\textsf{pair/first}}[keyparse:pair:first]
267 % \DescribeEnv{pair/first}
268 % \begin{descr}
269 % \item[Keys] \KeyparseKeys{pair/first}
270 % \item[Rule 1] \pkgpattpair{\meta{first}}{\meta{second}}\pkgrule\meta{first}
271 % \end{descr}
272 %
273 % \DocPhantomSection{\textsf{pair/merge}}[keyparse:pair:merge]
274 % \DescribeEnv{pair/merge}
275 % \begin{descr}
276 % \item[Keys] \KeyparseKeys{pair/merge}
277 % \item[Rule 1] \pkgpattpair{\meta{first}}{\meta{second}}\pkgrule\meta{first}\meta{second}
278 % \end{descr}
279 %
280 % \clearpage
281 % \part{Listing}\label{part:listing}
282 % \addcontentsline{toc}{subsection}
283 % {\ref{listing:keyparse:plain}.
284 % Making rules for \texttt{\&}, \texttt{>\{.\}}, and \texttt{+.+}}
285 % \iffalse
286 %<*guardlisting>
287 % \fi
288 \begin{listing}
289 [Making rules for \texttt{\&}, \texttt{>\{.\}}, and \texttt{+.+}]
290 {label=listing:keyparse:plain}
291 \ExplSyntaxOn
292 \group_begin:
293 \keyparse_set:nnnnn{foo}{&}{#1}{{&}}{#1}
294 \keyparse_set:nnnnn{foo}{>}{#1#2}{{#1}}{#2}
295 \keyparse_set:nnnnn{foo}{+}{#1+#2}{{#1}}{#2}
296 \exp_args:Nx
297 \tl_map_inline:nn
298 {\keyparse_eval:nn{foo}{&>{123}+xyz+}}
299 {\texttt{(\tl_to_str:n{#1})}}
300 \group_end:
301 \ExplSyntaxOff
302 \end{listing}
303 % \iffalse
304 %</guardlisting>
305 % \fi
306 %
307 % \addcontentsline{toc}{subsection}
308 % {\ref{listing:keyparse:leslie}. Embedding `\LaTeX' in \enquote{Leslie Lamport built \dots}}
309 % \iffalse
310 %<*guardlisting>
311 % \fi
312 \begin{listing}
313 [Embedding `\LaTeX' in \enquote{Leslie Lamport built \dots}]
314 {label=listing:keyparse:leslie}
315 \begingroup
316 \KeyparseEval{pair/first}
317 {>{}{Leslie~}
318 >{La}{mport~built~LaTeX~on~top~of~Donald~Knuth's~}
319 >{TeX}{.}}
320 \endgroup
321 \end{listing}
322 % \iffalse
323 %</guardlisting>
324 % \fi
325 %
326 % \addcontentsline{toc}{subsection}
327 % {\ref{listing:keyparse:argspec}. \nameref{keyparse:argspec}.}
328 % \iffalse
329 %<*guardlisting>
330 % \fi
331 \begin{listing}
332 [\nameref{keyparse:argspec}]
333 {label=listing:keyparse:argspec}
334 \ExplSyntaxOn
335 \group_begin:
336 \tl_set:Nx\l_tmpa_tl
337 {\keyparse_eval:nn{argspec}{msotae{_^}r<]d[>}}
338 \exp_args:Nx
339 \tl_map_inline:Nn
340 \l_tmpa_tl
341 {\texttt{(\tl_to_str:n{#1})}}
342 \group_end:
343 \ExplSyntaxOff
344 \end{listing}
345 % \iffalse
346 %</guardlisting>
347 % \fi
348 %
349 % \section{Support}\label{other:support}
350 %
351 % This package is available from \url{https://github.com/rogard/keyparse}.
352 %
353 % \changes{Version 1.0}
354 % {2020/08/03}
355 % {Initial version}
356 % \changes{Version 1.1}
357 % {2020/08/18}
358 % {Name change from lex to keyparse at request of ctan}
359 %
360 % \StopEventually{
361 % \clearpage
362 % \PrintChanges
363 % ^^A \PrintIndex % https://tex.stackexchange.com/q/610349/112708
364 % }
365 %\end{documentation}
366 % \begin{implementation}
367 % \part{Implementation}\label{part:impl}
368 % \begin{macrocode}
369 %<*package>
370 %<@@=keyparse>
371 \ExplSyntaxOn
372 % \end{macrocode}
373 % \section{\textsf{keyparse}}
374 % \subsection{Interface}
375 % \begin{macro}[int]
376 % {not-set}
377 % \begin{macrocode}
378 \msg_new:nnn
379 {@@}
380 {not-set}
381 {recursion~for~rule~#1~is~not~set}
382 % \end{macrocode}
383 % \end{macro}
384 % \begin{macro}
385 % {\@@_keyparse_rule_w:n,
386 % \@@_keyparse_rule:n,
387 % \@@_keyparse_eval_aux:nn,
388 % \@@_keyparse_eval_aux:ne}
389 % \begin{arguments}
390 % \item rule
391 % \end{arguments}
392 % \begin{macrocode}
393 \cs_new_protected:Nn
394 \@@_keyparse_rule_w:n
395 {\clist_clear_new:c{@@_keys_#1_clist}
396 \cs_new:cpn
397 {@@_keyparse_eval_#1:w} ##1 ##2 \q_recursion_stop
398 {\quark_if_recursion_tail_stop:n{##1}
399 \use:c{@@_keyparse_eval_#1_##1:w}##2\q_recursion_stop }}
400 \cs_new_protected:Nn
401 \@@_keyparse_rule:n{\@@_keyparse_rule_w:n{#1}}
402 \cs_new:Nn
403 \@@_keyparse_eval_aux:nn
404 {\cs_if_exist:cTF
405 {@@_keyparse_eval_#1:w}
406 { \use:c{@@_keyparse_eval_#1:w}#2
407 \q_recursion_tail
408 \q_recursion_stop}
409 {\msg_error:nnn{@@}
410 {not-set}
411 {#1}}}
412 \cs_generate_variant:Nn\@@_keyparse_eval_aux:nn{ne}
413 % \end{macrocode}
414 % \end{macro}
415 % \begin{macro}
416 % {\keyparse_eval:nn,
417 % \keyparse_set:nnnnn}
418 % \begin{macrocode}
419 \cs_new:Nn
420 \keyparse_eval:nn
421 {\@@_keyparse_eval_aux:ne{#1}
422 {\tl_trim_spaces:n{#2}}}
423 \cs_new_protected:Nn
424 \keyparse_set:nnnnn
425 {\cs_if_exist:cTF
426 {@@_keyparse_eval_#1:w}
427 {\clist_put_right:cn
428 {@@_keys_#1_clist}{\texttt{\tl_to_str:n{#2}}}
429 \cs_new:cpn
430 {@@_keyparse_eval_#1_#2:w}#3 \q_recursion_stop
431 {#4\use:c{@@_keyparse_eval_#1:w}#5 \q_recursion_stop}}
432 {\@@_keyparse_rule:n{#1}
433 \keyparse_set:nnnnn
434 {#1}{#2}{#3}{#4}{#5}}}
435 % \end{macrocode}
436 % \end{macro}
437 % \begin{macro}{\KeyparseKeys, \KeyparseEval}
438 % \begin{macrocode}
439 \ProvideDocumentCommand
440 {\KeyparseKeys}
441 {m}
442 {\clist_use:cnnn
443 {@@_keys_#1_clist}
444 {~and~}{,~}{~and~}}
445 \NewDocumentCommand{\KeyparseEval}
446 {mm}
447 {\keyparse_eval:nn{#1}{#2}}
448 % \end{macrocode}
449 % \end{macro}
450 % \subsection{\textsf{argspec}}\label{impl:argspec}
451 % \begin{macro}
452 % {\keyparse_argspec_e:n}
453 % \begin{macrocode}
454 \cs_new:Nn\keyparse_argspec_e:n{{e{#1}}}
455 % \end{macrocode}
456 % \end{macro}
457 % \begin{macro}[int]
458 % {argspec}
459 % Expandability forbids inline, hence \cs{keyparse_argspec_e:n} for key `e'
460 % \begin{macrocode}
461 \keyparse_set:nnnnn{argspec}{e}{#1#2}
462 { \tl_map_function:nN{#1}\keyparse_argspec_e:n}{#2}
463 \keyparse_set:nnnnn{argspec}{d}{#1#2#3}{{d#1#2}}{#3}
464 \keyparse_set:nnnnn{argspec}{m}{#1}{{m}}{#1}
465 \keyparse_set:nnnnn{argspec}{o}{#1}{{o}}{#1}
466 \keyparse_set:nnnnn{argspec}{r}{#1#2#3}{{r#1#2}}{#3}
467 \keyparse_set:nnnnn{argspec}{s}{#1}{{s}}{#1}
468 \keyparse_set:nnnnn{argspec}{t}{#1#2}{{t#1}}{#2}
469 % \end{macrocode}
470 % \end{macro}
471 % \subsection{\textsf{pair}}\label{impl:pair}
472 % \begin{macro}[int]
473 % {pair/first,
474 % pair/merge}
475 % \begin{macrocode}
476 \keyparse_set:nnnnn{pair/first}{>}{#1#2#3}{#1}{#3}
477 \keyparse_set:nnnnn{pair/merge}{>}{#1#2#3}{#1#2}{#3}
478 % \end{macrocode}
479 % \end{macro}
480 % \begin{macrocode}
481 \ExplSyntaxOff
482 %</package>
483 % \end{macrocode}
484 % \end{implementation}
485 % \Finale
486 \endinput