summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/lualatex/piton/piton.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/lualatex/piton/piton.dtx')
-rw-r--r--Master/texmf-dist/source/lualatex/piton/piton.dtx620
1 files changed, 476 insertions, 144 deletions
diff --git a/Master/texmf-dist/source/lualatex/piton/piton.dtx b/Master/texmf-dist/source/lualatex/piton/piton.dtx
index 6bce058842d..0a655ed2784 100644
--- a/Master/texmf-dist/source/lualatex/piton/piton.dtx
+++ b/Master/texmf-dist/source/lualatex/piton/piton.dtx
@@ -15,8 +15,8 @@
%
% \fi
% \iffalse
-\def\myfileversion{0.95}
-\def\myfiledate{2022/11/09}
+\def\myfileversion{0.99}
+\def\myfiledate{2022/11/29}
%
%
%<*batchfile>
@@ -135,6 +135,9 @@ version 2005/12/01 or later.
%
% \section{Use of the package}
%
+%
+% \subsection{Loading the package}
+%
% The package \pkg{piton} should be loaded with the classical command
% |\usepackage|: |\usepackage{piton}|.
%
@@ -149,27 +152,105 @@ version 2005/12/01 or later.
% fatal error will be raised.
% \end{itemize}
%
-% \medskip
-% The package \pkg{piton} provides three tools to typeset Python code: the
+% \subsection{The tools provided to the user}
+%
+% The package \pkg{piton} provides several tools to typeset Python code: the
% command |\piton|, the environment |{Piton}| and the command |\PitonInputFile|.
%
-% \begin{itemize}
-% \item The command |\piton| should be used to typeset small pieces of code
-% inside a paragraph. \emph{Caution}: That fonction takes in its argument
-% \emph{verbatim}. Therefore, it cannot be used in the argument of another
-% command (however, it can be used within an environment).
-% \item The environment |{Piton}| should be used to typeset multi-lines code.
-% For sake of customization, it's possible to define new environments similar to
-% the environment |{Piton}| with the command |\NewPitonEnvironment|:
+% \begin{itemize}\setlength{\fboxsep}{1pt}
+% \item The command \colorbox{gray!20}{\texttt\textbackslash piton} should be
+% used to typeset small pieces of code inside a paragraph. For example:
+%
+% {\color{gray}\verb|\piton{def square(x): return x*x}|}\qquad
+% \piton{def square(x): return x*x}
+%
+% The syntax and particularities of the command |\piton| are detailed below.
+%
+% \item The environment \colorbox{gray!20}{\ttfamily\{Piton\}} should be used to
+% typeset multi-lines code. Since it takes its argument in a verbatim mode, it
+% can't be used within the argument of a LaTeX command. For sake of
+% customization, it's possible to define new environments similar to the
+% environment |{Piton}| with the command |\NewPitonEnvironment|:
% cf.~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
-% \item The command |\PitonInputFile| is used to insert and typeset a whole
-% external file.
%
-% \colorbox{yellow!50}{\textbf{New 0.95}}\enskip The command |\PitonInputFile|
-% takes in as optional argument (between square brackets) two keys |first-line|
-% and |last-line|: only the part between the corresponding lines will be inserted.
+% \item The command \colorbox{gray!20}{\ttfamily\textbackslash PitonInputFile}
+% is used to insert and typeset a whole external file.
+%
+% That command takes in as optional argument (between square brackets) two keys
+% |first-line| and |last-line|: only the part between the corresponding lines
+% will be inserted.
% \end{itemize}
%
+% \subsection{The syntax of the command \textbackslash piton}
+%
+% In fact, the command |\piton| is provided with a double syntax. It may be used
+% as a standard command of LaTeX taking its argument between curly braces
+% (|\piton{...}|) but it may also be used with a syntax similar to the syntax of
+% the command
+% |\verb|, that is to say with the argument delimited by two identical characters (e.g.: \verb!\piton|...|!).
+%
+% \begin{itemize}
+% \item {\color{blue} \textsf{Syntax} \verb|\piton{...}|}\par\nobreak
+% When its argument is given between curly braces, the command |\piton| does not
+% take its argument in verbatim mode. In particular:
+% \begin{itemize}
+% \item several consecutive spaces will be replaced by only one space;
+% \item it's not possible to use |%| inside the argument;
+% \item the braces must be appear by pairs correctly nested;
+% \item the LaTeX commands (those beginning with a backslash |\| but also the
+% active characters) are fully expanded (but not executed).
+% \end{itemize}
+%
+% An escaping mechanism is provided: the commands |\\|, |\%|, |\{| and |\}|
+% insert the corresponding characters |\|, |%|, |{| and |}|. The last two
+% commands are necessary only if one need to insert braces which are not
+% balanced.
+%
+% The other characters (including |#|, |^|, |_|, |&|, |$| and |@|)
+% must be inserted without backslash.
+%
+% Examples:
+%
+%\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
+% \verb|\piton{MyString = '\\n'}| &
+% \piton{MyString = '\\n'} \\
+% \verb|\piton{def even(n): return n\%2==0}| &
+% \piton{def even(n): return n\%2==0} \\
+% \verb|\piton{c="#" # an affectation }| &
+% \piton{c="#" # an affectation } \\
+% \verb|\piton{MyDict = {'a': 3, 'b': 4 }}| &
+% \piton{MyDict = {'a': 3, 'b': 4 }}
+% \end{tabular}
+%
+%
+% It's possible to use the command |\piton| in the arguments of a
+% LaTeX command.\footnote{For example, it's possible to use the command
+% \texttt{\textbackslash piton} in a footnote. Example :
+% \piton{s = 'A string'}.}
+%
+% \bigskip
+% \item {\color{blue} \textsf{Syntaxe} \verb!\piton|...|!}\par\nobreak
+%
+% When the argument of the command |\piton| is provided between two identical
+% characters, that argument is taken in a \emph{verbatim mode}. Therefore, with
+% that syntax, the command |\piton| can't be used within the argument of another
+% command.
+%
+% \medskip
+% Exemples :
+%
+% \begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
+% \verb!\piton|MyString = '\n'|! &
+% \piton|MyString = '\n'| \\
+% \verb|\piton!def even(n): return n%2==0!| &
+% \piton!def even(n): return n%2==0! \\
+% \verb|\piton+c="#" # an affectation +| &
+% \piton+c="#" # an affectation + \\
+% \verb|\piton?MyDict = {'a': 3, 'b': 4}?| &
+% \piton!MyDict = {'a': 3, 'b': 4}!
+% \end{tabular}
+%
+% \end{itemize}
%
% \section{Customization}
%
@@ -218,45 +299,23 @@ version 2005/12/01 or later.
% |line-all-numbers| if one does not want the numbers in an overlapping position
% on the left.
%
-% \colorbox{yellow!50}{\textbf{New 0.95}}\enskip It's possible to use the key
-% |left-margin| with the value |auto|. With that value, if the key
-% |line-numbers| or the key |all-line-numbers| is used, a margin will be
-% automatically inserted to fit the numbers of lines. See an example part
-% \ref{example-numbering} on page~\pageref{example-numbering}.
-%
-% \item The key |splittable| allows page breaks within the environments
-% |{Piton}| and the listings produced by
-% |\PitonInputFile|.
-%
-% \smallskip
-% It's possible to give as value to the key |splittable| a positive integer~$n$.
-% With that value, the environments |{Piton}| and the listings produced by
-% |\PitonInputFile| are splittable but no page break can occur within the first
-% $n$ lines and within the last $n$ lines. The default value of the key
-% |splittable| is, in fact, $1$, which allows pages breaks everywhere.
+% It's possible to use the key |left-margin| with the value |auto|. With that
+% value, if the key |line-numbers| or the key |all-line-numbers| is used, a
+% margin will be automatically inserted to fit the numbers of lines. See an
+% example part \ref{example-numbering} on page~\pageref{example-numbering}.
%
% \item The key |background-color| sets the background color of the environments
% |{Piton}| and the listings produced by |\PitonInputFile| (that background has
-% a width of |\linewidth|). Even with a background color, the pages breaks are
-% allowed, as soon as the key |splittable| is in force.\footnote{With the key
-% |splittable|, the environments \texttt{\{Piton\}} are breakable, even within a
-% (breakable) environment of \pkg{tcolorbox}. Remind that an environment of
-% \pkg{tcolorbox} included in another environment of \pkg{tcolorbox} is
-% \emph{not} breakable, even when both environments use the key |breakable| of
-% \pkg{tcolorbox}.}
-%
-% \item \colorbox{yellow!50}{\textbf{New 0.95}}\enskip When the key
-% |show-spaces| is activated, the spaces in the short strings (that is to say
-% those delimited by |'| or |"|) are replaced by the character~␣ (U+2423 :
-% \textsc{open box}). Of course, that character~U+2423 must be present in the
-% monospaced font which is used.\footnote{The package \pkg{piton} simply uses
-% the current monospaced font. The best way to change that font is to use the
-% command \texttt{\textbackslash setmonofont} of \pkg{fontspec}.}
-%
-% \begingroup
-% \PitonOptions{show-spaces}
-% Example : \piton|my_string = 'Very good answer'|
-% \endgroup
+% a width of |\linewidth|).
+%
+% \item When the key |show-spaces| is activated, the spaces in the short strings
+% (that is to say those delimited by |'| or |"|) are replaced by the character~␣
+% (U+2423 : \textsc{open box}). Of course, that character~U+2423 must be present
+% in the monospaced font which is used.\footnote{The package \pkg{piton} simply
+% uses the current monospaced font. The best way to change that font is to use
+% the command \texttt{\textbackslash setmonofont} of
+% \pkg{fontspec}.}\par\nobreak \begingroup \PitonOptions{show-spaces} Example :
+% \piton|my_string = 'Very good answer'| \endgroup
% \end{itemize}
%
% \bigskip
@@ -309,7 +368,10 @@ version 2005/12/01 or later.
% \end{Piton}
% \endgroup
%
-%
+% \bigskip
+% The command |\PitonOptions| provides in fact several other keys which will be
+% described further (see in particular the ``Pages breaks and line breaks''
+% p.~\pageref{breakable}).
%
% \subsection{The styles}
%
@@ -480,23 +542,29 @@ version 2005/12/01 or later.
% comments (which begins by |#|) will, in fact, be ``LaTeX comments''.
%
% \smallskip
-% \item \colorbox{yellow!50}{\bfseries New 0.95}\enskip It's possible to change
-% the formatting of the LaTeX comment itself by changing the \pkg{piton} style
-% |Comment.LaTeX|.
+% \item It's possible to change the formatting of the LaTeX comment itself by
+% changing the \pkg{piton} style |Comment.LaTeX|.
%
% For example, with |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|,
% the LaTeX comments will be composed in blue.
%
+% If you want to have a character |#| at the beginning of the LaTeX comment in
+% the \textsc{pdf}, you can use set |Comment.LaTeX| as follows:
+%
+% \begin{Verbatim}
+% \SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space }
+% \end{Verbatim}
+%
% For other examples of customization of the LaTeX comments, see the part
% \ref{example-comments} p.~\pageref{example-comments}
% \end{itemize}
%
% \subsubsection{The key ``math-comments''}
%
-% \colorbox{yellow!50}{\textbf{New 0.95}}\enskip It's possible to request that,
-% in the standard Python comments (that is to say those beginning by |#| and not
-% |#>|), the elements between \texttt{\$} be composed in LaTeX mathematical mode
-% (the other elements of the comment being composed verbatim).
+% It's possible to request that, in the standard Python comments (that is to say
+% those beginning by |#| and not |#>|), the elements between \texttt{\$} be
+% composed in LaTeX mathematical mode (the other elements of the comment being
+% composed verbatim).
%
% That feature is activated by the key |math-comments| at load-time (that is to
% say with the |\usepackage|).
@@ -520,8 +588,8 @@ version 2005/12/01 or later.
% \subsubsection{The mechanism ``escape-inside''}
%
% It's also possible to overwrite the Python listings to insert LaTeX code
-% almost everywhere. By default, \pkg{piton} does not fix any character for that
-% kind of escape.
+% almost everywhere (but between lexical units, of course). By default,
+% \pkg{piton} does not fix any character for that kind of escape.
%
% In order to use this mechanism, it's necessary to specify two characters which
% will delimit the escape (one for the beginning and one for the end) by using
@@ -566,6 +634,94 @@ version 2005/12/01 or later.
% beginning it with |#>|; such comments are merely called ``LaTeX comments'' in
% this document).
%
+%
+% \subsection{Page breaks and line breaks}
+%
+% \label{breakable}
+%
+% \subsubsection{Page breaks}
+%
+% By default, the listings produced by the environment |{Piton}| and the command
+% |\PitonInputFile| are not breakable.
+%
+% However, the command |\PitonOptions| provides the key |splittable| to allow such
+% breaks.
+%
+% \begin{itemize}
+% \item If the key |splittable| is used without any value, the listings are
+% breakable everywhere.
+% \item If the key |splittable| is used with a numeric value~$n$ (which must be
+% a non-negative integer number), the listings are breakable but no break will
+% occur within the first $n$ lines and within the last $n$ lines. Therefore,
+% |splittable=1| is equivalent to |splittable|.
+% \end{itemize}
+%
+% \medskip
+% Even with a background color (set by |background-color|), the pages breaks are
+% allowed, as soon as the key |splittable| is in force.\footnote{With the key
+% |splittable|, the environments \texttt{\{Piton\}} are breakable, even within a
+% (breakable) environment of \pkg{tcolorbox}. Remind that an environment of
+% \pkg{tcolorbox} included in another environment of \pkg{tcolorbox} is
+% \emph{not} breakable, even when both environments use the key |breakable| of
+% \pkg{tcolorbox}.}
+%
+% \subsubsection{Line breaks}
+%
+% By default, the lines of the listings produced by |{Piton}| and
+% |\PitonInputFile| are not breakable.
+%
+% \smallskip
+% \colorbox{yellow!50}{\textbf{New 0.99}}\enskip There exist several keys
+% (available in |\PitonOptions|) to allow and control such line breaks.
+%
+% \begin{itemize}
+% \item The key |break-lines| actives the lines breaks. Only the spaces (even in
+% the strings) are allowed break points.
+%
+% \item With the key |indent-broken-lines|, the indentation of a broken line is
+% respected at carriage return.
+%
+% \item The key |end-of-broken-line| corresponds to the symbol placed at the end
+% of a broken line. The initial value is: |\hspace*{0.5em}\textbackslash|.
+%
+% \item The key |continuation-symbol| corresponds to the symbol placed at each
+% carriage return. The initial value is: |+\;|.
+%
+% \item The key |continuation-symbol-on-indentation| coresponds to the symbol
+% placed at each carriage return, on the position of the indentation (only when
+% the key |indent-broken-line| is in force). The initial value is:
+% |$\hookrightarrow\;$|.
+% \end{itemize}
+%
+%
+% \bigskip
+% The following code has been composed in a |{minipage}| of width 12~cm with the
+% following tuning:
+%
+% \begin{Verbatim}
+% \PitonOptions{break-lines,indent-broken-lines,background-color=gray!15}
+% \end{Verbatim}
+%
+% \begin{center}
+% \PitonOptions{break-lines,indent-broken-lines,background-color=gray!15}
+% \begin{minipage}{12cm}
+% \begin{Piton}
+% def dict_of_list(l):
+% """Converts a list of subrs and descriptions of glyphs in a dictionary"""
+% our_dict = {}
+% for list_letter in l:
+% if (list_letter[0][0:3] == 'dup'): # if it's a subr
+% name = list_letter[0][4:-3]
+% print("We treat the subr of number " + name)
+% else:
+% name = list_letter[0][1:-3] # if it's a glyph
+% print("We treat the glyph of number " + name)
+% our_dict[name] = [treat_Postscript_line(k) for k in list_letter[1:-1]]
+% return dict
+% \end{Piton}
+% \end{minipage}
+% \end{center}
+%
% \subsection{Footnotes in the environments of piton}
%
% \label{footnote}
@@ -1417,6 +1573,36 @@ version 2005/12/01 or later.
% \end{macrocode}
%
% \medskip
+% The following booleans correspond to the keys |break-lines| and
+% |indent-broken-lines| of |\PitonOptions|.
+% \begin{macrocode}
+\bool_new:N \l_@@_break_lines_bool
+\bool_new:N \l_@@_indent_broken_lines_bool
+% \end{macrocode}
+%
+% \medskip
+% The following token list corresponds to the key |continuation-symbol|.
+% \begin{macrocode}
+\tl_new:N \l_@@_continuation_symbol_tl
+\tl_set:Nn \l_@@_continuation_symbol_tl { + }
+% \end{macrocode}
+%
+% \medskip
+% \begin{macrocode}
+% The following token list corresponds to the key
+% |continuation-symbol-on-indentation|. The name has been shorten to |csoi|.
+\tl_new:N \l_@@_csoi_tl
+\tl_set:Nn \l_@@_csoi_tl { $ \hookrightarrow \; $ }
+% \end{macrocode}
+%
+% \medskip
+% The following token list corresponds to the key |end-of-broken-line|.
+% \begin{macrocode}
+\tl_new:N \l_@@_end_of_broken_line_tl
+\tl_set:Nn \l_@@_end_of_broken_line_tl { \hspace*{0.5em} \textbackslash }
+% \end{macrocode}
+%
+% \medskip
% The following boolean corresponds to the key |slim| of |\PitonOptions|.
% \begin{macrocode}
\bool_new:N \l_@@_slim_bool
@@ -1424,13 +1610,19 @@ version 2005/12/01 or later.
%
% \medskip
% The following dimension corresponds to the key |left-margin| of
-% |\PitonOptions|. By convention, when the final user will uses
-% |left-margin=auto|, |\l_@@_left_margin_dim| will be equal to -1~cm.
+% |\PitonOptions|.
% \begin{macrocode}
\dim_new:N \l_@@_left_margin_dim
% \end{macrocode}
%
% \medskip
+% The following boolean correspond will be set when the key |left-margin=auto|
+% is used.
+% \begin{macrocode}
+\bool_new:N \l_@@_left_margin_auto_bool
+% \end{macrocode}
+%
+% \medskip
% The tabulators will be replaced by the content of the following token list.
% \begin{macrocode}
\tl_new:N \l_@@_tab_tl
@@ -1459,30 +1651,71 @@ version 2005/12/01 or later.
\tl_set:Nn \l_@@_space_tl { ~ }
% \end{macrocode}
%
+%
+% \medskip
+% At each line, the following counter will count the spaces at the beginning.
+% \begin{macrocode}
+\int_new:N \g_@@_indentation_int
+% \end{macrocode}
+%
+% \medskip
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_an_indentation_space:
+ { \int_gincr:N \g_@@_indentation_int }
+% \end{macrocode}
+%
% \bigskip
% \subsubsection{Treatment of a line of code}
%
+%
+% \bigskip
% In the contents provided by Lua, each line of the Python code will be
% surrounded by |\@@_begin_line:| and |\@@_end_line:|.
%
% \begin{macrocode}
\cs_set_protected:Npn \@@_begin_line: #1 \@@_end_line:
{
+ \int_gzero:N \g_@@_indentation_int
% \end{macrocode}
%
+%
% Be careful: there is curryfication in the following lines.
% \begin{macrocode}
\bool_if:NTF \l_@@_slim_bool
- { \hbox_set:Nn \l_tmpa_box }
+ { \hcoffin_set:Nn \l_tmpa_coffin }
{
\str_if_empty:NTF \l_@@_background_color_str
- { \hbox_set_to_wd:Nnn \l_tmpa_box \linewidth }
{
- \hbox_set_to_wd:Nnn \l_tmpa_box
- { \dim_eval:n { \linewidth - 0.5 em } }
+ \vcoffin_set:Nnn \l_tmpa_coffin
+ { \dim_eval:n { \linewidth - \l_@@_left_margin_dim } }
+ }
+ {
+ \vcoffin_set:Nnn \l_tmpa_coffin
+ { \dim_eval:n { \linewidth - \l_@@_left_margin_dim - 0.5 em } }
}
}
{
+ \language = -1
+ \raggedright
+ \strut
+ \tl_set:Nn \l_tmpa_tl { #1 }
+% \end{macrocode}
+% If the key |break-lines| is in force, we replace all the characters U+0032
+% (that is to say the spaces) by |\@@_breakable_space:|. Remark that, except the
+% spaces inserted in the LaTeX comments (and maybe in the math comments), all
+% these spaces are of catcode ``other'' (=12) and are unbreakable.
+% \begin{macrocode}
+ \bool_if:NT \l_@@_break_lines_bool
+ {
+ \regex_replace_all:nnN
+ { \x20 }
+ { \c { @@_breakable_space: } }
+ \l_tmpa_tl
+ }
+ \l_tmpa_tl \strut \hfil
+ }
+ \hbox_set:Nn \l_tmpa_box
+ {
\skip_horizontal:N \l_@@_left_margin_dim
\bool_if:NT \l_@@_line_numbers_bool
{
@@ -1490,13 +1723,13 @@ version 2005/12/01 or later.
{ \tl_if_empty:nF { #1 } }
\@@_print_number:
}
- \strut
- \str_if_empty:NF \l_@@_background_color_str \space
- #1 \hfil
- }
+ \str_if_empty:NF \l_@@_background_color_str
+ { \skip_horizontal:n { 0.5 em } }
+ \coffin_typeset:Nnnnn \l_tmpa_coffin T l \c_zero_dim \c_zero_dim
+ }
% \end{macrocode}
% We compute in |\g_@@_width_dim| the maximal width of the lines of the
-% environments.
+% environment.
% \begin{macrocode}
\dim_compare:nNnT { \box_wd:N \l_tmpa_box } > \g_@@_width_dim
{ \dim_gset:Nn \g_@@_width_dim { \box_wd:N \l_tmpa_box } }
@@ -1542,6 +1775,36 @@ version 2005/12/01 or later.
}
}
% \end{macrocode}
+%
+% \bigskip
+% \begin{macrocode}
+\cs_set_protected:Npn \@@_breakable_space:
+ {
+ \discretionary
+ { \hbox:n { \color { gray } \l_@@_end_of_broken_line_tl } }
+ {
+ \hbox_overlap_left:n
+ {
+ {
+ \normalfont \footnotesize \color { gray }
+ \l_@@_continuation_symbol_tl
+ }
+ \skip_horizontal:n { 0.3 em }
+ \str_if_empty:NF \l_@@_background_color_str
+ { \skip_horizontal:n { 0.5 em } }
+ }
+ \bool_if:NT \l_@@_indent_broken_lines_bool
+ {
+ \hbox:n
+ {
+ \prg_replicate:nn { \g_@@_indentation_int } { ~ }
+ { \color { gray } \l_@@_csoi_tl }
+ }
+ }
+ }
+ { \hbox { ~ } }
+ }
+% \end{macrocode}
%
% \bigskip
% \subsubsection{PitonOptions}
@@ -1589,13 +1852,26 @@ version 2005/12/01 or later.
slim .default:n = true ,
left-margin .code:n =
\str_if_eq:nnTF { #1 } { auto }
- { \dim_set:Nn \l_@@_left_margin_dim { -1cm } }
+ {
+ \dim_zero:N \l_@@_left_margin_dim
+ \bool_set_true:N \l_@@_left_margin_auto_bool
+ }
{ \dim_set:Nn \l_@@_left_margin_dim { #1 } } ,
left-margin .value_required:n = true ,
tab-size .code:n = \@@_set_tab_tl:n { #1 } ,
tab-size .value_required:n = true ,
show-spaces .code:n = \tl_set:Nn \l_@@_space_tl { ␣ } , % U+2423
show-spaces .value_forbidden:n = true ,
+ break-lines .bool_set:N = \l_@@_break_lines_bool ,
+ break-lines .default:n = true ,
+ indent-broken-lines .bool_set:N = \l_@@_indent_broken_lines_bool ,
+ indent-broken-lines .default:n = true ,
+ end-of-broken-line .tl_set:N = \l_@@_end_of_broken_line_tl ,
+ end-of-broken-line .value_required:n = true ,
+ continuation-symbol .tl_set:N = \l_@@_continuation_symbol_tl ,
+ continuation-symbol .value_required:n = true ,
+ continuation-symbol-on-indentation .tl_set:N = \l_@@_csoi_tl ,
+ continuation-symbol-on-indentation .value_required:n = true ,
unknown .code:n =
\msg_error:nn { piton } { Unknown~key~for~PitonOptions }
}
@@ -1604,13 +1880,30 @@ version 2005/12/01 or later.
%
% \bigskip
% \begin{macrocode}
-\msg_new:nnn { piton } { Unknown~key~for~PitonOptions }
+\msg_new:nnnn { piton } { Unknown~key~for~PitonOptions }
{
Unknown~key. \\
- The~key~'\l_keys_key_str'~is~unknown~for~\token_to_str:N \PitonOptions.~The~
- available~keys~are:~all-line-numbers,~auto-gobble,~env-gobble,~gobble,~
- left-margin,~line-numbers,~resume,~show-spaces,~slim,~splittable~and~tab-size.\\
- If~you~go~on,~that~key~will~be~ignored.
+ The~key~'\l_keys_key_str'~is~unknown~for~\token_to_str:N \PitonOptions.~
+ It~will~be~ignored.\\
+ For~a~list~of~the~available~keys,~type~H~<return>.
+ }
+ {
+ The~available~keys~are~(in~alphabetic~order):~
+ all-line-numbers,~
+ auto-gobble,~
+ break-lines,~
+ continuation-symbol,~
+ continuation-symbol-on-indentation,~
+ end-of-broken-line,~
+ env-gobble,~gobble,~
+ left-margin,~
+ indent-broken-lines,~
+ line-numbers,~
+ resume,~
+ show-spaces,~
+ slim,~
+ splittable~
+ and~tab-size.\\
}
% \end{macrocode}
%
@@ -1686,27 +1979,54 @@ version 2005/12/01 or later.
% \bigskip
% \subsubsection{The main commands and environments for the final user}
%
+% \medskip
+% \begin{macrocode}
+\NewDocumentCommand { \piton } { }
+ { \peek_meaning:NTF \bgroup \@@_piton_standard \@@_piton_verbatim }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\NewDocumentCommand { \@@_piton_standard } { m }
+ {
+ \group_begin:
+ \ttfamily
+ \cs_set_eq:NN \\ \c_backslash_str
+ \cs_set_eq:NN \% \c_percent_str
+ \cs_set_eq:NN \{ \c_left_brace_str
+ \cs_set_eq:NN \} \c_right_brace_str
+ \cs_set_eq:NN \$ \c_dollar_str
+ \cs_set_protected:Npn \@@_begin_line: { }
+ \cs_set_protected:Npn \@@_end_line: { }
+ \lua_now:n { piton.pitonParse(token.scan_string()) } { #1 }
+ \group_end:
+ }
+% \end{macrocode}
+%
+%
% \begin{macrocode}
-\NewDocumentCommand { \piton } { v }
+\NewDocumentCommand { \@@_piton_verbatim } { v }
{
\group_begin:
\ttfamily
\cs_set_protected:Npn \@@_begin_line: { }
\cs_set_protected:Npn \@@_end_line: { }
- \lua_now:n { piton.Parse(token.scan_argument()) } { #1 }
+ \lua_now:n { piton.Parse(token.scan_string()) } { #1 }
\group_end:
}
% \end{macrocode}
%
-% \medskip
-% The command |\@@_piton:n| does \emph{not} take in its argument verbatim.
+% \bigskip
+% The following command is not a user command. It will be used when you will
+% have to ``rescan'' some chunks of Python code. For example, if will be the
+% initial value of the Piton style |InitialValues| (the default values of the
+% arguments of a Python function).
% \begin{macrocode}
\cs_new_protected:Npn \@@_piton:n #1
{
\group_begin:
- \cs_set_protected:Npn \@@_begin_line: { }
- \cs_set_protected:Npn \@@_end_line: { }
- \lua_now:n { piton.Parse(token.scan_argument()) } { #1 }
+ \cs_set_protected:Npn \@@_begin_line: { }
+ \cs_set_protected:Npn \@@_end_line: { }
+ \lua_now:n { piton.Parse(token.scan_string()) } { #1 }
\group_end:
}
% \end{macrocode}
@@ -1761,34 +2081,27 @@ version 2005/12/01 or later.
% If the final user has used both |left-margin=auto| and |line-numbers| or
% |all-line-numbers|, we have to compute the width of the maximal number of
% lines at the end of the composition of the listing to fix the correct value to
-% |left-margin|. Par convention, when |left-margin=auto|, the dimension
-% |\l_@@_left_margin_dim| is set to -1~cm.
+% |left-margin|.
% \begin{macrocode}
- \dim_compare:nNnT \l_@@_left_margin_dim < \c_zero_dim
+ \bool_lazy_and:nnT \l_@@_left_margin_auto_bool \l_@@_line_numbers_bool
{
- \bool_if:NT \l_@@_line_numbers_bool
- {
- \hbox_set:Nn \l_tmpa_box
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \bool_if:NTF \l_@@_all_line_numbers_bool
{
- \footnotesize
- \bool_if:NTF \l_@@_all_line_numbers_bool
- {
- \int_to_arabic:n
- { \g_@@_visual_line_int + \l_@@_nb_lines_int }
- }
- {
- \lua_now:n
- { piton.CountNonEmptyLinesFile(token.scan_argument()) }
- { #2 }
- \int_to_arabic:n
- {
- \g_@@_visual_line_int +
- \l_@@_nb_non_empty_lines_int
- }
- }
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_lines_int }
+ }
+ {
+ \lua_now:n
+ { piton.CountNonEmptyLinesFile(token.scan_argument()) }
+ { #2 }
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_non_empty_lines_int }
}
- \dim_set:Nn \l_@@_left_margin_dim { \box_wd:N \l_tmpa_box + 0.5em }
}
+ \dim_set:Nn \l_@@_left_margin_dim { \box_wd:N \l_tmpa_box + 0.5em }
}
% \end{macrocode}
% Now, the main job.
@@ -1844,36 +2157,30 @@ version 2005/12/01 or later.
% to compute the width of the maximal number of lines at the end of the
% environment to fix the correct value to |left-margin|.
% \begin{macrocode}
- \dim_compare:nNnT \l_@@_left_margin_dim < \c_zero_dim
+ \bool_lazy_and:nnT \l_@@_left_margin_auto_bool \l_@@_line_numbers_bool
{
- \bool_if:NT \l_@@_line_numbers_bool
+ \bool_if:NTF \l_@@_all_line_numbers_bool
{
- \bool_if:NTF \l_@@_all_line_numbers_bool
- {
- \hbox_set:Nn \l_tmpa_box
- {
- \footnotesize
- \int_to_arabic:n
- { \g_@@_visual_line_int + \l_@@_nb_lines_int }
- }
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_lines_int }
}
- {
- \lua_now:n
- { piton.CountNonEmptyLines(token.scan_argument()) }
- { ##1 }
- \hbox_set:Nn \l_tmpa_box
- {
- \footnotesize
- \int_to_arabic:n
- {
- \g_@@_visual_line_int +
- \l_@@_nb_non_empty_lines_int
- }
- }
+ }
+ {
+ \lua_now:n
+ { piton.CountNonEmptyLines(token.scan_argument()) }
+ { ##1 }
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_non_empty_lines_int }
}
- \dim_set:Nn \l_@@_left_margin_dim
- { \box_wd:N \l_tmpa_box + 0.5 em }
}
+ \dim_set:Nn \l_@@_left_margin_dim
+ { \box_wd:N \l_tmpa_box + 0.5 em }
}
% \end{macrocode}
% Now, the main job.
@@ -2087,7 +2394,7 @@ version 2005/12/01 or later.
% If the key |math-comments| has been used at load-time, we change the style
% |Comment.Math| which should be considered only at an ``internal style''.
% However, maybe we will document in a future version the possibility to write
-% change the style \emph{locally} in a document).
+% change the style \emph{locally} in a document)].
% \begin{macrocode}
\bool_if:NT \c_@@_math_comments_bool
{ \SetPitonStyle { Comment.Math } }
@@ -2326,6 +2633,12 @@ local Tab = P "\t" * Lc ( '\\l_@@_tab_tl' )
% \end{macrocode}
%
% \bigskip
+% \begin{macrocode}
+local SpaceIndentation =
+ Lc ( '\\@@_an_indentation_space:' ) * K " "
+% \end{macrocode}
+%
+% \bigskip
% The following \textsc{lpeg} |EOL| is for the end of lines.
% \begin{macrocode}
local EOL =
@@ -2343,6 +2656,8 @@ local EOL =
% \begin{macrocode}
Lc ( '\\@@_end_line: \\@@_newline: \\@@_begin_line:' )
)
+ *
+ SpaceIndentation ^ 0
% \end{macrocode}
%
% \bigskip
@@ -2429,7 +2744,7 @@ local Decorator = K ( P "@" * letter^1 , 'Name.Decorator' )
% style |Name.Class|).
%
% \smallskip
-% Example:\enskip \piton|class myclass:|
+% Example:\enskip \piton{class myclass:}
% \begin{macrocode}
local DefClass =
K ( P "class" , 'Keyword' ) * Space * K ( identifier , 'Name.Class' )
@@ -2446,14 +2761,14 @@ local DefClass =
% module and its alias must be formatted with the \pkg{piton} style |Name.Namespace|.
%
% \smallskip
-% Example:\enskip \piton|import numpy as np|
+% Example:\enskip \piton{import numpy as np}
%
% \smallskip
% Moreover, after the keyword |import|, it's possible to have a comma-separated
% list of modules (if the keyword |as| is not used).
%
% \smallskip
-% Example:\enskip \piton|import math, numpy|
+% Example:\enskip \piton{import math, numpy}
% \begin{macrocode}
local ImportAs =
K ( P "import" , 'Keyword' )
@@ -2477,7 +2792,7 @@ local ImportAs =
% |Keyword| and must \emph{not} be catched by the \textsc{lpeg} |ImportAs|.
%
% \smallskip
-% Example:\enskip \piton|from math import pi|
+% Example:\enskip \piton{from math import pi}
%
% \smallskip
% \begin{macrocode}
@@ -2514,7 +2829,7 @@ local FromImport =
% style of the encompassing string, that is to say |String.Short| or
% |String.Long|.} in that interpolation:
%
-% \piton|f'Total price: {total+1:.2f} €'|
+% \piton{f'Total price: {total+1:.2f} €'}
%
% \medskip
% The following \textsc{lpeg} |SingleShortInterpol| (and the three variants)
@@ -2797,7 +3112,7 @@ local Expression =
% parameters (that is to say the \emph{argspec}) in the definition of a Python
% function. For example, in the line of code
% \begin{center}
-% \piton|def MyFunction(a,b,x=10,n:int): return n|
+% \piton{def MyFunction(a,b,x=10,n:int): return n}
% \end{center}
% the \textsc{lpeg} |Params| will be used to catch the chunk\enskip |a,b,x=10,n:int|.
%
@@ -2874,7 +3189,7 @@ local DefFunction =
% \medskip
% \begingroup
% \SetPitonStyle{Dict.Value = \color{black}}
-% \piton|mydict = { 'name' : 'Paul', 'sex' : 'male', 'age' : 31 } |
+% \piton{mydict = { 'name' : 'Paul', 'sex' : 'male', 'age' : 31 } }
% \endgroup
%
% \medskip
@@ -2909,6 +3224,7 @@ local SyntaxPythonAux =
% \begin{macrocode}
Lc ( '\\@@_begin_line:' ) *
( ( space - P "\r" ) ^0 * P "\r" ) ^ -1 *
+ SpaceIndentation ^ 0 *
( ( space^1 * -1 )
+ EOL
+ Tab
@@ -2933,7 +3249,7 @@ local SyntaxPythonAux =
+ DefClass
+ Keyword * ( Space + Punct + Delim + EOL + -1)
+ Decorator
- + OperatorWord
+ + OperatorWord * ( Space + Punct + Delim + EOL + -1)
+ Builtin * ( Space + Punct + Delim + EOL + -1)
+ Identifier
+ Number
@@ -2963,6 +3279,17 @@ function piton.Parse(code)
end
% \end{macrocode}
%
+%
+% \bigskip
+% The following command will be used by the user commands |\piton|.
+% For that command, we have to undo the duplication of the symbols |#|.
+% \begin{macrocode}
+function piton.pitonParse(code)
+ local s = ( Cs ( ( P '##' / '#' + 1 ) ^ 0 ) ) : match ( code )
+ return piton.Parse(s)
+end
+% \end{macrocode}
+%
% \bigskip
% The function |ParseFile| will be used by the LaTeX command |\PitonInputFile|.
% That function merely reads the whole file (that is to say all its lines) and
@@ -3178,6 +3505,11 @@ end
%
% New keys |first-line| and |last-line| for the command |\InputPitonFile|.
%
+% \subsection*{Changes between versions 0.95 and 0.99}
+%
+% New key |break-lines| to allow breaks of the lines of code (and other keys to
+% customize the appearance).
+%
% \end{document}
%
%