\documentclass[final]{llncs}


%%%% Compression Light+: LNCS margin reduced by +/-7mm along all edges (RG).
%\textwidth=124mm   % LNCS: 122mm
%\textheight=194mm  % LNCS: 193mm
%\topmargin=19mm
%\headheight=0mm
%\headsep=0mm
%\oddsidemargin=11mm
%\evensidemargin=11mm

%section name
\usepackage{makeidx}  % allows for index generation
\usepackage{amsmath}
\usepackage[hyphens]{url}
\usepackage{tabularx}
\usepackage{graphicx}
\usepackage{verbatim}
\usepackage{microtype}
\usepackage[utf8]{inputenc}
\usepackage[ngerman]{babel}
\usepackage[export]{adjustbox} %[2011/08/13]
\usepackage{bsymb}
\usepackage{amsmath}

\usepackage[utf8]{inputenc}

\usepackage{skak} % for Chess

\newcommand{\prob}{{\sc ProB}}
\newcommand{\probrepl}[2][silent]{repl} %{#2}
\newcommand{\probexpr}[2][silent]{expr} %{#2}
\newcommand{\probtable}[3][no]{table} %{#2}
\newcommand{\probdot}[3][File]{dot} %{#3}
\newcommand{\probif}[3]{if} %{if #1 then #2 else #3}
\newcommand{\probfor}[3]{for} %{for #1 in #2 do #3}

\begin{document}
%


\pagestyle{empty}  % headings switches on printing of running heads

\addtocmark{ProB Latex} % additional mark in the TOC
%
\mainmatter              % start of the contributions
%

\title{ProB Latex Comands}
% \subtitle{B and ProB}
%
\titlerunning{ProB for Latex}  % abbreviated title (for running head)
%                                     also used for the TOC unless
%                                     \toctitle is used
%
\author{Michael Leuschel}
%
\authorrunning{Leuschel} % abbreviated author list (for running head)
%
%%%% list of authors for the TOC (use if author list has to be modified)
\tocauthor{}
%
\institute{Institut f\"{u}r Informatik, Heinrich-Heine-Universit\"{a}t D\"{u}sseldorf%
 \\
  Universit\"{a}tsstr. 1, D-40225 D\"{u}sseldorf\\
  {\tt\scriptsize \{michael.leuschel\}@hhu.de}
 }

\maketitle              % typeset the title of the contribution


\section{Overview}

\prob\ can be used to process Latex files, i.e., \prob\ scans a given Latex file
 and replaces certain commands by processed results.

\subsubsection*{Usage}
A typical usage would be as follows: 

\begin{verbatim}
   probcli FILE -init -latex Raw.tex Final.tex
\end{verbatim}

Note: the FILE and -init commands are optional; they are required in case you want to
process the commands in the context of a certain model.
Currently the \prob\ Latex commands mainly support B and Event-B models, 
 TLA+ and Z models can also be processed but all commands below expect B syntax.
You can add more commands if you wish, e.g., set preferences using {\tt -p PREF VAL}
 or run model checking {\tt --model-check}.
The Latex processing will take place after most other commands, such as model checking.

You will probably want to put the probcli call into a Makefile, in particular when you want
to generate dot graphics using \prob (see below).
This file was generated by putting the following into the Makefile:

\begin{verbatim}
prob_latex_doc.tex: prob_latex_doc_raw.tex
   probcli -latex prob_latex_doc_raw.tex prob_latex_doc.tex
\end{verbatim}

\subsubsection*{Applications}

\begin{itemize}
 \item model documentation: generate a documentation for a formal model, that is guaranteed
  to be up-to-date and shows the reader how to operate on the model.
 \item worksheets for particular tasks: for certain tasks the Latex document can replace
  a formal model, the model is built-up by Latex commands and the results shown in the
  final Latex output.
  This is probably most appropriate for smaller, isolated mathematical problems.
 \item validation reports for model checking or assertion checking results
 \item coverage reports for test-case generation,
 \item funding proposals with a B modelling of workpackages, tasks and partners,
 \item and hopefully many more.
\end{itemize} 

% ----------------

\section{ProB Latex Commands}

\subsection{General Aspects}

Currently every \prob\ Latex command has to be put onto a {\bf single} line.
In future this may be relaxed.
Every command has the following form:
\begin{verbatim}
  \probCMD{ARG}{Opt1}...{Optn}
\end{verbatim}
The arguments {\tt Opt1} to {\tt Optn} are optional.

If you add dummy Latex command definitions for the \prob\ commands you can use Latex to process the
original, raw Latex file without running \prob, e.g., to check for errors and general layout.
E.g., for the first command presented below you could write:

\begin{verbatim}
 \newcommand{\probexpr}[1]{#1}
\end{verbatim}

Also, \prob\ commands are not replaced within line comments starting with \verb+%+.
However, \prob\ commands are processed within block comments (started by \verb+\begin{comment}+).

% -----------------

\subsection{Evaluating Expressions}

\newcommand{\probCMD}[1]{{\tt $\backslash$prob#1}}

The {\tt \probCMD{expr}} command takes a B expression as argument and evaluates it.
By default it shows the B expression and the value of the expression.

Here are a few examples:
\begin{itemize}
   \item  \probCMD{expr}\verb+{{1}\/{2**10}}+ in the raw Latex file will yield:\\
        {$\probexpr{{1}\/{2**10}}$}
    \item   \probCMD{expr}\verb+{{1}\/{2**10}}{ascii}+  instructs \prob\ to use the B ASCII syntax:\\
        {\tt \verb+\probexpr{{1}\/{2**10}}{ascii}+}
    \item    \probCMD{expr}\verb+{{1}\/{2**10}}{value}+  means that only the value will be displayed:\\
        $\probexpr{{1}\/{2**10}}{value}$
    \item    \probCMD{expr}\verb+{"B-String"}{value}{string}+  means that for string results the B quotes are removed:\\
        \probexpr{"B-String"}{value}{string}
\end{itemize}


\subsection{Executing REPL commands}

The {\tt \probCMD{repl}} command takes a REPL command and executes it.
By default it shows only the output of the execution, e.g., in case it is a predicate
TRUE or FALSE.

Here are a few examples:
\begin{itemize}
   \item  \probCMD{repl}\verb+{2**10>1000}+ in the raw Latex file will yield:\\
        {$\probrepl{2**10>1000}$}
    \item   \probCMD{repl}\verb+{let DOM = 1..3}+ outputs a value and will define the variable 
    {\tt DOM} for the remainder of the Latex run%
\footnote{Unless it is removed using {\tt :unlet DOM}}:\\
        {$\probrepl{let DOM = 1..3}$}
    \item    \probCMD{repl}\verb+{a:(DOM * DOM)-->DOM}+  uses the above variable {\tt DOM}:\\
        $\probrepl{a:(DOM * DOM)-->DOM}$
\end{itemize}


\subsection{Generating Latex Tables}
The {\tt \probCMD{table}} command takes a B expression as argument, evaluates it and shows it as a table.
Valid options are {\tt no-headings}, {\tt no-tabular}, {\tt no-hline}, {\tt no-row-numbers}
 as well as {\tt max-table-size=N} where N is a number.

Here are a few examples:
\begin{itemize}
   \item  \probCMD{table}\verb+{{(1,2)|->3,(4,5)|->9}}+ in the raw Latex file will yield:\\
   
        \probtable{{(1,2)|->3,(4,5)|->9}}
        
   \item    \probCMD{table}\verb+{a:((1..2) * BOOL)-->>DOM}{no-row-numbers}+  yields:\\
   
        \probtable{a:((1..2) * BOOL)-->>DOM}{no-row-numbers}
        
   \item    \probCMD{table}\verb+{a:((1..2) * BOOL)-->>DOM}{no-headings}{no-tabular}{no-row-numbers}+  means we have
    to provide ourselves the tabular environment and can set it up and format it accordingly:\\
    
      \begin{tabular}{|l|r|r|}
       \hline
         Idx & Truth & Range\\
        \hline
        \probtable{a:((1..2) * BOOL)-->>DOM}{no-headings}{no-tabular}{no-row-numbers}
        \hline
       \end{tabular}
       
\end{itemize}

\subsection{Generating Dot Graphics}
The {\tt \probCMD{dot}} command takes a B expression or predicate as argument, evaluates it and 
 translates it into a dot graphic.
It takes either one or two additional arguments.
The first additional argument is always the name/path of the generated dot file.
The second optional argument is the name/path of the generated pdf file, it will be generated
using the dot command.
You can give \prob\ the path to the dot command at startup using the {\tt DOT} preference, e.g., using:
\begin{verbatim}
   probcli -latex Raw.tex Final.tex -p DOT /usr/local/bin/dot
\end{verbatim}

When the second additional argument is missing, you need to generate the PDF yourself, e.g., using {\tt sfdp}
  in the Makefile.

Here is an example:
\begin{itemize}
   \item \probCMD{dot}\verb+{bij:DOM>->>DOM & !x.(x:DOM=>bij(x)/=x)}{figures/bij.dot}{figures/bij.pdf}+  
     generates the file bij.pdf. It then can be included using the command {\tt includegraphics}, see Figure~\ref{fig:bij}.
        \probdot{bij:DOM>->>DOM & !x.(x:DOM=>bij(x)/=x)}{figures/bij.dot}{figures/bij.pdf}
   \item \probCMD{dot}\verb+{a={TRUE}*(1..10) & s=%x.(x:1..3|x*x)}{figures/ab.dot}+  
     generates the file ab.dot. In the associated Makefile we use {\tt sfdp} to generate the graphic
     included in Figure~\ref{fig:ab}.
     The example also shows how to display two relations/graphs in one figure.
        \probdot{a={TRUE}*(1..10) & s=%x.(x:1..3|x*x)}{figures/ab.dot}
\end{itemize}

The Makefile for Figure~\ref{fig:ab} contains:
\begin{verbatim}
figures/ab.pdf: figures/ab.dot
     $(SFDP) -Tpdf figures/ab.dot > figures/ab.pdf
\end{verbatim}

\begin{figure}
  \centering
  \includegraphics[width=0.20\textwidth]{figures/bij.pdf}
  \caption{Illustrating a bijection}
  \label{fig:bij}
\end{figure}

\begin{figure}
  \centering
  \includegraphics[width=0.50\textwidth]{figures/ab.pdf}
  \caption{Illustrating two graphs in a figure}
  \label{fig:ab}
\end{figure}

\subsection{Pretty Printing Formulas}

The {\tt \probCMD{print}} command takes an expression or predicate and pretty prints it.
Some symbols require the {\tt bsymb.sty} package to be imported using \verb+\usepackage{bsymb}+.
If the formula is a predicate the second argument should be \verb+pred+.

\begin{itemize}
   \item \probCMD{print}\verb@{bool({1}<|{1|->2,2|->3}|>>{4}:NATURAL+->INTEGER)}@ yields:\\
    $\probprint{bool({1}<|{1|->2,2|->3}|>>{4}:NATURAL+->INTEGER)}$
   \item \probCMD{print}\verb+{2>1 & 3-2=1}{pred}+ yields:\\
    $\probprint{2>1 & 3-2=1}{pred}$
\end{itemize}


\subsection{Conditional}

The {\tt \probCMD{if}} command takes an expression or predicate and two Latex texts.
If the expression evaluates to TRUE the first branch is processed, otherwise the other one is processed.

Here are a few examples:
\begin{itemize}
   \item  \probCMD{if}\verb+{2**10>1000}{$\top$}{$\bot$}+ in the raw Latex file will yield:\\
   
        \probif{2**10>1000}{$\top$}{$\bot$}
   \item  \probCMD{if}\verb+{bool(2**10<1000)}{$\top$}{$\bot$}+ in the raw Latex file will yield:\\
   
        \probif{bool(2**10<1000)}{$\top$}{$\bot$}

\end{itemize}


\subsection{Repetition}
The {\tt \probCMD{for}} command takes an identifier, a set expression and a Latex text,
 and processes the Latex text for every element of the set expression, setting the identifier to
 a value of the set.

For example, below we embed the command:\\
 \probCMD{for}\verb+{ii}{1..5}{ \item the square of \probexpr+\verb+{ii} is \probexpr+\verb+{ii*ii} }+
 within an itemize environment to generate a list of entries:

\begin{itemize}
 \probfor{ii}{1..5}{ \item the square of \probexpr{ii} is \probexpr{ii*ii} }
\end{itemize}

\section{Examples}

\subsection{Visualising all bijections}


\begin{comment}
 put into comments so that we do not see the output:
 \probrepl{let bijs = SORT(DOM >->>DOM)}
\end{comment}
 \label{SORT}
 
In Figure~\ref{fig:bij6} we show all $\probexpr{card(bijs)}{value}$ bijections for $\probexpr{DOM}$ to itself.
We have used the command \probCMD{repl}\verb+{let bijs = SORT(DOM >->>DOM)}+ to compute all bijections and sort them into a sequence (using the external
 function {\tt SORT}). This command is in a comment block, so its output does not appear in the Latex file.
We then use one \probCMD{for}\verb+{ii}{dom(bijs)}{...}+ to generate the PDFs and one to include the graphics in the figure.
The Latex code does not know how many bijections there are.

 \probfor{ii}{dom(bijs)}{ \probdot{bijs(ii)}{figures/bij.dot}{figures/bij\probexpr{ii}{value}.pdf}}

%\probdot{bijs(1)}{figures/bij.dot}{figures/bij1.pdf}

\begin{figure}
  \centering
 \probfor{ii}{dom(bijs)}{ \includegraphics[width=0.20\textwidth]{figures/bij\probexpr{ii}{value}.pdf} }
%  \includegraphics[width=0.20\textwidth]{figures/bij1.pdf}

  \caption{Illustrating all bijections from $\probexpr{DOM}$ to itself}
  \label{fig:bij6}
\end{figure}

\begin{comment}
 put into comments so that we do not see the output:
 \probrepl{let bijs = SORT(1..2 >->> BOOL)}
\end{comment}

Indeed, we can use very similar commands to generate in Figure~\ref{fig:bij2} we show all $\probexpr{card(bijs)}{value}$ bijections between $1..2$ and $BOOL$.

 \probfor{ii}{dom(bijs)}{ \probdot{bijs(ii)}{figures/bij.dot}{figures/bij2-\probexpr{ii}{value}.pdf}}

\begin{figure}
  \centering
 \probfor{ii}{dom(bijs)}{ \includegraphics[width=0.35\textwidth]{figures/bij2-\probexpr{ii}{value}.pdf} }
  \caption{Illustrating all bijections between $1..2$ and $BOOL$}
  \label{fig:bij2}
\end{figure}

\subsection{N-Queens}

Let us solve the N-Queens problem for n=\probrepl{let n = 8}.
For this we use \probCMD{repl} to solve the predicate
  $\probprint{queens : 1..n >-> 1..n & !(q1,q2).(q1:1..n & q2:2..n & q2>q1 => queens(q1)+(q2-q1) /= queens(q2) & queens(q1)+(q1-q2) /= queens(q2))}{pred}$.
 %\verb+queens : 1..n >-> 1..n+  % it would be nice to have a \probpretty{} command here
% together with \verb+!(q1,q2).(q1:1..n & q2:2..n & q2>q1 =>+ \verb@queens(q1)+(q2-q1) /= queens(q2) & queens(q1)+(q1-q2) /= queens(q2))@.
We use the optional argument \verb+{store}+ to store the found value of {\tt queens} (similar to a let).
We then set up a tabular environment in which we next two \probCMD{for} commands (one for the rows and
then one for the columns), with
 a \probCMD{if} to generate the symbol \verb+\WhiteQueenOnWhite+ from the skak package whenever a queen is at the present position.
 
% we need something like \probsolve and store a solution: the new store option does this
\probrepl{queens : 1..n >-> 1..n & !(q1,q2).(q1:1..n & q2:2..n & q2>q1 => queens(q1)+(q2-q1) /= queens(q2) & queens(q1)+(q1-q2) /= queens(q2))}{store}{silent}

%\probrepl{let qt = %i.(i:1..n| %j.(j:1..n|bool(queens(i)=j)))}{silent}

\begin{center}
\begin{tabular}{\probfor{ii}{1..n}{|c}|}
\hline
\probfor{ii}{1..n}{  \probfor{jj}{1..(n-1)}{  \probif{queens(ii)=jj}{\WhiteQueenOnWhite}{} &} \probif{queens(ii)=n}{\WhiteQueenOnWhite}{} \\ \hline}
\end{tabular}
\end{center}

% other symbols would be \BlackEmptySquare, \WhiteQueenOnWhite, \symqueen

\subsection{Primes}

Using a similar scheme as used to display the N-Queens solution, we can visualise the
 prime numbers up to \probrepl{let n = 99}:
 \probrepl{let primes = {p|p:2..n & !x.(x:2..(p-1) => p mod x >0)}}{silent}
   
\begin{center}
\begin{tabular}{\probfor{ii}{0..9}{|c}|}
\hline
\probfor{ii}{0..(n/10)}{  \probfor{jj}{0..8}{  \probif{ii*10+jj:primes}{\probexpr{ii*10+jj}{value}}{~~~} &} \probif{ii*10+9:primes}{\probexpr{ii*10+9}{value}}{~~~} \\ \hline}
\end{tabular}
\end{center}

% ---------

\section{Version and Configuration Information}


\subsection{Version Information}

Using external functions you can obtain various information which can be useful to include in the
generated Latex files.
For example, this document was generated using \prob\ version $\probexpr{PROB_INFO_STR("prob-version")}{value}{string}$.
Here are the external functions used for this Latex file, they can be found in the machine {\tt ProBLatex.mch}
 and in the imported files in \prob's {\tt stdlib} folder (e.g., {\tt LibraryMeta.def}).

\begin{verbatim}
DEFINITIONS
 "LibraryMeta.def";
 EXTERNAL_FUNCTION_SORT(X) == POW(X) --> POW(INTEGER*X);
 SORT(x) == [];
\end{verbatim}
 

The {\tt SORT} function was used above in Section~\ref{SORT}.
Using the {\tt PROB\_INFO\_STR} external function we can gather the following information about \prob\ (the
 {\tt prolog-version} information is not shown):

\probtable{{Flag,StringValue|StringValue=PROB_INFO_STR(Flag) & Flag /= "prolog-version"}}

Using the {\tt PROB\_INFO\_INT} external function we can gather the following information about \prob\ and its
 current state:

\probtable{{Flag,IntValue|IntValue=PROB_INFO_INT(Flag)}}

% ---------
\subsection{Model Information}

Using the {\tt PROJECT\_INFO} external function we can gather information about the B project (the {\tt absolute-files}
 information is not shown):

\probtable{{Flag,Value|Value=PROJECT_INFO(Flag) & Flag /= "absolute-files"}}

% ---------
\subsection{Preferences}

Using the {\tt GET\_PREF} and {\tt GET\_PREF\_DEFAULT} external function we can gather information about preferences and, e.g., display the non-default preferences:

\probtable{{Preference,Value|Value=GET_PREF(Preference) & Value /= GET_PREF_DEFAULT(Preference)}}


% ---------

\subsection{History}

Using the {\tt STATE\_AS\_STRING} and {\tt HISTORY} external function we can gather information about
 the current history (e.g., can be used to display a counter-example after model checking).

\probtable{{Step,ID,State|(Step,ID):HISTORY & State=STATE_AS_STRING(ID)}}{no-row-numbers}

Using the {\tt STATE\_SUCC} external predicate we can also inspect the entire state space:

\probtable{{ID,SuccID| STATE_SUCC(ID,SuccID)}}{no-row-numbers}

% ---------

\subsection{Status of Assertions, Invariants, etc.}

Using the {\tt FORMULA\_INFOS} and {\tt FORMULA\_VALUES} external function we can gather information about invariants, guards and assertions (actually everything that is displayed in the \prob\ evaluation view):

\probrepl{let assi = FORMULA_INFOS("theoremsc")}{silent}
\probrepl{let assv = FORMULA_VALUES("theoremsc")}{silent}
\begin{itemize}
\probfor{ii}{dom(assi)}{\item[\probexpr{ii}{value}] $\probexpr{assi(ii)}{value}{string}$\\ \probexpr{assv(ii)}{value}{string} }
\end{itemize}


Here are the invariants and their status:

\probrepl{let invi = FORMULA_INFOS("inv")}{silent}
\probrepl{let invv = FORMULA_VALUES("inv")}{silent}
\begin{itemize}
\probfor{ii}{dom(invi)}{\item[\probexpr{ii}{value}] $\probexpr{invi(ii)}{value}{string}$\\ \probexpr{invv(ii)}{value}{string} }
\end{itemize}

\section{Issues and to do's}

The Latex interface is still evolving, commands and command format may change.
The same is true for the relevant external functions.

\begin{itemize}
\item Error handling could be improved (check all arguments valid; try and make raw Latex be valid),
\item refactor eval\_codes and eval\_strings in general
\item check performance of parsing via Java (seems to take 10-20 ms per parsing call), we now cache parse results,
\item add {\tt probinclude} command; can be used e.g. for graphical visualisation of history,
\item more external functions (setStateID,...), maybe more or less complete reification of interface,
  repl and tk and prob2\_interface commands ideally implemented via external function ?
\item the rendering of strings is not yet optimal. 
\end{itemize}

\end{document}
