[SCM] Lisaac documentation branch, master, updated. fd8694fcbcae00431b138c0c400a07e017589469
Xavier Oswald
xoswald at debian.org
Fri Aug 21 16:04:42 UTC 2009
The following commit has been merged in the master branch:
commit fd8694fcbcae00431b138c0c400a07e017589469
Author: Xavier Oswald <xoswald at debian.org>
Date: Fri Aug 21 18:01:48 2009 +0200
* Add a Lip Section and some explanation how Lip works
* Add the -lip slot in Section Header description
* Add lstlisting package support
TODO: Write a small lstlisting lisaac mode and transform all existing
lisaac latex code in lstlisting.
diff --git a/reference_manual/Lisaac_RM.tex b/reference_manual/Lisaac_RM.tex
index aba8586..452095a 100644
--- a/reference_manual/Lisaac_RM.tex
+++ b/reference_manual/Lisaac_RM.tex
@@ -28,6 +28,10 @@
\usepackage{verbatim}
\usepackage{color}
+% For including Lisaac code in latex
+\usepackage{listings}
+\lstset{ basicstyle=\scriptsize } % small font
+
%\setlength{\hoffset}{-18pt}
\setlength{\oddsidemargin}{5mm} % Marge gauche sur pages impaires
\setlength{\evensidemargin}{0mm} % Marge gauche sur pages paires
@@ -187,7 +191,8 @@ FRANCE\\
by
\vskip 10mm
S{\sc{}onntag} Benoit ({\tt{}sonntag at icps.u-strasbg.fr})\\
-C{\sc{}habert} Alexandre ({\tt{}a.chabert at cegetel.net})
+C{\sc{}habert} Alexandre ({\tt{}a.chabert at cegetel.net})\\
+O{\sc{}swald} Xavier ({\tt{}xoswald at debian.org})
\end{center}
@@ -219,8 +224,10 @@ Section\,: Compiler and optimization}
{Version 0.3} & {September 24, 2007} \\
{} & {Benoit Sonntag, Alexandre Chabert}\\
{} & {} \\
-{Version 0.31} & {\today} \\
+{Version 0.31} & {September 22, 2008} \\
{} & {Benoit Sonntag, Pierre-Alexandre Voye}\\
+{Version 0.4} & {\today} \\
+{} & {Xavier Oswald}\\
\end{tabular}
\end{center}
@@ -579,6 +586,9 @@ Le symbole {\bf{} :=} est une affectation. Faites bien attention à ne pas utili
Vous verrez le symbole {\bf{} +} or {\bf{} -} avant chaque slot. Il d'efinie le type, la port'ee du slot et est obligatoire. Son rôle sera expliqu'e dans les prochains pages.
}
+
+
+
%=========================================================
\section{Objects}
\label{quickstart:objects}
@@ -1535,7 +1545,173 @@ Object {\sc{}son}
\chapter{Language Reference}
\label{language_reference}
%*********************************************************
-%
+
+%=========================================================
+\section{Lip: Lisaac project file (Lisaac Makefile)}
+\label{language_reference:lip}
+%=========================================================
+
+Before entering deeper with the Lisaac language, the first step is to explain
+how to compile a Lisaac program using Lip files. They are used to describe
+compiler options, paths, include external libs even do inheritance between
+projects.
+
+\subsection{Lip Grammar}
+
+The Lip grammar is a subset of the Lisaac grammar.
+
+\begin{lstlisting}[frame=trBL]
+PROGRAM -> { 'Section' ('Inherit' | 'Public' | 'Private') { SLOT ';' } }
+SLOT -> '+' identifier ':' TYPE [ ':=' EXPR_CONSTANT ]
+ | '-' identifier [ identifier ':' TYPE ] '<-' '(' { EXPR ';' } ')'
+TYPE -> 'BOOLEAN' | 'STRING' | 'INTEGER'
+EXPR -> [ identifier !!AMBIGU!! ':=' ] EXPR_OPERATOR [ '.' FUNCTION ]
+FUNCTION -> 'if' '{' { EXPR ';' } '}' [ 'else' '{' { EXPR ';' } '}' ]
+ | 'print'
+EXPR_OPERATOR -> EXPR_CMP { ('|' | '&') EXPR_CMP }
+EXPR_CMP -> EXPR_BINARY { ('='|'!='|'>'|'<'|'>='|'<=') EXPR_BINARY }
+EXPR_BINARY -> EXPR_UNARY { ('-'|'+') EXPR_UNARY }
+EXPR_UNARY -> ( '-' | '!' ) EXPR_UNARY
+ | EXPR_BASE
+ | identifier [ EXPR_ARGUMENT ]
+EXPR_BASE -> '(' EXPR_OPERATOR ')'
+ | EXPR_CONSTANT
+EXPR_CONSTANT -> integer
+ | string
+ | TRUE
+ | FALSE
+EXPR_ARGUMENT -> identifier
+ | EXPR_BASE
+\end{lstlisting}
+
+\subsection{Example}
+
+\begin{lstlisting}
+
+Section Inherit
+
+ + parent:STRING;
+
+Section Private
+
+ + is_valid:BOOLEAN;
+
+ - src_path <-
+ (
+ path (lisaac + "src/*");
+ );
+
+ - front_end <-
+ (
+ general_front_end;
+ ((input_file = "") | (input_file = "lisaac")).if {
+ compiler_path;
+ (is_valid).if {
+ boost;
+ };
+ };
+ );
+
+ - back_end <-
+ (
+ general_back_end;
+ (is_valid).if {
+ execute "cp lisaac.c ../bin/.";
+ execute "cp lisaac ../bin/.";
+ };
+ );
+
+Section Public
+
+ - compiler <-
+ // Compile the Lisaac compiler.
+ (
+ compiler_path;
+ );
+\end{lstlisting}
+
+
+\subsection{Lip usage and features}
+
+The compiler always needs a Lip file to work. By default the compiler will look
+in the default Lip file found in the Lisaac environnement variable path
+\textbf{LISAAC\_DIRECTORY} or with the old way in the path.h. This will appear
+if tou don't have a Lip file for your project, otherwise the compiler will at
+first read the Lip file in the directory you are calling the compiler. The
+compiler look in the current directory and in all parents to find a
+\textit{make.lip} file. If no inheritance is set, the \textit{make.lip} file
+from the compiler is inherited. You can also add inheritance by hand with this
+two ways:
+
+\begin{lstlisting}
+
+ + parent : STRING;
+ + parent := "../../../path../file";
+
+\end{lstlisting}
+
+The \textbf{+} is used for variables and \textbf{-} for methods.\\
+
+In the \textit{Private Section}, variables and functions will not appear to the
+compiler. You can then use this Section to describe things you want to be done
+before the compiler is working and to set options you want to call in the
+\textit{Public Section} with the compiler. All compiler options are thus
+described in the \textit{Public Section}. \\
+
+When you add a public function, It is possible to add a commentary down to the
+function definition, then when calling the compiler this description and
+arguments will appear as show this example:\\
+
+
+\begin{lstlisting}
+Section Public
+
+ - debug level:INTEGER <-
+ // Fix debug level (default: 15)
+ (
+ // some code
+ );
+
+================================================================
+
+$lisaac
+
+Usage:
+ lisaac [<lip_file.lip>] [<input_file[.li]>] {<Options>}
+
+Options:
+ ...
+ -debug <level:INTEGER> :
+ Fix debug level (default: 15)
+ ...
+\end{lstlisting}
+
+
+\subsection{Advanced Lip usage}
+
+Some builtin methiods are part of the compiler:
+
+\begin{itemize}
+\item \textbf{exit}: exit from function as in C
+\item \textbf{path(STRING)}: add prototype path location
+\item \textbf{run(STRING)}: execute the string as a unix command
+\item \textbf{get\_integer}: get command line integer
+\item \textbf{get\_string}: get command line string\\
+\end{itemize}
+
+For describing a path you can use the \textbf{*} symbol as for example:
+\textit{lisaac/personnal/*}.\\
+
+\noindent{}Compiling steps:
+
+\begin{enumerate}
+\item The compiler look for a \textit{make.lip} file
+\item the front\_end method is runned
+\item compilation and C generation
+\item the back\_end method is runned
+\end{enumerate}
+
+
%=========================================================
\section{Lexical and syntax overview}
\label{language_reference:lexical_syntax}
@@ -1865,6 +2041,8 @@ You can't modify any slot during execution: imagine for example the consequences
\hline
{'external'} & {\it{} external} & {C code which will be included in the C compiled file} \cr
\hline
+{'lip'} & {\it{} piece of code} & {Include Lip code} \cr
+\hline
\end{tabularx}
\begin{alltt}
@@ -1881,6 +2059,7 @@ You can't modify any slot during execution: imagine for example the consequences
- {\bf{}type} := `unsigned long`;
- {\bf{}default} := {\sc{}100};
- {\bf{}external} := {\sc{}`\#include <stdio.h>`};
+ - {\bf{}lip} := ( add\_lib "-lX11" );
\end{alltt}
\paragraph{Objects and clone}
--
Lisaac documentation
More information about the Lisaac-commits
mailing list