% -*- coding: utf-8 ; -*- This file should be compiled with LuaLaTeX only
\documentclass{article}

\usepackage{geometry}
\geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}}
\usepackage{fontspec}
\usepackage[dvipsnames,svgnames]{xcolor}
\usepackage{caption,tabularx,luacolor,lua-ul,upquote,varwidth}
\usepackage[framemethod=tikz]{mdframed}
\usepackage{tcolorbox}
\tcbuselibrary{skins,breakable}
\tcbset{enhanced}
\def\emphase{\bgroup\color{RoyalPurple}\let\next=}

% We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb
% because we don't want small elements in verbatim to be colored in gray
\usepackage{shortvrb}
\MakeShortVerb{\|}

\usepackage{fancyvrb}
\fvset{commandchars=\~\#\@,formatcom=\color{gray}}

\usepackage[executable=python3.exe]{pyluatex}

\usepackage{underscore}

\usepackage{booktabs}

\captionsetup{labelfont = bf}
\usepackage{ragged2e}

\NewDocumentCommand {\pkg} {m} {\textsf{#1}}
\NewDocumentCommand {\cls} {m} {\textsf{#1}}

\usepackage[footnotehyper]{piton} 
\PitonOptions
  { 
    splittable = 4 ,
    math-comments ,
    begin-escape = ! ,
    end-escape = ! ,
    begin-escape-math = \( , 
    end-escape-math = \) ,
    detected-commands = { highLight , footnote , emph , textsl , textbackslash } ,
    vertical-detected-commands = newpage ,
    raw-detected-commands = { NameTable , rowcolor } 
  }

\ExplSyntaxOn

\dim_new:N \l__pantigny_width_dim 

\keys_define:nn { pantigny }
  { width .dim_set:N = \l__pantigny_width_dim }

\NewPitonEnvironment { Code } { O { } }
  {
    \SetPitonStyle{ Number = , Comment = , String = }
    \PitonOptions{language = minimal}
    \char_set_catcode_other:N |
    \cs_set_eq:NN \emph \emphase
    \dim_zero:N \l__pantigny_width_dim 
    \keys_set:nn { pantigny } { #1 }
    \color{gray}
    \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim 
      { 
        \PitonOptions { width = \l__pantigny_width_dim } 
        \begin{minipage}[c]{\l__pantigny_width_dim} 
      }
  }
  { \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim 
      { \end{minipage} }
  }

\ExplSyntaxOff  
  

\parindent 0pt
\skip\footins = 2\bigskipamount

\def\CC{{C\nolinebreak[4]\hspace{-.05em}\raisebox{.4ex}{\tiny\bfseries ++}}}

\usepackage{makeidx}
\makeindex

\NewDocumentCommand{\indexcommand}{m}{\index{#1@\texttt{\textbackslash #1}}}

\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}}}

\usepackage[hyperfootnotes = false]{hyperref}
\usepackage{bookmark}

\VerbatimFootnotes
  
\catcode`\" = 11

\begin{document}

\title{The package \pkg{piton}\thanks{This document corresponds to the
version~\PitonFileVersion\space of \pkg{piton}, at the date of~\PitonFileDate.}} 
\author{F. Pantigny \\ \texttt{fpantigny@wanadoo.fr}}

\maketitle

\begin{abstract}
The package \pkg{piton} provides tools to typeset computer listings, with
syntactic highlighting, by using the Lua library LPEG. It requires LuaLaTeX.
\end{abstract}


\section{Presentation}



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 computer
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}|.

\bigskip

   \begin{Piton}
from math import pi

def arctan(x,n:int=10):
   """Compute the mathematical value of arctan(x)

   n is the number of terms in the sum
   """
    if x < 0:
        return -arctan(-x) # recursive call
    elif x > 1: 
        return pi/2 - arctan(1/x) 
        #> (we have used that $\arctan(x)+\arctan(1/x)=\frac{\pi}{2}$ for $x>0$)\footnote{This LaTeX escape has been done by beginning the comment by \ttfamily\#>.}
    else: 
        s = 0
        for k in range(n):
            s += (-1)**k/(2*k+1)*x**(2*k+1)
        return s 
   \end{Piton}


\medskip
The main alternatives to the package \pkg{piton} are probably the packages
\pkg{listings} and \pkg{minted}.

\medskip
The name of this extension (\pkg{piton}) has been chosen arbitrarily by
reference to the pitons used by the climbers in mountaineering.


\section{Installation}

The package \pkg{piton} is contained in two files: |piton.sty| and |piton.lua|
(the LaTeX file |piton.sty| loaded by |\usepackage| will load the Lua file
|piton.lua|). Both files must be in a repertory where LaTeX will be able to
find them, for instance in a |texmf| tree. However, the best is to install
\pkg{piton} with a TeX distribution such as MiKTeX, TeX Live or MacTeX.

\medskip
Note that the character \emph{quote} (U+0027 : \verb|'|) is never transformed by
\pkg{piton} in an apostrophe U+2019. There is no point loading the package
\pkg{upquote}.

\section{Use of the package}

The package \pkg{piton} must be used with \textbf{LuaLaTeX exclusively}: if
another LaTeX engine (|latex|, |pdflatex|, |xelatex|,\dots ) is used, a fatal
error will be raised.

\subsection{Loading the package}

The package \pkg{piton} should be loaded by: |\usepackage{piton}|.

\smallskip
The package \pkg{piton} uses and \emph{loads} the package \pkg{xcolor}. It
does not use any exterior program.

\subsection{Choice of the computer language}

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 two special languages called |minimal| and |verbatim|;
\item the languages defined by the end 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 languages supported
natively by \pkg{piton}).
\end{itemize}



\smallskip
By default, the language used is Python.

\smallskip
\index{language (key)}
It's possible to change the current language with the command |\PitonOptions|
and its key \Definition{language}: |\PitonOptions{language = OCaml}|.

\smallskip
In fact, for \pkg{piton}, the names of the computer languages are always
\textbf{case-insensitive}. In this example, we might have written |Ocaml| or
|ocaml|. 

\smallskip
For the developers, let's say that the name of the current language is stored
(in lower case) in the L3 public variable |\l_piton_language_str|.

\smallskip
In what follows, we will speak of Python, but the features described also
apply to the other languages.

\subsection{The tools provided to the user}

\indexenv{Piton}

The package \pkg{piton} provides several tools to typeset computer listings: the
command |\piton|, the environment |{Piton}| and the command |\PitonInputFile|.

\begin{itemize}
\item The command \DefinitionCommand{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 \Definition{\{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| or its friends:
cf.~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.

\item The command \DefinitionCommand{PitonInputFile} is used to insert and
typeset an external file: cf.~\ref{PitonInputFile}
p.~\pageref{PitonInputFile}.


\end{itemize}

\subsection{The double syntax of the command \textbackslash piton}

\indexcommand{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 LaTeX command |\verb|, that is to say with the argument delimited by two identical
characters (e.g.: \verb!\piton|...|! or \verb!\piton+...+!). 

\begin{itemize}
\item {\color{blue} \textsf{Syntax} \verb|\piton{...}|}

\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 (and also
the character of end of line),

{\color{cyan} but the command |\|␣ is provided to force the insertion of a space};

\item it's not possible to use |%| inside the argument,

{\color{cyan} but the command |\%| is provided to insert a |%|};

\item the braces must be appear by pairs correctly nested

{\color{cyan} but the commands |\{| and |\}| are provided for individual braces};

\item the LaTeX commands\footnote{That concerns the commands beginning with a
backslash but also the active characters (with catcode equal to 13). } of the
argument are fully expanded (in the TeX meaning) and not executed,

{\color{cyan} so, it's possible to use |\\| to insert a backslash}.
\end{itemize}


The other characters (including |#|, |^|, |_|, |&|, |$| and |@|) %$
must be inserted without backslash.

\bigskip
\begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l}
\omit Examples : \hfil \\
\noalign{\vskip1mm}
\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{c="#" \ \ \ # an affectation }| & 
\piton{c="#" \ \ \ # an affectation } \\
\verb|\piton{MyDict = {'a': 3, 'b': 4 }}| &
\piton{MyDict = {'a': 3, 'b': 4 }}
\end{tabular}

\bigskip
It's possible to use the command |\piton| with that syntax in the arguments of
a LaTeX command.\footnote{For example, it's possible to use the command
|\piton| in a footnote. Example : \piton{s = 123}.}

However, since the argument is expanded (in the TeX sens), one should take
care not using in its argument \emph{fragile} commands (that is to say
commands which are neither \emph{protected} nor \emph{fully expandable}).

\bigskip
\item {\color{blue} \textsf{Syntax} \verb!\piton|...|!}

\nobreak
When the argument of the command |\piton| is provided between two identical
characters (all the characters are allowed except |%|, |\|, |#|, |{|, |}| and
the space), 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

\begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l}
\omit Examples : \hfil \\
\noalign{\vskip1mm}
\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}


\subsection{The keys of the command \textbackslash PitonOptions}


\indexcommand{PitonOptions}

The command |\PitonOptions| takes in as argument a comma-separated list of
\textsl{key=value} pairs. The scope of the settings done by that command is
the current TeX group.\footnote{We remind that a LaTeX environment is, in
particular, a TeX group.}

These keys may also be applied to an individual environment |{Piton}| (between
square brackets).

\begin{itemize}
\item The key \Definition{language} specifies which computer language is
considered (that key is case-insensitive). It's possible to use the name of
the six built-in languages (|Python|, |OCaml|, |C|, |SQL|, |minimal| and
|verbatim|) or the name of a language defined by the user with
|\NewPitonLanguage| (cf.~part~\ref{NewPitonLanguage},
p.~\pageref{NewPitonLanguage}).   

The initial value is |Python|.

\item \index{font-command}
The key \Definition{font-command} contains instructions of font which will be
inserted at the beginning of all the elements composed by \pkg{piton} (without
surprise, these instructions are not used for the so-called ``LaTeX comments'').

The initial value is |\ttfamily| and, thus, \pkg{piton} uses by default the
current monospace font.

\item \colorbox{yellow!50}{\bfseries New 4.12}

The key \Definition{font-command +} puts some intructions on the right of the
parameter |font-command|. The name of that parameter contains a space in order
to be able to write something like, for example,
|\PitonOptions{font-command += \bfseries}|. Nevertheless, this space is optional.

\item \index{gobble}\label{gobble} The key \Definition{gobble} takes in as
value a positive integer~$n$: the first $n$ characters are discarded (before
the process of highlighting of the code) for each line of the environment
|{Piton}|. These characters are not necessarily spaces.

When the key |gobble| is used without value, it is equivalent to the key
|auto-gobble|, that we describe now.

\item \index{auto-gobble}\index{gobble!auto-gobble} When the key
\Definition{auto-gobble} is in force, the extension \pkg{piton} computes the
minimal value $n$ of the number of consecutive spaces beginning each (non
empty) line of the environment |{Piton}| and applies |gobble| with that value
of~$n$.

\item \index{env-gobble}\index{gobble!env-gobble}
When the key \Definition{env-gobble} is in force, \pkg{piton} analyzes the last
line of the environment |{Piton}|, that is to say the line which contains
|\end{Piton}| and determines whether that line contains only spaces followed
by the |\end{Piton}|. If we are in that situation, \pkg{piton} computes the
number~$n$ of spaces on that line and applies |gobble| with that value of~$n$.
The name of that key comes from \emph{environment gobble}: the effect of
gobble is set by the position of the commands
\texttt{\textbackslash begin\{Piton\}}
and \texttt{\textbackslash end\{Piton\}} which delimit the current environment. 

\item \index{line-numbers} The key \Definition{line-numbers} activates the
line numbering in the environments |{Piton}| and in the listings resulting
from the use of |\PitonInputFile|.

In fact, the key |line-numbers| has several subkeys.
\begin{itemize}
\item With the key \Definition{line-numbers/skip-empty-lines}, the empty lines
(which contains only spaces) are considered as non existent for the line
numbering (if the key |/absolute|, described below, is in force, the key
|/skip-empty-lines| is no-op in |\PitonInputFile|). The initial value of that
key is |true| (and not |false|).\footnote{For the language Python, the empty
lines in the docstrings are taken into account (by design).}

\item \colorbox{yellow!50}{\textbf{New 4.10}}

\nobreak
The key \Definition{line-numbers/step} should be used when we don't want to print all the
numbers of line. If $n$ is the value of that key, only one number out of~$n$
will be printed. Of course, the initial value is 1.

\item With the key \Definition{line-numbers/label-empty-lines}, the labels
(that is to say the numbers) of the empty lines are displayed. If the key
|/skip-empty-line| is in force, the clé |/label-empty-lines| is no-op. The
initial value of that key is~|true|.\footnote{When the key
|split-on-empty-lines| is in force, the labels of the empty lines are never printed.}

\item With the key \Definition{line-numbers/absolute}, in the listings
generated in |\PitonInputFile|, the numbers of the lines displayed are
\emph{absolute} (that is to say: they are the numbers of the lines in the
file). That key may be useful when |\PitonInputFile| is used to insert only a
part of the file (cf. part~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}).
The key |/absolute| is no-op in the environments |{Piton}| and those created
by |\NewPitonEnvironment|.

\item The key \Definition{line-numbers/start} requires that the line numbering
begins to the value of the key. 

\item With the key \Definition{line-numbers/resume}, the counter of lines is
not set to zero at the beginning of each environment |{Piton}| or use of
|\PitonInputFile| as it is otherwise. That allows a numbering of the lines
across several environments.

\item The key \Definition{line-numbers/sep} is the horizontal distance between
the numbers of lines (inserted by |line-numbers|) and the beginning of the
lines of code. The initial value is 0.7~em.

\item The key \Definition{line-numbers/format} is a list of tokens which are inserted before
the number of line in order to format it. It's possible to put, \emph{at the
end} of the list, a LaTeX command with one argument, such as, for example,
|\fbox|. 

The initial value is |\footnotesize\color{gray}|.

\item \colorbox{yellow!50}{\textbf{New 4.11}}

\nobreak
The key \Definition{line-numbers/position} specifies the position of the numbers.
Two values are possible: |left| and |right|. The initial value is |left|.
\end{itemize}

For convenience, a mechanism of factorisation of the prefix |line-numbers| is
provided. That means that it is possible, for instance, to write:

\begin{Code}
\PitonOptions
  {
    line-numbers = 
      { 
        skip-empty-lines = false ,
        label-empty-lines = false ,
        sep = 1 em ,
        format = \footnotesize \color{blue}
      }
  }
\end{Code}

Be careful : the previous code is not enough to print the numbers of lines.
For that, one also has to use the key |line-numbers| is a absolute way, that
is to say without value.

\item \index{left-margin} The key \Definition{left-margin} corresponds to a
margin on the left. That key may be useful in conjunction with the key
|line-numbers| if one does not want the numbers in an overlapping position on
the left. 

It's possible to use the key |left-margin| with the special value |auto|. With that
value, if the key |line-numbers| is in force, 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 \index{right-margin}
\colorbox{yellow!50}{\textbf{Nouveau 4.11}}

\nobreak
The key |right-margin| is similar to the previous one, but for the margin on the
right.

\item \index{background-color} \label{background-color} The key
\Definition{background-color} sets the background color of the environments
|{Piton}| and the listings produced by |\PitonInputFile| (it's possible to fix
the width of that background with the key |width| or the key |max-width|
described below).

The key |background-color| accepts a color
defined «on the fly». For example, it's possible to write
|background-color = [cmyk]{0.1,0.05,0,0}|.

\smallskip
The key |background-color| supports also as value a \emph{list} of colors. In
this case, the successive rows are colored by using the colors of the list in
a cyclic way.

\smallskip
In that list, the special color \Definition{none} may be used to specify no
color at all.

\emph{Example} : |\PitonOptions{background-color = {gray!15,none}}|

\item \index{rounded-corners} 
It's possible to use the key \Definition{rounded-corners} to require rounded
corners for the colored panels drawn by the key |background-color| The initial
value of that is $0$~pt, which means that the corners are not rounded. If the
key |rounded-corners| is used, the extension \pkg{tikz} must be loaded because
those rounded corners are drawn by using \pkg{tikz}. If \pkg{tikz} is not
loaded, an error will be raised at the first use of the key |rounded-corners|.

The default value of the key |rounded-corners| is $4$~pt.\footnote{This value is the
initial value of the \emph{rounded corners} of TikZ.}

\item \index{prompt-background-color} With the key
\Definition{prompt-background-color}, \pkg{piton} adds a 
color background to the lines beginning with the prompt ``|>>>|'' (and its
continuation ``|...|'') characteristic of the Python consoles with
\textsc{repl} (\emph{read-eval-print loop}).

The initial value is: |gray!15|

\item \index{width} \label{width} The key \Definition{width} fixes the width
of the listing in the \textsc{pdf}. The initial value of that parameter
is the current value of |\linewidth| (LaTeX parameter which corresponds to the
width of the lines of text).

That parameter is used for:
\begin{itemize}
\item the breaking the lines which are too long (except, of course, when the key
|break-lines| is set to false: cf.~p.~\pageref{line-breaks});
\item the width of the backgrounds specified by the keys |background-color| and
|prompt-background-color| described below;
\item the width of the colored backgrounds added by |\rowcolor|
(cf.~p.~\pageref{rowcolor});
\item the width of the LaTeX box created by the key |box| (cf. p.~\pageref{box});
\item the width of the graphical box created by the key |tcolorbox|
(cf.~p.~\pageref{tcolorbox}).
\end{itemize}

\item \index{max-width}

The key \Definition{max-width} is similar to the key |width| but it fixes the
\emph{maximal} width of the lines. If all the lines of the listing are shorter
than the value provided to |max-width|, the parameter |width| will be equal to
the maximal length of the lines of the listing, that is to say the natural width of
the listing.

For legibility of the code, |width=min| is a shortcut for |max-width=\linewidth|.


\item \index{show-spaces-in-strings} When the key
\Definition{show-spaces-in-strings} is activated, the spaces in the 
strings of characters\footnote{With the language Python that feature applies
only to the short strings (delimited by~\verb|'| or~\verb|"|) and, in
particular, it does not apply for the \emph{doc strings}. In OCaml, that
feature does not apply to the \emph{quoted strings}.} are replaced by the
character~␣ (U+2423 : \textsc{open box}). Of course, that character~U+2423
must be present in the monospace font which is used.\footnote{The initial
value of |font-command| is |\ttfamily| and, thus,  by default, \pkg{piton}
merely uses the current monospace font.}

\nobreak
\begingroup
\PitonOptions{show-spaces-in-strings} Example : 
\piton|my_string = 'Very good answer'| \endgroup

With the key \index{show-spaces} \Definition{show-spaces}, all the spaces are
replaced by U+2423 (and no line break can occur on those ``visible spaces'',
even when the key |break-lines|\footnote{cf. \ref{line-breaks}
p.~\pageref{line-breaks}} is in force). By the way, one should remark that all
the trailing spaces (at the end of a line) are deleted by \pkg{piton} --- and,
therefore, won't be represented by~␣. Moreover, when the key |show-spaces| is
in force, the tabulations at the beginning of the lines are represented by arrows.
\end{itemize}

\bigskip
\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
~emphase&\begin{Piton}[language=C,line-numbers,gobble,background-color=gray!15@
~emphase&              rounded-corners,width=min,splittable=4]@
    void bubbleSort(int arr[], int n) {
        int temp;
        int swapped;
        for (int i = 0; i < n-1; i++) {
            swapped = 0;
            for (int j = 0; j < n - i - 1; j++) {
                if (arr[j] > arr[j + 1]) {
                    temp = arr[j];
                    arr[j] = arr[j + 1];
                    arr[j + 1] = temp;
                    swapped = 1; 
                }
            }
            if (!swapped) break;
        }
    }   
~emphase&~textbackslash&@end{Piton}@
\end{Verbatim}
\endgroup

\begingroup
\PitonOptions{language=C,line-numbers,gobble=4,background-color = gray!15,
   rounded-corners,width=min}
    \begin{Piton}
    void bubbleSort(int arr[], int n) {
        int temp;
        int swapped;
        for (int i = 0; i < n-1; i++) {
            swapped = 0;
            for (int j = 0; j < n - i - 1; j++) {
                if (arr[j] > arr[j + 1]) {
                    temp = arr[j];
                    arr[j] = arr[j + 1];
                    arr[j + 1] = temp;
                    swapped = 1; 
                }
            }
            if (!swapped) break;
        }
    }   
    \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}

\label{styles}
\index{styles (concept of \pkg{piton})}

\subsubsection{Notion of style}

The package \pkg{piton} provides the command
\DefinitionCommand{SetPitonStyle} to customize the different styles used to
format the syntactic elements of the computer 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}
The command |\SetPitonStyle| takes in as argument a comma-separated list of
\textsl{key=value} pairs. The keys are names of styles and the value are LaTeX
formatting instructions.

\bigskip
These LaTeX instructions must be formatting instructions such as
|\color{ }|, |\bfseries|, |\slshape|, etc. (the commands of this kind are
sometimes called \emph{semi-global} commands). It's also possible to put,
\emph{at the end of the list of instructions}, a LaTeX command taking exactly
one argument.

\bigskip
Here an example which changes the style used to highlight, in the definition
of a Python function, the name of the function which is defined. That code
uses the command |\highLight| of \pkg{lua-ul} (that package requires also the
package \pkg{luacolor}).

\begin{Code}
\SetPitonStyle
  { Name.Function = \bfseries \highLight[red!30] }
\end{Code}

In that example, |\highLight[red!30]| must be considered as the name of a
LaTeX command which takes in exactly one argument, since, usually, it is used
with |\highLight[red!30]{...}|.

\medskip
\begingroup
\SetPitonStyle 
  { Name.Function = \bfseries \highLight[red!30] }
With that setting, we will have : \piton{def cube(x) : return x * x * x }
\endgroup

\bigskip
The different styles, and their use by \pkg{piton} in the different languages
which it supports (Python, OCaml, C, SQL, ``|minimal|'' and ``|verbatim|''),
are described in the part \ref{Semantic}, starting at the page
\pageref{Semantic}.  


\bigskip
\indexcommand{PitonStyle}
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. That command is \emph{fully expandable} (in the TeX sens).

\smallskip
For example, it's possible to write |{\PitonStyle{Keyword}{function}}| and we
will have the word {\PitonStyle{Keyword}{function}} formatted as a keyword.

\smallskip
The syntax |{\PitonStyle{|\textsl{\texttt{style}}|}{...}}| is mandatory in
order to be able to deal both with the semi-global commands and the commands
with arguments which may be present in the definition of the style
\texttt{\textsl{style}}. 

\bigskip
\subsubsection{Global styles and local styles}

A style may be defined globally with the command |\SetPitonStyle|. That means
that it will apply to all the computer languages that use that style.

\bigskip
For example, with the command
\begin{Verbatim}
\SetPitonStyle{Comment = \color{gray}}
\end{Verbatim}
all the comments will be composed in gray in all the listings, whatever
computer 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 computer
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 computer languages are
case-insensitive.}

\bigskip
For example, with the command
\begin{Verbatim}
\SetPitonStyle~emphase#[SQL]@{Keyword = \color[HTML]{006699} \bfseries \MakeUppercase}
\end{Verbatim}
the keywords in the SQL listings will be composed in capital letters, even if
they appear in lower case in the LaTeX source (we recall that, in SQL, the
keywords are case-insensitive).

\bigskip
As expected, if a computer language uses a given style and if that style has
no local definition for that language, the global version is used. That notion
of ``global style'' has no link with the notion of global definition in TeX
(the notion of \emph{group} in TeX).\footnote{As regards the TeX groups, the
definitions done by \texttt{\textbackslash SetPitonStyle} are always local.}

\bigskip
The package \pkg{piton} itself (that is to say the file |piton.sty|) defines
all the styles globally. 

\bigskip

\bigskip
\subsubsection{The command \textbackslash rowcolor}

\label{rowcolor}
\indexcommand{rowcolor}

\colorbox{yellow!50}{\textbf{New 4.8}}

\nobreak
\medskip
The extension \pkg{piton} provides the command \DefinitionCommand{rowcolor} which adds
a colored background to the current line (the \emph{whole} line and not only the part with
text) which may be used in the styles.

\smallskip
The command |\rowcolor| has a syntax similar to the classical command |\color|. For example,
it's possible to write |\rowcolor[rgb]{0.9,1,0.9}|.

\smallskip
The command |\rowcolor| is protected against the TeX expansions.

\smallskip
Here is an example for the language Python where we modify the style |String.Doc|
of the ``documentation strings'' in order to have a colored background.

% here, don't use {Code}
\begin{Verbatim}
~emphase#\SetPitonStyle{String.Doc = \rowcolor{gray!15}\color{black!80}}@
\begin{Piton}[width=min]
def square(x):
    """Computes the square of x
       Second line of the documentation"""
    return x*x
\end{Piton}
\end{Verbatim}


\bigskip
\begingroup
\SetPitonStyle{String.Doc = \rowcolor{gray!15}\color{black!80}}
\begin{Piton}[width=min]
def square(x):
    """Computes the square of x
       Second line of the documentation"""
    return x*x
\end{Piton}
\endgroup


\bigskip
If the command |\rowcolor| appears (through a style of \pkg{piton}) inside a
command |\piton|, it is no-op (as expected).


\subsubsection{The style UserFunction}

\index{UserFunction (style)}

The extension \pkg{piton} provides a special style called~|UserFunction|.
That style applies to the names of the functions previously defined by the user
(for example, in Python, these names are those following the keyword \piton{def}
in a previous listing). The initial value of that style |\PitonStyle{Identifier}|
and, therefore, the names of the functions are formatted like the other identifiers
(that is to say, by default, with no special formatting except the features provided
in |font-command|). However, it's possible to change the value of that style, as any
other style, with the command |\SetPitonStyle|.

\medskip
In the following example, we tune the styles |Name.Function| and |UserFunction|
so as to have clickable names of functions linked to the definition of the function.

\begingroup

\NewDocumentCommand{\MyDefFunction}{m}{\hypertarget{piton:#1}{\color[HTML]{CC00FF}{#1}}}
\NewDocumentCommand{\MyUserFunction}{m}{\hyperlink{piton:#1}{#1}}

\SetPitonStyle
  {
    Name.Function = \MyDefFunction ,
    UserFunction = \MyUserFunction
  }

\medskip
\begin{Code}
\NewDocumentCommand{\MyDefFunction}{m}
   {\hypertarget{piton:#1}{\color[HTML]{CC00FF}{#1}}}
\NewDocumentCommand{\MyUserFunction}{m}{\hyperlink{piton:#1}{#1}}

\SetPitonStyle{Name.Function = \MyDefFunction, \emph{UserFunction} = \MyUserFunction}
\end{Code}

\smallskip

\begin{Piton}
def transpose(v,i,j):
    x = v[i]
    v[i] = v[j]
    v[j] = x 

def passe(v):
    for in in range(0,len(v)-1):
        if v[i] > v[i+1]:
            transpose(v,i,i+1)
\end{Piton}

\endgroup


\PitonClearUserFunctions[Python]

\bigskip
\begin{small}
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 \DefinitionCommand{PitonClearUserFunctions}. When it
is used without argument, that command is applied to all the computer
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 computer languages to
which the command will be applied.\footnote{We remind that, in \pkg{piton},
the name of the computer languages are case-insensitive.}
\end{small}

\subsection{Creation of new environments}

\label{NewPitonEnvironment}
\indexcommand{NewPitonEnvironment}
\indexcommand{RenewPitonEnvironment}
\indexcommand{DeclarePitonEnvironment}
\indexcommand{ProvidePitonEnvironment}


Since the environment |{Piton}| has to catch its body in a special way (more
or less as verbatim text), it's not possible to construct new environments
directly over the environment |{Piton}| with the classical commands
|\newenvironment| (of standard LaTeX) or |\NewDocumentEnvironment| (of
LaTeX3). 

It's possible to use |\NewEnvironmentCopy| on the environment |{Piton}| but
it's not very powerful.

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
not allowed (of course)}

\medskip
There also exist three other commands \DefinitionCommand{RenewPitonEnvironment},
\DefinitionCommand{DeclarePitonEnvironment} and
\DefinitionCommand{ProvidePitonEnvironment}, similar to the corresponding
commands of L3.

\bigskip
With the following instruction, a new environment |{Python}| will be
constructed with the same behaviour as |{Piton}|:

\medskip
\begin{Code}
\emph{\NewPitonEnvironment}{Python}{O{}}{\PitonOptions{#1}}{} 
\end{Code}

\bigskip
If one wishes to format Python code in a box of \pkg{mdframed}, it's possible
to define an environment |{Python}| with the following code.

\begin{footnotesize}
\begin{Verbatim}
\usepackage[framemethod=tikz]{mdframed} % in the preamble
\end{Verbatim}
\end{footnotesize}

\begin{Code}
\emph{\NewPitonEnvironment}{Python}{}
  {\begin{mdframed}[roundcorner=3mm]}
  {\end{mdframed}}
\end{Code}

\bigskip
With this new environment |{Python}|, it's possible to write:

\begin{Code}
\emph{\begin{Python}}
def square(x):
    """Compute the square of x"""
    return x*x
\emph{\end{Python}}
\end{Code}

\NewPitonEnvironment{Python}{}
  {\begin{mdframed}[roundcorner=3mm]}
  {\end{mdframed}}

\begin{Python}
def square(x):
    """Compute the square of x"""
    return x*x
\end{Python}

\bigskip
It's possible to a similar construction with an environment of \pkg{tcolorbox}.
However, for a better cooperation between \pkg{piton} and \pkg{tcolorbox}, the
extension \pkg{piton} provides a key \pkg{tcolorbox}: cf.~p.~\pageref{tcolorbox}.


\section{Definition of new languages with the syntax of listings}

\indexcommand{NewPitonLanguage}
\label{NewPitonLanguage}
\index{listings@\pkg{listings} (extension)}

\medskip
The package \pkg{listings} is a famous LaTeX package to format computer
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 (available 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, C, SQL, |minimal| and |verbatim|),
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{small}
\begin{Verbatim}
\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}
\end{small}

\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{small}
\begin{Verbatim}
~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}
\end{small}


\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 computer languages are case-insensitive. Hence, it's possible to
write, for instance, |language=java|.}


\bigskip
\begingroup
\small
\PitonOptions{splittable-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 |\lstdefinelanguage| 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|, |alsoletter|
and |alsoother|.

For the description of those keys, we redirect the reader to the documentation
of the package \pkg{listings} (type |texdoc| |listings| in a terminal). 

\bigskip
For example, here is a language called ``LaTeX'' to format LaTeX chunks of codes:

\begin{Verbatim}
\NewPitonLanguage{LaTeX}{keywordsprefix = \ , alsoother = ~@_ }
\end{Verbatim}

Initially, the characters |@| and |_| are considered as letters because, in
many computer languages, they are allowed in the keywords and the names of
the identifiers. With \verb|alsoother = @_|, we retrieve them from the
category of the letters. 

\section{Import and export}


\subsection{Importation of a listing}

\label{PitonInputFile}

\subsubsection{The command \textbackslash PitonInputFile}

\indexcommand{PitonInputFile}

The command \DefinitionCommand{PitonInputFile} includes the content of the
file specified in argument (or only a part of that file: see below). The
extension \pkg{piton} also provides the commands
\DefinitionCommand{PitonInputFileT}, \DefinitionCommand{PitonInputFileF} and
\DefinitionCommand{PitonInputFileTF} with supplementary arguments
corresponding to the letters~|T| and~|F|. Those arguments will be executed if
the file to include has been found (letter~|T|) or not found (letter~|F|).

\smallskip
The syntax for the paths (absolute or relative) is the following one:
\begin{itemize}
\item The paths beginning by |/| are absolute.

\emph{Example} : |\PitonInputFile{/Users/joe/Documents/program.py}|

\item The paths which do not begin with |/| are relative to the current
repertory. 

\emph{Example} : |\PitonInputFile{my_listings/program.py}|
\end{itemize}

\index{path}
The key \Definition{path} of the command |\PitonOptions| specifies a
\emph{list} of paths where the files included by |\PitonInputFile| will be
searched. That list is comma separated.

As previously, the absolute paths must begin with |/|.

\bigskip
\subsubsection{Insertion of a part of a file}

\label{part-of-a-file}
\indexcommand{PitonInputFile}

The command |\PitonInputFile| inserts (with formatting) the content of a file.
In fact, it's possible to insert only \emph{a part} of that file. Two
mechanisms are provided in this aim.
\begin{itemize}
\item It's possible to specify the part that we want to insert by the numbers
of the lines (in the original file).
\item It's also possible to specify the part to insert with textual markers.
\end{itemize}
In both cases, if we want to number the lines with the numbers of the
lines in the file, we have to use the key |line-numbers/absolute|.

\bigskip
\textbf{With line numbers}

\nobreak
The command |\PitonInputFile| supports the keys \Definition{first-line} and
\Definition{last-line} in order to insert only the part of file between the
corresponding lines. Not to be confused with the key |line-numbers/start|
which fixes the first line number for the line numbering. In one sense,
|line-numbers/start| deals with the output whereas |first-line| and
|last-line| deal with the input.

\bigskip
\textbf{With textual markers}

\nobreak
\index{marker/beginning}
\index{marker/end}

In order to use that feature, we first have to specify the format of the
markers (for the beginning and the end of the part to include) with the keys
\Definition{marker-beginning} and \Definition{marker-end} (usually with the
command |\PitonOptions|). 


\medskip
Let us take a practical example.

\medskip
We assume that the file to include contains solutions to exercises of
programming on the following model.

\begin{small}
\begin{Verbatim}
~#[Exercise 1] Iterative version
def fibo(n):
    if n==0: return 0 
    else:
        u=0
        v=1
        for i in range(n-1):
            w = u+v
            u = v
            v = w
        return v
~#<Exercise 1>
\end{Verbatim}
\end{small}

The markers of the beginning and the end are the strings |#[Exercise 1]| and
|#<Exercise 1>|. The string ``|Exercise 1|'' will be called the \emph{label}
of the exercise (or of the part of the file to be included).

In order to specify such markers in \pkg{piton}, we will use the keys
|marker/beginning| and |marker/end| with the following instruction (the
character |#| of the comments of Python must be inserted with the protected
form |\#|). 

\begin{Verbatim}
\PitonOptions{ ~emphase#marker/beginning@ = \~#[~#1] , ~emphase#marker/end@ = \~#<~#1> } 
\end{Verbatim}

As one can see, |marker/beginning| is an expression corresponding to the
mathematical function which transforms the label (here |Exercise 1|) into the
the beginning marker (here |#[Exercise 1]|). The string |#1|
corresponds to the occurrences of the argument of that function, which the
classical syntax in TeX. Idem for |marker/end|.\footnote{In regard to LaTeX,
both functions must be \emph{fully expandable}.}

\bigskip 
Now, you only have to use the key \Definition{range} of |\PitonInputFile| to
insert a marked content of the file.

\smallskip
\begin{Verbatim}
\PitonInputFile[~emphase#range = Exercise 1@]{~textsl#file_name@}
\end{Verbatim}

\medskip
\begin{Piton}
def fibo(n):
    if n==0: return 0 
    else:
        u=0
        v=1
        for i in range(n-1):
            w = u+v
            u = v
            v = w
        return v
\end{Piton}

\vspace{1cm}
\index{marker/include-lines}
The key \Definition{marker/include-lines} requires the insertion of the lines
containing the markers.

\begin{Verbatim}
\PitonInputFile[~emphase#marker/include-lines@,range = Exercise 1]{~textsl#file_name@}
\end{Verbatim}

\begin{Piton}
#[Exercise 1] Iterative version
def fibo(n):
    if n==0: return 0 
    else:
        u=0
        v=1
        for i in range(n-1):
            w = u+v
            u = v
            v = w
        return v
#<Exercise 1>
\end{Piton}


\bigskip
\index{begin-range}
\index{end-range}
In fact, there exist also the keys \Definition{begin-range} and
\Definition{end-range} to insert several marked contents at the same time.

For example, in order to insert the solutions of the exercises~3 to~5, we will
write (if the file has the correct structure!):


\begin{Verbatim}
\PitonInputFile[~emphase#begin-range = Exercise 3, end-range = Exercise 5@]{~textsl#file_name@}
\end{Verbatim}


\subsection{Exportation of a listing}

Alongside the command |\PitonInputFile|, which allows the final user to import a
listing from an external file, \pkg{piton} provides tools to export some listings
included in the \textsc{pdf} file to an external file or as joined files embedded in
\textsc{pdf} generated by LuaLaTeX.

\bigskip
\begin{itemize}
\item \index{write} The key \Definition{write} takes in as argument a name of
file (with its extension) and write the content\footnote{In fact, it's not
exactly the body of the environment but the value of |piton.get_last_code()|
which is the body without the overwritten LaTeX formatting instructions (cf.
the part~\ref{API}, p.~\pageref{API}).} of the current environment in
that file. At the first use of a file by \pkg{piton} (during a given
compilation done by LuaLaTeX), it is erased. In fact, the file is written once at
the end of the compilation of the file by LuaLaTeX.

For legibility, \pkg{piton} provides the key \Definition{no-write} (without value)
as alias for |write={}|.

\item \index{path-write} The key \Definition{path-write} specifies a path
where the files written by the key |write| will be written.

\item \index{join (key)}

The key \Definition{join} is similar to the key |write| but the files which
are created are joined (as \emph{joined files}) in the \textsc{pdf}. Be
careful: Some \textsc{pdf} readers don't provide any tool to access to these
joined files.

For legibility, \pkg{piton} provides the key \Definition{no-join} (without value)
as alias for |join={}|.

\item \index{print}
The key \Definition{print} controls whether the content of the environment is 
actually printed (with the syntactic formating) in the \textsc{pdf}. Of
course, the initial value of |print| is |true|. However, it may be useful to
use |print=false| in some circumstancies (for example, when the key |write| or
the key |join| is used).

\item \index{paperclip (key)}
\colorbox{yellow!50}{\textbf{New 4.9}}

\nobreak
The key \Definition{paperclip} will, for each environment |{Piton}|, add in the right
margin a \textsc{pdf} annotation linked with a file joined in the \textsc{pdf}
corresponding to the listing of the environment.

The value provided to the key |paperclip| is the name that will be given to the embedded
file. If no value is provided, the file will have the name \texttt{listing_\textsl{i}.txt}
where \textsl{i} is a counter incremented by \pkg{piton} each time that a new file is
created by use of |paperclip| without value.

\medskip
\begin{Code}
\begin{Piton}[\emph{paperclip},background-color=gray!15]
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}    
\end{Code}

\medskip
\begin{Piton}[paperclip,background-color=gray!15]
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}    


\item \index{annotation (key)}
\colorbox{yellow!50}{\textbf{New 4.9}}

\nobreak
The key \Definition{annotation} will, for each environment |{Piton}|, add in the right
margin a \textsc{pdf} annotation whose content is directly the body of the
environment |{Piton}|.

\medskip
\begin{Code}
\begin{Piton}[\emph{annotation},background-color=gray!15]
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}    
\end{Code}

\medskip
\begin{Piton}[annotation,background-color=gray!15]
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}    


\end{itemize}

\section{Advanced features}

\subsection{The key ``box''}

\label{box}
\index{box (key)}

If one wishes to compose a listing in a box of LaTeX, he should use the key
|box|. That key takes in as value |c|, |t| or |b| corresponding to the parameter
of vertical position (as for the envionment |{minipage}| of LaTeX which creates also
a LaTeX box). The default value is |c| (as for |{minipage}|).

When the  key |box| is used, |width=min| is activated (except, of course, when the
key |width| or the key |max-width| is explicitly used). For the keys |width| and
|max-width|, cf.~p.~\pageref{width}.


\smallskip
\begin{Code}
\begin{center}
\PitonOptions{\emph{box},background-color=gray!15}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def cube(x):
    return x*x*x
\end{Piton}
\end{center}
\end{Code}

\begin{center}
\PitonOptions{box,background-color=gray!15}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def cube(x):
    return x*x*x
\end{Piton}
\end{center}

\vspace{1cm}
It's possible to use the key |box| with a numerical value for the key |width|.


\smallskip

\begin{Code}
\begin{center}
\PitonOptions{\emph{box,width=5cm},background-color=gray!15}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def cube(x):
    return x*x*x
\end{Piton}
\end{center}
\end{Code}

\begin{center}
\PitonOptions{box,width=5cm,background-color=gray!15}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def cube(x):
    return x*x*x
\end{Piton}
\end{center}

\vspace{1cm}
Here is an example with the key |max-width|, equal to 7~cm for both listings.

\smallskip

\begin{Code}
\begin{center}
\PitonOptions{\emph{box=t,max-width=7cm},background-color=gray!15}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def P(x):
    return 24*x**8 - 7*x**7 + 12*x**6 -4*x**5 + 4*x**3 + x**2 - 5*x + 2
\end{Piton}
\end{center}
\end{Code}

\begin{center}
\PitonOptions{box=t,max-width=7cm,background-color=gray!15}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def P(x):
    return 24*x**8 - 7*x**7 + 12*x**6 -4*x**5 + 4*x**3 + x**2 - 5*x + 2
\end{Piton}
\end{center}

\subsection{The key ``tcolorbox''}

\label{tcolorbox}
\index{tcolorbox (key)}

The extension \pkg{piton} provides a key \Definition{tcolorbox} in order to
ease the use of the extension \pkg{tcolorbox} in conjunction with the extension
\pkg{piton}. However, the extension \pkg{piton} does not load \pkg{tcolorbox} and
the end user should have loaded it. Moreover, he must load the library |breakable|
of \pkg{tcolorbox} with |\tcbuselibrary{breakable}| in the preamble of the LaTeX document.
If this is not the case, an error will be raised at the first use of the key
|tcolorbox|.

\bigskip
When the key |tcolorbox| is used, the listing formated by \pkg{piton} is
included in an environment |{tcolorbox}|. That applies both to the command
|\PitonInputFile| and the environment |{Piton}| (or, more generally, an
environment created by the dedicated command |\NewPitonEnvironment|:
cf.~p.~\pageref{NewPitonEnvironment}). If the key |splittable| of \pkg{piton}
is used (cf. p.~\pageref{page breaks}), the graphical box created by
\pkg{tcolorbox} will be splittable by a change of page.

\bigskip
In the present document, we have loaded, besides \pkg{tcolorbox} and its library
|breakable|, the library |skins| of \pkg{tcolorbox} and we have activated the
``\emph{skin}'' |enhanced|, in order to have a better appearance at the page break.


\begin{footnotesize}
\begin{Verbatim}
\tcbuselibrary{skins,breakable} % in the preamble
\tcbset{enhanced}               % in the preamble 
\end{Verbatim}
\end{footnotesize}

\begin{Verbatim}
\begin{Piton}~emphase#[tcolorbox,splittable=3]@
def square(x):
    """Computes the square of x"""
    return x*x
...
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}
\end{Verbatim}

\begin{Piton}[tcolorbox,splittable=3]
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}

Of course, if we want to change the color of the background, we won't use the key
|background-color| of \pkg{piton} but the tools provided by \pkg{tcolorbox}
(the key |colback| for the color of the background).

\bigskip
If we want to adjust the width of the graphical box to its content, we only
have to use the key |width=min| provided by \pkg{piton} (cf.
p.~\pageref{width}). It's also possible to use |width| or |max-width| with a
numerical value. The environment is splittable if the key |splittable| is used (cf.
p.~\pageref{page breaks}).

\begin{Verbatim}
\begin{Piton}~emphase#[tcolorbox,width=min,splittable=3]@
def square(x):
    """Computes the square of x"""
    return x*x
...
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}
\end{Verbatim}

\begin{Piton}[tcolorbox,width=min,splittable=3]
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}

\bigskip
If we want an output composed in a LaTeX box (despites its name, an environment
of \pkg{tcolorbox} does not always create a LaTeX box), we only have to use,
in conjunction with the key |tcolorbox|, the key |box| provided by \pkg{piton}
(cf. p.~\pageref{box}). Of course, such LaTeX box, as all the LaTeX boxes, can't
be broken by a change of page, even if the key |splittable| (cf.~p.~\pageref{splittable})
is in force.

We recall that, when the key |box| is used, |width=min| is activated (except,
when the key |width| or the key |max-width| is explicitly used).


\smallskip
\begin{Verbatim}
\begin{center}
\PitonOptions{~emphase#tcolorbox,box=t@}
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def cube(x):
    """The cube of x"""
    return x*x*x
\end{Piton}
\end{center}
\end{Verbatim}

\begin{center}
\PitonOptions{tcolorbox,box=t}%
\begin{Piton}
def square(x):
    return x*x
\end{Piton}
\hspace{1cm}
\begin{Piton}
def cube(x):
    """The cube of x"""
    return x*x*x
\end{Piton}
\end{center}



\bigskip
For a more sophisticated example of use of the key |tcolorbox|, see the example
given at the page~\pageref{examples-tcolorbox}.



\bigskip
\subsection{Line breaks and page breaks}

\label{breakable}

\subsubsection{Line breaks}

\label{line-breaks}

There are keys to control the line breaks (the possible breaking points are
the spaces, even the spaces which appear in the strings of the computer
languages).
\begin{itemize}
\item \index{break-lines!break-lines-in-piton} With the key
\Definition{break-lines-in-piton}, the line breaks are allowed in the command
|\piton{...}| (but not in the command \verb+\piton|...|+, that is to say the
command |\piton| in verbatim mode).
\item \index{break-lines!break-lines-in-Piton} With the key
\Definition{break-lines-in-Piton}, the line breaks are allowed in the
environment |{Piton}| (hence the capital letter |P| in the name) and in the
listings produced by |\PitonInputFile|. {\bfseries The initial value of that parameter is
|true| (and not |false|).}
\item \index{break-lines} The key \Definition{break-lines} is a conjunction of
the two previous keys. 
\end{itemize}

\bigskip 
The package \pkg{piton} provides also several keys to control the appearance
on the line breaks allowed by |break-lines-in-Piton|.

\begin{itemize}
\item \index{indent-broken-lines} With the key
\Definition{indent-broken-lines}, the indentation of a 
broken line is respected at carriage return (on the condition that the used
font is a monospace font and this is the case by default since the initial
value of |font-command| is |\ttfamily|).

\item The key \Definition{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 \index{continuation-symbol} The key \Definition{continuation-symbol}
corresponds to the symbol placed at each carriage return. The initial value
is: |+\;| (the command |\;| inserts a small horizontal space).

\item \index{continuation-symbol-on-indentation} 
The key \Definition{continuation-symbol-on-indentation} corresponds 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 with the following tuning:

\begin{Verbatim}
\PitonOptions{width=12cm,indent-broken-lines,background-color=gray!15}
\end{Verbatim}

\begin{center}
\PitonOptions{width=12cm,break-lines,indent-broken-lines,background-color=gray!15}
\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{center}

\bigskip
With the key \Definition{break-strings-anywhere}, the strings may be broken
anywhere (and not only on the spaces). 

\bigskip
With the key \Definition{break-numbers-anywhere}, the numbers may be broken
anywhere.

\subsubsection{Page breaks}
\label{page breaks}
\label{splittable}
\index{splittable}
\index{splittable-on-empty-lines}

By default, the listings produced by the environment |{Piton}| and the command
|\PitonInputFile| are not breakable.

However, \pkg{piton} provides the keys |splittable-on-empty-lines| and
|splittable| to allow such breaks.

\begin{itemize}
\item The key \Definition{splittable-on-empty-lines} allows breaks on the empty
lines. The ``empty lines'' are in fact the lines which contains only spaces.

\item Of course, the key |splittable-on-empty-lines| may not be sufficient and
that's why \pkg{piton} provides the key \Definition{splittable}.

When the key |splittable| is used with the numeric value~$n$ (which must be a
positive integer) the listing, or each part of the listing delimited by empty
lines (when |split-on-empty-lines| is in force) may be broken anywhere with
the restriction that no break will occur within the $n$ first lines of
the listing or within the $n$ last lines.\footnote{Remark that we speak of the
lines of the original computer listing and such line may be composed on
several lines in the final \textsc{pdf} when the key |break-lines-in-Piton| is
in force.} 

For example, a tuning with |splittable = 4| may be a good choice.

When used without value, the key |splittable| is equivalent to 
|splittable = 1| and the listings may be broken anywhere (it's probably 
not recommandable).

The initial value of the key |splittable| is equal to 100 (by default, the
listings are not breakable at all).
\end{itemize} 

\medskip
\begin{tcolorbox}[breakable]
Even with a background color (set by the key |background-color|), the pages
breaks are allowed, as soon as the key |split-on-empty-lines| or the key
|splittable| is in force.

\medskip
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}.

\medskip
We illustrate that point with the following code (the current environment
|{tcolorbox}| uses the key |breakable|).

\begin{Verbatim}
~emphase#\begin{Piton}[background-color=gray!30,rounded-corners,width=min,splittable=4]@
def square(x):
    """Computes the square of x"""
    return x*x
...
def square(x):
    """Computes the square of x"""
    return x*x
~emphase#~textbackslash#@end{Piton}@
\end{Verbatim}

\bigskip
\begin{Piton}[background-color=gray!30,rounded-corners,width=min,splittable=4]
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x 
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
\end{Piton}

\end{tcolorbox}

\subsection{Splitting of a listing in sub-listings}

\index{split-on-empty-lines}
\label{split-on-empty-lines}
\index{split-separation}
\index{add-to-split-separation}

The extension \pkg{piton} provides the key \Definition{split-on-empty-lines},
which should not be confused with the key |splittable-on-empty-lines|
previously defined.

\smallskip
In order to understand the behaviour of the key |split-on-empty-lines|, one
should imagine that he has to compose an computer listing which contains
several definitions of computer functions. Usually, in the computer
languages, those definitions of functions are separated by empty lines.

\smallskip
The key |split-on-empty-lines| splits the listings on the empty lines. Several
empty lines are deleted and replaced by the content of the parameter
corresponding to the key \Definition{split-separation}.
\begin{itemize}
\item That parameter must contain elements allowed to be inserted in
\emph{vertical mode} of TeX. For example, it's possible to put the TeX
primitive |\hrule|.

\item The initial value of this parameter is
|\vspace{\baselineskip}\vspace{-1.25pt}| which corresponds eventually to an 
empty line in the final \textsc{pdf} (this vertical space is deleted if it
occurs on a page break). If the key |background-color| is in force, no
background color is added to that empty line.

\item In fact, the extension \pkg{piton} provides also the key
\Definition{split-separation~+} to add elements on the right of the parameter
|split-separation|. The name of that key contains a space in order to be able
to write, for example, |split-separation += \hrule|.
\end{itemize}


Each chunk of the computer listing is composed in an environment whose name
is given by the key \Definition{env-used-by-split}. The initial value of that
parameter is, not surprisingly, |Piton| and, hence, the different chunks are
composed in several environments |{Piton}|. If one decides to change the value
of |env-used-by-split|, he should use the name of an environment created by
|\NewPitonEnvironment| (cf.~part~\ref{NewPitonEnvironment},
p.~\pageref{NewPitonEnvironment}).

Each chunk of the computer listing is formated in its own environment.
Therefore, it has its own line numbering (if the key
|line-numbers| is in force) and its own colored background (when the key
|background-color| is in force), separated from the background color of the
other chunks. When used, the key |splittable| applies in each chunk
(independently of the other chunks). Of course, a page break may occur between
the chunks of code, regardless of the value of |splittable|.

\bigskip
\begin{Verbatim}
\begin{Piton}[~emphase#split-on-empty-lines@,background-color=gray!15,line-numbers]
def square(x):
    """Computes the square of x"""
    return x*x

def cube(x):
    """Calcule the cube of x"""
    return x*x*x
\end{Piton}
\end{Verbatim}


\begin{Piton}[split-on-empty-lines,background-color=gray!15,line-numbers]
def square(x):
    """Computes the square of x"""
    return x*x

def cube(x):
    """Calcule the cube of x"""
    return x*x*x
\end{Piton}


\bigskip
If we wish to have a continuity of the line numbers between the sublistings
it's possible to add |\PitonOptions{resume}| to the parameter |split-separation|.

\bigskip
\begin{Verbatim}
\begin{Piton}[
split-on-empty-lines, ~emphase#split-separation += \PitonOptions{resume}@ , background-color=gray!15, line-numbers ]
def square(x):
    """Computes the square of x"""
    return x*x

def cube(x):
    """Computes the square of x"""
    return x*x*x
\end{Piton}
\end{Verbatim}

\begin{Piton}[
   split-on-empty-lines,
   split-separation += \PitonOptions{resume} ,
   background-color = gray!15,
   line-numbers
 ]
def square(x):
    """Computes the square of x"""
    return x*x

def cube(x):
    """Computes the square of x"""
    return x*x*x
\end{Piton}


\bigskip
\textbf{Caution}: Since each chunk is treated independently of the others, the
commands specified by |detected-commands| or |raw-detected-commands|
(cf.~p.~\pageref{detected-commands}) and the commands and environments of
Beamer automatically detected by \pkg{piton} must not cross the empty lines of
the original listing.

\subsection{Highlighting some identifiers}

\label{SetPitonIdentifier}

The command \DefinitionCommand{SetPitonIdentifier} allows to automatically
change the formatting of some identifiers. That change is only based on the
name of those indentifiers.

\smallskip
That command takes in three arguments: 

\begin{itemize}
\item The optional argument (within square brackets) specifies the computer
language. If this argument is not present, the tunings done by
|\SetPitonIdentifier| will apply to all the computer languages of
\pkg{piton}.\footnote{We recall, that, in the package \pkg{piton}, the
names of the computer languages are case-insensitive.}

\item The first mandatory argument is a comma-separated list of names of
identifiers.

\item The second mandatory argument is a list of LaTeX instructions of the
same type as \pkg{piton} ``styles'' previously presented (cf.~\ref{styles}
p.~\pageref{styles}). 
\end{itemize}

\emph{Caution}: Only the identifiers may be concerned by that key. The
keywords and the built-in functions won't be affected, even if their name
appear in the first argument of |\SetPitonIdentifier|.

\begin{Verbatim}
~emphase#\SetPitonIdentifier{l1,l2}{\color{red}}@
\begin{Piton}
def tri(l):
    """Segmentation sort"""
    if len(l) <= 1:
        return l
    else:
        a = l[0]
        l1 = [ x for x in l[1:] if x < a  ]
        l2 = [ x for x in l[1:] if x >= a ]
        return tri(l1) + [a] + tri(l2)
\end{Piton}
\end{Verbatim}


\bigskip

\begingroup

\SetPitonIdentifier{l1,l2}{\color{red}}

\begin{Piton}
def tri(l):
    """Segmentation sort"""
    if len(l) <= 1:
        return l
    else:
        a = l[0]
        l1 = [ x for x in l[1:] if x < a  ]
        l2 = [ x for x in l[1:] if x >= a ]
        return tri(l1) + [a] + tri(l2)
\end{Piton}

\endgroup

\bigskip
By using the command |\SetPitonIdentifier|, it's possible to add other
built-in functions (or other new keywords, etc.) that will be detected by
\pkg{piton}.


\begin{Verbatim}
~emphase#\SetPitonIdentifier[Python]@
  {cos, sin, tan, floor, ceil, trunc, pow, exp, ln, factorial}
  {\PitonStyle{Name.Builtin}}

\begin{Piton}
from math import *
cos(pi/2) 
factorial(5)
ceil(-2.3) 
floor(5.4) 
\end{Piton}
\end{Verbatim}

\begingroup

\SetPitonIdentifier[Python]
  {cos, sin, tan, floor, ceil, trunc, pow, exp, ln, factorial}
  {\PitonStyle{Name.Builtin}}

\begin{Piton}
from math import *
cos(pi/2) 
factorial(5)
ceil(-2.3) 
floor(5.4) 
\end{Piton}


\endgroup


\subsection{Mechanisms to escape to LaTeX}

\label{LaTeX-escapes}
\index{escapes to LaTeX}

The package \pkg{piton} provides several mechanisms for escaping to LaTeX:
\begin{itemize}
\item It's possible to compose comments entirely in LaTeX.
\item It's possible to have the elements between \texttt{\$} in the comments
composed in LateX mathematical mode.
\item It's possible to ask \pkg{piton} to detect automatically some LaTeX
commands, thanks to the keys |detected-commands|, |raw-detected-commands| and
|vertical-detected-commands|.
\item It's also possible to insert LaTeX code almost everywhere in a Python listing.
\end{itemize}

One should also remark that, when the extension \pkg{piton} is used with the
class \cls{beamer}, \pkg{piton} detects in |{Piton}| many commands and
environments of Beamer: cf. \ref{beamer} p.~\pageref{beamer}.

\subsubsection{The ``LaTeX comments''}

\index{comment-latex}

In this document, we call ``LaTeX comments'' the comments which begins by
|#>|. The code following those characters, until the end of the line, will be
composed as standard LaTeX code. There is two tools to customize those
comments.

\begin{itemize}
\item It's possible to change the syntactic mark (which, by default, is |#>|).
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 syntactic marker.

For example, if the preamble contains the following instruction:

\quad \verb|\PitonOptions{comment-latex = LaTeX}|

the LaTeX comments will begin by |#LaTeX|.

If the key |comment-latex| is used with the empty value, all the Python
comments (which begins by |#|) will, in fact, be ``LaTeX comments''.

\smallskip
\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}

\bigskip
If the user has required line numbers (with the key |line-numbers|), it's
possible to refer to a number of line with the command |\label| used in a
LaTeX comment.\footnote{That feature is implemented by using a redefinition of
the standard command \texttt{\textbackslash label} in the environments
\texttt{\{Piton\}}. Therefore, incompatibilities may occur with extensions
which redefine (globally) that command \texttt{\textbackslash label} (for
example: \pkg{varioref}, \pkg{refcheck}, \pkg{showlabels}, etc.).} The same goes
for the |\zlabel| command from the \pkg{zref} package.\footnote{Using the
command \texttt{\textbackslash zcref} command from \pkg{zref-clever} is also 
supported.}

\subsubsection{The key ``label-as-zlabel''}

\index{label-as-zlabel}

The key |label-as-zlabel| will be used to indicate if the user wants |\label|
inside |Piton| environments to be replaced by a |\zlabel|-compatible command
(which is the default behavior of \pkg{zref} outside of such environments).

That feature is activated by the key \Definition{label-as-zlabel}, \emph{which is
available only in the preamble of the document}.

\subsubsection{The key ``math-comments''}

\index{math-comments}

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 \Definition{math-comments}, \emph{which is
available only in the preamble of the document}.

\nobreak
\begin{footnotesize}
\begin{Verbatim}
\PitonOptions{math-comment} % in the preamble
\end{Verbatim}
\end{footnotesize}

\begin{Verbatim}
\begin{Piton}
def square(x):
    return x*x ~# compute $x^2$
\end{Piton}
\end{Verbatim}

\begin{Piton}
def square(x):
    return x*x # compute $x^2$
\end{Piton}

\subsubsection{The key ``detected-commands'' and its variants}

\index{raw-detected-commands (key)}
\label{raw-detected-commands}
\index{vertical-detected-commands (key)}
\label{vertical-detected-commands}
\index{detected-commands (key)}
\label{detected-commands}

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}.

\begin{itemize}
\item The key |detected-commands| must be used in the preamble of the LaTeX document.

\item The names of the LaTeX commands must appear without the leading
backslash (eg. |detected-commands = { emph, textbf }|). 

\item These commands must be LaTeX commands with only one (mandatory) argument
between braces (and these braces must appear explicitly in the computer
listing). 

\item These commands must be \textbf{protected}\footnote{We recall that the
command \texttt{\textbackslash NewDocumentCommand} creates protected commands,
unlike the historical LaTeX command \texttt{\textbackslash newcommand} (and
unlike the command \texttt{\textbackslash def} of TeX).} against expansion in
the TeX sens (because the command |\piton| expands its arguments before
throwing it to Lua for syntactic analysis).
\end{itemize}

\bigskip
In the following example, which is a recursive programming in C of the
factorial function, we decide to highlight the recursive call. The command
|\highLight| of \pkg{lua-ul}\footnote{The package \pkg{lua-ul} requires itself
the package \pkg{luacolor}.} directly does the job.

\medskip
\begin{footnotesize}
\begin{Verbatim}
\PitonOptions{~emphase#detected-commands@ = highLight} % in the preamble
\end{Verbatim}
\end{footnotesize}

\begin{Verbatim}
\begin{Piton}[language=C]
int factorielle(int n)
  {
    if (n > 0) ~emphase#\highLight{return n * factorielle(n - 1)}@ ;
    else return 1;
  }
\end{Piton}
\end{Verbatim}

\begin{Piton}[language=C]
int factorielle(int n)
  {
    if (n > 0) \highLight{return n * factorielle(n - 1)} ;
    else return 1;
  }
\end{Piton}

\bigskip
The key \Definition{raw-detected-commands} is similar to the key
|detected-commands| but \pkg{piton} won't do any syntactic analysis of the
arguments of the LaTeX commands which are detected.

If there is a line break within the argument of a command detected by the mean
of |raw-detected-commands|, that line break is replaced by a space (as does
LaTeX by default).

\medskip
Imagine, for example, that we wish, in the main text of a document about
databases, introduce some specifications of tables of the language
\textsc{sql} by the the name of the table, followed, between brackets, by the
names of its fields (ex. : |client(name,town)|).

If we insert that element in a command |\piton|, the word \emph{client} won't
be recognized as a name of table but as a name of field. It's possible to
define a personal command |\NomTable| which we will apply by hand to the names
of the tables. In that aim, we declare that command with
|raw-detected-commands| and, thus, its argument won't be re-analyzed by
\pkg{piton} (that second analysis would format it as a name of field).

\medskip
In the preamble of the LaTeX document, we insert the following lines:

\begin{Verbatim}
\NewDocumentCommand{\NameTable}{m}{{\PitonStyle{Name.Table}{~#1}}}
\PitonOptions{language=SQL, ~emphase#raw-detected-commands = NameTable@}
\end{Verbatim}

In the main document, the instruction:

\begin{Verbatim}
Exemple : \piton{\NameTable{client} (name, town)}
\end{Verbatim}

\NewDocumentCommand{\NameTable}{m}{{\PitonStyle{Name.Table}{#1}}}

produces the following output :

\smallskip
\begingroup
\PitonOptions{language=SQL}%
Exemple : \piton{\NameTable{client} (nom, prénom)}
\endgroup

\bigskip
The key \Definition{vertical-detected-commands} is similar to the key |raw-detected-commands|
but the commands which are detected by this key must be LaTeX commands (with one argument)
which are executed in \emph{vertical} mode between the lines of the code.

\smallskip
For example, it's possible to detect the command |\newpage| by

\begin{Verbatim}
\PitonOptions{vertical-detected-commands = newpage}
\end{Verbatim}

and ask in a listing a mandatory break of page with |\newpage{}| (the pair of braces |{}|
is mandatory because the commands detected by \pkg{piton} are meant to be LaTeX commands
with one mandatory argument, written between explicit braces).

\begin{Code}
\begin{Piton}
def square(x):
    return x*x  \emph{\textbackslash{}newpage{}}
def cube(x):
    return x*x*x
\end{Piton}
\end{Code}

\medskip
It would also be possible to require the detection of the command |\vspace|.

\subsubsection{The mechanism ``escape''}

\label{escape}

It's also possible to overwrite the computer listings to insert LaTeX code
almost everywhere (but between lexical units, of course). By default,
\pkg{piton} does not fix any delimiters for that kind of escape.

In order to use this mechanism, it's necessary to specify the delimiters which
will delimit the escape (one for the beginning and one for the end) by using
the keys \Definition{begin-escape} and \Definition{end-escape}, \emph{available only
in the preamble of the document}.

\medskip
We consider once again the previous example of a recursive programming of
the factorial. We want to highlight in pink the instruction containing the
recursive call. With the package \pkg{lua-ul}, we can use the syntax
|\highLight[LightPink]{...}|. Because of the optional argument between square
brackets, it's not possible to use the key |detected-commands| but it's
possible to achieve our goal with the more general mechanism ``escape''.

\medskip
We assume that the preamble of the document contains the following
instruction:

\begin{Verbatim}
\PitonOptions{~emphase#begin-escape=!,end-escape=!@}
\end{Verbatim}

\medskip
Then, it's possible to write:
\begin{Verbatim}
\begin{Piton}
def fact(n):
    if n==0:
        return 1
    else:
        ~emphase#!\highLight[LightPink]{!@return n*fact(n-1)~emphase#!}!@
\end{Piton}
\end{Verbatim}

   \begin{Piton}
def fact(n):
    if n==0:
        return 1
    else:
        !\highLight[LightPink]{!return n*fact(n-1)!}!
   \end{Piton}



\bigskip
\emph{Caution} : The mechanism ``escape'' is not active in the strings nor in
the comments (however, it's possible to have a whole Python comment
composed in LaTeX by beginning it with |#>|; such comments are merely called
``LaTeX comments'' in this document).


\subsubsection{The mechanism ``escape-math''}

The mechanism ``escape-math'' is very similar to the mechanism ``escape''
since the only difference is that the elements sent to LaTeX are composed in
the math mode of LaTeX.

This mechanism is activated with the keys \Definition{begin-escape-math} and
\Definition{end-escape-math} (\emph{which are available only in the preamble of the
document}). 

Despite the technical similarity, the use of the the mechanism
``escape-math'' is in fact rather different from that of the mechanism
``escape''. Indeed, since the elements are composed in a mathematical mode
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 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}
\PitonOptions{~emphase#begin-escape-math=$,end-escape-math=$@}
\end{Verbatim}
Note: the character \verb|$| must \emph{not} be protected by a backslash.

\bigskip
However, it's probably more prudent to use |\(| et |\)|, which are delimiters
of the mathematical mode provided by LaTeX.
\begin{Verbatim}
\PitonOptions{~emphase#begin-escape-math=\(,end-escape-math=\)@}
\end{Verbatim}

\bigskip
Here is an example of use.

\medskip
\begin{Verbatim}
\begin{Piton}[line-numbers]
def arctan(x,n=10):
    if ~emphase#\(x < 0\)@ :
        return ~emphase#\(-\arctan(-x)\)@ 
    elif ~emphase#\(x > 1\)@ : 
        return ~emphase#\(\pi/2 - \arctan(1/x)\)@ 
    else: 
        s = ~emphase#\(0\)@
        for ~emphase#\(k\)@ in range(~emphase#\(n\)@): s += ~emphase#\(\smash{\frac{(-1)^k}{2k+1} x^{2k+1}}\)@
        return s
\end{Piton}
\end{Verbatim}


\bigskip

\begin{Piton}[line-numbers]
def arctan(x,n=10):
    if \(x < 0\) :
        return \(-\arctan(-x)\) 
    elif \(x > 1\) : 
        return \(\pi/2 - \arctan(1/x)\) 
    else: 
        s = \(0\)
        for \(k\) in range(\(n\)): s += \(\smash{\frac{(-1)^k}{2k+1} x^{2k+1}}\)
        return s
\end{Piton}




\subsection{Behaviour in the class Beamer}

\label{beamer}
\index{Beamer@\cls{Beamer} (class)}

\emph{First remark}

\nobreak
Since the environment |{Piton}| catches its body with a verbatim mode, it's
necessary to use the environments |{Piton}| within environments |{frame}| of
Beamer protected by the key |fragile|, i.e. beginning with
|\begin{frame}[fragile]|.\footnote{Remind that for an environment
|{frame}| of Beamer using the key |fragile|, the instruction
|\end{frame}| must be alone on a single line (except
for any leading whitespace).}

Note that, if the frame contains only one slide, it's recommended to write

|\begin{frame}[fragile=singleslide]|.

\bigskip
When the package \pkg{piton} is used within the class
\cls{beamer}\footnote{The extension \pkg{piton} detects the class \cls{beamer}
and the package \pkg{beamerarticle} if it is loaded previously
but, if needed, it's also possible to activate that mechanism with the key
|beamer| provided by \pkg{piton} at load-time:
|\usepackage[beamer]{piton}|}, the behaviour of \pkg{piton} is slightly 
modified, as described now. This is done via an environment |{actionenv}| of
Beamer.

\subsubsection{\{Piton\} and \textbackslash PitonInputFile are
``overlay-aware''}

When \pkg{piton} is used in the class \cls{beamer}, the command
|\PitonInputFile| and the environment |{Piton}| (but not the environments
created by |\NewPitonEnvironment|) accept the optional argument |<...>| of
Beamer for the overlays which are involved.

For example, it's possible to write:

\begin{Verbatim}
\begin{Piton}~emphase#<2-5>@
...
\end{Piton}
\end{Verbatim}

and 

\begin{Verbatim}
\PitonInputFile~emphase#<2-5>@{my_file.py}
\end{Verbatim}

\subsubsection{Commands of Beamer allowed in \{Piton\} and \textbackslash PitonInputFile}

\index{detected-beamer-commands}

When \pkg{piton} is used in the class \cls{beamer}, the following commands of
\cls{beamer} (classified upon their number of arguments) are automatically
detected in the environments |{Piton}| (and in the listings processed by
|\PitonInputFile|):
\begin{itemize}
\item no mandatory argument : |\pause|\footnote{One should remark that it's
also  possible to use the command |\pause| in a ``LaTeX
comment'', that is to say by writing |#> \pause|. By
this way, if the code is copied, it's still executable}.  ;
\item one mandatory argument : |\action|, |\alert|, |\invisible|, |\only|,
|\uncover| and |\visible| ; \newline
% It's possible to add new commands to that list with the key
\Definition{detected-beamer-commands} (the names of the commands must
\emph{not} be preceded by a backslash). 
\item two mandatory arguments : |\alt| ; 
\item three mandatory arguments  : |\temporal|.
\end{itemize}

\medskip 
These commands must be used preceded and following by a space. In the
mandatory arguments of these commands, the braces must be balanced. However,
the braces included in short strings\footnote{The short strings of Python are
the strings delimited by characters |'| or the characters |"|
and not |'''| nor |"""|. In Python, the short strings can't
extend on several lines.} of Python are not considered.

\medskip
Regarding the functions |\alt| and |\temporal| there should be no carriage
returns in the mandatory arguments of these functions.

\medskip
Here is a complete example of file:

\begin{small}
\begin{Code}
\documentclass{beamer}
\usepackage{piton}
\begin{document}
\begin{frame}[fragile]
\begin{Piton}
def string_of_list(l):
    """Convert a list of numbers in string"""
    \emph{\only<2->{s = "{" + str(l[0])}}
    \emph{\only<3->{for x in l[1:]: s = s + "," + str(x)}}
    \emph{\only<4->{s = s + "}"}}
    return s
\end{Piton}
\end{frame}
\end{document}
\end{Code}
\end{small}

In the previous example, the braces in the Python strings |"{"| and |"}"| are
correctly interpreted (without any escape character).




\bigskip
\subsubsection{Environments of Beamer allowed in \{Piton\} and \textbackslash PitonInputFile}

When \pkg{piton} is used in the class \pkg{beamer}, the following environments
of Beamer are directly detected in the environments |{Piton}| (and in the
listings processed by |\PitonInputFile|): |{actionenv}|, |{alertenv}|,
|{invisibleenv}|, |{onlyenv}|, |{uncoverenv}| and |{visibleenv}|.

\smallskip
\index{detected-beamer-environments}
It's possible to add new environments to that list with the key
\Definition{detected-beamer-environments}. 

\smallskip

However, there is a restriction: these environments must contain only \emph{whole
lines of code} in their body. The instructions |\begin{...}| and
|\end{...}| must be alone on their lines.

\medskip
Here is an example:

\begin{small}
\begin{Code}
\documentclass{beamer}
\usepackage{piton}
\begin{document}
\begin{frame}[fragile]
\begin{Piton}
def square(x):
    """Compute the square of its argument"""
\emph{\begin{uncoverenv}<2>}
    return x*x
\emph{\end{uncoverenv}}
\end{Piton}
\end{frame}
\end{document}
\end{Code}
\end{small}


\vspace{1cm}
\textbf{Remark concerning the command \textbackslash alert and the environment
\{alertenv\} of Beamer}

\nobreak
\smallskip
Beamer provides an easy way to change the color used by the environment
|{alertenv}| (and by the command |\alert| which relies upon it) to highlight
its argument. Here is an example:

\begin{Verbatim}
\setbeamercolor{~emphase#alerted text@}{fg=blue} 
\end{Verbatim}

However, when used inside an environment |{Piton}|, such tuning will probably
not be the best choice because \pkg{piton} will, by design, change (most of
the time) the color the different elements of text. One may prefer an environment
|{alertenv}| that will change the background color for the elements to be
highlighted. 

\smallskip
Here is a code that will do that job and add a yellow background. That code
uses the command |\@highLight| of \pkg{lua-ul} (that extension requires also
the package \pkg{luacolor}).

\begingroup
\small
\fvset{commandchars=\~\#\+}
\begin{Verbatim}
\setbeamercolor{alerted text}{bg=yellow!50}
\makeatletter
\AddToHook{env/Piton/begin}
  {\renewenvironment<>{alertenv}{\only~#1{~emphase#\@highLight+[alerted text.bg]}}{}}
\makeatother
\end{Verbatim}
\endgroup

That code redefines locally the environment |{alertenv}| within the
environments |{Piton}| (we recall that the command |\alert| relies upon that
environment |{alertenv}|).


\subsection{Footnotes in the environments of piton}

 \index{footnote@\pkg{footnote} (extension)}
\index{footnote (key)}
\index{footnotehyper@\pkg{footnotehyper} (extension)}
\index{footnotehyper (key)}

\label{footnote}
If you want to put footnotes in an environment |{Piton}| or
(or, more unlikely, in a listing produced by |\PitonInputFile|), you can use a
pair |\footnotemark|--|\footnotetext|. 

\smallskip
However, it's also possible to extract the footnotes with the help of the
package \pkg{footnote} or the package \pkg{footnotehyper}.

\smallskip
If \pkg{piton} is loaded with the option \Definition{footnote} (with
|\usepackage[footnote]{piton}|), 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 \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.
The package \pkg{footnotehyper} is the successor of the package \pkg{footnote}
and should be used preferably. The package \pkg{footnote} has some drawbacks,
in particular: it must be loaded after the package \pkg{xcolor} and it is not
perfectly compatible with \pkg{hyperref}.


\medskip
\textbf{Important remark} : If you use Beamer, you should know that Beamer has
its own system to extract the footnotes. Therefore, \pkg{piton} must be loaded
in that class without the option |footnote| nor the option |footnotehyper|.


\bigskip
By default, in an environment |{Piton}|, a command |\footnote| may appear only
within a ``LaTeX comment''. But it's also possible to add the command
|\footnote| to the list of the ``\emph{detected-commands}''
(cf.~part~\ref{detected-commands}, p.~\pageref{detected-commands}). 

\medskip 
In this document, the package \pkg{piton} has been loaded with the
option |footnotehyper| dans we added the command |\footnote| to the list of
the ``\emph{detected-commands}'' with the following instruction in the
preamble of the LaTeX document.

\qquad \verb|\PitonOptions{detected-commands = footnote}|


\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
\PitonOptions{background-color=gray!15}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)~emphase&\footnote{First recursive call.}]@
    elif x > 1: 
        return pi/2 - arctan(1/x)~emphase&\footnote{Second recursive call.}@
    else: 
        return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) 
\end{Piton}
\end{Verbatim}
\endgroup

\begingroup
\PitonOptions{background-color=gray!15}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)\footnote{First recursive call.}
    elif x > 1: 
        return pi/2 - arctan(1/x)\footnote{Second recursive call.}
    else: 
        return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) 
\end{Piton}
\endgroup


\vspace{1cm}

If an environment |{Piton}| is used in an environment |{minipage}| of LaTeX,
the notes are composed, of course, at the foot of the environment
|{minipage}|. Recall that such |{minipage}| can't be broken by a page break.


\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
\PitonOptions{background-color=gray!15}
~emphase&\begin{minipage}{\linewidth}@
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)~emphase&\footnote{First recursive call.}@
    elif x > 1: 
        return pi/2 - arctan(1/x)~emphase&\footnote{Second recursive call.}@
    else: 
        return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) 
\end{Piton}
~emphase&\end{minipage}@
\end{Verbatim}
\endgroup

\begingroup
\PitonOptions{background-color=gray!15}
\begin{minipage}{\linewidth}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)\footnote{First recursive call.}
    elif x > 1: 
        return pi/2 - arctan(1/x)\footnote{Second recursive call.}
    else: 
        return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) 
\end{Piton}
\end{minipage}
\endgroup


\subsection{Tabulations}

\index{tabulations}
\index{tab-size}

\smallskip 
Even though it's probably recommended to indent the computers listings with
spaces and not tabulations\footnote{For the language Python, see the note %
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 \Definition{tab-size} of |\PitonOptions|.

\smallskip
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).

The key |env-gobble| is not compatible with the tabulations.


\bigskip
\section{API for the developpers}

\label{API}

The L3 variable \DefinitionCommand{l_piton_language_str} contains the name of
the current language of \pkg{piton} (in lower case).

\bigskip

The extension \pkg{piton} provides a Lua function
\Definition{piton.get_last_code} without argument which returns the code in
the latest environment of \pkg{piton}.
\begin{itemize}
\item The carriage returns (which are present in the initial environment)
appears as characters |\r| (i.e. U+000D).

\item The code returned by |piton.get_last_code()| takes into account the
potential application of a key |gobble|, |auto-gobble| or |env-gobble|
(cf.~p.~\pageref{gobble}). 

\item The extra formatting elements added in the code are deleted by
|piton.get_last_code()|. That concerns the LaTeX commands declared by the key
|detected-commands| and its variants (cf. part~\ref{detected-commands}) and the
elements inserted by the mechanism ``|escape|'' (cf. part~\ref{escape}).

\item |piton.get_last_code| is a Lua function and not a Lua string: the
treatments outlined above are executed when the function is called. Therefore,
it might be judicious to store the value returned by |piton.get_last_code()|
in a variable of Lua if it will be used several times.
\end{itemize}

\medskip
For an example of use, see the part concerning |pyluatex|, part~\ref{pyluatex},
p.~\pageref{pyluatex}. 


\section{Examples}


\subsection{An example of tuning of the styles}

The graphical styles have been presented in the section \ref{styles},
p.~\pageref{styles}.

\smallskip
We present now an example of tuning of these styles adapted to the documents
in black and white.

That tuning uses the command |\highLight| of \pkg{lua-ul} (that package
requires itself the package \pkg{luacolor}).

\begin{Verbatim}
\SetPitonStyle
  {
    Number = ,
    String = \itshape , 
    String.Doc = \color{gray} \slshape ,
    Operator = , 
    Operator.Word = \bfseries ,
    Name.Builtin = ,
    Name.Function = \bfseries \highLight[gray!20] ,
    Comment = \color{gray} ,
    Comment.LaTeX = \normalfont \color{gray},
    Keyword = \bfseries ,
    Name.Namespace = ,
    Name.Class = , 
    Name.Type = ,
    InitialValues = \color{gray}
  }
\end{Verbatim}

In that tuning, many values given to the keys are empty: that means that the
corresponding style won't insert any formatting instruction, except those in
the value of the parameter |font-command|, whose initial value is |\ttfamily|
(the element will be composed in the standard color, usually in black, etc.).
Nevertheless, those entries are mandatory because the initial value of those
keys in \pkg{piton} is \emph{not} empty.

\begingroup
 \PitonOptions{splittable}

\SetPitonStyle
  {
    Number = ,
    String = \itshape , 
    String.Doc = \color{gray} \slshape ,
    Operator.Word = \bfseries ,
    Operator = , 
    Name.Builtin = ,
    Name.Function = \bfseries \highLight[gray!20] ,
    Comment = \color{gray} ,
    Comment.LaTeX = \normalfont \color{gray} ,
    Keyword = \bfseries ,
    Name.Namespace = ,
    Name.Class = , 
    Name.Type = ,
    InitialValues = \color{gray}
  }


\bigskip

\begin{Piton}
from math import pi

def arctan(x,n=10):
    """Compute the mathematical value of arctan(x)
                                              
    n is the number of terms in the sum
    """
    if x < 0:
        return -arctan(-x) # recursive call
    elif x > 1: 
        return pi/2 - arctan(1/x) 
        #> (we have used that $\arctan(x)+\arctan(1/x)=\pi/2$ for $x>0$)
    else: 
        s = 0
        for k in range(n):
            s += (-1)**k/(2*k+1)*x**(2*k+1)
        return s 
\end{Piton}

\endgroup


\subsection{Line numbering}

\label{example-numbering}
\index{numbers of the lines de code|emph}

We remind that it's possible to have an automatic numbering of the lines in
the computer listings by using the key |line-numbers| (used without value).

By default, the numbers of the lines are composed by \pkg{piton} in an
overlapping position on the left (by using internally the command |\llap| of LaTeX).

\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
~emphase&\PitonOptions{background-color=gray!15, line-numbers}@
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call) 
    else: 
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\end{Verbatim}
\endgroup



\begingroup
\PitonOptions{background-color=gray!15, line-numbers}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call) 
    else: 
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\endgroup

\bigskip
In order to avoid that overlapping, it's possible to use the option |left-margin=auto|
which will insert automatically a margin adapted to the numbers of lines that
will be written (that margin is larger when the numbers are greater than~10).


\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
~emphase&\PitonOptions{background-color=gray!15, left-margin = auto, line-numbers}@
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call) 
    else: 
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\end{Verbatim}
\endgroup



\begingroup
\PitonOptions{background-color=gray!15,left-margin = auto, line-numbers}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call) 
    else: 
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\endgroup

\bigskip
It's possible to have the numbers of lines on the right with
|line-numbers/position=right| (the initial value of the parameter
|line-numbers/position| is, without surprise, |left|). In that case, it is good
to provide a positive value to |right-margin| (it's possible to use
|right-margin=auto| but the actual value computed for |right-margin| will be
probably appear to be too small if there is long broken lines of code.

\begingroup
\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
\begin{Verbatim}
\PitonOptions
  {
    background-color=gray!15,
    ~emphase&line-numbers/position = right@,
    ~emphase&right-margin = 1cm@,
    ~emphase&line-numbers@
  }
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call)
    else:
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\end{Verbatim}
\endgroup



\begingroup
\PitonOptions
  {
    background-color=gray!15,
    line-numbers/position = right,
    right-margin = 1cm,
    line-numbers
  }
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call) 
    else:
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\endgroup

\bigskip
The same example with the key |width=min|.


\begingroup
\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
\begin{Verbatim}
\PitonOptions
  {
    background-color=gray!15,
    ~emphase&line-numbers/position = right@,
    ~emphase&right-margin = 1cm@,
    ~emphase&line-numbers@,
    ~emphase&width=min@
  }
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call)
    else:
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\end{Verbatim}
\endgroup



\begingroup
\PitonOptions
  {
    background-color=gray!15,
    line-numbers/position = right,
    right-margin = 1cm,
    line-numbers,
    width=min
  }
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> (recursive call)
    elif x > 1: 
        return pi/2 - arctan(1/x) #> (other recursive call) 
    else:
        s = 0.0
        for k in range(n):
            s = s + (-1)**k/(2*k+1)*x**(2*k+1)
        return s
\end{Piton}
\endgroup




\bigskip
\subsection{Formatting of the LaTeX comments}

\label{example-comments}

It's possible to modify the style |Comment.LaTeX| (with |\SetPitonStyle|) in
order to display the LaTeX comments (which begin with |#>|) aligned on the
right margin.


\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
\PitonOptions{background-color=gray!15}
~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> recursive call
    elif x > 1: 
        return pi/2 - arctan(1/x) #> other recursive call 
    else: 
        return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) 
\end{Piton}
\end{Verbatim}
\endgroup

\begingroup
\PitonOptions{background-color=gray!15}
\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x)        #> recursive call
    elif x > 1: 
        return pi/2 - arctan(1/x) #> another recursive call 
    else: 
        return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) 
\end{Piton}
\endgroup


\vspace{1cm}
It's also possible to display these LaTeX comments in a kind of second column
by limiting the width of the listing with the key |width|. 

\begingroup
\small
\fvset{commandchars=\~\&\@}
\begin{Verbatim}
\PitonOptions{background-color=gray!15, width=9cm}
~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@
~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x) #> recursive call
    elif x > 1: 
        return pi/2 - arctan(1/x) #> another recursive call 
    else: 
        s = 0
        for k in range(n):
             s += (-1)**k/(2*k+1)*x**(2*k+1)
        return s 
\end{Piton}
\end{Verbatim}
\endgroup



\begingroup
\PitonOptions{background-color=gray!15, width=9cm}
\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}
\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}
\begin{Piton}
def arctan(x,n=10):
    if x < 0:
        return -arctan(-x) #> recursive call
    elif x > 1: 
        return pi/2 - arctan(1/x) #> another recursive call 
    else: 
        s = 0
        for k in range(n):
             s += (-1)**k/(2*k+1)*x**(2*k+1)
        return s 
\end{Piton}
\endgroup


\subsection{The command \textbackslash rowcolor}

\indexcommand{rowcolor}


The command |\rowcolor| has been presented in the part \ref{rowcolor}, at the
page~\pageref{rowcolor}. We recall that this command adds a colored background
to the current line (the \emph{whole} line, and not only the part with text).

It's possible to use that command in a style of \pkg{piton}, as shown in
p.~\pageref{rowcolor}, but maybe we wish to use it directly in a listing. In that aim,
it's mandatory to use one of the mechanisms to escape to LaTeX provided by \pkg{piton}.
In the following example, we use the key |raw-detected-commands|
(cf.~p.~\pageref{raw-detected-commands}). Since the ``detected commands'' are commands
with only one argument, it won't be possible to write (for example)
|\rowcolor[rgb]{0.9,1,0.9}| but the syntax |\rowcolor{[rgb]{0.9,1,0.9}}| will be
allowed.

\bigbreak
\begin{footnotesize}
\begin{Verbatim}
\PitonOptions{raw-detected-commands = rowcolor} % in the preamble
\end{Verbatim}
\end{footnotesize}

\medskip

\begin{BVerbatim}[boxwidth=87mm,baseline=c]
\begin{Piton}[width=min]
def fact(n):
    if n==0:
        return 1 ~emphase#\rowcolor{yellow!50}@
    else:
        return n*fact(n-1)
\end{Piton}        
\end{BVerbatim}
\hspace{1cm}
\begin{Piton}[width=min,box]
def fact(n):
    if n==0:
        return 1 \rowcolor{yellow!50}
    else:
        return n*fact(n-1)
\end{Piton}        


\bigbreak
Here is now the same example with the use of the key |background-color|
(cf. p.~\pageref{background-color}).

\medskip
\begin{BVerbatim}[boxwidth=92mm,baseline=c]
\begin{Piton}[width=min,~emphase#background-color=gray!15@]
def fact(n):
    if n==0:
        return 1 ~emphase#\rowcolor{yellow!50}@
    else:
        return n*fact(n-1)
\end{Piton}        
\end{BVerbatim}
\hspace{5mm}
\begin{Piton}[width=min,box,background-color=gray!15]
def fact(n):
    if n==0:
        return 1 \rowcolor{yellow!50}
    else:
        return n*fact(n-1)
\end{Piton}        


\bigbreak
As you can see, a margin has been added on both sides of the code by the key
|background-color|. If you wish those margins without general background, you
should use |background-color| with the special value~|none|.

\medskip
\begin{BVerbatim}[boxwidth=87mm,baseline=c]
\begin{Piton}[width=min,~emphase#background-color=none@]
def fact(n):
    if n==0:
        return 1 ~emphase#\rowcolor{yellow!50}@
    else:
        return n*fact(n-1)
\end{Piton}        
\end{BVerbatim}
\hspace{1cm}
\begin{Piton}[width=min,box,background-color=none]
def fact(n):
    if n==0:
        return 1 \rowcolor{yellow!50}
    else:
        return n*fact(n-1)
\end{Piton}        





\subsection{Use with tcolorbox}

\label{examples-tcolorbox}

The key |tcolorbox| of \pkg{piton} has been presented at the page
\pageref{tcolorbox}.

If, when that key is used, we wish to customize the graphical box created by
\pkg{tcolorbox} (with the keys provided by \pkg{tcolorbox}), we should use the
command |\tcbset| provided by \pkg{tcolorbox}. In order to limit the scope of
the settings done by that command, the best way is to create a new environment
with the dedicated command |\NewPitonEnvironment|
(cf.~p.~\pageref{NewPitonEnvironment}). That environment with contain the
settings done by \pkg{piton} (with |\PitonOptions|) and those done by
\pkg{tcolorbox} (with |\tcbset|).


\bigskip Here is an example of such environment |{Python}| with a colored
column on the left for the numbers of lines.

\begin{footnotesize}
\begin{Verbatim}
\usepackage{tcolorbox}          % in the preamble
\tcbuselibrary{breakable,skins} % in the preamble 
\end{Verbatim}
\end{footnotesize}

\smallskip

\begin{Verbatim}
\NewPitonEnvironment{Python}{m}
  {%
    \PitonOptions
      {
        ~emphase#tcolorbox@,
        splittable=3,
        width=min,
        line-numbers,       % activate the numbers of lines
        line-numbers =      % tuning for the numbers of lines
         {
           format = \footnotesize\color{white}\sffamily ,
           sep = 2.5mm
         }
      }%
    \tcbset
      {
        enhanced,
        title=~#1,
        fonttitle=\sffamily,
        left = 6mm,
        top = 0mm,
        bottom = 0mm,
        overlay=
         {%
            \begin{tcbclipinterior}%
                \fill[gray!80]
                    (frame.south west) rectangle
                    ([xshift=6mm]frame.north west); 
            \end{tcbclipinterior}%
         }
      } 
  } 
  { }
\end{Verbatim}

\bigskip
In the following example of use, we have illustrated the fact that it is possible
to impose a break of page in such environment with |\newpage{}| if we have required the
detection of the LaTeX command |\newpage| with the key |vertical-detected-commands|
(cf.~p.~\pageref{vertical-detected-commands}) in the preamble of the LaTeX document.

Remark that we must use |\newpage{}| and not |\newpage| because the LaTeX
commands detected by \pkg{piton} are meant to be commands with one argument
(between explicit curly braces).

\begin{footnotesize}
\begin{Verbatim}
\PitonOptions{vertical-detected-commands = newpage} % in the preamble
\end{Verbatim}
\end{footnotesize}

\medskip
\begin{Verbatim}
~emphase#\begin{Python}@{My example}
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x ~emphase#\newpage{}@
def square(x):
    """Computes the square of x"""
    return x*x
...    
def square(x):
    """Computes the square of x"""
    return x*x
~emphase#\end{Python}@
\end{Verbatim}

\bigskip

\RenewPitonEnvironment{Python}{m}
  {%
    \PitonOptions
      {
        tcolorbox,
        splittable=3,
        width=min,
        line-numbers,
        line-numbers =
         {
           format = \footnotesize\color{white}\sffamily ,
           sep = 2.5mm
         }
      }%
    \tcbset
      {
        enhanced,
        title=#1,
        fonttitle=\sffamily,
        left = 6mm,
        top = 0mm,
        bottom = 0mm,
        overlay=
         {%
            \begin{tcbclipinterior}%
                \fill[gray!80]
                    (frame.south west) rectangle
                    ([xshift=6mm]frame.north west); 
            \end{tcbclipinterior}%
         }
      } 
  } 
  { }
 

\begin{Python}{My example}
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x \newpage{}
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
def square(x):
    """Computes the square of x"""
    return x*x
\end{Python}



\bigskip
\subsection{Use with pyluatex}

\subsubsection{Standard use of pyluatex}

\index{pyluatex@{\pkg{pyluatex}} (extension)}
\label{pyluatex}


\textcolor{red}{Caution: The following examples require the version 0.7.0 of
  \pkg{pyluatex}.}

\bigskip

The package \pkg{pyluatex} is an extension which allows the execution of some
Python code from |lualatex| (as long as Python is installed on the machine
and that the compilation is done with |lualatex| and |--shell-escape|).

Here is, for example, an environment |{PitonExecute}| which formats a Python
listing (with \pkg{piton}) but also displays the output of the execution of the
code with Python.

\medskip
\begin{Code}
\NewPitonEnvironment{\emph{PitonExecute}}{O{}}
  {\PitonOptions{#1}}
  {\begin{center}
   \directlua
     {
       pyluatex.execute(piton.get_last_code(),false,cctab_latex,
         false,false,true,"default",false,false)
       tex.print(pyluatex.get_last_output())          
     }
   \end{center}}
\end{Code}

\medskip
We have used the Lua function |piton.get_last_code| provided in the API of
\pkg{piton} : cf.~part~\ref{API}, p.~\pageref{API}.

\medskip
This environment |{PitonExecute}| takes in as optional argument (between
square brackets) the options of the command |\PitonOptions|.


\NewPitonEnvironment{PitonExecute}{O{}}
  {\PitonOptions{#1}}
  {\begin{center}
   \directlua
     {
       pyluatex.execute(piton.get_last_code(),false,cctab_latex,
         false,false,true,"default",false,false)
       tex.print(pyluatex.get_last_output())          
     }
   \end{center}}


\medskip
\begin{Verbatim}
~emphase#\begin{PitonExecute}@[background-color=gray!15]
def square(x):
    """Computes the square of x"""
    return x*x
print(f'The square of 12 is {square(12)}.')
~emphase#\end{PitonExecute}@
\end{Verbatim}


\medskip
\begin{PitonExecute}[background-color=gray!15]
def square(x):
    """Computes the square of x"""
    return x*x
print(f'The square of 12 is {square(12)}.')
\end{PitonExecute}


\bigskip
It's also possible to use, in that environment, the mechanims for escape to LaTeX
as previously (cf. p.~\pageref{LaTeX-escapes}).

\begin{footnotesize}
\begin{Verbatim}
\usepackage{luacolor,lua-ul}                  % in the preamble
\PitonOptions{detected-commands = highLight}  % in the preamble
\end{Verbatim}
\end{footnotesize}

\medskip
\begin{Verbatim}
\begin{PitonExecute}[background-color=gray!15]
def square(x):
    """Computes the square of x"""
    ~emphase#\highLight{return x*x}@
print(f'The square of 12 is {square(12)}.')
\end{PitonExecute}
\end{Verbatim}

\medskip
\begin{PitonExecute}[background-color=gray!15]
def square(x):
    """Computes the square of x"""
    \highLight{return x*x}
print(f'The square of 12 is {square(12)}.')
\end{PitonExecute}

\bigskip
\subsubsection{Use of the environment \{pythonrepl\} of pyluatex}

\label{pythonrepl}
\index{pythonrepl@\texttt{\{pythonrepl\}} (environment of \pkg{pyluatex})}

The environment |{pythonrepl}| of \pkg{pyluatex} submit its content to Python and
return what we obtain when we submit that code to a \textsc{repl}
(\emph{read-eval-print loop}) of Python. We obtain a succession of instructions
preceded by the prompt |>>>| of Python and values returned by Python (and the outputs of
potential commands |print| of Python).

\medskip
It's possible to give that to an environment |{Piton}| which will do the usual formatting
and put on a colored background the lignes corresponding to the instructions provided to
the Python interpreter (the color of that background may be changed with the key
|prompt-background-color| whose inital value is |gray!15|).

\medskip
Here a programmation of environment |{PitonREPL}| which does that job (for technical
reasons, the |!| is here mandatory in the signature of the environment). It's not
possible to process as previously (in the ``standard'' use of \pkg{pyluatex}) because,
of course, the output of |{pythonrepla}| must be treated by \pkg{piton}. Therefore, it's not
possible to use the escaping tools (|detected-commands|, |begin-escape|, etc.) in the code.

\begin{Verbatim}
\NewDocumentEnvironment { PitonREPL } { ! O { } } % the ! is mandatory
 { 
   \PitonOptions
     {
       ~emphase#prompt-background-color=blue!15@ ,
       ~emphase#background-color=none@, % for small margins
       ~#1
     }
   \PyLTVerbatimEnv
   \begin{pythonrepl}
 }
 {
   \end{pythonrepl}
   \directlua
     {
       tex.print("\\begin{Piton}")
       tex.print(pyluatex.get_last_output())
       tex.print("\\end{Piton}")
       tex.print("") 
     } 
   \ignorespacesafterend
 }
\end{Verbatim}

\medskip
Here is an example of use of that new environment |{PitonREPL}|.

\medskip
\begin{Code}
\emph{\begin{PitonREPL}}
    def absolute_value(x):
        """Computes the absolute value of x"""
        if x > 0:
           return x
        else:
           return -x

    absolute_value(-3)
    absolute_value(0)
    absolute_value(5)
\emph{\end{PitonREPL}}
\end{Code}

\bigskip


\NewDocumentEnvironment { PitonREPL } { ! O { } }
 { 
   \PitonOptions
     {
       background-color=none ,
       prompt-background-color=blue!15 ,
       #1
     }
   \PyLTVerbatimEnv
   \begin{pythonrepl}
 }
 {
   \end{pythonrepl}
   \directlua
     {
       tex.print("\\begin{Piton}")
       tex.print(pyluatex.get_last_output())
       tex.print("\\end{Piton}")
       tex.print("") 
     }
   \ignorespacesafterend
 }

 
\begin{PitonREPL}
    def absolute_value(x):
        """Computes the absolute value of x"""
        if x > 0:
           return x
        else:
           return -x

    absolute_value(-3)
    absolute_value(0)
    absolute_value(5)
\end{PitonREPL}

\bigskip
In fact, it's possible to avoid the display of the prompts themselves (that is to say
the strings |>>>| and |...|). Indeed, \pkg{piton} provides a style for those elements,
called |Prompt|. The initial value of that style is empty, and that's why no action is done
for those elements and they are displayed as they are. By using a value which
is a function which gobbles its argument, it's possible to require that these prompts are not
displayed.


\bigskip
\begin{savenotes}
\begin{Verbatim}
\NewDocumentCommand{\Gobe}{m}{}#~color#black@~footnote#Here we have defined a function ~texttt#~string~Gobe@ but, in fact, it already exists in L3 with the name ~texttt#~string~use~_none:n@.@@
\SetPitonStyle{ ~emphase#Prompt = \Gobe@ }
\end{Verbatim}
\end{savenotes}

\NewDocumentCommand{\Gobe}{m}{}
\ExplSyntaxOn
\SetPitonStyle{ Prompt = \use_none:n }
\ExplSyntaxOff

\bigskip
L'exemple précédent donne alors :

\medskip
\begin{Verbatim}
~emphase#\begin{PitonREPL}@
    def absolute_value(x):
        """Computes the absolute value of x"""
        if x > 0:
           return x
        else:
           return -x

    absolute_value(-3)
    absolute_value(0)
    absolute_value(5)
~emphase#\end{PitonREPL}@
\end{Verbatim}


\bigskip

\begin{PitonREPL}
    def absolute_value(x):
        """Computes the absolute value of x"""
        if x > 0:
           return x
        else:
           return -x

    absolute_value(-3)
    absolute_value(0)
    absolute_value(5)
\end{PitonREPL}




\clearpage
\section{The styles for the different computer languages}

\label{Semantic}


\subsection{The language Python}

In \pkg{piton}, the default language is Python. If necessary, it's possible to
come back to the language Python with |\PitonOptions{language=Python}|.

\bigskip

The initial settings
done by \pkg{piton} in |piton.sty| are inspired by the style \pkg{manni} of
Pygments, as applied by Pygments to the language Python.\footnote{See:
\url{https://pygments.org/styles/}. Remark that, by default, Pygments provides
for its style \pkg{manni} a colored background whose color is the HTML color
|#F0F3F3|. It's possible to have the same color in |{Piton}|
with the instruction |\PitonOptions{background-color = [HTML]{F0F3F3}}|.} 

\vspace{1cm}

\begin{center}
\begin{tabularx}{\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
\toprule
\normalfont Style  & Use \\
\midrule
Number & the numbers \\
String.Short & the short strings (entre \texttt{'} ou \texttt{"}) \\
String.Long & the long strings (entre \texttt{'''} ou \texttt{"""}) excepted
              the doc-strings (governed by |String.Doc|)\\
String & that key fixes both |String.Short| et |String.Long| \\
String.Doc & the doc-strings (only with |"""| following PEP~257) \\
String.Interpol & the syntactic elements of the fields of the f-strings
(that is to say the characters \texttt{\{} et \texttt{\}}); that style
inherits for the styles |String.Short| and |String.Long| (according the kind
of string where the interpolation appears) \\
Interpol.Inside & the content of the interpolations in the f-strings (that
is to say the elements between \texttt{\{} and~\texttt{\}}); if the final
user has not set that key, those elements will be formatted by \pkg{piton}
as done for any Python code. \\
Operator & the following operators: \texttt{!= == << >> - \~{} + / * \% = < >
\& .} \verb+|+ \verb|@| \\ 
Operator.Word & the following operators: |in|, |is|, |and|, |or| et |not| \\
Name.Builtin & almost all the functions predefined by Python \\
Name.Decorator & the decorators (instructions beginning by \verb|@|) \\
Name.Namespace & the name of the modules \\
Name.Class & the name of the Python classes defined by the user \emph{at their
point of definition} (with the keyword |class|) \\  
Name.Function & the name of the Python functions defined by the user \emph{at their
point of definition} (with the keyword |def|) \\ 
UserFunction & the name of the Python functions previously defined by the user
               (the initial value of that parameter is
               {\ttfamily \textbackslash PitonStyle\{Identifier\}} and,
               therefore, the names of that functions are formatted like the
               identifiers).  \\
Exception & les exceptions prédéfinies (ex.: \texttt{SyntaxError}) \\
InitialValues & the initial values (and the preceding symbol |=|) of the
optional arguments in the definitions of functions; if the final
user has not set that key, those elements will be formatted by \pkg{piton}
as done for any Python code. \\
Comment & the comments beginning with \texttt{\#} \\
Comment.LaTeX & the comments beginning with \texttt{\#>}, which are composed by
\pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
Keyword.Constant & |True|, |False| et |None| \\
Keyword & the following keywords:
          \ttfamily assert, break, case, continue, del,
          elif, else, except, exec, finally, for, from, 
          global, if, import, in, lambda, non local,
          pass, raise, return, try, while,
          with, yield et yield from.\\
Identifier & the identifiers. \\
\bottomrule
\end{tabularx}
\end{center}


\newpage

\subsection{The language OCaml}

It's possible to switch to the language |OCaml| with the key |language|:
|language = OCaml|. 


\bigskip


\begin{center}
\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
  \toprule
  \normalfont Style  & Use \\
  \midrule
  Number & the numbers \\
  String.Short & the characters (between \texttt{'}) \\
  String.Long & the strings, between |"| but also the \emph{quoted-strings} \\
  String & that key fixes both |String.Short| and |String.Long| \\
  Operator & the oporators, in particular: |+|, |-|, |/|, |*|, |@|, |!=|, |==|, |&&| \\
  Operator.Word & the following operators: |asr|, |land|, |lor|, |lsl|, |lxor|, |mod| et |or| \\
  Name.Builtin & the functions |not|, |incr|, |decr|, |fst| et |snd| \\
  Name.Type & the name of a type of OCaml \\
  Name.Field & the name of a field of a module \\
  Name.Constructor & the name of the constructors of types (which begins by a capital) \\
  Name.Module & the name of the modules \\
  Name.Function & the name of the Python functions defined by the user \emph{at their
  point of definition} (with the keyword |let|) \\ 
  UserFunction & the name of the Python functions previously defined by the user
                 (the initial value of that parameter is
                 {\ttfamily \textbackslash PitonStyle\{Identifier\}} and,
                 therefore, the names of that functions are formatted like the identifiers). \\
  Exception & the predefined exceptions (eg : |End_of_File|) \\
  TypeParameter &  the parameters of the types \\
  Comment & the comments, between |(*| et |*)|; these comments may be nested \\
  Keyword.Constant & |true| et |false| \\
  Keyword & the following keywords: |assert|, |as|, |done|, |downto|, |do|,
  |else|, |exception|, |for|, |function| , |fun|, |if|, |lazy|, |match|,
  |mutable|, |new|, |of|, |private|, |raise|, |then|, |to|, |try| , |virtual|,
  |when|, |while| and |with| \\  
  Keyword.Governing & the following keywords: |and|, |begin|, |class|, |constraint|,
                     |end|, |external|, |functor|, |include|, |inherit|, |initializer|,
                     |in|, |let|, |method|, |module|, |object|, |open|, |rec|, |sig|,
                     |struct|, |type| and |val|. \\
 Identifier & the identifiers. \\
  \bottomrule
\end{tabularx}
\end{center}

\vspace{1cm}

Here is an example:

\medskip
\begin{Piton}[language = OCaml]
let rec quick_sort lst =    (* Quick sort *)
  match lst with
  | [] -> []
  | pivot :: rest ->
      let left  = List.filter (fun x -> x < pivot) rest in
      let right = List.filter (fun x -> x >= pivot) rest in
      quick_sort left @ [pivot] @ quick_sort right
\end{Piton}


\newpage

\subsection[The language C (and C++)]{The language C (and \CC)}


It's possible to switch to the language |C| with the key |language|: |language = C|.

\bigskip

\begin{center}
\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
\toprule
\normalfont Style  & Use \\
\midrule
Number & the numbers \\
String.Short & the characters (between \texttt{'}) \\
String.Long & the strings (between \texttt{"}) \\
String.Interpol &  the elements \texttt{\%d}, \texttt{\%i}, \texttt{\%f},
\texttt{\%c}, etc. in the strings; that style inherits from the style |String.Long| \\
Operator & the following operators : 
\texttt{!= == << >> - \~{} + / * \% = < > \& .} \verb+|+ \verb|@| \\ 
Name.Type & the following predefined types:
  |bool|, |char|, |char16_t|, |char32_t|, |double|, |float|, |int|, |int8_t|,
  |int16_t|, |int32_t|, |int64_t|, |uint8_t|, |uint16_t|, |uint32_t|, |uint64_t|,
  |long|, |short|, |signed|, |unsigned|, |void| et |wchar_t| \\  
Name.Builtin & the following predefined functions: |printf|, |scanf|,
|malloc|, |sizeof| and |alignof|  \\ 
Name.Class & the names of the classes when they are defined, that is to say after
  the keyword \verb|class| \\
Name.Function & the name of the Python functions defined by the user \emph{at their
  point of definition} (with the keyword |let|) \\ 
UserFunction & the name of the Python functions previously defined by the user
                 (the initial value of that parameter is
                 {\ttfamily \textbackslash PitonStyle\{Identifier\}} and,
                 therefore, the names of that functions are formatted like the
                 identifiers). \\ 
Preproc & the instructions of the preprocessor (beginning par |#|) \\
Comment & the comments (beginning by \texttt{//} or between |/*| and |*/|) \\
Comment.LaTeX & the comments beginning by  \texttt{//>} which are composed by
\pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
Keyword.Constant & |default|, |false|, |NULL|, |nullptr| and |true| \\
Keyword & the following keywords:
|alignas|, |asm|, |auto|, |break|, |case|, |catch|, |class|, 
|constexpr|, |const|, |continue|, |decltype|, |do|, |else|, |enum|,
|extern|, |for|, |goto|, |if|, |nexcept|, |private|, |public|, |register|,
|restricted|, |try|, |return|, |static|, |static_assert|, |struct|, |switch|,
|thread_local|, |throw|, |typedef|, |union|, |using|, |virtual|, |volatile|
and |while| \\
 Identifier & the identifiers. \\
\bottomrule
\end{tabularx}
\end{center}

\newpage

\subsection{The language SQL}


It's possible to switch to the language |SQL| with the key |language|: |language = SQL|.

\bigskip

\begin{center}
\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
\toprule
\normalfont Style  & Use \\
\midrule
Number & the numbers \\
String.Long & the strings (between \texttt{'} and not \texttt{"} because the
elements between \texttt{"} are names of fields and formatted with |Name.Field|) \\
Operator & the following operators : \texttt{= != <> >= > < <= * + / } \\
Name.Table & the names of the tables \\
Name.Field & the names of the fields of the tables \\
Name.Builtin & the following built-in functions (their names are \emph{not} case-sensitive): 
   |avg|, |count|, |char_length|, |concat|, |curdate|, |current_date|,
   |date_format|, |day|, |lower|, |ltrim|, |max|, |min|, |month|, |now|,
   |rank|, |round|, |rtrim|, |substring|, |sum|, |upper| and |year|. \\
Comment & the comments (beginning by \texttt{--} or between |/*| and |*/|) \\
Comment.LaTeX & the comments beginning by  \texttt{-->} which are composed by
\pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
Keyword & the following keywords (their names are \emph{not} case-sensitive):
|abort|, |action|, |add|, |after|, |all|, |alter|, |always|, |analyze|,
|and|, |as|, |asc|, |attach|, |autoincrement|, |before|, |begin|, |between|,
|by|, |cascade|, |case|, |cast|, |check|, |collate|, |column|, |commit|,
|conflict|, |constraint|, |create|, |cross|, |current|, |current_date|,
|current_time|, |current_timestamp|, |database|, |default|, |deferrable|,
|deferred|, |delete|, |desc|, |detach|, |distinct|, |do|, |drop|, |each|,
|else|, |end|, |escape|, |except|, |exclude|, |exclusive|, |exists|,
|explain|, |fail|, |filter|, |first|, |following|, |for|, |foreign|, |from|,
|full|, |generated|, |glob|, |group|, |groups|, |having|, |if|, |ignore|,
|immediate|, |in|, |index|, |indexed|, |initially|, |inner|, |insert|,
|instead|, |intersect|, |into|, |is|, |isnull|, |join|, |key|, |last|,
|left|, |like|, |limit|, |match|, |materialized|, |natural|, |no|, |not|,
|nothing|, |notnull|, |null|, |nulls|, |of|, |offset|, |on|, |or|, |order|,
|others|, |outer|, |over|, |partition|, |plan|, |pragma|, |preceding|,
|primary|, |query|, |raise|, |range|, |recursive|, |references|, |regexp|,
|reindex|, |release|, |rename|, |replace|, |restrict|, |returning|, |right|,
|rollback|, |row|, |rows|, |savepoint|, |select|, |set|, |table|, |temp|,
|temporary|, |then|, |ties|, |to|, |transaction|, |trigger|, |unbounded|,
|union|, |unique|, |update|, |using|, |vacuum|, |values|, |view|, |virtual|,
|when|, |where|, |window|, |with|, |without| \\
\bottomrule
\end{tabularx}
\end{center}


\bigskip
It's possible to automatically capitalize the keywords by modifying locally
for the language SQL the style |Keywords|.
\begin{Verbatim}
\SetPitonStyle~emphase#[SQL]@{Keywords = \bfseries \MakeUppercase}
\end{Verbatim}

\newpage
\subsection{The languages defined by \textbackslash NewPitonLanguage}

\vspace{1cm}
The command |\NewPitonLanguage|, which defines new computer 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| \\
Tag & the ``tags'' defined by the key |tag| (the lexical units detected within
the tag will also be formatted with their own style) \\
 Identifier & the identifiers. \\
\bottomrule
\end{tabularx}
\end{center}


\vspace{1cm}
Here is for example a definition for the language HTML, obtained with a slight
adaptation of the definition done by \pkg{listings} (file |lstlang1.sty|).

\medskip
\begin{small}
\begin{Verbatim}
\NewPitonLanguage{HTML}%
  {morekeywords={A,ABBR,ACRONYM,ADDRESS,APPLET,AREA,B,BASE,BASEFONT,%
      BDO,BIG,BLOCKQUOTE,BODY,BR,BUTTON,CAPTION,CENTER,CITE,CODE,COL,%
      COLGROUP,DD,DEL,DFN,DIR,DIV,DL,DOCTYPE,DT,EM,FIELDSET,FONT,FORM,%
      FRAME,FRAMESET,HEAD,HR,H1,H2,H3,H4,H5,H6,HTML,I,IFRAME,IMG,INPUT,%
      INS,ISINDEX,KBD,LABEL,LEGEND,LH,LI,LINK,LISTING,MAP,META,MENU,%
      NOFRAMES,NOSCRIPT,OBJECT,OPTGROUP,OPTION,P,PARAM,PLAINTEXT,PRE,%
      OL,Q,S,SAMP,SCRIPT,SELECT,SMALL,SPAN,STRIKE,STRING,STRONG,STYLE,%
      SUB,SUP,TABLE,TBODY,TD,TEXTAREA,TFOOT,TH,THEAD,TITLE,TR,TT,U,UL,%
      VAR,XMP,%
      accesskey,action,align,alink,alt,archive,axis,background,bgcolor,%
      border,cellpadding,cellspacing,charset,checked,cite,class,classid,%
      code,codebase,codetype,color,cols,colspan,content,coords,data,%
      datetime,defer,disabled,dir,event,error,for,frameborder,headers,%
      height,href,hreflang,hspace,http-equiv,id,ismap,label,lang,link,%
      longdesc,marginwidth,marginheight,maxlength,media,method,multiple,%
      name,nohref,noresize,noshade,nowrap,onblur,onchange,onclick,%
      ondblclick,onfocus,onkeydown,onkeypress,onkeyup,onload,onmousedown,%
      profile,readonly,onmousemove,onmouseout,onmouseover,onmouseup,%
      onselect,onunload,rel,rev,rows,rowspan,scheme,scope,scrolling,%
      selected,shape,size,src,standby,style,tabindex,text,title,type,%
      units,usemap,valign,value,valuetype,vlink,vspace,width,xmlns},%
   tag=<>,%
   alsoletter = - ,%
   sensitive=f,%
   morestring=[d]",
  }
\end{Verbatim}
\end{small}



\subsection{The language ``minimal''}

\label{minimal}

It's possible to switch to the language ``|minimal|'' with the key |language|:
|language = minimal|.

\bigskip

\begin{center}
\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
\toprule
\normalfont Style  & Usage \\
\midrule
Number & the numbers \\
String & the strings (between \texttt{"}) \\
Comment & the comments (which begin with |#|) \\
Comment.LaTeX &  the comments beginning with \texttt{\#>}, which are composed by
  \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document)
  \\
 Identifier & the identifiers. \\
\bottomrule
\end{tabularx}
\end{center}

\bigskip
That language is provided for the end user who might wish to add keywords in
that language (with the command |\SetPitonIdentifier|: cf. \ref{SetPitonIdentifier},
p.~\pageref{SetPitonIdentifier}) in order to create, for example, a language
for pseudo-code.

\vspace{1cm}

\subsection{The language ``verbatim''}

\label{verbatim}

It's possible to switch to the language ``|verbatim|'' with the key |language|:
|language = verbatim|.

\bigskip

\begin{center}
\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
\toprule
\normalfont Style  & Usage \\
\midrule
None... & \\
\bottomrule
\end{tabularx}
\end{center}

The language |verbatim| doesn't provide any style and, thus, does not do any
syntactic formating. However, it's possible to use the mechanism
|detected-commands| (cf. part~\ref{detected-commands},
p.~\pageref{detected-commands}) and the detection of the commands and
environments of Beamer.



\vspace{1cm}
\section{History}


The development of the extension \pkg{piton} is done on the following GitHub
repository:

\verb|https://github.com/fpantigny/piton|

\medskip
The successive versions of the file |piton.sty| provided by TeX Live are also available
on the \textsc{svn} server of TeX Live:

\nobreak
\smallskip
{
\small
\nolinkurl{https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty}
}

\subsection*{Changes between versions 4.11 and 4.12}

The documentation has been changed in order to be compatible with the version
0.7.0 of \pkg{pyluatex}.

New key ``|font-command +|''.

\subsection*{Changes between versions 4.10 and 4.11}

New keys |right-margin| and |line-numbers/position|.


\subsection*{Changes between versions 4.9 and 4.10}

New key |line-numbers/step|.

\subsection*{Changes between versions 4.8 and 4.9}

New keys |paperclip| and |annotations|.

The package \pkg{piton} is now provided with three TeX files: |piton-code.dtx| (for the
code), |piton.tex| (the documentation in English) and |piton-french.tex| (the
documentation in French).

\subsection*{Changes between versions 4.7 and 4.8}

New key |\rowcolor|

The command |\label| redefined by \pkg{piton} is now compatible with \pkg{hyperref}
(thanks to P. Le Scornet).

New key |label-as-zlabel|.

\subsection*{Changes between versions 4.6 and 4.7}

New key |rounded-corners|

\subsection*{Changes between versions 4.5 and 4.6}

New keys |tcolorbox|, |box|, |max-width| and |vertical-detected-commands|

New special color: |none|

\subsection*{Changes between versions 4.4 and 4.5}

New key |print|

|\RenewPitonEnvironment|,
|\DeclarePitonEnvironment| and |\ProvidePitonEnvironment| have been added.

\subsection*{Changes between versions 4.3 and 4.4}

New key |join| which generates files embedded in the \textsc{pdf} as \emph{joined files}.

\subsection*{Changes between versions 4.2 and 4.3}

New key |raw-detected-commands|

The key |old-PitonInputFile| has been deleted.

\subsection*{Changes between versions 4.1 and 4.2}

New key |break-numbers-anywhere|.

\subsection*{Changes between versions 4.0 and 4.1}

New language |verbatim|.

New key |break-strings-anywhere|.

\subsection*{Changes between versions 3.1 and 4.0}

The syntax for the relative and absolute paths in |\PitonInputFile| and the key
|path| has been changed to be conform to usual conventions.


New keys |font-command|, |splittable-on-empty-lines| and |env-used-by-split|.


\subsection*{Changes between versions 3.0 and 3.1}

Keys |line-numbers/format|, |detected-beamer-commands| and
|detected-beamer-environments|. 


\subsection*{Changes between versions 2.8 and 3.0}

New command |\NewPitonLanguage|. Thanks to that command, it's now possible to
define new computer languages with the syntax used by \pkg{listings}.
Therefore, it's possible to say that virtually all the computer 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 paths where the files to include
will be searched.

New commands |\PitonInputFileT|, |\PitonInputFileF| and |\PitonInputFileTF|.

\subsection*{Changes between versions 2.6 and 2.7}

New keys |split-on-empty-lines| and |split-separation|

\subsection*{Changes between versions 2.5 and 2.6}

API: |piton.last_code| and |\g_piton_last_code_tl| are provided.

\subsection*{Changes between versions 2.4 and 2.5}

New key |path-write|

\subsection*{Changes between versions 2.3 and 2.4}

The key |identifiers| of the command |\PitonOptions| is now deprecated and
replaced by the new command |\SetPitonIdentifier|.

A new special language called ``minimal'' has been added.

New key |detected-commands|.

\subsection*{Changes between versions 2.2 and 2.3}

New key |detected-commands|

The variable |\l_piton_language_str| is now public.


New key |write|.

\subsection*{Changes between versions 2.1 and 2.2}

New key |path| for |\PitonOptions|.

New language SQL.

It's now possible to define styles locally to a given language.

\subsection*{Changes between versions 2.0 and 2.1}

The key |line-numbers| has now subkeys |line-numbers/skip-empty-lines|,
|line-numbers/label-empty-lines|, etc. 

The key |all-line-numbers| is deprecated: use
|line-numbers/skip-empty-lines=false|. 

New system to import, with |\PitonInputFile|, only a part (of the file)
delimited by textual markers. 

New keys |begin-escape|, |end-escape|, |begin-escape-math| and |end-escape-math|.

The key |escape-inside| is deprecated: use |begin-escape| and |end-escape|.





\section*{Other documentation}

The document |piton-french.pdf| (provided by the extension \pkg{piton}) contains a French
translation of the current documentation. The file |piton-code.pdf| describes the
implementation of the package \pkg{piton} (both L3 and Lua parts).


\section*{Acknowledgments}

Acknowledgments to Yann Salmon and Pierre Le Scornet for their numerous suggestions
of improvments.




\cleardoublepage

\phantomsection
\addcontentsline{toc}{section}{Index}

\printindex
 

\tableofcontents

\end{document}

% Local Variables:
% fill-column: 80
% End: