Debian Codegraph @

texmf-dist/source/latex/conv-xkv/conv-xkv.dtx

raw
1 % \iffalse
2 %<*copyright>
3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4 %% conv-xkv package %%
5 %% Copyright (C) 2016--2017 D. P. Story %%
6 %% [email protected] %%
7 %% %%
8 %% This program can redistributed and/or modified under %%
9 %% the terms of the LaTeX Project Public License %%
10 %% Distributed from CTAN archives in directory %%
11 %% macros/latex/base/lppl.txt; either version 1.2 of the %%
12 %% License, or (at your option) any later version. %%
13 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 %</copyright>
15 %<package>\NeedsTeXFormat{LaTeX2e}
16 %<package>\ProvidesPackage{conv-xkv}
17 %<package> [2017/02/17 v1.1c convert xkeyval format (dps)]
18 %<*driver>
19 \documentclass{ltxdoc}
20 \usepackage[colorlinks,hyperindex=false]{hyperref}
21 \OnlyDescription % comment out for implementation details
22 \EnableCrossrefs
23 \CodelineIndex
24 \RecordChanges
25 \InputIfFileExists{aebdocfmt.def}{\PackageInfo{web}{Inputting aebdocfmt.def}}
26 {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
27 \PackageInfo{web}{aebdocfmt.def cannot be found}}
28 \begin{document}
29 \def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
30 \def\meta#1{\textsl{\texttt{#1}}}
31 \def\darg#1{{\ttfamily\char123\relax#1\char125\relax}}
32 \def\CMD#1{\textbackslash#1}
33 \let\pkg\textsf
34 \let\opt\texttt
35 \GetFileInfo{conv-xkv.sty}
36 \title{\textsf{conv-xkv}: Convert \textsf{xkeyval} format style}
37 \author{D. P. Story\\
38 Email: \texttt{[email protected]}}
39 \date{processed \today}
40 \maketitle
41 \tableofcontents
42 \DocInput{conv-xkv.dtx}
43 \IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here.\\Execute
44 \texttt{makeindex -s gind.ist -o conv-xkv.ind conv-xkv.idx} on the command line and recompile
45 \texttt{conv-xkv.dtx}.}
46 \IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here.\\Execute
47 \texttt{makeindex -s gglo.ist -o conv-xkv.gls conv-xkv.glo} on the command line and recompile
48 \texttt{conv-xkv.dtx}.}
49 \end{document}
50 %</driver>
51 % \fi
52 %
53 % \MakeShortVerb{|}
54 % \DoNotIndex{\w,\x,\y,\z}
55 % \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}}
56 % {\PackageInfo{web}{cannot find aebdonotindex.def}}
57 %
58 % \begin{macrocode}
59 %<*package>
60 % \end{macrocode}
61 % \section{Introduction}
62 % This is a intellectual exercise for creating \emph{alternate key-value} notation. The standard {\LaTeX}
63 % notation is \texttt{\ameta{key}=\ameta{value}}. To change to the JavaScript object style of
64 % key-values (\texttt{\ameta{key}:\ameta{value}}), use \cs{cxkvsetkeys} as you would \cs{setkeys}:
65 %\begin{quote}
66 % \cs{cxkvsetkeys}\darg{\ameta{family}}\darg{\ameta{KV-pairs}}
67 %\end{quote}
68 % to convert \texttt{\ameta{key}:\ameta{value}} to \texttt{\ameta{key}=\ameta{value}} and \pkg{xkeyval} processes the keys as it
69 % normally does. The comma (,) separates sets of key-value pairs and must not, therefore, be used as the delimiter
70 % that separates the \ameta{key} from the \ameta{value}.
71 %
72 % The package is more general than what is described above. You can define several key-value delimiters, for whatever reason,
73 % in your document or package. Declare a \textit{named} delimiter:
74 %\begin{quote}\ttfamily
75 %\cs{DeclareDelimiter}\darg{\ameta{name}}\darg{\ameta{delimiter}}
76 %\end{quote}
77 %Use the newly declared delimited as follows:
78 %\begin{quote}
79 %\cs{cxkvsetkeys(\ameta{name})}\darg{\ameta{family}}\darg{\ameta{KV-pairs}}
80 %\end{quote}
81 %The case of using a colon (:) for the delimiter is already defined, its name is `\texttt{colon}' and need not be declared.
82 %
83 %\paragraph*{Important change in syntax} With version dated 2017/01/03 or later, the optional argument \ameta{name} is now delimited
84 %by \textbf{parentheses}, rather than the standard brackets. This is to be able to detect \ameta{name} when the full syntax
85 %of \cs{setkeys} is used:
86 %\changes{v1.1a}{2017/01/03}{Change in syntax, use parentheses rather than brackets}
87 %\begin{quote}
88 % \cs{setkeys*[\ameta{prefix}]\darg{\ameta{families}}[\ameta{na}]\darg{\ameta{keys}}}
89 %\end{quote}
90 %The syntax for \cs{cxkvsetkeys} shall be
91 %\begin{quote}
92 % \cs{cxkvsetkeys(\ameta{name})*[\ameta{prefix}]\darg{\ameta{families}}[\ameta{na}]\darg{\ameta{keys}}}
93 %\end{quote}
94 % The \pkg{conv-xkv} package does nothing with \pkg{xkeyval} arguments \texttt{*[\ameta{prefix}]} and
95 % \texttt{[\ameta{na}]} other than to collect them and pass them on to \cs{setkeys} at the appropriate time.
96 % The \pkg{conv-xkv} is concerned only with converting a new notation \texttt{\ameta{key}\ameta{delim}\ameta{value}}
97 % to \texttt{\ameta{key}=\ameta{value}}.
98 %
99 % If the key-values do not contain the designated delimiter, \pkg{conv-xkv} simply passes everything on to \cs{setkeys}.
100 % What this means is that, for example, both \cs{cxkvsetkeys\darg{myfam}\darg{fname:Don,lname:Story}} works as does
101 % \cs{cxkvsetkeys\darg{myfam}\darg{fname=Don,lname=Story}}. One then has the option of using the standard notation
102 % or an alternate notation.
103 %
104 %
105 % \paragraph*{Demo file} The example file is \texttt{convert2xkeyval.tex}, use it to explore the possibilities and is found
106 % in the \texttt{examples} folder of this distribution.
107 %
108 % \section{Preliminaries}
109 % We require the \pkg{xkeyval} package.
110 % \changes{v1.0}{2016/12/20}{Date of first upload to CTAN}
111 % \begin{macrocode}
112 \RequirePackage{xkeyval}
113 % \end{macrocode}
114 % The code below is taken from \pkg{hyperref}, and set and restore commands are renamed. This hopefully makes
115 % a number of special characters available to act as a delimiter.
116 % \begin{macrocode}
117 \begingroup
118 \@makeother\`%
119 \@makeother\=%
120 \edef\x{%
121 \edef\noexpand\x{%
122 \endgroup
123 \noexpand\toks@{%
124 \catcode 96=\noexpand\the\catcode`\noexpand\`\relax
125 \catcode 61=\noexpand\the\catcode`\noexpand\=\relax
126 }%
127 }%
128 \noexpand\x
129 }%
130 \x
131 \@makeother\`
132 \@makeother\=
133 \def\ckv@SetCatcodes{%
134 \@makeother\`%
135 \@makeother\=%
136 \@makeother\~%
137 \catcode`\$=3 %
138 \catcode`\&=4 %
139 \catcode`\^=7 %
140 \catcode`\_=8 %
141 \@makeother\|%
142 \@makeother\:%
143 \@makeother\(%
144 \@makeother\)%
145 \@makeother\[%
146 \@makeother\]%
147 \@makeother\/%
148 \@makeother\!%
149 \@makeother\<%
150 \@makeother\>%
151 \@makeother\.%
152 \@makeother\;%
153 \@makeother\+%
154 \@makeother\-%
155 \@makeother\"%
156 \@makeother\'%
157 }
158 \begingroup
159 \def\x#1{\catcode`\noexpand#1=\the\catcode`#1\relax}%
160 \xdef\ckv@RestoreCatcodes{%
161 \the\toks@
162 \x\~%
163 \x\$%
164 \x\&%
165 \x\^%
166 \x\_%
167 \x\|%
168 \x\:%
169 \x\(%
170 \x\)%
171 \x\[%
172 \x\]%
173 \x\/%
174 \x\!%
175 \x\<%
176 \x\>%
177 \x\.%
178 \x\;%
179 \x\+%
180 \x\-%
181 \x\"%
182 \x\'%
183 }%
184 \endgroup
185 \ckv@SetCatcodes
186 % \end{macrocode}
187 % \section{Core commands for this package}
188 % The default delimiter is the colon (:).
189 % \begin{macrocode}
190 \def\csarg#1#2{\expandafter#1\csname#2\endcsname}
191 \csarg\def{kvdelim-colon}{:}
192 % \end{macrocode}
193 % Use \DescribeMacro{\usekvdelim}\cs{usekvdelim} to display delimiter, as associated with
194 % the argument \texttt{\#1}.
195 % \begin{macrocode}
196 \def\usekvdelim#1{\@nameuse{kvdelim-#1}}
197 % \end{macrocode}
198 % \begin{macro}{\DeclareDelimiter}
199 % In the preamble, we declare the delimiter to be used. The command takes one argument, which
200 % is the delimiter to be used, for example `\texttt{:}' or `\texttt{->}'. If this declaration
201 % does not appear in the preamble, the delimiter is taken to be `\texttt{:}'.
202 % \begin{macrocode}
203 \def\DeclareDelimiter{\ckv@SetCatcodes\DeclareDelimiter@i}
204 \def\DeclareDelimiter@i#1#2{\@ifundefined{kvdelim-#1}
205 {\csarg\def{kvdelim-#1}{#2}\ckv@RestoreCatcodes\cxkvSetup{#1}}
206 {\ckv@RestoreCatcodes}}
207 \@onlypreamble\DeclareDelimiter
208 % \end{macrocode}
209 % \end{macro}
210 % \cs{cxkv@tmptoks} is used to hold the converted key-values, the contents of
211 % this token register is passed to \cs{setkeys} in \cs{cxkv@cnvrtDelimniiEquali}
212 % \begin{macrocode}
213 \newtoks\cxkv@tmptoks \cxkv@tmptoks={}
214 \def\cxkv@dummy{dummy}
215 \def\cxkv@dummyc{dummy,}
216 \bgroup
217 \catcode`\#=12\relax\gdef\cxkvarg{#}
218 \obeyspaces\gdef\cxkv@TAB{ }
219 \egroup
220 % \end{macrocode}
221 % \begin{macro}{\cxkvsetkeys}
222 % This is the default definition, setup for using the colon (:) as the key-value
223 % delimiter. But these next two commands are redefined by the
224 % \cs{DeclareDelimiter} command in the preamble. The syntax is
225 %\begin{quote}
226 %\cs{cxkvsetkeys[\ameta{name}]}\darg{\ameta{family}}\darg{\ameta{KV-pairs}}
227 %\end{quote}
228 %where \ameta{KV-pairs} are the key-value pairs using the declared delimiter.
229 %\begin{quote}\ttfamily
230 %\cs{cxkvsetkeys}\darg{myfam}\{fname:\,Fred,lname:\,Flintstone\}
231 %\end{quote}
232 %The family \texttt{myfam} and keys \texttt{fname} and \texttt{lname} must have been defined
233 %earlier: If the optional argument is not specified, then it is assumed the \ameta{name} argument
234 %is \texttt{colon}, a reserved word for this package for this argument.
235 %\begin{verbatim}
236 % \define@key{myfam}{\def\fname{#1}}
237 % \define@key{myfam}{\def\lname{#1}}
238 %\end{verbatim}
239 % \begin{macrocode}
240 \def\cxkv@colon{colon}
241 % \end{macrocode}
242 % The general form for \cs{setkeys} is
243 %\begin{quote}
244 % \cs{setkeys*[\ameta{prefix}]\darg{\ameta{families}}[\ameta{na}]\darg{\ameta{keys}}}
245 %\end{quote}
246 % \begin{macro}{\cxkvsetkeys}
247 %The syntax for \cs{cxkvsetkeys} shall be
248 %\begin{quote}
249 % \cs{cxkvsetkeys(\ameta{name})*[\ameta{prefix}]\darg{\ameta{families}}[\ameta{na}]\darg{\ameta{keys}}}
250 %\end{quote}
251 %The process to pick up the full parameter set of \cs{setkeys} is lengthy.
252 % \begin{macrocode}
253 \newcommand\cxkvsetkeys{%
254 \@ifnextchar({\cxkvsetkeys@i}{\cxkvsetkeys@i(colon)}}
255 \def\cxkvsetkeys@i(#1){\cxkvsetkeys@ii{#1}}
256 \def\cxkvsetkeys@ii#1{\def\cxkv@delimname{#1}\@ifstar
257 {\def\cxkv@skOpts{*}\cxkvsetkeys@iii}
258 {\def\cxkv@skOpts{}\cxkvsetkeys@iii}}
259 \newcommand\cxkvsetkeys@iii[2][]{\def\@rgi{#1}\ifx\@rgi\@empty
260 \expandafter\def\expandafter\cxkv@skOpts
261 \expandafter{\cxkv@skOpts{#2}}\else
262 \expandafter\def\expandafter
263 \cxkv@skOpts\expandafter{\cxkv@skOpts[#1]{#2}}\fi
264 \def\thisxkvF@mily{#2}\cxkvsetkeys@iv}
265 \newcommand\cxkvsetkeys@iv[2][]{\def\@rgi{#1}\ifx\@rgi\@empty\else
266 \expandafter\def\expandafter\cxkv@skOpts
267 \expandafter{\cxkv@skOpts[#1]}\fi
268 \expandafter\cxkvsetkeys@v\expandafter{\thisxkvF@mily}{#2}}
269 \def\cxkvsetkeys@v#1#2{\cxkv@skipfalse
270 \ifx\cxkv@delimname\cxkv@colon\else
271 \InputIfFileExists{xkv-\[email protected]}
272 {\PackageInfo{conv-xkv}{Inputting xkv-\[email protected]}}
273 {\PackageInfo{conv-xkv}{Cannot find xkv-\[email protected]}}\fi
274 \@nameuse{cxkvsetkeys-\cxkv@delimname}{#1}{#2}}
275 % \end{macrocode}
276 % \end{macro}
277 % \begin{macrocode}
278 \csarg\def{cxkvsetkeys-colon}#1#2{%
279 \def\thisxkvF@mily{#1}\def\thisxkvV@lues{#2}\def\cxkv@scratch{}%
280 \cxkv@tmptoks={}%
281 \@nameuse{cxkv@cnvrtDelimniiEqual-colon}#2,dummy:dummy,\@nil}
282 \csarg\def{cxkv@cnvrtDelimniiEqual-colon}#1:#2,#3\@nil{%
283 \cxkv@cnvrtDelimniiEquali{colon}{#1}{#2}{#3}}
284 % \end{macrocode}
285 % \end{macro}
286 % \begin{macro}{\cxkvSetup}
287 % Write the definitions of \cs{cxkvsetkeys} and \cs{cxkv@cnvrtDelimniiEqual} to
288 % the file \texttt{conv-xkv.cut} then input this file back in.
289 % \begin{macrocode}
290 \def\cxkvSetup#1{\bgroup
291 \IfFileExists{xkv-#1.cut}{\PackageInfo{conv-xkv}{xkv-#1.cut
292 already exists,\MessageBreak will not create another one}}{%
293 \PackageInfo{conv-xkv}{Creating the file xkv-#1.cut
294 containing\MessageBreak required definitions}%
295 \newwrite \cxkv@write
296 \uccode`c=`\%
297 \def\w{#1}\def\x{cxkvsetkeys-#1}%
298 \def\y{cxkv@cnvrtDelimniiEqual-#1}%
299 \def\z{kvdelim-#1}%
300 \immediate\openout \cxkv@write xkv-#1.cut
301 \immediate\write\cxkv@write{\string\makeatletter}%
302 \uppercase{\immediate\write\cxkv@write{\string
303 \csarg\string\def{\y}\cxkvarg1\@nameuse{\z}%
304 \cxkvarg2,\cxkvarg3\string\@nil{c^^J\cxkv@TAB
305 \string\cxkv@cnvrtDelimniiEquali{\w}{\cxkvarg1}%
306 {\cxkvarg2}{\cxkvarg3}}}}
307 \uppercase{\immediate\write\cxkv@write{\string\csarg\string\def
308 {\x}\cxkvarg1\cxkvarg2{c^^J\cxkv@TAB
309 \string\def\string\thisxkvF@mily{\cxkvarg1}\string
310 \def\string\thisxkvV@lues{\cxkvarg2}\string
311 \let\string\cxkv@scratch\string\@empty\string
312 \cxkv@tmptoks={}c^^J\cxkv@TAB
313 \string\@nameuse{\y}\cxkvarg2,%
314 \cxkv@dummy\@nameuse{\z}\cxkv@dummy,\string\@nil}}}
315 \immediate\write\cxkv@write{\string\makeatother}%
316 \immediate\closeout \cxkv@write
317 }%
318 \egroup}
319 % \end{macrocode}
320 % \end{macro}
321 % \cs{cxkv@cnvrtDelimniiEquali} continues \cs{cxkv@cnvrtDelimniiEqual}. It is
322 % the part that does not need to be redefined.
323 % \begin{macrocode}
324 \newif\ifcxkv@keyonly \cxkv@keyonlyfalse
325 \def\cxkv@comma{,}
326 \def\cxkv@removecomma#1,\@nil{\def\cxkv@key{#1}}
327 \def\cxkv@parsecomma#1,#2\@nil{\def\@rgi{#1}\def\@rgii{#2}%
328 \ifx\@rgii\@empty\cxkv@keyonlyfalse\else
329 \cxkv@keyonlytrue\cxkv@removecomma#2\@nil\fi}
330 \newif\ifcxkv@skip \cxkv@skipfalse
331 \def\cxkv@cnvrtDelimniiEquali#1#2#3#4{%
332 \def\cxkv@rgiii{#3}\def\cxkv@rgiv{#4}%
333 % \end{macrocode}
334 % If the fourth argument is empty, that means there were no delimiters in the argument,
335 % so we pass the original argument \cs{thisxkvF@mily} to \cs{setkeys}.
336 % \changes{v1.1}{2017/01/03}{Try to detect if the expected delimiter is present at all}
337 % \begin{macrocode}
338 \ifx\thisxkvV@lues\@empty\else
339 \ifx\cxkv@rgiv\@empty
340 \edef\cxkv@next{\noexpand
341 \setkeys\cxkv@skOpts{\thisxkvV@lues}}%
342 \cxkv@skiptrue
343 \fi
344 \fi
345 \let\thisxkvV@lues\@empty
346 \ifcxkv@skip\else
347 \ifx\cxkv@rgiii\cxkv@dummy
348 \cxkv@parsecomma#2,\@nil
349 \ifcxkv@keyonly
350 \edef\cxkv@tmp{\the\cxkv@tmptoks,\@rgi}%
351 \cxkv@tmptoks=\expandafter{\cxkv@tmp}%
352 \edef\cxkv@scratch{\the\cxkv@tmptoks}%
353 \edef\cxkv@next{\noexpand
354 \setkeys\cxkv@skOpts{\the\cxkv@tmptoks}}%
355 \else
356 \edef\cxkv@next{\noexpand
357 \setkeys\cxkv@skOpts{\the\cxkv@tmptoks}}%
358 \fi
359 \else
360 \cxkv@parsecomma#2,\@nil
361 \ifcxkv@keyonly
362 \edef\cxkv@tmp{\the\cxkv@tmptoks,\@rgi}%
363 \cxkv@tmptoks=\expandafter{\cxkv@tmp}%
364 \edef\cxkv@scratch{\the\cxkv@tmptoks}%
365 \edef\cxkv@next{\noexpand
366 \@nameuse{cxkv@cnvrtDelimniiEqual-#1}\cxkv@key
367 \@nameuse{kvdelim-#1}#3,#4\noexpand\@nil}
368 \else
369 % \end{macrocode}
370 % (2017/02/17) Enclose \texttt{\#3} in braces
371 % \changes{v1.1c}{2017/02/17}{Enclose \string\texttt{\#3} in braces}
372 % \begin{macrocode}
373 \cxkv@tmptoks=\expandafter{\cxkv@scratch,#2={#3}}%
374 \edef\cxkv@scratch{\the\cxkv@tmptoks}%
375 \def\cxkv@next{%
376 \@nameuse{cxkv@cnvrtDelimniiEqual-#1}#4\@nil}\fi
377 \fi\fi\cxkv@next
378 }
379 \ckv@RestoreCatcodes
380 % \end{macrocode}
381 % \begin{macrocode}
382 %</package>
383 % \end{macrocode}
384 % \Finale
385 \endinput