Debian Codegraph @

texmf-dist/source/latex/naive-ebnf/naive-ebnf.dtx

raw
1 % \iffalse meta-comment
2 % (The MIT License)
3 %
4 % Copyright (c) 2023-2024 Yegor Bugayenko
5 %
6 % Permission is hereby granted, free of charge, to any person obtaining a copy
7 % of this software and associated documentation files (the 'Software'), to deal
8 % in the Software without restriction, including without limitation the rights
9 % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 % copies of the Software, and to permit persons to whom the Software is
11 % furnished to do so, subject to the following conditions:
12 %
13 % The above copyright notice and this permission notice shall be included in all
14 % copies or substantial portions of the Software.
15 %
16 % THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 % IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 % FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 % AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 % LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 % SOFTWARE.
23 % \fi
24
25 % \CheckSum{0}
26 %
27 % \CharacterTable
28 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
29 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
30 % Digits \0\1\2\3\4\5\6\7\8\9
31 % Exclamation \! Double quote \" Hash (number) \#
32 % Dollar \$ Percent \% Ampersand \&
33 % Acute accent \' Left paren \( Right paren \)
34 % Asterisk \* Plus \+ Comma \,
35 % Minus \- Point \. Solidus \/
36 % Colon \: Semicolon \; Less than \<
37 % Equals \= Greater than \> Question mark \?
38 % Commercial at \@ Left bracket \[ Backslash \\
39 % Right bracket \] Circumflex \^ Underscore \_
40 % Grave accent \` Left brace \{ Vertical bar \|
41 % Right brace \} Tilde \~}
42
43 % \GetFileInfo{naive-ebnf.dtx}
44 % \DoNotIndex{\endgroup,\begingroup,\let,\else,\s,\n,\r,\\,\1,\fi}
45
46 % \iffalse
47 %<*driver>
48 \ProvidesFile{naive-ebnf.dtx}
49 %</driver>
50 %<package>\NeedsTeXFormat{LaTeX2e}
51 %<package>\ProvidesPackage{naive-ebnf}
52 %<*package>
53 [2024/11/13 0.0.18 EBNF in Plain Text]
54 %</package>
55 %<*driver>
56 \documentclass{ltxdoc}
57 \usepackage[T1]{fontenc}
58 \usepackage[tt=false, type1=true]{libertine}
59 \usepackage{microtype}
60 \AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
61 \usepackage{href-ul}
62 \usepackage{xcolor}
63 \usepackage[dtx]{docshots}
64 \PageIndex
65 \EnableCrossrefs
66 \CodelineIndex
67 \RecordChanges
68 \begin{document}
69 \DocInput{naive-ebnf.dtx}
70 \PrintChanges
71 \PrintIndex
72 \end{document}
73 %</driver>
74 % \fi
75
76 % \title{|naive-ebnf|: \LaTeX{} Package \\ for EBNF in Plain Text\thanks{The sources are in GitHub at \href{https://github.com/yegor256/naive-ebnf}{yegor256/naive-ebnf}}}
77 % \author{Yegor Bugayenko \\ \texttt{[email protected]}}
78 % \date{\filedate, \fileversion}
79 %
80 % \maketitle
81 %
82 % \textbf{\color{red}NB!}
83 % Large ENBF snippets may take too long to render!
84 %
85 % \section{Introduction}
86 %
87 % This package helps render an
88 % \href{https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form}{Extended Backus-Naur Form}
89 % using plain text notation:
90 % \begin{docshot}
91 % \documentclass{minimal}
92 % \usepackage{naive-ebnf}
93 % \usepackage{mathtools}
94 % \begin{document}
95 % \begin{ebnf}
96 % <$\lambda$-Expr> := <Var> \\
97 % || "$\lambda$" <Var> "." <Expr> \\
98 % || "\char`\(" <Expr> <Expr> "\char`\)"
99 % \end{ebnf}
100 % \end{document}
101 % \end{docshot}
102
103 % \DescribeMacro{ebnf}
104 % The |ebnf| environment \emph{doesn't} add any formatting to the paragraph, but only replaces the plain text symbols, such as ``|:=|'' and ``|<Var>|'' with proper \LaTeX{} commands.
105 % The following syntax is understood inside the |ebnf| environment:
106 % \begin{itemize}
107 % \item |:=| separates the left-hand side from the right-hand side of the production rule;
108 % \item |<...>| denotes a non-terminal (variable);
109 % \item |"..."| denotes a terminal symbol;
110 % \item |'...'| denotes a special non-printable terminal symbol, like |'EOL'|;
111 % \item \texttt{(...\char`\|...)} denotes a series of options to choose from;
112 % \item |/.../| denotes a regular expression, like |/[a-z]+/|;
113 % \item |[...]| denotes an optional substitution;
114 % \item |{...}| denotes a zero or more times repetition;
115 % \item |{...}+| denotes one or more times repetition;
116 % \item \texttt{\char`\|\char`\|\char`\|} denotes an indent at the beginning of the string.
117 % \item \texttt{\char`\|\char`\|} denotes an indented vertical bar at the beginning of the string.
118 % \end{itemize}
119
120 % \textbf{Attention}: The usage of some symbols is prohibited inside terminals. Instead, the following substitutions are recommended:
121 % \begin{itemize}
122 % \item |$\lparen$| and |$\rparen$| instead of ``|(|'' and ``|)|'' (from the \href{https://ctan.org/pkg/mathtools}{mathtools} package);
123 % \item |$\langle$| and |$\rangle$| instead of ``|<|'' and ``|>|'';
124 % \item |$\lbrace$| and |$\rbrace$| instead of ``|{|'' and ``|}|'' (also |mathtools|);
125 % \item |$\lbrack$| and |$\rbrack$| instead of ``|[|'' and ``|]|'' (also |mathtools|);
126 % \item |$\vert$| instead of ``\texttt{\char`\|}''.
127 % \end{itemize}
128
129 % They would look even better, if the following notation is used:
130 % \begin{itemize}
131 % \item |\char`\(| and |\char`\)| instead of ``|(|'' and ``|)|'';
132 % \item |\char`\<| and |\char`\>| instead of ``|<|'' and ``|>|'';
133 % \item |\char`\{| and |\char`\}| instead of ``|{|'' and ``|}|'';
134 % \item |\char`\[| and |\char`\]| instead of ``|[|'' and ``|]|''.
135 % \end{itemize}
136
137 % \DescribeMacro{width}
138 % There is an optional argument of |ebnf| environment, which sets the width of the left-hand side of each rule
139 % (the default width is |6em|):
140 % \docshotOptions{firstline=4,lastline=10}
141 % \begin{docshot}
142 % \documentclass{minimal}
143 % \usepackage{naive-ebnf}
144 % \begin{document}\noindent
145 % This EBNF has a larger width of \\
146 % the left hand side than usual: \par
147 % \begin{ebnf}[1.5in]
148 % <VeryLongVariable> := <X> | <Y> \\
149 % <X> := "X" 'EOL' \\
150 % <Y> := "Y" \\
151 % \end{ebnf}
152 % \end{document}
153 % \end{docshot}
154
155 % \DescribeMacro{\EbnfTerminal}
156 % \DescribeMacro{\EbnfNonTerminal}
157 % \DescribeMacro{\EbnfSpecial}
158 % Inside the text, terminals, non-terminals, and special terminals may be formatted using three supplementary commands:
159 % \docshotOptions{firstline=6,lastline=10}
160 % \begin{docshot}
161 % \documentclass{article}
162 % \pagestyle{empty}
163 % \usepackage[paperwidth=3in]{geometry}
164 % \usepackage{naive-ebnf}
165 % \begin{document}
166 % The non-terminal \EbnfNonTerminal{Var}
167 % in $\lambda$-calculus may be equal
168 % to $v_1, v_2, \dots$. Application
169 % starts with \EbnfTerminal{(} and ends
170 % with \EbnfTerminal{)}.
171 % \end{document}
172 % \end{docshot}
173 % It's possible to use them in math-mode too, for example:
174 % \docshotOptions{firstline=6,lastline=9}
175 % \begin{docshot}
176 % \documentclass{article}
177 % \pagestyle{empty}
178 % \usepackage[paperwidth=3in]{geometry}
179 % \usepackage{naive-ebnf}
180 % \begin{document}
181 % If $\EbnfTerminal{(} f_1
182 % \EbnfNonTerminal{$\lambda$-Var}
183 % \EbnfTerminal{)}$ is always true, then
184 % $f_1$ is a tautology.
185 % \end{document}
186 % \end{docshot}
187
188 % \DescribeMacro{\EbnfRegex}
189 % A regular expression is possible too:
190 % \docshotOptions{firstline=6,lastline=12}
191 % \begin{docshot}
192 % \documentclass{article}
193 % \pagestyle{empty}
194 % \usepackage[paperwidth=4in]{geometry}
195 % \usepackage{naive-ebnf}
196 % \begin{document}
197 % \begin{ebnf}
198 % <data> := <bool> | <integer> | <byte> \\
199 % <bool> := "TRUE" | "FALSE" \\
200 % <integer> := /(+\char`\|-)?[0-9]+/ \\
201 % <byte> := /[0-9a-f]\char`\{2\char`\}/ \\
202 % <number> := /[1-9]+/ /[0-9]+/
203 % \end{ebnf}
204 % \end{document}
205 % \end{docshot}
206
207 % Special symbols are interpreted correctly, if they stay inside quotes:
208 % \docshotOptions{firstline=5,lastline=9}
209 % \begin{docshot}
210 % \documentclass{minimal}
211 % \usepackage[T1]{fontenc}
212 % \usepackage{naive-ebnf}
213 % \begin{document}
214 % \begin{ebnf}
215 % <X> := 'EOL' "'" "|" \\
216 % <Y> := ">" "<" "[" "]" "/" "/" \\
217 % <Z> := "\LaTeX" "\textdollar" \\
218 % \end{ebnf}
219 % \end{document}
220 % \end{docshot}
221
222 % Nested brackets work fine too:
223 % \docshotOptions{firstline=5,lastline=11}
224 % \begin{docshot}
225 % \documentclass{minimal}
226 % \usepackage[T1]{fontenc}
227 % \usepackage{naive-ebnf}
228 % \begin{document}
229 % \begin{ebnf}
230 % % There is no meaning in this:
231 % <x> := ( "x" ( "y" | ( "z" | <z> ) ) ) \\
232 % <y> := [ [ "x1" ] { /[a-z]+/ } ] \\
233 % <z> := { { { <x> }+ <y> } <z> }+ \\
234 % <t> := [ <x> ] [ <y> ] \\
235 % \end{ebnf}
236 % \end{document}
237 % \end{docshot}
238
239
240 % The \texttt{\char`\|\char`\|\char`\|} character allows indenting the text on a new line, allowing breaking long expressions:
241 % \docshotOptions{firstline=5,lastline=11}
242 % \begin{docshot}
243 % \documentclass{minimal}
244 % \usepackage[T1]{fontenc}
245 % \usepackage{naive-ebnf}
246 % \begin{document}
247 % \begin{ebnf}
248 % <x> := "beginning" \\
249 % ||| ( <y> | <z> ) \\
250 % ||| "ending" \\
251 % \end{ebnf}
252 % \end{document}
253 % \end{docshot}
254
255 % \section{Package Options}
256
257 % It's possible to configure the behavior of the package with the help of a few package options:
258
259 % \DescribeMacro{bw}
260 % By default, some colors are used in the rendered grammar. However, the |bw| package option disables any colors and makes sure the gammar is black-and-white:
261 %\iffalse
262 %<*verb>
263 %\fi
264 \begin{verbatim}
265 \usepackage[bw]{naive-ebnf}
266 \end{verbatim}
267 %\iffalse
268 %</verb>
269 %\fi
270
271 % \DescribeMacro{trail}
272 % The |ebnf| environment is doing pre-processing of the \TeX{} commands provided and then let \LaTeX{} render them. It may be useful to see the output generated by the pre-processing. The |trail| option (with a file name) asks the package to save the content of the environment after the pre-processing into the file:
273 %\iffalse
274 %<*verb>
275 %\fi
276 \begin{verbatim}
277 \usepackage[trail=log.tex]{naive-ebnf}
278 \end{verbatim}
279 %\iffalse
280 %</verb>
281 %\fi
282
283 % \StopEventually{}
284
285 % \section{Implementation}
286 % \changes{0.0.1}{2023/01/28}{First draft.}
287 % \changes{0.0.2}{2023/01/29}{Proper parsing of grouping.}
288 % \changes{0.0.2}{2023/01/29}{Substitutions suggested for special symbols.}
289 % \changes{0.0.5}{2023/02/04}{New package option \texttt{trail} added, to enable saving of the generated \TeX{} content to a file, for debugging purposes.}
290
291 % First, we process package options:
292 % \begin{macrocode}
293 \RequirePackage{pgfopts}
294 \pgfkeys{
295 /ebnf/.cd,
296 bw/.store in=\ebnf@bw,
297 trail/.store in=\ebnf@trail,
298 trail/.default=naive-ebnf.tmp.tex,
299 }
300 \ProcessPgfPackageOptions{/ebnf}
301 % \end{macrocode}
302
303 % Then, we include a few packages, mostly to deal with \LaTeX{}3 expressions:
304 % \begin{macrocode}
305 \RequirePackage{expl3}
306 % \end{macrocode}
307
308 % \begin{macro}{\ebnf@color}
309 % Then, we include \href{https://ctan.org/pkg/xcolor}{xcolor} to colorize the output a bit:
310 % \begin{macrocode}
311 \makeatletter\ifdefined\ebnf@bw\else
312 \RequirePackage{xcolor}
313 \fi
314 \newcommand\ebnf@color[2]
315 {\ifdefined\ebnf@bw#2\else\textcolor{#1}{#2}\fi}
316 \makeatother
317 % \end{macrocode}
318 % \end{macro}
319
320 % \begin{macro}{\EbnfTerminal}
321 % \changes{0.0.2}{2023/01/29}{New command \texttt{\char`\\EbnfTerminal} added, to enable rendering terminal symbols outside of the \texttt{ebnf} environment.}
322 % \changes{0.0.3}{2023/01/30}{Quotes fixed in both text and math modes.}
323 % Then, we define a command to render a single terminal:
324 % \begin{macrocode}
325 \makeatletter
326 \newcommand\EbnfTerminal[1]{{%
327 \relax\ifmmode\else\ttfamily\fi%
328 \ebnf@color{gray}{\relax\ifmmode\textsf{``}\else{\sffamily``}\fi}%
329 #1%
330 \ebnf@color{gray}{\relax\ifmmode\textsf{''}\else{\sffamily''}\fi}}}
331 \makeatother
332 % \end{macrocode}
333 % \end{macro}
334
335 % \begin{macro}{\EbnfTerminal}
336 % \changes{0.0.2}{2023/01/29}{New command \texttt{\char`\\EbnfNonTerminal} added, to enable rendering non-terminal symbols outside of the \texttt{ebnf} environment.}
337 % Then, we define a command to render a single non-terminal:
338 % \begin{macrocode}
339 \makeatletter
340 \newcommand\EbnfNonTerminal[1]{{%
341 \ebnf@color{gray}{\relax\ifmmode\langle\else\(\langle\)\fi}%
342 \relax\ifmmode\textsf{#1}\else{\sffamily#1}\fi%
343 \ebnf@color{gray}{\relax\ifmmode\rangle\else\(\rangle\)\fi}}}
344 \makeatother
345 % \end{macrocode}
346 % \end{macro}
347
348 % \begin{macro}{\EbnfSpecial}
349 % \changes{0.0.6}{2023/05/27}{New command \texttt{\char`\\EbnfSpecial} added, to enable rendering of special non-printable terminal symbols outside of the \texttt{ebnf} environment.}
350 % Then, we define a command to render a single non-terminal:
351 % \begin{macrocode}
352 \makeatletter
353 \newcommand\EbnfSpecial[1]{{\relax\ifmmode\else\ttfamily\fi#1}}%
354 \makeatother
355 % \end{macrocode}
356 % \end{macro}
357
358 % \begin{macro}{\EbnfRegex}
359 % \changes{0.0.8}{2023/07/11}{New command \texttt{\char`\\EbnfRegex} added, to enable rendering of regular expresions outside of the \texttt{ebnf} environment.}
360 % Then, we define a command to render a regular expression:
361 % \begin{macrocode}
362 \makeatletter
363 \newcommand\EbnfRegex[1]{{\relax\ifmmode\else\ttfamily\fi/#1/}}%
364 \makeatother
365 % \end{macrocode}
366 % \end{macro}
367
368 % Then, we define supplementary commands:
369 % \begin{macrocode}
370 \makeatletter
371 \newcommand\ebnf@optional[1]
372 {\ebnf@color{gray}{[}#1\ebnf@color{gray}{]}}
373 \newcommand\ebnf@repetition[2][]
374 {\ebnf@color{gray}{\{}#2\ebnf@color{gray}{\}\(^{\scriptscriptstyle #1}\)}}
375 \newcommand\ebnf@grouping[1]
376 {\ebnf@color{gray}{(}#1\ebnf@color{gray}{)}}
377 \ExplSyntaxOn
378 \newcommand\ebnf@terminal[1]{
379 \tl_set:Nn \l_ebnf_tl {}
380 \tl_set_rescan:Nnn \l_ebnf_tl {} { #1 }
381 \EbnfTerminal{\l_ebnf_tl}
382 }
383 \newcommand\ebnf@special[1]{
384 \tl_set:Nn \l_ebnf_tl {}
385 \tl_set_rescan:Nnn \l_ebnf_tl {} { #1 }
386 \EbnfSpecial{\l_ebnf_tl}
387 }
388 \newcommand\ebnf@nonterminal[1]{
389 \tl_set:Nn \l_ebnf_tl {}
390 \tl_set_rescan:Nnn \l_ebnf_tl {} { #1 }
391 \EbnfNonTerminal{\l_ebnf_tl}
392 }
393 \newcommand\ebnf@regexp[1]{
394 \tl_set:Nn \l_ebnf_tl {}
395 \tl_set_rescan:Nnn \l_ebnf_tl {} { #1 }
396 \EbnfRegex{\l_ebnf_tl}
397 }
398 \ExplSyntaxOff
399 \newcommand\ebnf@to
400 {\ebnf@color{gray}{\(\to\)}}
401 \newcommand\ebnf@alternation
402 {\ebnf@color{gray}{\(\vert\)}}
403 \makeatother
404 % \end{macrocode}
405
406 % \begin{macro}{ebnf}
407 % \changes{0.0.4}{2023/02/03}{Any symbols are allowed inside \texttt{\char`\\EbnfNonTerminal} commands and inside the \texttt{ebnf} environment, where non-terminals are mentioned.}
408 % \changes{0.0.11}{2023/07/12}{Many bugs fixed in the area of regular expression matching.}
409 % \changes{0.0.14}{2023/08/08}{One-or-more repetition introduced with \texttt{\char`\{...\char`\}+} syntax.}
410 % \changes{0.0.15}{2023/08/11}{The \texttt{iteration} removed, only \texttt{repetition} is left, with the second optional parameter.}
411 % Then, we define the |ebnf| environment:
412 % \begin{macrocode}
413 \ExplSyntaxOn
414 \cs_generate_variant:Nn \tl_replace_all:Nnn {Nx}
415 \makeatletter
416 \NewDocumentEnvironment{ebnf}{O{4em}+b}
417 {\tl_set:Nn\ebnf_tmp{#2}}
418 {%
419 \regex_replace_all:nnN
420 { ([^\s])/([^\s]) } {\1\\slash{}\2} \ebnf_tmp%
421 \regex_replace_all:nnN
422 { ([^\s])< } {\1\\textless{}} \ebnf_tmp%
423 \regex_replace_all:nnN
424 { >([^\s]) } {\\textgreater{}\1} \ebnf_tmp%
425 \regex_replace_all:nnN
426 { ([^\s])'([^\s]) } {\1\\textquotesingle{}\2} \ebnf_tmp%
427 \regex_replace_all:nnN { \|\|\| }%
428 {\c{makebox}[#1][r]{ }} \ebnf_tmp%
429 \regex_replace_all:nnN
430 { ([^\s])\|([^\s]) } {\1\\textbar{}\2} \ebnf_tmp%
431 %
432 \regex_replace_all:nnN
433 { /(.+?)/ }%
434 {\c{ebnf@regexp}{\1}} \ebnf_tmp%
435 \cs_undefine:N\ebnf_curled%
436 \cs_new:Npn\ebnf_curled{%
437 \regex_replace_all:nnNT
438 { \{\s(([^\s]*(\s[^\}\{]|\s(\}|\{)[^\s])?)*)\s\}([\+\*])? }%
439 {\c{ebnf@repetition}[\5]{\1}} \ebnf_tmp \ebnf_curled}%
440 \ebnf_curled%
441 \cs_undefine:N\ebnf_brackets%
442 \cs_new:Npn\ebnf_brackets{%
443 \regex_replace_all:nnNT
444 { \(\s(([^\s]*(\s[^\)\(]|\s(\)|\()[^\s])?)*)\s\) }%
445 {\c{ebnf@grouping}{\1}} \ebnf_tmp \ebnf_brackets}%
446 \ebnf_brackets%
447 \cs_undefine:N\ebnf_squares%
448 \cs_new:Npn\ebnf_squares{%
449 \regex_replace_all:nnNT
450 { \[\s(([^\s]*(\s[^\]\[]|\s(\]|\[)[^\s])?)*)\s\] }%
451 {\c{ebnf@optional}{\1}} \ebnf_tmp \ebnf_squares}%
452 \ebnf_squares%
453 \regex_replace_all:nnN { (<[^>]+?>\s:=) }%
454 {\c{makebox}[#1][r]{\1}} \ebnf_tmp%
455 \regex_replace_all:nnN { <(.+?)> }%
456 {\c{ebnf@nonterminal}{\1}} \ebnf_tmp%
457 \regex_replace_all:nnN { "(.+?)" }%
458 {\c{ebnf@terminal}{\1}} \ebnf_tmp%
459 \regex_replace_all:nnN { '(.+?)' }%
460 {\c{ebnf@special}{\1}} \ebnf_tmp%
461 \regex_replace_all:nnN { \|(\|) }%
462 {\c{makebox}[#1][r]{ \1 }} \ebnf_tmp%
463 \regex_replace_all:nnN { \| }%
464 {\c{ebnf@alternation}{}} \ebnf_tmp%
465 \regex_replace_all:nnN { := }%
466 {\c{ebnf@to}{}} \ebnf_tmp%
467 \tl_put_left:Nn \ebnf_tmp {\noindent}
468 \tl_put_right:Nn \ebnf_tmp {}
469 \ifdefined\ebnf@trail%
470 \newwrite\ebnf@write%
471 \immediate\openout\ebnf@write\ebnf@trail\relax%
472 \immediate\write\ebnf@write{\unexpanded\expandafter{\ebnf_tmp}}%
473 \immediate\closeout\ebnf@write%
474 \message{naive-ebnf:\space pre-processed\space TeX
475 \space saved\space to\space "\ebnf@trail"^^J}%
476 \fi%
477 \ebnf_tmp}
478 \makeatother
479 \ExplSyntaxOff
480 % \end{macrocode}
481 % \end{macro}
482
483 % \begin{macrocode}
484 \endinput
485 % \end{macrocode}
486
487 % \Finale
488
489 % \clearpage
490 % \clearpage
491
492 % \PrintChanges
493 % \clearpage
494 % \PrintIndex