summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/naive-ebnf/naive-ebnf.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/naive-ebnf/naive-ebnf.dtx')
-rw-r--r--macros/latex/contrib/naive-ebnf/naive-ebnf.dtx283
1 files changed, 283 insertions, 0 deletions
diff --git a/macros/latex/contrib/naive-ebnf/naive-ebnf.dtx b/macros/latex/contrib/naive-ebnf/naive-ebnf.dtx
new file mode 100644
index 0000000000..6213cf6d52
--- /dev/null
+++ b/macros/latex/contrib/naive-ebnf/naive-ebnf.dtx
@@ -0,0 +1,283 @@
+% \iffalse meta-comment
+% (The MIT License)
+%
+% Copyright (c) 2023 Yegor Bugayenko
+%
+% Permission is hereby granted, free of charge, to any person obtaining a copy
+% of this software and associated documentation files (the 'Software'), to deal
+% in the Software without restriction, including without limitation the rights
+% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+% copies of the Software, and to permit persons to whom the Software is
+% furnished to do so, subject to the following conditions:
+%
+% The above copyright notice and this permission notice shall be included in all
+% copies or substantial portions of the Software.
+%
+% THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+% SOFTWARE.
+% \fi
+
+% \CheckSum{0}
+%
+% \CharacterTable
+% {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
+% 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
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+
+% \GetFileInfo{naive-ebnf.dtx}
+% \DoNotIndex{\endgroup,\begingroup,\let,\else,\s,\n,\r,\\,\1,\fi}
+
+% \iffalse
+%<*driver>
+\ProvidesFile{naive-ebnf.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{naive-ebnf}
+%<*package>
+[2023-01-29 0.0.2 EBNF in Plain Text]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[T1]{fontenc}
+\usepackage[tt=false, type1=true]{libertine}
+\usepackage{microtype}
+\AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
+\usepackage{href-ul}
+\usepackage{xcolor}
+\usepackage[dtx]{docshots}
+\PageIndex
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{naive-ebnf.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+
+% \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}}}
+% \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}}
+% \date{\filedate, \fileversion}
+%
+% \maketitle
+%
+% \section{Introduction}
+%
+% This package helps render a
+% \href{https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form}{Extended Backus-Naur Form}
+% using plain text notation:
+% \begin{docshot}
+% \documentclass{minimal}
+% \usepackage{naive-ebnf}
+% \usepackage{mathtools}
+% \begin{document}
+% \begin{ebnf}
+% <Expr> := <Var>
+% | "$\lambda$" <Var> "." <Expr>
+% | "$\lparen$" <Expr> <Expr> "$\rparen$"
+% \end{ebnf}
+% \end{document}
+% \end{docshot}
+
+% The following syntax is understood inside the |ebnf| environment:
+% \begin{itemize}
+% \item |:=| separates the left-hand side from the right-hand side of the production rule;
+% \item |<...>| denotes a non-terminal (variable);
+% \item |"..."| denotes a terminal symbol;
+% \item \texttt{(...\char`\|...)} denotes a series of options to choose from;
+% \item |[...]| denotes an optional substitution;
+% \item |{...}| denotes a zero or more times repetition;
+% \end{itemize}
+
+% \textbf{Attention}: The usage of some symbols is prohibited inside terminals. Instead, the following substitutions are recommended:
+% \begin{itemize}
+% \item |$\lparen$| and |$\rparen$| instead of ``|(|'' and ``|)|'' (from the \href{https://ctan.org/pkg/mathtools}{mathtools} package);
+% \item |$\langle$| and |$\rangle$| instead of ``|<|'' and ``|>|'';
+% \item |$\lbrace$| and |$\rbrace$| instead of ``|{|'' and ``|}|'' (also |mathtools|);
+% \item |$\lbrack$| and |$\rbrack$| instead of ``|[|'' and ``|]|'' (also |mathtools|);
+% \item |$\vert$| instead of ``\texttt{\char`\|}''.
+% \end{itemize}
+
+% \DescribeMacro{\terminal}
+% \DescribeMacro{\nonterminal}
+% Inside the text, terminals and non-terminals may be formatted using two supplementary commands:
+% \docshotOptions{firstline=6,lastline=10}
+% \begin{docshot}
+% \documentclass{article}
+% \pagestyle{empty}
+% \usepackage[paperwidth=3in]{geometry}
+% \usepackage{naive-ebnf}
+% \begin{document}
+% The non-terminal \nonterminal{Var}
+% in $\lambda$-calculus may be equal
+% to $v_1, v_2, \dots$. Application
+% starts with \terminal{(} and ends
+% with \terminal{)}.
+% \end{document}
+% \end{docshot}
+
+% \section{Package Options}
+
+% It's possible to configure the behavior of the package with the help of a few package options:
+
+% \DescribeMacro{bw}
+% 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:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[bw]{naive-ebnf}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \StopEventually{}
+
+% \section{Implementation}
+% \changes{0.0.1}{2023/01/28}{First draft.}
+% \changes{0.0.2}{2023/01/29}{Proper parsing of grouping.}
+% \changes{0.0.2}{2023/01/29}{Substitutions suggested for special symbols.}
+
+% First, we process package options:
+% \begin{macrocode}
+\RequirePackage{pgfopts}
+\pgfkeys{
+ /ebnf/.cd,
+ bw/.store in=\ebnf@bw,
+}
+\ProcessPgfPackageOptions{/ebnf}
+% \end{macrocode}
+
+% Then, we include a few packages, mostly to deal with \LaTeX{}3 expressions:
+% \begin{macrocode}
+\RequirePackage{filecontentsdef}
+\RequirePackage{expl3}
+% \end{macrocode}
+
+% \begin{macro}{\ebnf@color}
+% Then, we include \href{https://ctan.org/pkg/xcolor}{xcolor} to colorize the output a bit:
+% \begin{macrocode}
+\makeatletter\ifdefined\ebnf@bw\else
+ \RequirePackage{xcolor}
+\fi
+\newcommand\ebnf@color[2]
+ {\ifdefined\ebnf@bw#2\else\textcolor{#1}{#2}\fi}
+\makeatother
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\terminal}
+% \changes{0.0.2}{2023/01/29}{New command \texttt{\char`\\terminal} added, to enable rendering terminal symbols outside of the \texttt{ebnf} environment.}
+% Then, we a command to render a single terminal:
+% \begin{macrocode}
+\makeatletter
+\newcommand\terminal[1]{%
+ \relax\ifmmode\else\ttfamily\fi%
+ \ebnf@color{gray}{"}#1\ebnf@color{gray}{"}}
+\makeatother
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\nonterminal}
+% \changes{0.0.2}{2023/01/29}{New command \texttt{\char`\\nonterminal} added, to enable rendering non-terminal symbols outside of the \texttt{ebnf} environment.}
+% Then, we a command to render a single non-terminal:
+% \begin{macrocode}
+\makeatletter
+\newcommand\nonterminal[1]
+ {\(\ebnf@color{gray}{\langle}\textsf{#1}\ebnf@color{gray}{\rangle}\)}
+\makeatother
+% \end{macrocode}
+% \end{macro}
+
+% Then, we define supplementary commands:
+% \begin{macrocode}
+\makeatletter
+\newcommand\ebnf@optional[1]
+ {\ebnf@color{gray}{[}#1\ebnf@color{gray}{]}}
+\newcommand\ebnf@repetition[1]
+ {\ebnf@color{gray}{\{}#1\ebnf@color{gray}{\}}}
+\newcommand\ebnf@grouping[1]
+ {\ebnf@color{gray}{(}#1\ebnf@color{gray}{)}}
+\ExplSyntaxOn
+\newcommand\ebnf@terminal[1]{
+ \tl_set:Nn \l_ebnf_tl { }
+ \tl_set_rescan:Nno \l_ebnf_tl { } { #1 }
+ \terminal{\l_ebnf_tl}
+}
+\ExplSyntaxOff
+\newcommand\ebnf@to
+ {\ebnf@color{gray}{\(\to\)}}
+\newcommand\ebnf@alternation
+ {\ebnf@color{gray}{\(\vert\)}}
+\newcommand\ebnf@eol{\\}
+\makeatother
+% \end{macrocode}
+
+% \begin{macro}{ebnf}
+% Then, we define the |ebnf| environment:
+% \begin{macrocode}
+\ExplSyntaxOn
+\cs_generate_variant:Nn \tl_replace_all:Nnn {Nx}
+\NewDocumentEnvironment{ebnf}{}{\filecontentsdefmacro\l__ebnf_tmp_tl}{
+ \endfilecontentsdefmacro
+ \str_set:NV \l__ebnf_tmp_tl \l__ebnf_tmp_tl
+ \str_set:Nx \l__ebnf_tmp_tl {\str_range:Nnn \l__ebnf_tmp_tl {1} {-2}}
+ \regex_replace_all:nnN { \{(.+?)\} }
+ {\c{ebnf@repetition}{\1}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { \((.+?)\) }
+ {\c{ebnf@grouping}{\1}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { \[([^\]]+?)\] }
+ {\c{ebnf@optional}{\1}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { <([A-Za-z][a-z-]+)> }
+ {\c{nonterminal}{\1}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { "([^"]+)" }
+ {\c{ebnf@terminal}{\1}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { \^^M\s*\| }
+ {\^^M :=} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { \| }
+ {\c{ebnf@alternation}{}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { \^^M\s*:= }
+ {\^^M \c{-}\c{hspace}{3em}\c{ebnf@alternation}{}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { := }
+ {\c{ebnf@to}{}} \l__ebnf_tmp_tl
+ \regex_replace_all:nnN { \^^M }
+ {\c{ebnf@eol}{}} \l__ebnf_tmp_tl
+ \tl_put_left:Nn \l__ebnf_tmp_tl {}
+ \tl_put_right:Nn \l__ebnf_tmp_tl {}
+ \l__ebnf_tmp_tl
+}
+\ExplSyntaxOff
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macrocode}
+\endinput
+% \end{macrocode}
+
+% \Finale
+
+% \clearpage
+% \clearpage
+
+% \PrintChanges
+% \clearpage
+% \PrintIndex