summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/piton/piton.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2024-04-30 03:01:32 +0000
committerNorbert Preining <norbert@preining.info>2024-04-30 03:01:32 +0000
commit3bb814fe836cd59db56f2f5d07f69cb531ed25e0 (patch)
tree53c08bd7d2d4d9422f8bc32aa66c67f24fc82ca2 /macros/luatex/latex/piton/piton.dtx
parent9ffa8712668c5055c54742499d06caeb5cc9c87b (diff)
CTAN sync 202404300301
Diffstat (limited to 'macros/luatex/latex/piton/piton.dtx')
-rw-r--r--macros/luatex/latex/piton/piton.dtx553
1 files changed, 437 insertions, 116 deletions
diff --git a/macros/luatex/latex/piton/piton.dtx b/macros/luatex/latex/piton/piton.dtx
index c40a3c8631..a6902b9914 100644
--- a/macros/luatex/latex/piton/piton.dtx
+++ b/macros/luatex/latex/piton/piton.dtx
@@ -59,6 +59,13 @@
\NewDocumentCommand{\indexenv}{m}{\index{#1@\texttt{\{#1\}}}}
+\NewDocumentCommand{\Definition}{m}
+ {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}}
+
+\NewDocumentCommand{\DefinitionCommand}{m}
+ {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily
+ \vphantom{gl}\textbackslash #1}}}
+
\PitonOptions{gobble=2}
@@ -72,12 +79,12 @@
% \iffalse
%<*STY>
% \fi
-\def\PitonFileVersion{2.8}
-\def\PitonFileDate{2024/04/14}
+\def\PitonFileVersion{3.0}
+\def\PitonFileDate{2024/04/29}
% \iffalse
%</STY>
%<*LUA>
-piton_version = "2.8" -- 2024/04/14
+piton_version = "3.0" -- 2024/04/29
%</LUA>
%\fi
%
@@ -90,9 +97,8 @@ piton_version = "2.8" -- 2024/04/14
% \maketitle
%
% \begin{abstract}
-% The package \pkg{piton} provides tools to typeset computer listings in Python,
-% OCaml, C and SQL with syntactic highlighting by using the Lua library LPEG. It
-% requires LuaLaTeX.
+% The package \pkg{piton} provides tools to typeset computer listings, with
+% syntactic highlighting, by using the Lua library LPEG. It requires LuaLaTeX.
% \end{abstract}
%
%
@@ -103,12 +109,12 @@ piton_version = "2.8" -- 2024/04/14
% The package \pkg{piton} uses the Lua library LPEG\footnote{LPEG is a
% pattern-matching library for Lua, written in C, based on \emph{parsing
% expression grammars}:
-% \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} for parsing Python, OCaml, C
-% or SQL listings and typesets them with syntactic highlighting. Since it uses
-% the Lua of LuaLaTeX, it works with |lualatex| only (and won't work with the
-% other engines: |latex|, |pdflatex| and |xelatex|). It does not use external
-% program and the compilation does not require |--shell-escape|. The compilation
-% is very fast since all the parsing is done by the library LPEG, written in C.
+% \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} for parsing informatic
+% listings and typesets them with syntactic highlighting. Since it uses the Lua
+% of LuaLaTeX, it works with |lualatex| only (and won't work with the other
+% engines: |latex|, |pdflatex| and |xelatex|). It does not use external program
+% and the compilation does not require |--shell-escape|. The compilation is very
+% fast since all the parsing is done by the library LPEG, written in C.
%
% \bigskip
% Here is an example of code typeset by \pkg{piton}, with the environment |{Piton}|.
@@ -134,6 +140,15 @@ piton_version = "2.8" -- 2024/04/14
% s += (-1)**k/(2*k+1)*x**(2*k+1)
% return s
% \end{Piton}
+%
+%
+% \bigskip
+% The main alternatives to the package \pkg{piton} are probably the packages
+% \pkg{listings} and \pkg{minted}.
+%
+% \bigskip
+% The name of this extension (\pkg{piton}) has been choosen arbitrarily by
+% reference to the pitons used by the climbers in alpinism.
%
%
% \section{Installation}
@@ -158,13 +173,22 @@ piton_version = "2.8" -- 2024/04/14
% If, at the end of the preamble, the package \pkg{xcolor} has not been loaded
% (by the final user or by another package), \pkg{piton} loads \pkg{xcolor} with
% the instruction |\usepackage{xcolor}| (that is to say without any option).
-% The package \pkg{piton} doesn't load any other package.
+% The package \pkg{piton} doesn't load any other package. It does not any
+% exterior program.
%
% \subsection{Choice of the computer language}
%
-% In current version, the package \pkg{piton} supports four computer languages:
-% Python, OCaml, SQL and C (in fact \CC). It supports also a special language
-% called ``|minimal|'': cf. p.~\pageref{minimal}.
+% The package \pkg{piton} supports two kinds of languages:
+% \begin{itemize}
+% \item the languages natively supported by \pkg{piton}, which are Python, OCaml,
+% C~(in fact \CC), SQL and a language called |minimal|\footnote{That language
+% |minimal| may be used to format pseudo-codes: cf. p.~\pageref{minimal}};
+% \item the languages defined by the final user by using the built-in command
+% |\NewPitonLanguage| described p.~\pageref{NewPitonLanguage} (the parsers of
+% those languages can't be as precise as those of the native languages supported
+% by \pkg{piton}).
+% \end{itemize}
+%
%
% \smallskip
% By default, the language used is Python.
@@ -172,7 +196,12 @@ piton_version = "2.8" -- 2024/04/14
% \smallskip
% \index{language (key)}
% It's possible to change the current language with the command |\PitonOptions|
-% and its key |language|: |\PitonOptions{language = C}|.
+% and its key |language|: |\PitonOptions{language = OCaml}|.
+%
+% \smallskip
+% In fact, for \pkg{piton}, the names of the informatic languages are always
+% \textbf{case-insensitive}. In this example, we might have written |Ocaml| or
+% |ocaml|.
%
% \smallskip
% For the developpers, let's say that the name of the current language is stored
@@ -186,7 +215,7 @@ piton_version = "2.8" -- 2024/04/14
%
% \indexenv{Piton}
%
-% The package \pkg{piton} provides several tools to typeset Python code: the
+% The package \pkg{piton} provides several tools to typeset Python codes: the
% command |\piton|, the environment |{Piton}| and the command |\PitonInputFile|.
%
% \begin{itemize}\setlength{\fboxsep}{1pt}
@@ -211,20 +240,16 @@ piton_version = "2.8" -- 2024/04/14
% It's possible to insert only a part of the file: cf.
% part~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}.
%
-%
-% \colorbox{yellow!50}{\bfseries New 2.8}\par\nobreak
-%
-%
-% The key |path| of the command |\PitonOptions| specifies a \emph{list} of
-% pathes where the files included by |\PitonInputFile| will be searched. That
-% list is comma separated.
+% The key \Definition{path} of the command |\PitonOptions| specifies a
+% \emph{list} of pathes where the files included by |\PitonInputFile| will be
+% searched. That list is comma separated.
%
% The extension \pkg{piton} also provides the commands
% \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFileT},
% \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFileF} and
% \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFileTF} with
% supplementary arguments corresponding to the letters~|T| and~|F|. Those
-% arguments will be exectued if the file to include has been found (letter~|T|)
+% arguments will be executed if the file to include has been found (letter~|T|)
% or not found (letter~|F|).
% \end{itemize}
%
@@ -323,8 +348,6 @@ piton_version = "2.8" -- 2024/04/14
% \subsection{The keys of the command \textbackslash PitonOptions}
%
%
-% \NewDocumentCommand{\Definition}{m}
-% {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}}
%
% \indexcommand{PitonOptions}
%
@@ -554,10 +577,11 @@ piton_version = "2.8" -- 2024/04/14
%
% \subsubsection{Notion of style}
%
-% The package \pkg{piton} provides the command |\SetPitonStyle| to customize the
-% different styles used to format the syntactic elements of the Python listings.
-% The customizations done by that command are limited to the current TeX
-% group.\footnote{We remind that a LaTeX environment is, in particular, a TeX group.}
+% The package \pkg{piton} provides the command
+% \DefinitionCommand{SetPitonStyle} to customize the different styles used to
+% format the syntactic elements of the Python listings. The customizations done
+% by that command are limited to the current TeX group.\footnote{We remind that
+% a LaTeX environment is, in particular, a TeX group.}
%
% \bigskip
% \indexcommand{SetPitonStyle}
@@ -601,8 +625,9 @@ piton_version = "2.8" -- 2024/04/14
%
% \bigskip
% \indexcommand{PitonStyle}
-% The command |\PitonStyle| takes in as argument the name of a style and allows
-% to retrieve the value (as a list of LaTeX instructions) of that style.
+% The command \DefinitionCommand{PitonStyle} takes in as argument the name of a
+% style and allows to retrieve the value (as a list of LaTeX instructions) of
+% that style.
%
% \smallskip
% For example, it's possible to write |{\PitonStyle{Keyword}{function}}| and we
@@ -626,11 +651,12 @@ piton_version = "2.8" -- 2024/04/14
% \SetPitonStyle{Comment = \color{gray}}
% \end{Verbatim}
% all the comments will be composed in gray in all the listings, whatever
-% informatic language they use (Python, C, OCaml, etc.).
+% informatic language they use (Python, C, OCaml, etc. or a language defined by
+% the command |\NewPitonLanguage|).
%
% \bigskip
% But it's also possible to define a style locally for a given informatic
-% langage by providing the name of that language as optional argument (between
+% language by providing the name of that language as optional argument (between
% square brackets) to the command |\SetPitonStyle|.\footnote{We recall, that, in
% the package \pkg{piton}, the names of the informatic languages are
% case-insensitive.}
@@ -694,7 +720,7 @@ piton_version = "2.8" -- 2024/04/14
% \SetPitonStyle{Name.Function = \MyDefFunction, ~emphase#UserFunction@ = \MyUserFunction}
% \end{Verbatim}
%
-% \bigskip
+% \smallskip
%
% \begin{Piton}
% def transpose(v,i,j):
@@ -710,6 +736,10 @@ piton_version = "2.8" -- 2024/04/14
%
% \endgroup
%
+% \medskip
+% (Some \textsc{pdf} viewers display a frame around the clickable word
+% |transpose| but other do not.)
+%
% \PitonClearUserFunctions[Python]
%
% \bigskip
@@ -717,12 +747,12 @@ piton_version = "2.8" -- 2024/04/14
% Of course, the list of the names of Python functions previously défined is
% kept in the memory of LuaLaTeX (in a global way, that is to say independently
% of the TeX groups). The extension \pkg{piton} provides a command to clear that
-% list : it's the command |\PitonClearUserFunctions|. When it is used without
-% argument, that command is applied to all the informatic languages used by the
-% user but it's also possible to use it with an optional argument (between
-% square brackets) which is a list of informatic languages to which the command
-% will be applied.\footnote{We remind that, in \pkg{piton}, the name of the
-% informatic languages are case-insensitive.}
+% list : it's the command \DefinitionCommand{PitonClearUserFunctions}. When it
+% is used without argument, that command is applied to all the informatic
+% languages used by the user but it's also possible to use it with an optional
+% argument (between square brackets) which is a list of informatic languages to
+% which the command will be applied.\footnote{We remind that, in \pkg{piton},
+% the name of the informatic languages are case-insensitive.}
% \end{small}
%
% \subsection{Creation of new environments}
@@ -736,9 +766,10 @@ piton_version = "2.8" -- 2024/04/14
% |\newenvironment| (of standard LaTeX) or |\NewDocumentEnvironment| (of
% LaTeX3).
%
-% That's why \pkg{piton} provides a command |\NewPitonEnvironment|. That
-% command takes in three mandatory arguments.
-
+% That's why \pkg{piton} provides a command
+% \DefinitionCommand{NewPitonEnvironment}. That command takes in three mandatory
+% arguments.
+%
% That command has the same syntax as the classical environment
% |\NewDocumentEnvironment|.\footnote{However, the specifier of argument |b|
% (used to catch the body of the environment as a LaTeX argument) is
@@ -783,6 +814,148 @@ piton_version = "2.8" -- 2024/04/14
% return x*x
% \end{Python}
%
+% \section{Definition of new languages with the syntax of listings}
+%
+% \indexcommand{NewPitonLanguage}
+% \label{NewPitonLanguage}
+% \index{listings@\pkg{listings} (extension)}
+% \colorbox{yellow!50}{\textbf{New 3.0}}
+%
+% \medskip
+% The package \pkg{listings} is a famous LaTeX package to format informatic
+% listings.
+%
+% That package provides a command |\lstdefinelanguage| which allows the user to
+% define new languages. That command is also used by \pkg{listings} itself to
+% provide the definition of the predefined languages in \pkg{listings} (in fact,
+% for this task, \pkg{listings} uses a command called |\lst@definelanguage| but
+% that command has the same syntax as |\lstdefinelanguage|).
+%
+% \medskip
+% The package \pkg{piton} provides a command
+% \DefinitionCommand{NewPitonLanguage} to define new languages (avaiblable in
+% |\piton|, |{Piton}|, etc.) with a syntax which is almost the same as the
+% syntax of~|\lstdefinelanguage|.
+%
+% Let's precise that \pkg{piton} does \emph{not} use that command to define the
+% languages provided natively (Python, OCaml, \CC, SQL and |minimal|), which
+% allows more powerful parsers.
+%
+% \medskip
+% For example, in the file |lstlang1.sty|, which is one of the definition files
+% of \pkg{listings}, we find the following instructions (in version 1.10a).
+%
+%\begin{Verbatim}[formatcom=\small\color{gray}]
+% \lst~@definelanguage{Java}%
+% {morekeywords={abstract,boolean,break,byte,case,catch,char,class,%
+% const,continue,default,do,double,else,extends,false,final,%
+% finally,float,for,goto,if,implements,import,instanceof,int,%
+% interface,label,long,native,new,null,package,private,protected,%
+% public,return,short,static,super,switch,synchronized,this,throw,%
+% throws,transient,true,try,void,volatile,while},%
+% sensitive,%
+% morecomment=[l]//,%
+% morecomment=[s]{/*}{*/},%
+% morestring=[b]",%
+% morestring=[b]',%
+% }[keywords,comments,strings]
+% \end{Verbatim}
+%
+% \medskip
+% In order to define a language called |Java| for \pkg{piton}, one has only to
+% write the following code {\bfseries where the last argument of
+% |\lst@definelanguage|, between square brackets, has been discarded} (in fact,
+% the symbols \verb+%+ may be deleted without any problem).
+%
+% \begin{Verbatim}[formatcom=\small\color{gray}]
+% ~emphase#\NewPitonLanguage@{Java}%
+% {morekeywords={abstract,boolean,break,byte,case,catch,char,class,%
+% const,continue,default,do,double,else,extends,false,final,%
+% finally,float,for,goto,if,implements,import,instanceof,int,%
+% interface,label,long,native,new,null,package,private,protected,%
+% public,return,short,static,super,switch,synchronized,this,throw,%
+% throws,transient,true,try,void,volatile,while},%
+% sensitive,%
+% morecomment=[l]//,%
+% morecomment=[s]{/*}{*/},%
+% morestring=[b]",%
+% morestring=[b]',%
+% }
+% \end{Verbatim}
+%
+%
+% \NewPitonLanguage{Java}
+% {morekeywords={abstract,boolean,break,byte,case,catch,char,class,
+% const,continue,default,do,double,else,extends,false,final,
+% finally,float,for,goto,if,implements,import,instanceof,int,
+% interface,label,long,native,new,null,package,private,protected,
+% public,return,short,static,super,switch,synchronized,this,throw,
+% throws,transient,true,try,void,volatile,while},
+% sensitive,
+% morecomment=[l]//,
+% morecomment=[s]{/*}{*/},
+% morestring=[b]",
+% morestring=[b]',
+% }
+%
+% \medskip
+% It's possible to use the language Java like any other language defined by
+% \pkg{piton}.
+%
+% Here is an example of code formatted in an environment |{Piton}| with
+% the key |language=Java|.\footnote{We recall that, for \pkg{piton}, the names
+% of the informatic languages are case-insensitive. Hence, it's possible to
+% write, for instance, |language=java|.}
+%
+%
+% \bigskip
+% \begingroup
+% \small
+% \PitonOptions{split-on-empty-lines}
+% \begin{Piton}[language = java]
+% public class Cipher { // Caesar cipher
+% public static void main(String[] args) {
+% String str = "The quick brown fox Jumped over the lazy Dog";
+% System.out.println( Cipher.encode( str, 12 ));
+% System.out.println( Cipher.decode( Cipher.encode( str, 12), 12 ));
+% }
+%
+% public static String decode(String enc, int offset) {
+% return encode(enc, 26-offset);
+% }
+%
+% public static String encode(String enc, int offset) {
+% offset = offset % 26 + 26;
+% StringBuilder encoded = new StringBuilder();
+% for (char i : enc.toCharArray()) {
+% if (Character.isLetter(i)) {
+% if (Character.isUpperCase(i)) {
+% encoded.append((char) ('A' + (i - 'A' + offset) % 26 ));
+% } else {
+% encoded.append((char) ('a' + (i - 'a' + offset) % 26 ));
+% }
+% } else {
+% encoded.append(i);
+% }
+% }
+% return encoded.toString();
+% }
+% }
+% \end{Piton}
+% \endgroup
+%
+% \bigskip
+
+% The keys of the command |\lstdeflinelanguage| of \pkg{listings} supported by |\NewPitonLanguage| are:
+% |morekeywords|, |otherkeywords|, |sensitive|, |keywordsprefix|, |moretexcs|,
+% |morestring| (with the letters |b|,
+% |d|, |s| and |m|), |morecomment| (with the letters |i|, |l|, |s| and |n|),
+% |moredelim| (with the letters |i|,
+% |l|, |s|, |*| and |**|), |moredirectives|, |tag|, |alsodigit| and |alsoletter|.
+%
+% For the description of those keys, we redirect the reader to the documentation
+% of the package \pkg{listings} (type |texdoc| |listings| in a terminal).
+%
%
% \section{Advanced features}
%
@@ -800,8 +973,7 @@ piton_version = "2.8" -- 2024/04/14
% and |splittable| to allow such breaks.
%
% \begin{itemize}
-% \item \colorbox{yellow!50}{\textbf{New 2.7}}\par\nobreak
-% The key \Definition{split-on-empty-lines} allows breaks on the empty
+% \item The key \Definition{split-on-empty-lines} allows breaks on the empty
% lines\footnote{The ``empty lines'' are the lines which contains only spaes.} in
% the listing. In the informatic listings, the empty lines usually seperate the
% definitions of the informatic functions and it's pertinent to allow breaks
@@ -1059,16 +1231,16 @@ piton_version = "2.8" -- 2024/04/14
%
% \label{SetPitonIdentifier}
%
-% The command |\SetPitonIdentifier| allows to change the formatting of some
-% identifiers.
+% The command \DefinitionCommand{SetPitonIdentifier} allows to change the
+% formatting of some identifiers.
%
% \smallskip
% That command takes in three arguments:
%
% \begin{itemize}
% \item The optionnal argument (within square brackets) specifies the informatic
-% langage. If this argument is not present, the tunings done by
-% |\SetPitonIdentifier| will apply to all the informatic langages of
+% language. If this argument is not present, the tunings done by
+% |\SetPitonIdentifier| will apply to all the informatic languages of
% \pkg{piton}.\footnote{We recall, that, in the package \pkg{piton}, the
% names of the informatic languages are case-insensitive.}
%
@@ -1187,9 +1359,9 @@ piton_version = "2.8" -- 2024/04/14
%
% \begin{itemize}
% \item It's possible to change the syntatic mark (which, by default, is |#>|).
-% For this purpose, there is a key |comment-latex| available only in the
-% preamble of the document, allows to choice the characters which,
-% preceded by |#|, will be the syntatic marker.
+% For this purpose, there is a key \Definition{comment-latex} available only in
+% the preamble of the document, allows to choice the characters which, preceded
+% by |#|, will be the syntatic marker.
%
% For example, if the preamble contains the following instruction:
%
@@ -1260,7 +1432,7 @@ piton_version = "2.8" -- 2024/04/14
% \index{detected-commands (key)}
% \label{detected-commands}
%
-% The key |detected-commands| of |\PitonOptions| allow to specify a
+% The key \Definition{detected-commands} of |\PitonOptions| allows to specify a
% (comma-separated) list of names of LaTeX commands that will be detected
% directly by \pkg{piton}.
%
@@ -1271,7 +1443,7 @@ piton_version = "2.8" -- 2024/04/14
% backslash (eg. |detected-commands = { emph, textbf }|).
%
% \item These commands must be LaTeX commands with only one (mandatory) argument
-% between braces (and these braces must be explicit).
+% between braces (and these braces must appear explicitly in the informatic listing).
% \end{itemize}
%
% \medskip
@@ -1375,7 +1547,7 @@ piton_version = "2.8" -- 2024/04/14
% of LaTeX, they are, in particular, composed within a TeX group and therefore,
% they can't be used to change the formatting of other lexical units.
%
-% In the langages where the character \verb|$| does not play a important role,
+% In the languages where the character \verb|$| does not play a important role,
% it's possible to activate that mechanism ``|escape-math|'' with the character
% \verb|$|:
% \begin{Verbatim}
@@ -1609,15 +1781,15 @@ piton_version = "2.8" -- 2024/04/14
% package \pkg{footnote} or the package \pkg{footnotehyper}.
%
% \smallskip
-% If \pkg{piton} is loaded with the option |footnote| (with
+% If \pkg{piton} is loaded with the option \Definition{footnote} (with
% |\usepackage[footnote]{piton}| or with |\PassOptionsToPackage|), the
% package \pkg{footnote} is loaded (if it is not yet loaded) and it is used to
% extract the footnotes.
%
% \smallskip
-% If \pkg{piton} is loaded with the option |footnotehyper|, the package
-% \pkg{footnotehyper} is loaded (if it is not yet loaded) ant it is used to
-% extract footnotes.
+% If \pkg{piton} is loaded with the option \Definition{footnotehyper}, the
+% package \pkg{footnotehyper} is loaded (if it is not yet loaded) ant it is used
+% to extract footnotes.
%
% \smallskip
% Caution: The packages \pkg{footnote} and \pkg{footnotehyper} are incompatible.
@@ -1641,15 +1813,15 @@ piton_version = "2.8" -- 2024/04/14
% PEP~8), \pkg{piton} accepts the characters of tabulation (that is to say the
% characters U+0009) at the beginning of the lines. Each character U+0009 is
% replaced by $n$~spaces. The initial value of $n$ is $4$ but it's possible to
-% change it with the key |tab-size| of |\PitonOptions|.
+% change it with the key \Definition{tab-size} of |\PitonOptions|.
%
% \smallskip
-% There exists also a key |tabs-auto-gobble| which computes the minimal value
-% $n$ of the number of consecutive characters U+0009 beginning each (non empty)
-% line of the environment |{Piton}| and applies |gobble| with that value of~$n$
-% (before replacement of the tabulations by spaces, of course). Hence, that key
-% is similar to the key |auto-gobble| but acts on U+0009 instead of U+0020
-% (spaces).
+% There exists also a key \Definition{tabs-auto-gobble} which computes the
+% minimal value $n$ of the number of consecutive characters U+0009 beginning
+% each (non empty) line of the environment |{Piton}| and applies |gobble| with
+% that value of~$n$ (before replacement of the tabulations by spaces, of
+% course). Hence, that key is similar to the key |auto-gobble| but acts on
+% U+0009 instead of U+0020 (spaces).
%
%
% \bigskip
@@ -2341,6 +2513,35 @@ piton_version = "2.8" -- 2024/04/14
% for pseudo-code.
%
% \newpage
+% \subsection{The languages defined by \textbackslash NewPitonLanguage}
+%
+% \vspace{1cm}
+% The command |\NewPitonLanguage| which define new informatic languages with the
+% syntax of the extension \pkg{listings} has been described p.~\pageref{NewPitonLanguage}.
+%
+% All the languages defined by the command |\NewPitonLanguage| use the same styles.
+% \vspace{1cm}
+%
+% \begin{center}
+% \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
+% \toprule
+% \normalfont Style & Use \\
+% \midrule
+% Number & the numbers \\
+% String.Long & the strings defined in |\NewPitonLanguage| by the key |morestring| \\
+% Comment & the comments defined in |\NewPitonLanguage| by the key |morecomment| \\
+% Comment.LaTeX & the comments which are composed by \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
+% Keyword & the keywords defined in |\NewPitonLanguage| by the keys |morekeywords|
+% and |moretexcs| (and also the key |sensitive| which specifies whether
+% the keywords are case-sensitive or not) \\
+% Directive & the directives defined in |\NewPitonLanguage| by the key |moredirectives| \\
+% \bottomrule
+% \end{tabularx}
+% \end{center}
+%
+%
+%
+% \newpage
%
% \section{Implementation}
%
@@ -3808,8 +4009,107 @@ piton_version = "2.8" -- 2024/04/14
%
% \bigskip
% \begin{macrocode}
-\NewDocumentCommand { \NewPitonLanguage } { m m }
- { \lua_now:e { piton.new_language("#1","\lua_escape:n{#2}") } }
+\NewDocumentCommand { \NewPitonLanguage } { O { } m ! o }
+ {
+ \tl_if_novalue:nTF { #3 }
+% \end{macrocode}
+% The last argument is provided by curryfication.
+% \begin{macrocode}
+ { \@@_NewPitonLanguage:nnn { #1 } { #2 } }
+% \end{macrocode}
+% The two last arguments are provided by curryfication.
+% \begin{macrocode}
+ { \@@_NewPitonLanguage:nnnnn { #1 } { #2 } { #3 } }
+ }
+% \end{macrocode}
+%
+% \bigskip
+% The following property list will contain the definitions of the informatic
+% languages as provided by the final user. However, if a language is defined
+% over another base language, the corresponding list will contain the \emph{whole}
+% definition of the language.
+% \begin{macrocode}
+\prop_new:N \g_@@_languages_prop
+% \end{macrocode}
+%
+% \bigskip
+% The function |\@@_NewPitonLanguage:nnn| will be used when the language is
+% \emph{not} defined above a base language (and a base dialect).
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_NewPitonLanguage:nnn #1 #2 #3
+ {
+% \end{macrocode}
+% We store in |\l_tmpa_tl| the name of the language with the potential dialect,
+% that is to say, for example : |[AspectJ]{Java}|. We use |\tl_if_blank:nF|
+% because the final user may have written |\NewPitonLanguage[ ]{Java}{...}|.
+% \begin{macrocode}
+ \tl_set:Nx \l_tmpa_tl
+ {
+ \tl_if_blank:nF { #1 } { [ \str_lowercase:n { #1 } ] }
+ \str_lowercase:n { #2 }
+ }
+% \end{macrocode}
+% We store in LaTeX the definition of the language because some languages may be
+% defined with that language as base language.
+% \begin{macrocode}
+ \prop_gput:Non \g_@@_languages_prop \l_tmpa_tl { #3 }
+% \end{macrocode}
+% The Lua part of the package \pkg{piton} will be loaded in a
+% |\AtBeginDocument|. Hence, we will put also in a |\AtBeginDocument| the
+% utilisation of the Lua function |piton.new_language| (which does the main job).
+% \begin{macrocode}
+ \exp_args:NV \@@_NewPitonLanguage:nn \l_tmpa_tl { #3 }
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_NewPitonLanguage:nn #1 #2
+ {
+ \hook_gput_code:nnn { begindocument } { . }
+ { \lua_now:e { piton.new_language("#1","\lua_escape:n{#2}") } }
+ }
+% \end{macrocode}
+%
+% \bigskip
+% Now the case when the language is defined upon a base language.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_NewPitonLanguage:nnnnn #1 #2 #3 #4 #5
+ {
+% \end{macrocode}
+% We store in |\l_tmpa_tl| the name of the base language with the dialect, that
+% is to say, for example : |[AspectJ]{Java}|. We use |\tl_if_blank:nF| because
+% the final user may have used |\NewPitonLanguage[Handel]{C}[ ]{C}{...}|
+% \begin{macrocode}
+ \tl_set:Nx \l_tmpa_tl
+ {
+ \tl_if_blank:nF { #3 } { [ \str_lowercase:n { #3 } ] }
+ \str_lowercase:n { #4 }
+ }
+% \end{macrocode}
+% We retrieve in |\l_tmpb_tl| the definition (as provided by the final user) of
+% that base language. Caution: |\g_@@_languages_prop| does not contain all the
+% languages provided by \pkg{piton} but only those defined by using
+% |\NewPitonLanguage|.
+% \begin{macrocode}
+ \prop_get:NoNTF \g_@@_languages_prop \l_tmpa_tl \l_tmpb_tl
+% \end{macrocode}
+% We can now define the new language by using the previous function.
+% \begin{macrocode}
+ { \@@_NewPitonLanguage:nnno { #1 } { #2 } { #5 } \l_tmpb_tl }
+ { \@@_error:n { Language~not~defined } }
+ }
+% \end{macrocode}
+%
+% \bigskip
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_NewPitonLanguage:nnnn #1 #2 #3 #4
+% \end{macrocode}
+% In the following line, we write |#4,#3| and not |#3,#4| because we want that the
+% keys which correspond to base language appear before the keys which are added
+% in the language we define.
+% \begin{macrocode}
+ { \@@_NewPitonLanguage:nnn { #1 } { #2 } { #4 , #3 } }
+\cs_generate_variant:Nn \@@_NewPitonLanguage:nnnn { n n n o }
% \end{macrocode}
%
% \bigskip
@@ -4514,7 +4814,7 @@ piton_version = "2.8" -- 2024/04/14
% Now, specific styles for the languages created with |\NewPitonLanguage| with
% the syntax of \pkg{listings}.
% \begin{macrocode}
- directive
+ Directive
}
\clist_map_inline:Nn \g_@@_styles_clist
@@ -4602,7 +4902,7 @@ piton_version = "2.8" -- 2024/04/14
TypeParameter = \color[HTML]{336666} \itshape ,
Preproc = \color[HTML]{AA6600} \slshape ,
Identifier = \@@_identifier:n ,
- directive = \color[HTML]{AA6600} ,
+ Directive = \color[HTML]{AA6600} ,
UserFunction = ,
Prompt = ,
ParseAgain.noCR = \@@_piton_no_cr:n ,
@@ -4787,6 +5087,18 @@ piton_version = "2.8" -- 2024/04/14
% \bigskip
% \subsubsection{The error messages of the package}
%
+%
+% \begin{macrocode}
+\@@_msg_new:nn { Language~not~defined }
+ {
+ Language~not~defined \\
+ The~language~'\l_tmpa_tl'~has~not~been~defined~previoulsy.\\
+ If~you~go~on,~your~command~\token_to_str:N \NewPitonLanguage\
+ will~be~ignored.
+ }
+% \end{macrocode}
+%
+%
% \begin{macrocode}
\@@_msg_new:nn { bad~version~of~piton.lua }
{
@@ -6529,12 +6841,12 @@ local Type =
K ( 'Name.Type' ,
P "bool" + "char" + "char16_t" + "char32_t" + "double" + "float" + "int" +
"int8_t" + "int16_t" + "int32_t" + "int64_t" + "long" + "short" + "signed"
- + "unsigned" + "void" + "wchar_t" )
+ + "unsigned" + "void" + "wchar_t" ) * Q "*" ^ 0
local DefFunction =
Type
* Space
- * Q "*" ^ -1
+ * Q "*" ^ -1
* K ( 'Name.Function.Internal' , identifier )
* SkipSpace
* # P "("
@@ -7394,7 +7706,7 @@ function piton.new_language ( lang , definition )
% \end{macrocode}
%
% \bigskip
-% Of course, the \textsc{lpeg} |b_braces| is for balanced braces (without the
+% Of course, the \textsc{lpeg} |strict_braces| is for balanced braces (without the
% question of strings of an informatic language). In fact, it \emph{won't} be
% used for an informatic language (as dealt by \pkg{piton}) but for LaTeX
% instructions;
@@ -7419,7 +7731,7 @@ function piton.new_language ( lang , definition )
local def_table = cut_definition : match ( definition )
% \end{macrocode}
% The definition of the language, provided by the final user of \pkg{piton} is
-% now in the Lua table |def_table|. We will use it several times.
+% now in the Lua table |def_table|. We will use it \emph{several times}.
%
% \medskip
% The following \textsc{lpeg} will be used to extract arguments in the values of
@@ -7551,18 +7863,18 @@ function piton.new_language ( lang , definition )
local keywords = P ( false )
% \end{macrocode}
% \begin{macrocode}
- local style = [[ \PitonStyle{Keyword} ]]
- if x[1] == "moredirectives" then style = [[ \PitonStyle{directive} ]] end
+ local style = [[\PitonStyle{Keyword}]]
+ if x[1] == "moredirectives" then style = [[ \PitonStyle{Directive} ]] end
style = tex_option_arg : match ( x[2] ) or style
- local n = tonumber (style )
+ local n = tonumber ( style )
if n then
- if n > 1 then style = [[ \PitonStyle{Keyword ]] .. style .. "}" end
+ if n > 1 then style = [[\PitonStyle{Keyword]] .. style .. "}" end
end
% \end{macrocode}
% \begin{macrocode}
for _ , word in ipairs ( split_clist : match ( x[2] ) ) do
if x[1] == "moretexcs" then
- keywords = Q ( [[ \ ]] .. word ) + keywords
+ keywords = Q ( [[\]] .. word ) + keywords
else
if sensitive
% \end{macrocode}
@@ -7597,44 +7909,42 @@ function piton.new_language ( lang , definition )
for _ , x in ipairs ( def_table ) do
if x[1] == "morestring" then
arg1 , arg2 , arg3 , arg4 = args_for_morekeywords : match ( x[2] )
- arg2 = arg2 or [[ \PitonStyle{String.Long} ]]
- if arg1 == "s" then
- long_string =
- Q ( arg3 )
- * ( Q ( ( 1 - P ( arg4 ) - S "$\r" ) ^ 1 ) -- $
- + EOL
- ) ^ 0
- * Q ( arg4 )
- else
- central_pattern = 1 - S ( " \r" .. arg3 )
- if arg1 : match "b" then
- central_pattern = P ( [[ \ ]] .. arg3 ) + central_pattern
- end
+ arg2 = arg2 or [[\PitonStyle{String.Long}]]
+ if arg1 ~= "s" then
+ arg4 = arg3
+ end
+ central_pattern = 1 - S ( " \r" .. arg4 )
+ if arg1 : match "b" then
+ central_pattern = P ( [[\]] .. arg3 ) + central_pattern
+ end
% \end{macrocode}
% In fact, the specifier |d| is point-less: when it is not in force, it's still
% possible to double the delimiter with a correct behaviour of \pkg{piton}
% since, in that case, \pkg{piton} will compose \emph{two} contiguous strings...
% \begin{macrocode}
- if arg1 : match "d" or arg1 == "m" then
- central_pattern = P ( arg3 .. arg3 ) + central_pattern
- end
- if arg1 == "m"
- then prefix = P ( false )
- else prefix = lpeg.B ( 1 - letter - ")" - "]" )
- end
+ if arg1 : match "d" or arg1 == "m" then
+ central_pattern = P ( arg3 .. arg3 ) + central_pattern
+ end
+ if arg1 == "m"
+ then prefix = lpeg.B ( 1 - letter - ")" - "]" )
+ else prefix = P ( true )
+ end
+% \end{macrocode}
+% We can write the pattern which matches the string.
+% \begin{macrocode}
+ local pattern =
+ prefix
+ * Q ( arg3 )
+ * ( VisualSpace + Q ( central_pattern ^ 1 ) + EOL ) ^ 0
+ * Q ( arg4 )
% \end{macrocode}
% First, we create |long_string| because we need that \textsc{lpeg} in the
% nested comments.
% \begin{macrocode}
- long_string = long_string +
- prefix
- * Q ( arg3 )
- * ( VisualSpace + Q ( central_pattern ^ 1 ) + EOL ) ^ 0
- * Q ( arg3 )
- end
+ long_string = long_string + pattern
LongString = LongString +
Ct ( Cc "Open" * Cc ( "{" .. arg2 .. "{" ) * Cc "}}" )
- * long_string
+ * pattern
* Ct ( Cc "Close" )
end
end
@@ -7655,12 +7965,12 @@ function piton.new_language ( lang , definition )
for _ , x in ipairs ( def_table ) do
if x[1] == "morecomment" then
local arg1 , arg2 , other_args = args_for_morecomment : match ( x[2] )
- arg2 = arg2 or [[ \PitonStyle{Comment} ]]
+ arg2 = arg2 or [[\PitonStyle{Comment}]]
% \end{macrocode}
% If the letter |i| is present in the first argument (eg:
% |morecomment = [si]{(*}{*)}|, then the corresponding comments are discarded.
% \begin{macrocode}
- if arg1 : match "i" then arg2 = [[ \PitonStyle{Discard} ]] end
+ if arg1 : match "i" then arg2 = [[\PitonStyle{Discard}]] end
if arg1 : match "l" then
local arg3 = ( tex_braced_arg + C ( P ( 1 ) ^ 0 * -1 ) )
: match ( other_args )
@@ -7772,8 +8082,12 @@ function piton.new_language ( lang , definition )
+ Beamer
+ DetectedCommands
+ CommentDelim
- + Delim
+% \end{macrocode}
+% We must put |LongString| before |Delim| because, in PostScript, the strings
+% are delimited by parenthesis and those parenthesis would be catched by |Delim|.
+% \begin{macrocode}
+ LongString
+ + Delim
+ Keyword * ( Space + Punct + Delim + EOL + -1 )
+ Punct
+ K ( 'Identifier' , letter * alphanum ^ 0 )
@@ -7802,11 +8116,11 @@ function piton.new_language ( lang , definition )
Ct (
( space ^ 0 * P "\r" ) ^ -1
* BeamerBeginEnvironments
- * Lc [[ \@@_begin_line: ]]
+ * Lc [[\@@_begin_line:]]
* SpaceIndentation ^ 0
* LPEG1[lang]
* -1
- * Lc [[ \@@_end_line: ]]
+ * Lc [[\@@_end_line:]]
)
% \end{macrocode}
%
@@ -7855,11 +8169,11 @@ function piton.new_language ( lang , definition )
Ct (
( space ^ 0 * P "\r" ) ^ -1
* BeamerBeginEnvironments
- * Lc [[ \@@_begin_line: ]]
+ * Lc [[\@@_begin_line:]]
* SpaceIndentation ^ 0
* LPEG1[lang]
* -1
- * Lc [[ \@@_end_line: ]]
+ * Lc [[\@@_end_line:]]
)
end
end
@@ -7886,6 +8200,13 @@ end
%
% \verb|https://github.com/fpantigny/piton|
%
+% \subsection*{Changes between versions 2.8 and 3.0}
+%
+% New command |\NewPitonLanguage|. Thanks to that command, it's now possible to
+% define new informatic languages with the syntax used by \pkg{listings}.
+% Therefore, it's possible to say that virtually all the informatic languages
+% are now supported by \pkg{piton}.
+%
% \subsection*{Changes between versions 2.7 and 2.8}
%
% The key |path| now accepts a \emph{list} of pathes where the files to include