% Manual of "CodeWorker", a scripting language for parsing and generating text.
%
% Copyright (C) 2002 Cédric Lemaire
%
% Permission is granted to copy, distribute and/or modify this document
% under the terms of the GNU Free Documentation License, Version 1.2
% or any later version published by the Free Software Foundation;
% with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
% A copy of the license is included in the section entitled "GNU
% Free Documentation License".
%
% To contact the author: codeworker@free.fr

\documentclass{manual}
\usepackage{makeidx}
\usepackage[T1]{fontenc}
\usepackage{alltt}
\usepackage[dvips]{color}

\usepackage[xdvi]{graphicx}
%%%%\usepackage[pdftex]{graphicx}


\usepackage{latexsym}
\usepackage{verbatim}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{varioref}


\newcommand{\CodeWorker}{{\sc CodeWorker}}
\newcommand{\WebSite}{{\texttt{codeworker@free.fr}}}
\newcommand{\SWORD}{{\textbf{SWORD}}}
\newcommand{\ACE}{{\textbf{ACE}}}
\newcommand{\libCURL}{{\textbf{libCURL}}}
\newcommand{\GraphViz}{{\textbf{GraphViz}}}
\newcommand{\JEdit}{{\textbf{JEdit}}}
\newcommand{\TODO}{{\textbf{* TO DO * TO DO * TO DO * TO DO * TO DO}}}

\newcommand{\arobas}{@}
\newcommand{\pipesup}{|>}

%%%%\usepackage[pdftex,bookmarks,bookmarksopen,
%%%%	    pdfauthor={Cédric Lemaire},
%%%%		pdftitle={User's guide + Reference manual},
%%%%		pdfkeywords={source code generation, text generation, parser generator, BNF, scripting language}]{hyperref}
%%%%
%%%%\newcommand{\pdfpart}[1]{\part{#1}}
%%%%\newcommand{\pdfchapter}[1]{\chapter{#1}}
%%%%\newcommand{\pdfsection}[1]{\section{#1}}
%%%%\newcommand{\pdfsubsection}[1]{\subsection{#1}}
%%%%\newcommand{\pdfsubsubsection}[1]{\subsubsection{#1}}
%%%%\newcommand{\pdflabel}[1]{\label{#1}}

	\special{pdf: docinfo << /Author (Cédric Lemaire) /Title (User's guide + Reference manual) >>}

	\newcommand{\pdfpart}[1]{\part{#1}\special{pdf: out 1 << /Title (\thepart\  #1)  /Dest [ @prevpage /FitH 0 ] >>}}
	\newcommand{\pdfchapter}[1]{\chapter{#1}\special{pdf: out 2 << /Title (\thechapter\  #1)  /Dest [ @thispage /FitH 0 ] >>}}
	\newcommand{\pdfsection}[1]{\section{#1}\special{pdf: out 3 << /Title (\thesection\  #1)  /Dest [ @thispage /FitH 0 ] >>}}
	\newcommand{\pdfsubsection}[1]{\subsection{#1}\special{pdf: out 4 << /Title (\thesubsection\  #1)  /Dest [ @thispage /FitH 0 ] >>}}
	\newcommand{\pdfsubsubsection}[1]{\subsubsection{#1}\special{pdf: out 4 << /Title (\thesubsubsection\  #1)  /Dest [ @thispage /FitH 0 ] >>}}
	\newcommand{\pdflabel}[1]{\special{pdf: dest (#1) [ @thispage /FitH @ypos ]}\label{#1}}


\title{\CodeWorker\ \\
		Parsing tool and Code generator\\
		--- \\
		User's guide \& Reference manual}

\author{Cédric Lemaire}
\authoraddress{
	Email: \email{\WebSite\ }
}

\date{Last update: 
%##markup##"today"
%##begin##"today"
may 01, 2006
%##end##"today"
}
\release{\\
%##markup##"version"
%##begin##"version"
4.2
%##end##"version"
}
\setreleaseinfo{}		% empty for final release
\setshortversion{1.0}		% major.minor only for software

\makeindex			% tell \index to actually write the .idx file

\begin{document}

\maketitle

\ifhtml
\pdfchapter*{Front Matter\pdflabel{front}}
\fi

%==========================================================================
\pagebreak


Copyright (C) 2002 Cédric Lemaire

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".

%==========================================================================

\tableofcontents

%==========================================================================

\pdfchapter{Overview}

CodeWorker is a scripting language distributed under the \textit{GNU Lesser General Public
License} and devoted to manipulate many aspects of \textit{generative programming} as easy and
intuitive as possible. \textit{Generative programming} is a software engineering approach for
producing reusable, tailor-made, evolvable and reliable IT systems with a high level
of automation.

The scripting language adapts its syntax to the subject it has to handle:
    - an extended-BNF syntax (declarative part of the language) for recognizing
      the format of the specifications to parse,
    - a procedural language for manipulating easily parse trees (the only
      structured type admitted by 'CodeWorker'), strings, files and directories,
	- a JSP-like syntax (imperative part of the language), which facilitates the
      writing of template-based code generation.

Thanks to this syntax adaptation, the scripting language is able to easily:
    - acquire any kind of specification of the IT system to produce (often XML
      but not necessary),
    - generate source code in a classical way (as Rational ROSE), managing
      protected areas of text that accept hand-typed code,
    - expand a source file like the class-wizard of Visual C++ (generated text
      is inserted at specified markups),
    - translate from a format to another (LaTeX to HTML, XSL to CodeWorker, ...
      no limit),
    - transform a source file (to instrument a source file with profiling
      features, ...).

These tasks are executed in a straightforward process, with no binding to an
external programming language and with no translation of requirements
specification.

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

\pdfsection{Building a parse tree}

\CodeWorker\ provides two methods for performing a parsing:
\begin{itemize}
	\item the \textbf{reading of tokens} is procedural,
	\item the \textbf{BNF description} is declarative, and conforms to a kind of BNF
	(the \samp{B}ackus-\samp{N}aur \samp{F}ormalism represents a grammar in a particular
	syntax) extended with regular expressions,
\end{itemize}
During the parsing of files, \CodeWorker\ feeds an appropriate data structure that is called
a \textit{tree}, a \textit{parse tree}. A tree is a convenient structure to represent
a hierarchical set of nodes, as in XML for instance. The parse tree is shared both by the parse
task, which takes in charge of populating the tree, and by the source code generation
that will walk through it for generating text.

We suggest to use the file extension \textbf{\samp{".cwp"}} for \textit{extended-BNF} parse scripts.

\pdfsection{A universal source code/text generation}

Given a specification provided in any kind of format, \CodeWorker\ will generate source code
or text as required in \textit{template-based} scripts.

The source code generation can use three modes: generation, expansion or translation.

\begin{itemize}
	\item \textbf{generation mode} is used to let the script produce the
most part of the output file, processing a kind of \textit{template-based} generation as
it exists for a JSP or PHP script. Only some areas called \textit{protected
areas} in the vocabulary of \CodeWorker\ are preserved in the file.
This philosophy has been adopted by some modeling tools that generate
a skinny skeleton copiously interspersed with areas intended to the developer.
	\item \textbf{expansion mode} is used when the file is mainly written by
hand, but small portions need to be generated. The points where to insert the code are
called \textit{markups} in the vocabulary of the scripting language. The \textit{Class Wizard}
of Visual C++ changes source code following this principle.
	\item \textbf{translation mode} is used when both parsing and source code generation are
required to process a file. It arrives for processing:
	\begin{itemize}
		\item a \textit{source-to-source} translation: a file must be rewritten in a
			different syntax. For example, a LaTeX file might have to be translated in HTML.
		\item a \textit{program transformation}: a source file has to change for optimizing,
			refactoring, instrumenting or rewriting some portions.\\
			For example, a script could add a trace at the beginning of each function body of
			a JAVA or C++ source code. To do that, parsing will serve to discover function
			bodies, and source code generation will insert the C++ or JAVA code that
			implements the trace.
	\end{itemize}
\end{itemize}

We suggest to use the file extension \textbf{\samp{".cwt"}} for \textit{template-based} scripts.

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

\pdfsection{About the manual}
Efforts are focused on improving the reliability of this documentation on examples
and on the reference manual (except on English text, I'm afraid!).

A formal representation describes all functions and procedures that \CodeWorker\
provides, with their prototype and a short explanation and an example and the list
of all-similar functions and procedures. This formal representation is used to generate
source codes of \CodeWorker\ that handle parsing and C++ mapping and execution of each
function and procedure of the scripting language. This formal representation that conforms
to what \CodeWorker\ expects in terms of function/procedure prototypes, is reused to
generate the LaTeX part of the reference manual that describes each of them. Examples are
executed while generating the documentation to be sure they are correct, and to report
an up to date output.

The chapter \textit{getting started} is partially generated too, and the guarantee is
given that every script runs successfully and that every example file has the last
annotations. To warrant that, scripts are executed while generating the documentation, and
example/script files contain some formatted comments just before lines to annotate.
While including them into the chapter, their content is numerated line by line, and notes
are extracted. Notes are written just after the content, and refer to the line they explain.

The documentation is written in LaTeX. The great advantage of LaTeX is that it offers
a powerful text processing and that it is easy to manipulate for source code generation (text
format instead of binary, and it accepts comments).
Markups are inserted into the documentation at the points where generated text must be
included. A markup is a special comment that \CodeWorker\ recognizes. This mode of code
generation is an illustration of what is called \textit{expansion mode} before.

%==========================================================================
\pdfchapter{Getting started}

This chapter is intended to help you to discover the scripting language and how it may
serve your software development process.

\CodeWorker\ is delivered with:
\begin{itemize}
	\item an executable called \samp{CodeWorker}, which runs into a shell and that requires
		options on a command line,
	\item a library called \samp{CodeWorker.lib}, which may be linked to C++ applications for
		extending them with parsing and source code generation feature,
	\item some C++ headers that allow exploiting the library and that are available into the
		\samp{"include"} directory,
\end{itemize}

Binaries are available into the \samp{"bin"} directory.

The scripting language adapts its syntax to the nature of the tasks to handle:
\begin{itemize}
	\item Acquiring the specifications of what to generate requires to be able to recognize
		format, either invented for answering as fine as possible to the particularities of
		the any kind of project or existing on the market and available on the \textit{script
		repository} (see http://www.codeworker.org/ScriptsRepository.html, in constant
		improvement). A declarative language processes the scan of the format, following an
		extended BNF syntax ; it accepts the intrusion of procedural instruction to
		populate the parse tree.
	\item Manipulating internal data easily and executing instructions with an expressiveness
		similar to a classical system programming language. The procedural part of the
		language enables to take them in charge.
	\item Generating, expanding or tranforming text. The imperative part of the language
	offers a \textit{template-based} syntax that accepts instructions to navigate into the
	parse tree and to take advantage of facilities brought by a programming language.
\end{itemize}

\textbf{Example:}

\CodeWorker\ allows saving time to implement source code, if it disposes of a detailed design.
Let start with a tiny modeling language that only understands object types and that we create
just for this example:
%##markup##"file:GettingStarted/Tiny.tml"
%##begin##"file:GettingStarted/Tiny.tml"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Tiny.tml":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} class A \{\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \\
	\makebox[1cm][r]{\textrm{\tiny    4}} class B : A \{\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \\
	\makebox[1cm][r]{\textrm{\tiny    7}} class C \{\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}B[] b\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \\
	\makebox[1cm][r]{\textrm{\tiny   11}} class D \{\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}A a\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}C[] c\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \}}


\textsc{line 1:}  we declare the class \samp{A}, without attributes,\\
\textsc{line 4:}  we declare the class \samp{B}, which inherits from \samp{A},\\
\textsc{line 7:}  we declare the class \samp{C} that encapsulates an array of \samp{B} instances,\\
\textsc{line 11:}  we declare the class \samp{D} that encapsulates an association to an instance of
 class \samp{A} and an array of \samp{C} instances,\\
%##end##"file:GettingStarted/Tiny.tml"

\pdfsection{The parse tree}

The role of the parsing is to populate the parse tree. Let suppose that, for each class, we
need of the following attributes:
\begin{itemize}
	\item \textbf{name}: the name of the class, \samp{C} for example,
	\item \textbf{parent}: the name of the parent if exists, \samp{A} for class \samp{B} for
		instance,
	\item \textbf{listOfAttributes}: an array that contains the description of encapsulated
		attributes, \samp{a} and \samp{c} into class \samp{D} for instance,
\end{itemize}
The description of an encapsulated attribute will require:
\begin{itemize}
	\item \textbf{name}: the name of the attribute, \samp{a} into class \samp{D} for instance,
	\item \textbf{class}: the name of the class it belongs to, \samp{A} for attribute \samp{a}
		for instance,
	\item \textbf{isArray}: \samp{true} if the attribute is an array like \samp{c} for
		example,
\end{itemize}

To discover the parse tree, we'll first populate it by hand. To do that, let run
\CodeWorker\ in console mode:\\
\texttt{CodeWorker -console}

Type the following line into the console, and be careful not to forget the final semi colon:\\
\texttt{insert \textit{listOfClasses["A"].name} = "A";\\
		traceObject(project);}

The \samp{insert} keyword is used to create new branches into the parse tree. The root is
named \textbf{project}, but hasn't to be specified, and a sub-node (or \textit{attribute})
\textit{listOfClasses} has been added. This sub-node is quite special: it has to contain an
array of nodes that describe classes. Items are indexed by a string and are stored into their
entrance order; so, the node that takes in charge of describing the class \samp{A} is
accessed via \textit{listOfClasses["A"]}. The string \samp{"A"} is assigned to the attribute
\textit{listOfClasses["A"].name}.

The procedure \samp{traceObject(project)} shows us the first-level content of the root: the
attribute \textit{listOfClasses} and all its entries (only \samp{"A"} for the moment). Let
populate the tree with the description of the class \samp{B}:\\
\texttt{set \textit{listOfClasses["B"].name} = "B";}

The \samp{set} keyword is used to assign a value to an existing branch of the parse tree. If
this branch doesn't exist yet, a warning notices you that perhaps you have done a spelling
mistake, to avoid inserting new bad nodes. But the node is inserted despite of the warning. As
the language isn't typed, it allows avoiding some troubles. Let's continue:\\
\texttt{ref \textit{listOfClasses["B"].parent} = listOfClasses["A"];\\
		traceLine(listOfClasses["B"].parent.name);}

The node \textit{listOfClasses["B"].parent} refers to the node \textit{listOfClasses["A"]}, so
\textit{listOfClasses["B"].parent.name} is similar to \textit{listOfClasses["A"].name}. Let
start filling in the tree for class \samp{C}:\\
\texttt{insert \textit{listOfClasses["C"].name} = "C";\\
		pushItem \textit{listOfClasses["C"].listOfAttributes};\\
		local \textit{myAttribute};\\
		ref \textit{myAttribute} = \textit{listOfClasses["C"].listOfAttributes\#back};}

The \samp{pushItem} assignment command is another way to add a new node into an array, where
the item is indexed by the position of the node, starting at 0. The \samp{local} keyword
allows declaring a variable on the stack. This variable is also a parse tree, but not
attached to the main parse tree \samp{project}. For more commodities, this variable will
refer to the last element of the attribute's list: \textit{myAttribute} is shorter to type
than \textit{listOfClasses["C"].listOfAttributes\#back}. Notice that the last element of an
array is accessed via \samp{'\#back'}. Let complete the attribute \samp{b} of class \samp{C}:
\texttt{insert myAttribute.name = "b";\\
		ref myAttribute.class = listOfClasses["B"];\\
		insert myAttribute.isArray = true;}

The keyword \samp{true} is a predefined constant string that is worth \samp{"true"}. The
keyword \samp{false} also exists and is worth an empty string.

\textbf{Exercise:}

Populate the parse tree with the description of class \samp{D}.

\pdfsection{Scanning our design with a BNF-driven script}

Now, we'll describe the format of our tiny modeling language thanks to a BNF grammar (see
paragraph \ref{BNF syntax} for more elements about it) like it is recognized by \CodeWorker\ :
%##markup##"file:GettingStarted/Tiny-BNF.cwp"
%##begin##"file:GettingStarted/Tiny-BNF.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Tiny-BNF.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} TinyBNF ::=\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}\#ignore(JAVA)\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[0.8cm][l]{}[classDeclaration]*\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}\#empty\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}=> \{ traceLine("this file is valid"); \};\\
	\makebox[1cm][r]{\textrm{\tiny    6}} classDeclaration ::=\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}IDENT:"class"\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}IDENT\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[0.8cm][l]{}[':' IDENT ]?\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[0.8cm][l]{}classBody;\\
	\makebox[1cm][r]{\textrm{\tiny   11}} classBody ::= '\{' [attributeDeclaration]* '\}';\\
	\makebox[1cm][r]{\textrm{\tiny   12}} attributeDeclaration ::= IDENT ['[' ']']? IDENT;\\
	\makebox[1cm][r]{\textrm{\tiny   13}} IDENT ::= \#!ignore ['a'..'z'|'A'..'Z']+;}


\textsc{line 1:}  the clause \samp{TinyBNF} takes in charge of reading our design,\\
\textsc{line 2:}  blanks and comments are allowed between tokens, conforming to the JAVA syntax
 (\textbf{'/*'} \textbf{'*/'} and \textbf{'//'}),\\
\textsc{line 3:}  the clause \samp{classDeclaration} is repeated as long as class declarations are
 encountered into the design,\\
\textsc{line 4:}  if no class anymore, the end of file may have been reached,\\
\textsc{line 5:}  the \samp{\textbf{'=>'}} operator allows executing instructions of the scripting language
 into the BNF-driven script; this one will be interpreted once the file will be matched
 successfully,\\
\textsc{line 6:}  the clause \samp{classDeclaration} takes in charge of reading a class,\\
\textsc{line 7:}  the clause \samp{IDENT} reads identifiers and the matched sequence must be worth
 \samp{"class"},\\
\textsc{line 8:}  the name of the class is expected here\\
\textsc{line 9:}  the declaration of the parent is facultative and is announced by a colon,\\
\textsc{line 11:}  the clause \samp{classBody} reads attributes as long as a it matches,\\
\textsc{line 12:}  the clause \samp{attributeDeclaration} expects a class identifier and, eventually,
 the symbol of an array, and the name of the attribute,\\
\textsc{line 13:}  the clause \samp{IDENT} reads an identifier, composed of a letter or more, which
 cannot be separated by blanks or comments (required by the directive \samp{\#!ignore}),\\
%##end##"file:GettingStarted/Tiny-BNF.cwp"

This \textit{BNF-driven} script only scans the design ; it doesn't parse the data. Type the
following line into the console to scan the design \textit{"Tiny.tml"}:
%##markup##"execute:parseAsBNF(\"Scripts/Tutorial/GettingStarted/Tiny-BNF.cwp\", project, \n\t\t\"Scripts/Tutorial/GettingStarted/Tiny.tml\");"
%##begin##"execute:parseAsBNF(\"Scripts/Tutorial/GettingStarted/Tiny-BNF.cwp\", project, \n\t\t\"Scripts/Tutorial/GettingStarted/Tiny.tml\");"
\begin{verbatim}
parseAsBNF("Scripts/Tutorial/GettingStarted/Tiny-BNF.cwp", project, 
		"Scripts/Tutorial/GettingStarted/Tiny.tml");
\end{verbatim}
\textbf{Output:}

\texttt{this file is valid}

%##end##"execute:parseAsBNF(\"Scripts/Tutorial/GettingStarted/Tiny-BNF.cwp\", project, \n\t\t\"Scripts/Tutorial/GettingStarted/Tiny.tml\");"

But this script isn't sufficient enough to complete the parse tree.

\pdfsection{Parsing our design with a BNF-driven script}

We have to improve the precedent script, called now \textit{"Tiny-BNFparsing.cwp"}, for
building the parse tree that represents the pertinent data of the design:
%##markup##"file:GettingStarted/Tiny-BNFparsing.cwp"
%##begin##"file:GettingStarted/Tiny-BNFparsing.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Tiny-BNFparsing.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} TinyBNF ::=    \#ignore(JAVA) [classDeclaration]* \#empty\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}=> \{ traceLine("this file has been parsed successfully"); \};\\
	\makebox[1cm][r]{\textrm{\tiny    3}} classDeclaration ::=\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}IDENT:"class"\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}IDENT:sName\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[0.8cm][l]{}=> insert project.listOfClasses[sName].name = sName;\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[1.6cm][l]{}':'\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[1.6cm][l]{}IDENT:sParent\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[1.6cm][l]{}=> \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[2.4cm][l]{}if !findElement(sParent, project.listOfClasses)\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[3.2cm][l]{}error("class '" + sParent + "' should have been declared before");\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[2.4cm][l]{}ref project.listOfClasses[sName].parent = project.listOfClasses[sParent];\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[0.8cm][l]{}]?\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[0.8cm][l]{}classBody(project.listOfClasses[sName]);\\
	\makebox[1cm][r]{\textrm{\tiny   17}} classBody(myClass : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[0.8cm][l]{}'\{' [attributeDeclaration(myClass)]* '\}';\\
	\makebox[1cm][r]{\textrm{\tiny   19}} attributeDeclaration(myClass : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[0.8cm][l]{}IDENT\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[0.8cm][l]{}['[' ']']?\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[0.8cm][l]{}IDENT;\\
	\makebox[1cm][r]{\textrm{\tiny   23}} IDENT ::= \#!ignore ['a'..'z'|'A'..'Z']+;}


\textsc{line 5:}  the name of the class is put into the local variable \samp{sName}. Note that the first
 time a variable is encountered after a token, it is declared as local automatically.\\
\textsc{line 6:}  we populate the parse tree as we have proceeded manually,\\
\textsc{line 9:}  the name of the parent class is put into the local variable \samp{sParent},\\
\textsc{line 11:}  the parent class must have been declared before: the item is searched into the list
 of classes,\\
\textsc{line 13:}  we populate the parse tree as we have proceeded manually,\\
\textsc{line 16:}  clauses may accept parameters; here, the current class is passed to \samp{classBody}
 that will populate it with attributes,\\
\textsc{line 17:}  the clause \samp{classBody} expects a parameter as a node; a parameter may be passed
 as \samp{value} or \samp{node} or \samp{reference},\\
\textsc{line 19:}  little exercise: complete the clause \samp{attributeDeclaration} that takes in charge
 of parsing an attribute of the class given to the argument \textit{myClass},\\
\textsc{line 20:}  remember that you must parse the class name of the association here (attribute
 \textit{myClass.listOfAttributes\#back.class} refers to the associated class),\\
\textsc{line 21:}  remember that you must parse the multiplicity of the association here (attribute
 \textit{myClass.listOfAttributes\#back.isArray} is worth \samp{true} if \textbf{'[]'} is present),\\
\textsc{line 22:}  remember that you must parse the name of the association here (to put into attribute
 \textit{myClass.listOfAttributes\#back.name}),\\
%##end##"file:GettingStarted/Tiny-BNFparsing.cwp"

\textbf{Exercise:}

Complete the precedent clause \samp{attributeDeclaration} to populate an attribute. You'll
find the solution into file \textit{"Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp"}.

\textbf{Solution:}
%##markup##"file:GettingStarted/Tiny-BNFparsing1.cwp"
%##begin##"file:GettingStarted/Tiny-BNFparsing1.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Tiny-BNFparsing1.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} classBody(myClass : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}'\{' [attributeDeclaration(myClass)]* '\}';\\
	\makebox[1cm][r]{\textrm{\tiny    3}} attributeDeclaration(myClass : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}IDENT:sClass\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}=> local myAttribute;\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[0.8cm][l]{}=> \{\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[1.6cm][l]{}pushItem myClass.listOfAttributes;\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[1.6cm][l]{}ref myAttribute = myClass.listOfAttributes\#back;\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[1.6cm][l]{}if !findElement(sClass, project.listOfClasses)\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}error("class '" + sClass + "' should have been declared before");\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[1.6cm][l]{}ref myAttribute.class = project.listOfClasses[sClass];\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}['[' ']' => insert myAttribute.isArray = true;]?\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}IDENT:sName => \{insert myAttribute.name = sName;\};\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \\
	\makebox[1cm][r]{\textrm{\tiny   16}} IDENT ::= \#!ignore ['a'..'z'|'A'..'Z']+;}


\textsc{line 4:}  the name of the class for the association is assigned to the local variable \samp{sName},\\
\textsc{line 5:}  we'll need a local variable to point to the attribute's node for commodity,\\
\textsc{line 7:}  the local variable \samp{myAttribute} hasn't been declared here, because it disappears
 at the end of the scope (the trailing brace); a new node is added to the list of
 attributes,\\
\textsc{line 8:}  the local variable \samp{myAttribute} points to the last item of the list,\\
\textsc{line 9:}  the class specifier of the association must have been declared,\\
\textsc{line 11:}  we populate the parse tree as done by hand,\\
\textsc{line 13:}  this attribute \textit{isArray} is added only if the type of the association is an array,\\
\textsc{line 14:}  we complete the attribute description by assigning its name,\\
%##end##"file:GettingStarted/Tiny-BNFparsing1.cwp"

Type the following line into the console to parse the design \textit{"Tiny.tml"}:

%##markup##"execute:parseAsBNF(\"Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp\", project, \n\t\t\"Scripts/Tutorial/GettingStarted/Tiny.tml\");"
%##begin##"execute:parseAsBNF(\"Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp\", project, \n\t\t\"Scripts/Tutorial/GettingStarted/Tiny.tml\");"
\begin{verbatim}
parseAsBNF("Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp", project, 
		"Scripts/Tutorial/GettingStarted/Tiny.tml");
\end{verbatim}
\textbf{Output:}

\texttt{this file has been parsed successfully}

%##end##"execute:parseAsBNF(\"Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp\", project, \n\t\t\"Scripts/Tutorial/GettingStarted/Tiny.tml\");"

\pdfsection{Implementing a leader script}

Now, we'll implement a little function that displays the content of our parse tree. We stop
using the console here, and we'll implement the call to the parsing and the function into a
\textit{leader script}. This script will be called at the command line, as seen further.

We suggest to use the file extension \textbf{\samp{".cws"}} for non-template and non-BNF scripts.

%##markup##"execute_file:GettingStarted/Tiny-leaderScript0.cws"
%##begin##"execute_file:GettingStarted/Tiny-leaderScript0.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -script Scripts/Tutorial/GettingStarted/Tiny-leaderScript0.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Tiny-leaderScript0.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} parseAsBNF("Tiny-BNFparsing1.cwp", project, "Scripts/Tutorial/GettingStarted/Tiny.tml");\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} \\
	\makebox[1cm][r]{\textrm{\tiny    4}} function displayParsingTree() \{\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}foreach i in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[1.6cm][l]{}traceLine("class '" + i.name + "'");\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[1.6cm][l]{}if existVariable(i.parent)\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[2.4cm][l]{}traceLine("$\backslash$tparent = '" + i.parent.name + "'");\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[1.6cm][l]{}foreach j in i.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}traceLine("$\backslash$tattribute '" + j.name + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[2.4cm][l]{}traceLine("$\backslash$t$\backslash$tclass = '" + j.class.name + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[2.4cm][l]{}if existVariable(j.isArray)\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[3.2cm][l]{}traceLine("$\backslash$t$\backslash$tarray = '" + j.isArray + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \\
	\makebox[1cm][r]{\textrm{\tiny   18}} displayParsingTree();}


\textsc{line 4:}  a user-defined function without parameters,\\
\textsc{line 5:}  the \samp{foreach} statement iterates all items of an array; here, all classes are
 explored,\\
\textsc{line 7:}  check whether the attribute \textit{parent} exists or not,\\
\textsc{line 9:}  all attributes of the current class \textit{i} are iterated,\\
\textsc{line 12:}  perhaps the association is multiple,\\
\textsc{line 18:}  a call to the user-defined function,\\


\textbf{Output:}

\texttt{this file has been parsed successfully\\
class 'A'\\
class 'B'\\
\makebox[0.8cm][l]{}parent = 'A'\\
class 'C'\\
\makebox[0.8cm][l]{}attribute 'b'\\
\makebox[1.6cm][l]{}class = 'B'\\
\makebox[1.6cm][l]{}array = 'true'\\
class 'D'\\
\makebox[0.8cm][l]{}attribute 'a'\\
\makebox[1.6cm][l]{}class = 'A'\\
\makebox[0.8cm][l]{}attribute 'c'\\
\makebox[1.6cm][l]{}class = 'C'\\
\makebox[1.6cm][l]{}array = 'true'}
%##end##"execute_file:GettingStarted/Tiny-leaderScript0.cws"

\pdfsection{Generating code with a pattern script}

The source code generation exploits the parse tree to generate any kind of output files: HTML, SQL,
C++, ...

A \textit{pattern} script is written in the scripting language of \CodeWorker\, extended to be
able to fuse the text to put into the output file and the instructions to interpret. It enables
to process a {template-based} generation.
Such a script looks like a JSP template: the script is embedded between
tags \textbf{'<\%'} and \textbf{'\%>'} or \textbf{'@'}.

We'll start by generating a short JAVA class for each class of the design. It translates
the attributes in JAVA and it generates their accessors:
%##markup##"file:Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"
%##begin##"file:Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} package tiny;\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} public class @this.name@ @\\
	\makebox[1cm][r]{\textrm{\tiny    4}} if existVariable(this.parent) \{\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}@ extends @this.parent.name@ @\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    7}} @\{\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}// attributes:\\
	\makebox[1cm][r]{\textrm{\tiny    9}} @\\
	\makebox[1cm][r]{\textrm{\tiny   10}} function getJAVAType(myAttribute : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}local sType = myAttribute.class.name;\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}if myAttribute.isArray \{\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[1.6cm][l]{}set sType = "java.util.ArrayList/*<" + sType + ">*/";\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[0.8cm][l]{}return sType;\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \\
	\makebox[1cm][r]{\textrm{\tiny   18}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[0.8cm][l]{}@    private @getJAVAType(i)@ \_@i.name@ = null;\\
	\makebox[1cm][r]{\textrm{\tiny   20}} @\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   22}} @\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[0.8cm][l]{}//constructor:\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[0.8cm][l]{}public @this.name@() \{\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[0.8cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny   28}} @\\
	\makebox[1cm][r]{\textrm{\tiny   29}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[0.8cm][l]{}@    public @getJAVAType(i)@ get@toUpperString(i.name)@() \{ return \_@i.name@; \}\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[0.8cm][l]{}public void set@toUpperString(i.name)@(@getJAVAType(i)@ @i.name@) \{ \_@i.name@ = @i.name@; \}\\
	\makebox[1cm][r]{\textrm{\tiny   32}} @\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   34}} setProtectedArea("Methods");\\
	\makebox[1cm][r]{\textrm{\tiny   35}} @\}}


\textsc{line 3:}  swapping to script mode: the value of \textit{this.name} is put into the output file,
 knowing that the variable \textit{this} is determined by the second parameter that is
 passed to the procedure \samp{generate} (see section \ref{generate()} and below). If
 the notation appears confusing to you (where does the writing mode ends, where does
 the script mode starts or the contrary), you can choose to inlay the variables in tags
 \textbf{'<\%'} and \textbf{'\%>'}.\\
\textsc{line 4:}  swapping once again to script mode for writing the inheritance, if any\\
\textsc{line 7:}  swapping to text mode,\\
\textsc{line 10:}  we'll need a function to convert a type specifier of the tiny modeling language to JAVA,
 which expects the attribute's node (parameter mode is \samp{variable}, instead of \samp{value}),\\
\textsc{line 13:}  we have chosen \samp{java.util.ArrayList} to represent an array, why not?\\
\textsc{line 18:}  swapping to script mode for declaring the attributes of the class\\
\textsc{line 22:}  swapping to text mode for putting the constructor into the output file,\\
\textsc{line 29:}  swapping to script mode for implementing the accessors to the attributes of the class\\
\textsc{line 30:}  the predefined function \samp{toUpperString} capitalizes the parameter,\\
\textsc{line 34:}  the procedure \samp{setProtectedArea} (see section \ref{setProtectedArea()}) adds
 a protected area that is intended to the user and that is preserved during a
 generation process,\\
\textsc{line 35:}  swapping to text mode for writing the trailing brace,\\
%##end##"file:Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"

The \textit{leader script} must be changed to require the generation of each class in JAVA:
%##markup##"execute_file:Scripts/Tutorial/GettingStarted/Tiny-leaderScript1.cws"
%##begin##"execute_file:Scripts/Tutorial/GettingStarted/Tiny-leaderScript1.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -script Scripts/Tutorial/GettingStarted/Tiny-leaderScript1.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Scripts/Tutorial/GettingStarted/Tiny-leaderScript1.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} parseAsBNF("Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp", project, "Scripts/Tutorial/GettingStarted/Tiny.tml");\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} foreach i in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}\textbf{generate("Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt", i, "Scripts/Tutorial/GettingStarted/tiny/" + i.name + ".java");}\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    6}} }


\textsc{line 4:}  the second argument is waiting for a tree node that will be accessed into the \textit{pattern script}
 via the predefined variable \samp{this}, which has been encountered above,\\


\textbf{Output:}

\texttt{this file has been parsed successfully}
%##end##"execute_file:Scripts/Tutorial/GettingStarted/Tiny-leaderScript1.cws"

Let have a look to the following generated file:
%##markup##"file:Scripts/Tutorial/GettingStarted/tiny/D.java"
%##begin##"file:Scripts/Tutorial/GettingStarted/tiny/D.java"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Scripts/Tutorial/GettingStarted/tiny/D.java":\\
	\makebox[1cm][r]{\textrm{\tiny     }} package tiny;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} public class D \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// attributes:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}private A \_a = null;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}private java.util.ArrayList/*<C>*/ \_c = null;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}//constructor:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public D() \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public A getA() \{ return \_a; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public void setA(A a) \{ \_a = a; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public java.util.ArrayList/*<C>*/ getC() \{ return \_c; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public void setC(java.util.ArrayList/*<C>*/ c) \{ \_c = c; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} //\#\#protect\#\#"Methods"\\
	\makebox[1cm][r]{\textrm{\tiny     }} //\#\#protect\#\#"Methods"\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}

%##end##"file:Scripts/Tutorial/GettingStarted/tiny/D.java"

\pdfsection{Expanding text with a pattern script}

We'll learn about another mode of generation: expanding a file. Let suppose that you want to
inlay generated code into an existing file. The way to do it is first to insert a special
comment at the expected place. This comment begins with \textbf{\#\#markup\#\#} and is
followed by a sequence of characters written between double quotes and called the
\textit{markup key}.

Here is a little HTML file that is going to be expanded:
%##markup##"file:Scripts/Tutorial/GettingStarted/Tiny.html"
%##begin##"file:Scripts/Tutorial/GettingStarted/Tiny.html"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Scripts/Tutorial/GettingStarted/Tiny.html":\\
	\makebox[1cm][r]{\textrm{\tiny     }} <HTML>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}<HEAD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}</HEAD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}<BODY>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#markup\#\#"classes"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}</BODY>\\
	\makebox[1cm][r]{\textrm{\tiny     }} </HTML>}

%##end##"file:Scripts/Tutorial/GettingStarted/Tiny.html"

The markup key is called \textit{"classes"} and is put into the file like it:
\samp{<!- -\#\#markup\#\#"classes"- ->}.

Now, we'll implement a short script that is intended to populate the markup area with all
classes of the design, displayed into tables:
%##markup##"file:Scripts/Tutorial/GettingStarted/Tiny-HTML.cwt"
%##begin##"file:Scripts/Tutorial/GettingStarted/Tiny-HTML.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Scripts/Tutorial/GettingStarted/Tiny-HTML.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} @\\
	\makebox[1cm][r]{\textrm{\tiny    2}} if getMarkupKey() == "classes" \{\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[0.8cm][l]{}foreach i in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[1.6cm][l]{}@        <TABLE>\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[2.4cm][l]{}<TR>\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[3.2cm][l]{}<TD colspan=3><B>@i.name@</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[2.4cm][l]{}<TR>\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[3.2cm][l]{}<TD><EM>Attribute</EM></TD><TD><EM>Type</EM></TD> <TD><EM>Description</EM></TD>\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny   11}} @\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[1.6cm][l]{}foreach j in i.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[2.4cm][l]{}@            <TR>\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[3.2cm][l]{}<TD><I>@j.name@</I></TD><TD><CODE>@\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[2.4cm][l]{}@@j.class.name@@\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[2.4cm][l]{}if j.isArray \{\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[3.2cm][l]{}@[]@\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[2.4cm][l]{}@</CODE></TD><TD>@\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[2.4cm][l]{}setProtectedArea(i.name + "::" + j.name);\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[2.4cm][l]{}@</TD>\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny   23}} @\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[1.6cm][l]{}@        </TABLE>\\
	\makebox[1cm][r]{\textrm{\tiny   26}} @\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \}}


\textsc{line 2:}  the function \samp{getMarkupKey()} returns the current expanding markup that is handled,\\
\textsc{line 3:}  all classes will be presented sequentially into tables of 3 columns, whose title is
 the name of the class, and rows are populated with attributes,\\
\textsc{line 12:}  the \textit{name}, \textit{Type} and \textit{Description} of all attributes of the
 class are presented into the table,\\
\textsc{line 15:}  the type is expressed in the syntax of our tiny modeling language,\\
\textsc{line 20:}  the description of an attribute must be filled by the user into a protected area, so
 as to preserve it from an expansion to another,\\
%##end##"file:Scripts/Tutorial/GettingStarted/Tiny-HTML.cwt"

The \textit{leader script} has to take into account the expansion of the HTML file:
%##markup##"execute_file:Scripts/Tutorial/GettingStarted/Tiny-leaderScript2.cws"
%##begin##"execute_file:Scripts/Tutorial/GettingStarted/Tiny-leaderScript2.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -script Scripts/Tutorial/GettingStarted/Tiny-leaderScript2.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Scripts/Tutorial/GettingStarted/Tiny-leaderScript2.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} parseAsBNF("Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp", project, "Scripts/Tutorial/GettingStarted/Tiny.tml");\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} foreach i in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}generate("Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt", i, "Scripts/Tutorial/GettingStarted/tiny/" + i.name + ".java");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \\
	\makebox[1cm][r]{\textrm{\tiny    7}} \textbf{traceLine("expanding file 'Tiny0.html'...");}\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \textbf{setCommentBegin("<!--");}\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \textbf{setCommentEnd("-->");}\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \textbf{expand("Scripts/Tutorial/GettingStarted/Tiny-HTML.cwt", project, "Scripts/Tutorial/GettingStarted/Tiny0.html");}\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \textbf{//normal;}}


\textsc{line 8:}  to expand a file, the interpreter has to know the format of comments used for
 declaring the markups. If the format isn't correct, the file will not be expanded.\\
\textsc{line 10:}  be careful to call the procedure \samp{expand()} and not to confuse with \samp{generate()}!
 Remember that a classic generation rewrites all according to the directives of the
 \textit{pattern script} and preserves protected areas, but doesn't recognize markup keys.\\


\textbf{Output:}

\texttt{this file has been parsed successfully\\
expanding file 'Tiny0.html'...}
%##end##"execute_file:Scripts/Tutorial/GettingStarted/Tiny-leaderScript2.cws"

It hasn't a great interest to present here the content of the HTML once it has been expanded,
but you can display it (file \textit{"Scripts/Tutorial/GettingStarted/Tiny0.html"}) into your
browser. You'll notice into the source code that the expanded text is put between tags
\textbf{<!- -\#\#begin\#\#"classes"- ->} and \textbf{<!- -\#\#end\#\#"classes"- ->}. Don't
type text into this tagged part, except into protected areas, because the next expansion will
destroy the tagged part.

For discovering more about \CodeWorker\ through a more complex example, please read the next
chapter. You'll learn how to do translations from a format to another, and to use template
functions or BNF clauses (very efficient for readability and extension!), and a lot of
various things. But it is recommended to practice a little before.

%==========================================================================
\pdfchapter{Discovering more with an example}

The first time, we recommend to read the precedent chapter, more approachable, before reading
this one.

Let imagine that we dispose of a design expressed in a simple modeling language, like it:
%##markup##"file:GettingStarted/SolarSystem0.sml"
%##begin##"file:GettingStarted/SolarSystem0.sml"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SolarSystem0.sml":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} class Planet \{\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}double diameter;\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[0.8cm][l]{}double getDistanceToSun(int day, int month, int year);\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \\
	\makebox[1cm][r]{\textrm{\tiny    6}} class Earth : Planet \{\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}string[] countryNames;\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \\
	\makebox[1cm][r]{\textrm{\tiny   10}} class SolarSystem \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}aggregate Planet[] planets;\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \}}


\textsc{line 1:}  a class is declared with keyword \textbf{class}\\
\textsc{line 2:}  declaration of attributes in a syntax close to C++ or JAVA\\
\textsc{line 3:}  declaration of methods in a syntax close to C++ or JAVA\\
\textsc{line 6:}  a class may inherit from an other ; the syntax looks like C++, see \textbf{':'}\\
\textsc{line 7:}  an attribute may be an array ; the syntax looks like JAVA\\
\textsc{line 11:}  an attribute may be an object or an array of objects,
 and an object may be an aggregation (meaning that it belongs to the instance),\\
%##end##"file:GettingStarted/SolarSystem0.sml"

This simple modeling language conforms to a BNF grammar (see paragraph \ref{BNF syntax} to
obtain information about the elements of a BNF syntax):\\
\samp{
	\textit{world} ::= [\textit{class_declaration}]*\\
	\textit{class_declaration} ::= \textbf{"class"} \textit{IDENT} [\textbf{':'} \textit{IDENT}]? \textit{class_body}\\
	\textit{class_body} ::= \textbf{'\{'} [\textit{attribute_decl} | \textit{method_decl}]* \textbf{'\}'}\\
	\textit{attribute_decl} ::= \textit{type_specifier} \textit{IDENT} \textbf{';'}\\
	\textit{method_decl} ::= \textit{type_specifier} \textit{IDENT}
				\textbf{'('} [\textit{parameters_decl}]? \textbf{')' ';'}\\
	\textit{parameters_decl} ::= \textit{parameter} [\textbf{','} \textit{parameters_decl}]*\\
	\textit{parameter} ::= [\textit{parameter_mode}]? \textit{type_specifier} \textit{IDENT}\\
	\textit{parameter_mode} ::= \textbf{"in"} | \textbf{"inout"} | \textbf{"out"}\\
	\textit{type_specifier} ::= \textit{basic_type} [\textbf{'[' ']'}]?\\
	\textit{basic_type} ::= \textbf{"int"} | \textbf{"double"} | \textbf{"string"} |\\
				\textbf{"boolean"} | \textit{class_specifier}\\
	\textit{class_specifier} ::= [\textbf{"aggregate"}]? \textit{IDENT}\\
	\textit{IDENT} ::= [\textbf{'a'..'z'}|\textbf{'A'..'Z'}|\textbf{'_'}] [\textbf{'a'..'z'}|\textbf{'A'..'Z'}|\textbf{'_'}|\textbf{'0'..'9'}]*
}

Starting from the desing file "SolarSystem0.sml" seen before, which conforms to the
\textit{Simple Modeling Language} described just above, we propose to implement the source
code for classes and a light documentation.

\pdfsection{The parse tree}
\CodeWorker\ doesn't belong to the category of typed languages. It recognizes only the
\textit{tree} as structured type and the \textit{string} as basic type (that may however
represent an integer or a boolean, ...). Each node may contain a string as a value, and/or
an array of nodes. The main tree is called \samp{project}, which is the name of its root node,
accessible everywhere into scripts.

Now, the best way to understand how to handle the tree is to run the console, and to practice
some examples.

Type \samp{CodeWorker} to the shell to set the console mode. A cursor is waiting for your
commands.

Type \samp{set a = "little";} and press enter. Don't forget the semi-colon at the end of the
line. If absent, the console wait for more input: type the expected semi-colon, and it should
be right.

What is the impact of the line you typed? You assigned \samp{"little"} to the variable \samp{a},
which doesn't exist. So, a node named \samp{'a'} has been added into the main parse tree
(called \samp{project}, remember), to which the variable a points. You noticed that a varning
has occurred. It means that you assigned a value to a node that doesn't exist yet. In fact,
the instruction \samp{set} supposes that the variable to assign already exists, and a warning
has been thrown to prevent you of a spelling error (perhaps do you intended to type another
variable that already exists?) or a logic mistake (at this point of the program, the variable
should exist, so what?). It is important to offer this protection, because the language isn't
typed, and so, a lot of errors may be reported during the runtime.

The variable \samp{a} has been added, even if the warning has occurred, but we prefer the
instruction \samp{insert} to add a new node properly : type \samp{insert b = "big";} and
press enter. No warning was displayed. Now, the root \samp{project} node contains two
sub-nodes, called \samp{'a'} and \samp{'b'}, and we control it by typing
\samp{traceObject(project);}. The following lines are displayed:
\begin{verbatim}
Tracing variable 'project':
        a = "little"
        b = "big"
End of variable's trace 'project'.
\end{verbatim}

Let's go further. What about storing a list of items?\\
Type \samp{insert classes["Planet"].name = "Planet";}. A node node called \samp{'classes'} has
been added to \samp{project}, and then an array entry called \samp{"Planet"} has been
pushed. This entry points to a node, to which \samp{'name'} is added, and node
\samp{'name'} is worth \samp{"Planet"}.

Type \samp{insert classes["Earth"].name = "Earth";} and then ask for tracing node
\samp{'project'}. The following lines are displayed:
\begin{verbatim}
Tracing variable 'project':
        a = "little"
        b = "big"
        classes = ""
        classes["Planet", "Earth"]
End of variable's trace 'project'.
\end{verbatim}
Notice that the node \samp{'classes'} has no value (but could have!) and contains an array of
nodes where entries are \samp{"Planet"} and \samp{"Earth"}.

To iterate items of array \samp{'classes'}, type
\samp{foreach i in classes traceLine("handling class '" + i.name + "'...");} and see the
result:
\begin{verbatim}
handling class 'Planet'...
handling class 'Earth'...
\end{verbatim}
Variable \samp{'i'} is an iterator and is declared locally for processing the \samp{foreach}
instruction. We'll see further that the statement \samp{local} allows declaring a tree to
the stack.

What you know about the parse tree in \CodeWorker\ is sufficient to tackle the next
section.

\pdfsection{Parsing our design}
\CodeWorker\ provides two different approaches for parsing files.

\pdfsubsection{The parsing scripts that read tokens}
Those that aren't familiar with a BNF representation will perhaps be more self-assured
in using a procedure-driven parsing, where control resides within the implementation and
where all tokens are explicitly read by a devoted operation. But it means for instance that
ignoring blanks and comments must be indicated explicitly between reading of tokens.

The parsing scripts that read tokens are the oldest way to parse into \CodeWorker\ and are
the fastest mode too. But it doesn't offer the same flexibility as BNF scripts, which
are syntax-oriented.

Below is an example of what a script that reads tokens looks like:
%##markup##"file:GettingStarted/SimpleML-token-reading.cws"
%##begin##"file:GettingStarted/SimpleML-token-reading.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SimpleML-token-reading.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} declare function readType();\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} while skipEmptyCpp() \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}if !readIfEqualToIdentifier("class") error("'class' expected");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[0.8cm][l]{}local sClassName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}if !sClassName error("class name expected");\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[0.8cm][l]{}if readIfEqualTo(":") \{\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[1.6cm][l]{}local sParentName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[1.6cm][l]{}if !sParentName error("parent name expected for class '" + sClassName + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[0.8cm][l]{}if !readIfEqualTo("\{") error("'\{' expected");\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[0.8cm][l]{}while !readIfEqualTo("\}") \{\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[1.6cm][l]{}readType();\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[1.6cm][l]{}local sMemberName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[1.6cm][l]{}if !sMemberName error("attribute or method name expected");\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[1.6cm][l]{}if readIfEqualTo("(") \{\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[2.4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[2.4cm][l]{}if !readIfEqualTo(")") \{\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[3.2cm][l]{}do \{\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[4cm][l]{}local iPosition = getInputLocation();\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[4cm][l]{}local sMode = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[4cm][l]{}if !sMode error("parameter type or mode expected");\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[4cm][l]{}if (sMode != "in") \&\& (sMode != "out") \&\& (sMode != "inout") \{\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[4.8cm][l]{}setInputLocation(iPosition);\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[4.8cm][l]{}set sMode = "";\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[4cm][l]{}readType();\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[4cm][l]{}local sParameterName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[4cm][l]{}if !sParameterName error("parameter name expected");\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   42}} \makebox[3.2cm][l]{}\} while readIfEqualTo(",");\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[3.2cm][l]{}if !readIfEqualTo(")") error("')' expected");\\
	\makebox[1cm][r]{\textrm{\tiny   44}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[2.4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[1.6cm][l]{}if !readIfEqualTo(";") \{\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[2.4cm][l]{}error("';' expected to close an attribute, instead of '" + readChar() + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   52}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   53}} traceLine("the file has been read successfully");\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \\
	\makebox[1cm][r]{\textrm{\tiny   55}} function readType() \{\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[0.8cm][l]{}local sType = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[0.8cm][l]{}if !sType error("type modifier or name expected, instead of '" + readChar() + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[0.8cm][l]{}if sType == "aggregate" \{\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \makebox[1.6cm][l]{}sType = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   61}} \makebox[1.6cm][l]{}if !sType error("aggregated class name expected");\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   64}} \makebox[0.8cm][l]{}if readIfEqualTo("[") \{\\
	\makebox[1cm][r]{\textrm{\tiny   65}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   66}} \makebox[1.6cm][l]{}if !readIfEqualTo("]") error("']' expected to close an array declaration");\\
	\makebox[1cm][r]{\textrm{\tiny   67}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   68}} \}}


\textsc{line 1:}  forward declaration of method \samp{readType()}, so as to start explanations
 about how to implement BNF clause \samp{\textit{world} ::= [\textit{class_declaration}]*},\\
\textsc{line 3:}  do a loop while the end of file hasn't been reached,
 skipping blanks and C++ comments: \samp{skipEmptyCpp()} returns \samp{false}
 only if an error occurs while reading the stream or the file has completed,\\
\textsc{line 4:}  waiting for token \samp{"class"} as an identifier (doesn't accept \samp{"class"} as
 the beginning of another identifier, such as \samp{"\textit{class}es"}). If not found,
 an error occurs. This token announces a class declaration.\\
\textsc{line 5:}  a disadvantage of writing a procedure-driven reading/parsing: don't forget to
 skip explicitly blanks and comments by yourself,\\
\textsc{line 6:}  populates a local variable with an identifier token that represents the name of the class\\
\textsc{line 7:}  if an identifier token hasn't been found (token is empty), an error is thrown,\\
\textsc{line 9:}  if the file location points to \samp{":"}, announcing the inheritance, function
 \samp{readIfEqualTo(":")} returns \samp{true}, and the location moves after the
 matched expression. If it fails, the file location remains the same.\\
\textsc{line 15:}  body of the class declaration expected\\
\textsc{line 17:}  while inside the class body, reading of attribute and method members,\\
\textsc{line 19:}  we don't conform exactly to the BNF: beginning of method and attribute declaration
 is factorized,\\
\textsc{line 21:}  name of the attribute or method member,\\
\textsc{line 24:}  not any more ambiguity : it starts by a parenthesis when the members is a method,\\
\textsc{line 27:}  the method expects at least one parameter,\\
\textsc{line 29:}  we keep the current file position, to be able to come back if the next token
 isn't an access mode (\samp{"in"}, \samp{"out"} or \samp{"inout"}),\\
\textsc{line 33:}  we were reading a basic type, instead of a parameter access mode: we come
 back to the beginning of this token and the mode is set as empty (no mode).
 Of course, it is possible not to waste time like this, and to optimize
 function \samp{readType()} by passing the token as a parameter. But here is
 the occasion of discovering how to handle the file position.\\
\textsc{line 37:}  type of the current parameter is expected,\\
\textsc{line 39:}  name of the current parameter is expected,\\
\textsc{line 42:}  parameters are separated by commas,\\
\textsc{line 47:}  both attributes and methods must finish with a semi colon,\\
\textsc{line 48:}  function \samp{readChar()} reads just one character, or returns an empty string
 if the end of file has been reached,\\
\textsc{line 53:}  once the read of file has completed, a message of success is written,\\
\textsc{line 55:}  user-defined function ; may return a value or not. The declaration always starts
 with keyword \samp{function}, even if it announces a procedure (no return value).
 Reading a type is called at several points of the grammar, so the code is
 factorized in the procedure \samp{readType()}. It doesn't return any value about
 success or failure, because an error is thrown in case of syntax mismatch.\\
\textsc{line 58:}  does the keyword is a modifier? If not \samp{sType} contains a basic type or a class name\\
\textsc{line 60:}  reads the name of the aggregated class\\
\textsc{line 64:}  perhaps that the type is an array, represented by \samp{\textbf{[]}},\\
%##end##"file:GettingStarted/SimpleML-token-reading.cws"

This script seems quite far from the BNF of our simple modeling language, while it
implements it in a procedural way. It is able to read a well-formed design file, as
our solar system presented at the beginning of the chapter. It doesn't care about
populating a parse tree yet, but produces contextual error messages when the design
file doesn't conform to the BNF.

Let apply the script on the design file:
%##markup##"execute:parseFree(\"GettingStarted/SimpleML-token-reading.cws\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
%##begin##"execute:parseFree(\"GettingStarted/SimpleML-token-reading.cws\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
\begin{verbatim}
parseFree("GettingStarted/SimpleML-token-reading.cws",
		project, "GettingStarted/SolarSystem0.sml");
\end{verbatim}
\textbf{Output:}

\texttt{the file has been read successfully}

%##end##"execute:parseFree(\"GettingStarted/SimpleML-token-reading.cws\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"

Now, let improve the script to allow populating a parse tree:
%##markup##"file:GettingStarted/SimpleML-token-parsing.cws"
%##begin##"file:GettingStarted/SimpleML-token-parsing.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SimpleML-token-parsing.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} declare function readType(myType : node);\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} while skipEmptyCpp() \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[0.8cm][l]{}if !readIfEqualToIdentifier("class") error("'class' expected");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[0.8cm][l]{}local sClassName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}if !sClassName error("class name expected");\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}insert project.listOfClasses[sClassName].name = sClassName;\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[0.8cm][l]{}if readIfEqualTo(":") \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[1.6cm][l]{}local sParentName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[1.6cm][l]{}if !sParentName error("parent name expected for class '" + sClassName + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[1.6cm][l]{}insert project.listOfClasses[sClassName].parent = sParentName;\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[0.8cm][l]{}if !readIfEqualTo("\{") error("'\{' expected");\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[0.8cm][l]{}local myClass;\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[0.8cm][l]{}ref myClass = project.listOfClasses[sClassName];\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[0.8cm][l]{}while !readIfEqualTo("\}") \{\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[1.6cm][l]{}local myType;\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[1.6cm][l]{}readType(myType);\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[1.6cm][l]{}local sMemberName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[1.6cm][l]{}if !sMemberName error("attribute or method name expected");\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[1.6cm][l]{}if readIfEqualTo("(") \{\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[2.4cm][l]{}insert myClass.listOfMethods[sMemberName].name = sMemberName;\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[2.4cm][l]{}if myType.name != "void" \{\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[3.2cm][l]{}setall myClass.listOfMethods[sMemberName].type = myType;\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[2.4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[2.4cm][l]{}if !readIfEqualTo(")") \{\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[3.2cm][l]{}local myMethod;\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[3.2cm][l]{}ref myMethod = myClass.listOfMethods[sMemberName];\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[3.2cm][l]{}do \{\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[4cm][l]{}local iPosition = getInputLocation();\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[4cm][l]{}local sMode = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   42}} \makebox[4cm][l]{}if !sMode error("parameter type or mode expected");\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[4cm][l]{}if (sMode != "in") \&\& (sMode != "out") \&\& (sMode != "inout") \{\\
	\makebox[1cm][r]{\textrm{\tiny   44}} \makebox[4.8cm][l]{}setInputLocation(iPosition);\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[4.8cm][l]{}set sMode = "";\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \makebox[4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[4cm][l]{}local myParameterType;\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[4cm][l]{}readType(myParameterType);\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[4cm][l]{}local sParameterName = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   52}} \makebox[4cm][l]{}if !sParameterName error("parameter name expected");\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[4cm][l]{}insert myMethod.listOfParameters[sParameterName].name = sParameterName;\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[4cm][l]{}setall myMethod.listOfParameters[sParameterName].type = myParameterType;\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \makebox[4cm][l]{}if sMode \{\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[4.8cm][l]{}insert myMethod.listOfParameters[sParameterName].name = sMode;\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \makebox[3.2cm][l]{}\} while readIfEqualTo(",");\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \makebox[3.2cm][l]{}if !readIfEqualTo(")") error("')' expected");\\
	\makebox[1cm][r]{\textrm{\tiny   61}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[2.4cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \makebox[1.6cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   64}} \makebox[2.4cm][l]{}insert myClass.listOfAttributes[sMemberName].name = sMemberName;\\
	\makebox[1cm][r]{\textrm{\tiny   65}} \makebox[2.4cm][l]{}setall myClass.listOfAttributes[sMemberName].type = myType;\\
	\makebox[1cm][r]{\textrm{\tiny   66}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   67}} \makebox[1.6cm][l]{}if !readIfEqualTo(";")  error("';' expected to close an attribute, instead of '" + readChar() + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   68}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   69}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   70}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   71}} traceLine("the file has been parsed successfully");\\
	\makebox[1cm][r]{\textrm{\tiny   72}} \\
	\makebox[1cm][r]{\textrm{\tiny   73}} function readType(myType : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   74}} \makebox[0.8cm][l]{}local sType = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   75}} \makebox[0.8cm][l]{}if !sType error("type modifier or name expected, instead of '" + readChar() + "'");\\
	\makebox[1cm][r]{\textrm{\tiny   76}} \makebox[0.8cm][l]{}if sType == "aggregate" \{\\
	\makebox[1cm][r]{\textrm{\tiny   77}} \makebox[1.6cm][l]{}insert myType.isAggregation = true;\\
	\makebox[1cm][r]{\textrm{\tiny   78}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   79}} \makebox[1.6cm][l]{}sType = readIdentifier();\\
	\makebox[1cm][r]{\textrm{\tiny   80}} \makebox[1.6cm][l]{}if !sType error("aggregated class name expected");\\
	\makebox[1cm][r]{\textrm{\tiny   81}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   82}} \makebox[0.8cm][l]{}insert myType.name = sType;\\
	\makebox[1cm][r]{\textrm{\tiny   83}} \makebox[0.8cm][l]{}if (sType != "int") \&\& (sType != "double") \&\& (sType != "boolean") \&\& (sType != "string") \{\\
	\makebox[1cm][r]{\textrm{\tiny   84}} \makebox[1.6cm][l]{}insert myType.isObject = true;\\
	\makebox[1cm][r]{\textrm{\tiny   85}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   86}} \makebox[0.8cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   87}} \makebox[0.8cm][l]{}if readIfEqualTo("[") \{\\
	\makebox[1cm][r]{\textrm{\tiny   88}} \makebox[1.6cm][l]{}skipEmptyCpp();\\
	\makebox[1cm][r]{\textrm{\tiny   89}} \makebox[1.6cm][l]{}if !readIfEqualTo("]") error("']' expected to close an array declaration");\\
	\makebox[1cm][r]{\textrm{\tiny   90}} \makebox[1.6cm][l]{}insert myType.isArray = true;\\
	\makebox[1cm][r]{\textrm{\tiny   91}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   92}} \}}


\textsc{line 8:}  about parsing, classes are modeled into node
 \textbf{project.listOfClasses[}\textit{sClassName}\textbf{]}. Its attribute
 \samp{name} contains the value of \textit{sClassName}.\\
\textsc{line 14:}  this class inherits from a parent, so the optional attribute \samp{parent}
 of the class is populated with the value of \textit{sParentName},\\
\textsc{line 19:}  to work easier with the current class node \samp{project.listOfClasses[sClassName]},
 we define a reference to it, called \samp{myClass},\\
\textsc{line 23:}  the class is populated with the characteristics of the member once 
 its declaration has finished. Otherwise, it may confuse between an attribute
 or a method declaration. So, we should have factorized the type declaration
 and the name of the member into a common clause, for example.\\
\textsc{line 30:}  about parsing, methods are modeled into node
 \textbf{myClass.listOfMethods[}\textit{sMemberName}\textbf{]},\\
\textsc{line 31:}  attribute \samp{name} is compulsory into a \textit{type} node, so if
 \samp{myType.name} returns \samp{"void"}, there is no return type,\\
\textsc{line 36:}  to work easier with the current class node \samp{myClass.listOfMethods[sMemberName]},
 we define a reference to it, called \samp{myMethod},\\
\textsc{line 53:}  about parsing, parameters are modeled into node
 \textbf{myMethod.listOfParameters[}\textit{sParameterName}\textbf{]},\\
\textsc{line 64:}  about parsing, attributes are modeled into node
 \textbf{myClass.listOfAttributes[}\textit{sMemberName}\textbf{]},\\
\textsc{line 65:}  the type is allocated on the stack, so it is copied into branch \samp{type}
 (no node reference) integrally,\\
\textsc{line 71:}  once the parsing of file has achieved, a message of success is written,\\
\textsc{line 73:}  function \samp{readType()} requires a node into which description of type
 will be populated,\\
\textsc{line 77:}  about parsing, \textbf{myType.isAggregation} contains \samp{true} if type is an array,\\
\textsc{line 82:}  about parsing, \textbf{myType.name} contains the name of basic type,\\
\textsc{line 83:}  check whether the type is a basic one or a class specifier,\\
\textsc{line 84:}  about parsing, \textbf{myType.isObject} contains \samp{true} because
 we suppose that this type is a class specifier (by default: it isn't a basic type),\\
\textsc{line 90:}  about parsing, \textbf{myType.isArray} contains \samp{true} if type is an array,\\
%##end##"file:GettingStarted/SimpleML-token-parsing.cws"

The first version of the script was just able to read a well-formed design file
written in the simple modeling language. The second version validates the file and
populates the parse tree:
%##markup##"execute:parseFree(\"GettingStarted/SimpleML-token-parsing.cws\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
%##begin##"execute:parseFree(\"GettingStarted/SimpleML-token-parsing.cws\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
\begin{verbatim}
parseFree("GettingStarted/SimpleML-token-parsing.cws",
		project, "GettingStarted/SolarSystem0.sml");
\end{verbatim}
\textbf{Output:}

\texttt{the file has been parsed successfully}

%##end##"execute:parseFree(\"GettingStarted/SimpleML-token-parsing.cws\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"

\pdfsubsection{The parsing scripts that describe a BNF syntax}
A BNF is more flexible and more synthetic than a procedural description
of parsing. \CodeWorker\ accepts parsing scripts that conform to a BNF.

For more information about elements of syntax for a BNF, let have a look to paragraph \ref{BNF syntax}.

Below is an example of what a BNF script looks like:
%##markup##"file:GettingStarted/SimpleML-reading.cwp"
%##begin##"file:GettingStarted/SimpleML-reading.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SimpleML-reading.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} // syntactical clauses:\\
	\makebox[1cm][r]{\textrm{\tiny    2}} world ::= \#ignore(C++) [class\_declaration]* \#empty\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[2.4cm][l]{}=> \{ traceLine("file read successfully"); \};\\
	\makebox[1cm][r]{\textrm{\tiny    4}} class\_declaration ::= IDENT:"class" IDENT [':' IDENT]? class\_body;\\
	\makebox[1cm][r]{\textrm{\tiny    5}} class\_body ::= '\{' [attribute\_decl | method\_decl]* '\}';\\
	\makebox[1cm][r]{\textrm{\tiny    6}} attribute\_decl ::= type\_specifier IDENT ';';\\
	\makebox[1cm][r]{\textrm{\tiny    7}} method\_decl ::= [IDENT:"void" | type\_specifier] IDENT\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[3.2cm][l]{}'(' [parameters\_decl]? ')' ';';\\
	\makebox[1cm][r]{\textrm{\tiny    9}} parameters\_decl ::= parameter [',' parameters\_decl]*;\\
	\makebox[1cm][r]{\textrm{\tiny   10}} parameter ::= [parameter\_mode]? type\_specifier IDENT;\\
	\makebox[1cm][r]{\textrm{\tiny   11}} parameter\_mode ::= IDENT:\{"in", "inout", "out"\};\\
	\makebox[1cm][r]{\textrm{\tiny   12}} type\_specifier ::= basic\_type ['[' ']']?;\\
	\makebox[1cm][r]{\textrm{\tiny   13}} basic\_type ::= "int" | "boolean" | "double" | "string" | class\_specifier;\\
	\makebox[1cm][r]{\textrm{\tiny   14}} class\_specifier ::= ["aggregate"]? IDENT;\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \\
	\makebox[1cm][r]{\textrm{\tiny   16}} // lexical clauses:\\
	\makebox[1cm][r]{\textrm{\tiny   17}} IDENT ::= \#!ignore ['a'..'z'|'A'..'Z'|'\_']\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[4cm][l]{}['a'..'z'|'A'..'Z'|'\_'|'0'..'9']*;}


\textsc{line 2:}  the world to model is composed of classes ; some special commands are
 used:
 \begin{itemize}
 	\item \samp{\#ignore(C++)} means that blank characters and \textit{C++-like}
 		comments will be ignored between pattern matching instructions,
 	\item \samp{\#empty} means that the position must point to the end
 		of the input file,
 	\item \samp{=> \textit{traceLine("file read successfully");}} means that
 		a trace must be executed just after matching with the end of file
 		(the pattern matching instruction is \samp{\#empty}) ; let retain that
			an instruction or a block of instructions is announced by \textbf{'=>'},
 \end{itemize}

\textsc{line 4:}  a class declaration begins with identifier "class", and \samp{\textit{IDENT}:"class"}
 means that an identifier is expected, and that this identifier is worth \samp{"class"}.
 This instruction isn't identical to \samp{"class" \textit{IDENT}} that validates
 the expression \textit{"classes"}, where \samp{\textit{IDENT}} matches to \textit{"es"}.
 A class has a name, read by the first \textit{IDENT} clause call,
 and may inherit from a parent, read by the second \textit{IDENT}\\
\textsc{line 5:}  the body of a class is composed of attributes and methods\\
\textsc{line 6:}  the attribute is preceded by its type, and \textit{IDENT} reads
 the name of the attribute\\
\textsc{line 7:}  the method has a return type or expects \samp{void} keyword, and
 may expect some parameters ;
 \textit{IDENT} reads the name of the method\\
\textsc{line 9:}  a comma separates parameters\\
\textsc{line 10:}  an access mode may be specified to the parameter ; the type is then
 specified, and \textit{IDENT} reads the name\\
\textsc{line 11:}  a parameter may be passed:
 \begin{itemize}
		\item \textbf{in} and its value cannot be changed by the method,
		\item \textbf{inout} and its value may be changed into the method,
		\item \textbf{out} and the method doesn't care about the initial value
			of the parameter, but is expected to assign a value to it into the body,
 \end{itemize}
 The pattern \samp{\textit{IDENT}:\{"in", "inout", "out"\}} means that the identifier
 must match with one of the constant strings listed between brackets. It isn't
 identical to the pattern \samp{"in" | "inout" | "out"} that validates
 the beginning of \textit{"\textbf{in}t"}.\\
\textsc{line 12:}  a type is a \textit{basic type} or an array of basic types\\
\textsc{line 13:}  some basic types, including object types\\
\textsc{line 14:}  \textit{IDENT} reads the class name, and the object may be aggregated\\
\textsc{line 17:}  this clause reads an identifier, such as \textit{pretty\_pig1} ;
 \samp{\#!ignore} means that no character is ignored, even if
 it matches C++ comment or a blank. If we forget clause \samp{\#!ignore},
 then \textit{IDENT} will validate \textit{pretty/*comment*/\_pig 1} as
 an identifier.\\
%##end##"file:GettingStarted/SimpleML-reading.cwp"

This BNF script is very close to the BNF of our simple modeling language, and is
able to read a well-formed design file, as our solar system presented at the beginning
of the chapter. It doesn't care about populating a parse tree yet, and doesn't produce
a contextual error message when the design file doesn't conform to the BNF.

Let apply the BNF script on the design file:
%##markup##"execute:parseAsBNF(\"GettingStarted/SimpleML-reading.cwp\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
%##begin##"execute:parseAsBNF(\"GettingStarted/SimpleML-reading.cwp\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
\begin{verbatim}
parseAsBNF("GettingStarted/SimpleML-reading.cwp",
		project, "GettingStarted/SolarSystem0.sml");
\end{verbatim}
\textbf{Output:}

\texttt{file read successfully}

%##end##"execute:parseAsBNF(\"GettingStarted/SimpleML-reading.cwp\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"

About differences, note that each BNF rule must end with a semi colon, and that they
have to indicate what is their behaviour while encountering blanks and comments.

Now, let improve the BNF script to allow populating a parse tree, or throwing an error
when a syntax error has occurred:
%##markup##"file:GettingStarted/SimpleML-parsing.cwp"
%##begin##"file:GettingStarted/SimpleML-parsing.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SimpleML-parsing.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} // syntactical clauses:\\
	\makebox[1cm][r]{\textrm{\tiny    2}} world ::= \#ignore(C++) [class\_declaration]* \#empty\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[2.4cm][l]{}=> \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[3.2cm][l]{}traceLine("file parsed successfully");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[3.2cm][l]{}saveProject("Scripts/Tutorial/SolarSystem0.xml");\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[2.4cm][l]{}\};\\
	\makebox[1cm][r]{\textrm{\tiny    7}} class\_declaration ::= IDENT:"class" \#continue\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[2.4cm][l]{}IDENT:sClassName\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[3.2cm][l]{}=> insert project.listOfClasses[sClassName].name = sClassName;\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}[':' \#continue IDENT:sParentName\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[3.2cm][l]{}=> insert project.listOfClasses[sClassName].parent = sParentName;\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[2.4cm][l]{}]?\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[2.4cm][l]{}class\_body(project.listOfClasses[sClassName]);\\
	\makebox[1cm][r]{\textrm{\tiny   14}} class\_body(myClass : node) ::= '\{'\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[1.6cm][l]{}[attribute\_decl(myClass) | method\_decl(myClass)]* '\}';\\
	\makebox[1cm][r]{\textrm{\tiny   16}} attribute\_decl(myClass : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[2.4cm][l]{}=> local myType;\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[2.4cm][l]{}type\_specifier(myType) IDENT:sAttributeName ';'\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[2.4cm][l]{}=> \{\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[3.2cm][l]{}insert myClass.listOfAttributes[sAttributeName].name = sAttributeName;\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[3.2cm][l]{}setall myClass.listOfAttributes[sAttributeName].type = myType;\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[2.4cm][l]{}\};\\
	\makebox[1cm][r]{\textrm{\tiny   23}} method\_decl(myClass : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[2.4cm][l]{}=> local myType;\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[2.4cm][l]{}[IDENT:"void" | type\_specifier(myType)]\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[2.4cm][l]{}IDENT:sMethodName '('\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[2.4cm][l]{}\#continue\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[3.2cm][l]{}=> \{\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[4cm][l]{}insert myClass.listOfMethods[sMethodName].name = sMethodName;\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[4cm][l]{}if myType.name\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[4.8cm][l]{}setall myClass.listOfMethods[sMethodName].type = myType;\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[3.2cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[2.4cm][l]{}[parameters\_decl(myClass.listOfMethods[sMethodName])]? ')' ';';\\
	\makebox[1cm][r]{\textrm{\tiny   34}} parameters\_decl(myMethod : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[3.2cm][l]{}parameter(myMethod)\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[3.2cm][l]{}[',' \#continue parameters\_decl(myMethod)]*;\\
	\makebox[1cm][r]{\textrm{\tiny   37}} parameter(myMethod : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[2.4cm][l]{}[parameter\_mode]?:sMode\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[2.4cm][l]{}=> local myType;\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[2.4cm][l]{}type\_specifier(myType)\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[2.4cm][l]{}IDENT:sParameterName\\
	\makebox[1cm][r]{\textrm{\tiny   42}} \makebox[3.2cm][l]{}=> \{\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[4cm][l]{}insert myMethod.listOfParameters[sParameterName].name = sParameterName;\\
	\makebox[1cm][r]{\textrm{\tiny   44}} \makebox[4cm][l]{}setall myMethod.listOfParameters[sParameterName].type = myType;\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[4cm][l]{}if sMode \{\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \makebox[4.8cm][l]{}insert myMethod.listOfParameters[sParameterName].name = sMode;\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[3.2cm][l]{}\};\\
	\makebox[1cm][r]{\textrm{\tiny   49}} parameter\_mode ::= IDENT:\{"in", "inout", "out"\};\\
	\makebox[1cm][r]{\textrm{\tiny   50}} type\_specifier(myType : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[0.8cm][l]{}basic\_type(myType)\\
	\makebox[1cm][r]{\textrm{\tiny   52}} \makebox[0.8cm][l]{}['[' \#continue ']' => insert myType.isArray = true; ]?;\\
	\makebox[1cm][r]{\textrm{\tiny   53}} basic\_type(myType : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[0.8cm][l]{}["int" | "boolean" | "double" | "string"]:myType.name\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \makebox[1.6cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[0.8cm][l]{}class\_specifier(myType);\\
	\makebox[1cm][r]{\textrm{\tiny   57}} class\_specifier(myType : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[0.8cm][l]{}["aggregate" => insert myType.isAggregation = true; ]?\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \makebox[0.8cm][l]{}IDENT:myType.name => \{insert myType.isObject = true; \};\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \\
	\makebox[1cm][r]{\textrm{\tiny   61}} IDENT ::= \#!ignore ['a'..'z'|'A'..'Z'|'\_']\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[4cm][l]{}['a'..'z'|'A'..'Z'|'\_'|'0'..'9']*;}


\textsc{line 2:}  the pattern \textit{[class_declaration]*} always matches with the parsed file,
 so the rule will continue in sequence in any case (supposing that no error has
 occurred into clause \textit{class_declaration}) and the end of file will be
 checked. If not reached, it doesn't write the message \samp{"file read successfully"},\\
\textsc{line 7:}  once keyword \samp{"class"} has been matched, there is no ambiguity : we are
 handling a class declaration and the rule must continue in sequence. To require
 that, instruction \samp{\#continue} is written after pattern \samp{"class"}.
 If a pattern of the sequence doesn't match the parsed file, the parser throws
 a syntax error automatically.\\
\textsc{line 8:}  the identifier that matches with clause call \textit{IDENT} is assigned to
 the local variable \samp{sClassName} : on contrary of other types of script,
 a new variable is considered as local, instead of an new attribute added to
 the current node \samp{\textbf{this}},\\
\textsc{line 9:}  about parsing, classes are modeled into node
 \textbf{project.listOfClasses[}\textit{sClassName}\textbf{]}. Its attribute
 \samp{name} contains the value of \textit{sClassName}.\\
\textsc{line 10:}  if the class inherits from a parent, \samp{\textbf{':'}} is necessary followed by
 an identifier (pattern \samp{\#continue}), and the identifier that matches with
 clause call \textit{IDENT} is assigned to the local variable \samp{sClassName},\\
\textsc{line 11:}  this class inherits from a parent, so the optional attribute \samp{parent}
 of the class is populated with the value of \textit{sParentName},\\
\textsc{line 14:}  clause \samp{class_body} expects an argument: the class node into which the
 class members must be described (\samp{myClass : \textbf{node}}),\\
\textsc{line 16:}  the class is populated with the characteristics of the attribute once 
 its declaration has finished. Otherwise, it may confuse with the beginning
 of a method declaration. To avoid this ambiguity, we should have factorized
 the type declaration and the name of the member into a common clause, for
 example.\\
\textsc{line 20:}  about parsing, attributes are modeled into node
 \textbf{myClass.listOfAttributes[}\textit{sAttributeName}\textbf{]},\\
\textsc{line 21:}  the type is allocated on the stack, so it is copied into branch \samp{type}
 (no node reference) integrally,\\
\textsc{line 23:}  the class is populated with the characteristics of the method once 
 the opened parenthesis is recognized,\\
\textsc{line 27:}  from here, there is no doubt that we are parsing a method declaration,\\
\textsc{line 29:}  about parsing, methods are modeled into node
 \textbf{myClass.listOfMethods[}\textit{sMethodName}\textbf{]},\\
\textsc{line 30:}  attribute \samp{name} is compulsory into a \textit{type} node, so if
 condition \samp{myType.name} returns \samp{false}, there is no return
 type (\samp{void}),\\
\textsc{line 36:}  a parameter declaration is expected after the comma,\\
\textsc{line 43:}  about parsing, parameters are modeled into node
 \textbf{myMethod.listOfParameters[}\textit{sParameterName}\textbf{]},\\
\textsc{line 52:}  about parsing, \textbf{myType.isArray} contains \samp{true} if type is an array,\\
\textsc{line 54:}  about parsing, \textbf{myType.name} contains the name of basic type,\\
\textsc{line 58:}  about parsing, \textbf{myType.isAggregation} contains \samp{true} if
 the object is aggregated,\\
\textsc{line 59:}  about parsing, \textbf{myType.isObject} contains \samp{true} because
 this type is a class specifier,\\
\textsc{line 61:}  the lexical clause \textit{IDENT} recognizes identifiers and might be replaced by
 the predefined clause \samp{\#readIdentifier}, which does the same work,\\
%##end##"file:GettingStarted/SimpleML-parsing.cwp"

The first version of the script was just able to read a well-formed design file
written in the simple modeling language. The second version validates the file and
populates the parse tree:
%##markup##"execute:parseAsBNF(\"GettingStarted/SimpleML-parsing.cwp\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
%##begin##"execute:parseAsBNF(\"GettingStarted/SimpleML-parsing.cwp\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"
\begin{verbatim}
parseAsBNF("GettingStarted/SimpleML-parsing.cwp",
		project, "GettingStarted/SolarSystem0.sml");
\end{verbatim}
\textbf{Output:}

\texttt{file parsed successfully}

%##end##"execute:parseAsBNF(\"GettingStarted/SimpleML-parsing.cwp\",\n\t\tproject, \"GettingStarted/SolarSystem0.sml\");"

\pdfsection{Decorating the parse tree}
Once our design file has been parsed (either procedure-driven or BNF-driven,
we don't care), there is sometimes a little more work to acomplish on the parse tree.
It may be verifying consistency of the whole, as checking existence of each 
class referenced as association or parent. It may also be reorganizing the graph
differently, so as to simplify tasks of source code generation. We call it
\textit{decorating the parse tree} in the \CodeWorker\ vocabulary.

The next script proposes to check the existence of each class specifier types and to
keep a reference to the node that describes this class specifier. Some nodes change their
nature (\samp{myClass.parent} becomes a reference to the parent node, for example),
some other are added (for object types, the new node \samp{myType.class} keeps a reference
to the class):
%##markup##"file:GettingStarted/TreeDecoration.cws"
%##begin##"file:GettingStarted/TreeDecoration.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/TreeDecoration.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}if myClass.parent \{\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[1.6cm][l]{}if !findElement(myClass.parent, project.listOfClasses)\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2.4cm][l]{}error("class '" + myClass.parent + "' doesn't exist while class '"\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[3.6cm][l]{}+ myClass.name + "intends to inherit from it");\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[1.6cm][l]{}ref myClass.parent = project.listOfClasses[myClass.parent];\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}foreach myAttribute in myClass.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[1.6cm][l]{}local myType;\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[1.6cm][l]{}ref myType = myAttribute.type;\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[1.6cm][l]{}if myType.isObject \{\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[2.4cm][l]{}if !findElement(myType.name, project.listOfClasses)\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[3.2cm][l]{}error("class '" + myType.name + "' doesn't exist while attribute '"\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[4.4cm][l]{}+ myClass.name + "::" + myAttribute.name + "' refers to it");\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[2.4cm][l]{}ref myType.class = project.listOfClasses[myType.name];\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[0.8cm][l]{}foreach myMethod in myClass.listOfMethods \{\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[1.6cm][l]{}if existVariable(myMethod.type) \&\& myMethod.type.isObject \{\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[2.4cm][l]{}localref myType = myMethod.type;\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[2.4cm][l]{}if !findElement(myType.name, project.listOfClasses)\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[3.2cm][l]{}error("class '" + myType.name + "' doesn't exist while method '"\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[4.4cm][l]{}+ myClass.name + "::" + myMethod.name + "' refers to it");\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[2.4cm][l]{}ref myType.class = project.listOfClasses[myType.name];\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[1.6cm][l]{}foreach myParameter in myMethod.listOfParameters \{\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[2.4cm][l]{}localref myType = myParameter.type;\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[2.4cm][l]{}if myType.isObject \{\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[3.2cm][l]{}if !findElement(myType.name, project.listOfClasses)\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[4cm][l]{}error("class '" + myType.name\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[5.2cm][l]{}+ "' doesn't exist while method '"\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[5.2cm][l]{}+ myClass.name + "::" + myMethod.name\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[5.2cm][l]{}+ "' refers to it");\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[3.2cm][l]{}ref myType.class = project.listOfClasses[myType.name];\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \}}


\textsc{line 1:}  we iterate all classes,\\
\textsc{line 2:}  if field \samp{parent} is filled, we check its existence and then, we change it
 as a reference to the parent class,\\
\textsc{line 8:}  we iterate all attributes of each class,\\
\textsc{line 11:}  only object attributes are interesting,\\
\textsc{line 12:}  check whether the class exists or not into the array node that contains all classes:
 does the key \samp{myType.name} exist as an array entry of node \samp{project.listOfClasses}?\\
\textsc{line 15:}  to optimize navigating into the parse tree later, we keep a reference to the
 class into new node \textbf{myType.class},\\
\textsc{line 18:}  we iterate all methods of each class,\\
\textsc{line 26:}  we iterate all parameters of each method,\\
%##end##"file:GettingStarted/TreeDecoration.cws"

Now, we dispose of a parsing script that loads well-formed \textit{Simple-Modeling} designs,
and a script that decorates the parse tree. It is time to write a \textit{leader script}
that will take in charge calling tasks of parsing, tree decoration and source code generation:
%##markup##"file:GettingStarted/LeaderScript0.cws"
%##begin##"file:GettingStarted/LeaderScript0.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial/GettingStarted  -define DESIGN_FILE=SolarSystem0.sml -script LeaderScript0.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript0.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny    3}} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} parseAsBNF("SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \#include "TreeDecoration.cws"}


\textsc{line 1:}  we expect the design as a file that conforms to our \textit{Simple-Modeling Language} ;
 the file name is given to the definition preprocessor \samp{DESIGN_FILE} on the command
 line by typing \samp{-define DESIGN_FILE=SolarSystem0.sml},\\
\textsc{line 5:}  the file is parsed thanks to our previous BNF script,\\
\textsc{line 7:}  the source code for decorating tree is included here, and its content will be
 executed just after the parsing,\\
%##end##"file:GettingStarted/LeaderScript0.cws"

\pdfsection{Generating code}
A script that is intended to source code generation is called a \textit{pattern script} in the
\CodeWorker\ vocabulary. The output file is rewritten completely after the protected areas
of user's source code have been preserved.

Such a script begins with a sequence of characters exactly like they must be written into
the output file, up to it encounters special character \textbf{'@'} or JSP-like tag \textbf{'<\%'}.
Then it swaps into script mode, and everything is interpreted as script instructions, up to
special character \textbf{'@'} or JSP-like tag \textbf{'\%>'} are encountered. Content of
the script file is again understood as a sequence of characters to write into the output file,
up to the next special character. And it continues swapping from a mode to another...

For convenience, the script mode may be just restrained to an expression (often the name of
a variable) whose value is written into the output file.

To do source code generation, we'll need some useful functions, such as converting a
\textit{Simple-Modeling} type to its C++ representation. These functions might be included
into the leader script, so as to be shared by all \textit{pattern} scripts.

We'll discover a new type of functions, called \textit{template functions} that bring a little
generic programming in the language: let imagine that we need function
\samp{getType(myType : node)}, to decline for every language we could have to generate
(C++ and JAVA in this chapter). You plan to generate an object library from
the design you have written in the \textit{Simple Modeling Language}. This object
library will be delivered both in C++ and JAVA, and a technical documentation will come
with each of these implementations. This technical documentation will give the signature
of methods and the type of attributes in the language the developer will choose. So the
C++ documentation will be slightly different from the JAVA one, just at the level of type's
spelling. Normally, you'll write the following lines to recover the type depending on the
language for which you are producing the documentation:
\begin{verbatim}
if doc_language == "C++" {
	sType = getCppType(myParameterType);
} else if doc_language == "JAVA" {
	sType = getJAVAType(myParameterType);
} else {
	error("unrecognized language '" + doc_language + "'");
}
\end{verbatim}
Thanks to the template functions, you may replace the precedent lines by the next one:
\begin{verbatim}
sType = getType<doc_language>(myParameterType);
...
function getType<"JAVA">(myType : node) {
	... // implementation for returning a Java type
}

function getType<"C++">(myType : node) {
	... // implementation for returning a C++ type
}
\end{verbatim}
During the execution, the function \samp{getType<\textbf{T}>(myType : node)} resolves
on what instantiated function it has to dispatch: either \samp{getType<\textbf{"JAVA"}>(myType : node)}
or \samp{getType<\textbf{"C++"}>(myType : node)}, depending on what value is assigned to
variable \textit{doc_language}.

Trying to call an instantiated function that doesn't exist, raises an error at runtime.
However, one might imagine an implementation by default. For instance:
\begin{verbatim}
function getType<T>(myType : node) {
	... // implementation for any unrecognized language
}
\end{verbatim}

For those that know generic programming with C++ templates, here is a classical example of
using template functions:
%%##markup##"execute:function f<1>() { return 1; }\nfunction f<N>() { return $N*f<$N - 1$>()$; }\nlocal f10 = f<10>();\nif $f10 != 3628800$ error(\"10! should be worth 3628800\");\ntraceLine(\"10! = \" + f10);"
%##begin##"execute:function f<1>() { return 1; }\nfunction f<N>() { return $N*f<$N - 1$>()$; }\nlocal f10 = f<10>();\nif $f10 != 3628800$ error(\"10! should be worth 3628800\");\ntraceLine(\"10! = \" + f10);"
\begin{verbatim}
function f<1>() { return 1; }
function f<N>() { return $N*f<$N - 1$>()$; }
local f10 = f<10>();
if $f10 != 3628800$ error("10! should be worth 3628800");
traceLine("10! = " + f10);
\end{verbatim}
\textbf{Output:}

\texttt{10! = 3628800}

%##end##"execute:function f<1>() { return 1; }\nfunction f<N>() { return $N*f<$N - 1$>()$; }\nlocal f10 = f<10>();\nif $f10 != 3628800$ error(\"10! should be worth 3628800\");\ntraceLine(\"10! = \" + f10);"

We'll find below all useful functions we'll need for source code generation, including the template
function \samp{getType<\textbf{T}>(myType : node)} we spoke about:
%##markup##"file:GettingStarted/SharedFunctions.cws"
%##begin##"file:GettingStarted/SharedFunctions.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SharedFunctions.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} function normalizeIdentifier(sName) \{\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}if sName \{\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[1.6cm][l]{}if startString(sName, "\_")\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2.4cm][l]{}return "\_" + normalizeIdentifier(subString(sName, 1));\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[1.6cm][l]{}set sName = toUpperString(charAt(sName, 0))\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[4cm][l]{}+ subString(sName, 1);\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[1.6cm][l]{}local iIndex = findFirstChar(sName, "\_.");\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[1.6cm][l]{}if !isNegative(iIndex) \{\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[2.4cm][l]{}local sNext = subString(sName, add(iIndex, 1));\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}return leftString(sName, iIndex)\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[4cm][l]{}+ normalizeIdentifier(sNext);\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}return sName;\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \\
	\makebox[1cm][r]{\textrm{\tiny   17}} function getType<"C++">(myType : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[0.8cm][l]{}local sType;\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[0.8cm][l]{}if myType.isObject set sType = myType.name + "*";\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[0.8cm][l]{}else if myType.name == "boolean" set sType = "bool";\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[0.8cm][l]{}else if myType.name == "string" set sType = "std::string";\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[0.8cm][l]{}else set sType = myType.name;\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[0.8cm][l]{}if myType.isArray set sType = "std::vector<" + sType + ">";\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[0.8cm][l]{}return sType;\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \\
	\makebox[1cm][r]{\textrm{\tiny   27}} function getParameterType<"C++">(myType : node, sMode) \{\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[0.8cm][l]{}local sType = getType<"C++">(myType);\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[0.8cm][l]{}if endString(sMode, "out") set sType += "\&";\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[0.8cm][l]{}else if (sMode == "in") set sType = "const " + sType + "\&";\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[0.8cm][l]{}return sType;\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \\
	\makebox[1cm][r]{\textrm{\tiny   34}} function getType<"JAVA">(myType : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[0.8cm][l]{}local sType;\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[0.8cm][l]{}if myType.name == "string" set sType = "String";\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[0.8cm][l]{}else set sType = myType.name;\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[0.8cm][l]{}if myType.isArray set sType = "java.util.ArrayList/*<" + sType + ">*/";\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[0.8cm][l]{}return sType;\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \\
	\makebox[1cm][r]{\textrm{\tiny   42}} function getParameterType<"JAVA">(myType : node, sMode) \{\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[0.8cm][l]{}return getType<"JAVA">(myType);\\
	\makebox[1cm][r]{\textrm{\tiny   44}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \\
	\makebox[1cm][r]{\textrm{\tiny   46}} function getVariableName(sName, myType : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[0.8cm][l]{}local sPrefix;\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[0.8cm][l]{}if myType.isArray set sPrefix = "t";\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[0.8cm][l]{}if myType.isObject set sPrefix += "p";\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[0.8cm][l]{}else \{\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[1.6cm][l]{}switch(myType.name) \{\\
	\makebox[1cm][r]{\textrm{\tiny   52}} \makebox[2.4cm][l]{}case "int": set sPrefix += "i";break;\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[2.4cm][l]{}case "double": set sPrefix += "d";break;\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[2.4cm][l]{}case "boolean": set sPrefix += "b";break;\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \makebox[2.4cm][l]{}case "string": set sPrefix += "s";break;\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[0.8cm][l]{}return sPrefix + normalizeIdentifier(sName);\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \\
	\makebox[1cm][r]{\textrm{\tiny   61}} function getMethodID(myMethod : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[0.8cm][l]{}local sMethodID = myMethod.name;\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \makebox[0.8cm][l]{}foreach i in myMethod.listOfParameters \{\\
	\makebox[1cm][r]{\textrm{\tiny   64}} \makebox[1.6cm][l]{}set sMethodID += "." + i.type.name;\\
	\makebox[1cm][r]{\textrm{\tiny   65}} \makebox[1.6cm][l]{}if i.type.isArray set sMethodID += "[]";\\
	\makebox[1cm][r]{\textrm{\tiny   66}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   67}} \makebox[0.8cm][l]{}return sMethodID;\\
	\makebox[1cm][r]{\textrm{\tiny   68}} \}}


\textsc{line 1:}  this function normalizes identifiers, so as to capitalize the first letter
 and to suppress \textbf{'\_'} or dots after capitalizing the letter that follows:
 \samp{average\_speed} becomes \samp{AverageSpeed}, for example. This function
 is applied on attribute names for instance.\\
\textsc{line 3:}  if the identifier starts with an underscore, it is preserved,\\
\textsc{line 7:}  points to the first character encountered among an underscore and a dot,\\
\textsc{line 17:}  this function returns the C++ type of a \textit{Simple-Modeling} type node:
 \begin{itemize}
		\item an object returns a pointer to it,
		\item type \samp{boolean} is written \samp{bool} in C++,
		\item type \samp{string} is written \samp{std::string} in the C++ standard library,
		\item an array is written as an instantiated class of \samp{std::vector},
 \end{itemize}

\textsc{line 27:}  this function returns the C++ type of a \textit{Simple-Modeling} type node as
 expected when passed to a method as a parameter type (\samp{sMode} is worth
 \textit{"in"}, \textit{"out"}, \textit{"inout"} or empty string),\\
\textsc{line 34:}  this function returns the JAVA type of a \textit{Simple-Modeling} type node:
 \begin{itemize}
		\item an object returns its class name,
		\item type \samp{boolean} is written identically in JAVA,
		\item type \samp{string} is written \samp{String} in JAVA,
		\item an array is written as a \samp{java.util.ArrayList} interface in JAVA,
 \end{itemize}

\textsc{line 42:}  this function returns the JAVA type of a \textit{Simple-Modeling} type node as
 expected when passed to a method as a parameter type (\samp{sMode} is worth
 \textit{"in"}, \textit{"out"}, \textit{"inout"} or empty string, but we don't
 care about \textit{"inout"} or \textit{"out"} for the moment),\\
\textsc{line 46:}  this function returns a variable name whose nomenclature depends on its type,\\
\textsc{line 51:}  the \samp{switch} statement allows selection among multiple sections of code,
 depending on the value of expression \samp{myType.name}, enclosed in parentheses.
 If no controlling expression (announced by label \samp{case}) matches with the
 value, and no \samp{default} label is present, \CodeWorker\ throws an error.\\
\textsc{line 61:}  this function returns a unique method ID, which is composed from the name of the
 method and the type of parameters, to avoid confusing protected areas from a method
 to another,\\
%##end##"file:GettingStarted/SharedFunctions.cws"

The next two examples both implement same functionalities, but in different languages
(C++ and JAVA). They describe the skeleton of our objects.

\pdfsubsection{C++ classes}
A \textit{pattern} script may be launched thanks to the procedure \samp{generate} that
expects three parameters:
\begin{itemize}
	\item the first one is the file name of the script,
	\item the second one is the current context of execution that will be accessed via the
		\samp{this} keyword into the script,
	\item the last one is the name of the file to generate,
\end{itemize}

The next \textit{pattern} script describes the pattern of a C++ header file:
%##markup##"file:GettingStarted/CppObjectHeader.cwt"
%##begin##"file:GettingStarted/CppObjectHeader.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/CppObjectHeader.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} \#ifndef \_@this.name@\_h\_\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \#define \_@this.name@\_h\_\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \\
	\makebox[1cm][r]{\textrm{\tiny    4}} @\\
	\makebox[1cm][r]{\textrm{\tiny    5}} newFloatingLocation("include files");\\
	\makebox[1cm][r]{\textrm{\tiny    6}} @\\
	\makebox[1cm][r]{\textrm{\tiny    7}} // this line separates the two insertion points, so as to distinguish them!\\
	\makebox[1cm][r]{\textrm{\tiny    8}} @\\
	\makebox[1cm][r]{\textrm{\tiny    9}} newFloatingLocation("class declarations");\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \\
	\makebox[1cm][r]{\textrm{\tiny   11}} function populateHeaderDeclarations(myType : node) \{\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}if myType.isObject insertTextOnce(getFloatingLocation("class declarations"), "class " + myType.name + ";" + endl());\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}if myType.isArray insertTextOnce(getFloatingLocation("include files"), "\#include <vector>" + endl());\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}if myType.name insertTextOnce(getFloatingLocation("include files"), "\#include <string>" + endl());\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \\
	\makebox[1cm][r]{\textrm{\tiny   17}} @\\
	\makebox[1cm][r]{\textrm{\tiny   18}} class @this.name@ @\\
	\makebox[1cm][r]{\textrm{\tiny   19}} if existVariable(this.parent) \{\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[0.8cm][l]{}insertTextOnce(getFloatingLocation("include files"), "\#include $\backslash$"" + this.parent.name +".h$\backslash$"" + endl());\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[0.8cm][l]{}@: public @this.parent.name@ @\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   23}} @\{\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[0.8cm][l]{}private:\\
	\makebox[1cm][r]{\textrm{\tiny   25}} @\\
	\makebox[1cm][r]{\textrm{\tiny   26}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[0.8cm][l]{}populateHeaderDeclarations(i.type);\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[0.8cm][l]{}@        @getType<"C++">(i.type)@ \_@getVariableName(i.name, i.type)@;\\
	\makebox[1cm][r]{\textrm{\tiny   29}} @\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   31}} @\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[0.8cm][l]{}public:\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[1.6cm][l]{}@this.name@();\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[1.6cm][l]{}\~{}@this.name@();\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[1.6cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny   37}} @\\
	\makebox[1cm][r]{\textrm{\tiny   38}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[0.8cm][l]{}local sVariableName = getVariableName(i.name, i.type);\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[0.8cm][l]{}\%>        inline <\%getType<"C++">(i.type)\%> get<\%normalizeIdentifier (i.name)\%>() const \{ return \_<\%sVariableName\%>; \}\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[1.6cm][l]{}inline void set<\%normalizeIdentifier(i.name)@(<\%getType <"C++">(i.type)\%> <\%sVariableName@) \{ \_<\%sVariableName\%> = <\%sVariableName\%>; \}\\
	\makebox[1cm][r]{\textrm{\tiny   42}} @\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   44}} @\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[1.6cm][l]{}// methods:\\
	\makebox[1cm][r]{\textrm{\tiny   46}} @\\
	\makebox[1cm][r]{\textrm{\tiny   47}} foreach i in this.listOfMethods \{\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[0.8cm][l]{}@        virtual @\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[0.8cm][l]{}if existVariable(i.type) \{\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[1.6cm][l]{}populateHeaderDeclarations(i.type);\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[1.6cm][l]{}@@getType<"C++">(i.type)@@\\
	\makebox[1cm][r]{\textrm{\tiny   52}} \makebox[0.8cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[1.6cm][l]{}@void@\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \makebox[0.8cm][l]{}@ @i.name@(@\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[0.8cm][l]{}foreach j in i.listOfParameters \{\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[1.6cm][l]{}if !first(j) \{\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[2.4cm][l]{}@, @\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \makebox[1.6cm][l]{}populateHeaderDeclarations(j.type);\\
	\makebox[1cm][r]{\textrm{\tiny   61}} \makebox[1.6cm][l]{}@@getParameterType<"C++">(j.type, j.mode)@ @getVariableName(j.name, j.type)@@\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \makebox[0.8cm][l]{}@);\\
	\makebox[1cm][r]{\textrm{\tiny   64}} @\\
	\makebox[1cm][r]{\textrm{\tiny   65}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   66}} @\\
	\makebox[1cm][r]{\textrm{\tiny   67}} \makebox[0.8cm][l]{}private:\\
	\makebox[1cm][r]{\textrm{\tiny   68}} \makebox[1.6cm][l]{}@this.name@(const @this.name@\&);\\
	\makebox[1cm][r]{\textrm{\tiny   69}} \makebox[1.6cm][l]{}@this.name@\& operator =(const @this.name@\&);\\
	\makebox[1cm][r]{\textrm{\tiny   70}} \};\\
	\makebox[1cm][r]{\textrm{\tiny   71}} \\
	\makebox[1cm][r]{\textrm{\tiny   72}} \#endif}


\textsc{line 1:}  the value of attribute \samp{\textit{this.}name} is written to the output file, where
 \samp{\textit{this}} points to a node that describes the current class. Note that
 \samp{\textit{this}} is facultative, and is assigned by the caller of procedure
 \samp{generate} that runs this script.\\
\textsc{line 5:}  put one anchor for including all files that we'll encounter as compulsory, while
 iterating attributes or methods. Example: if an attribute is an array, we'll need
 to include the STL header \textit{vector} at this position of the file:
 \textit{\#include <vector>}. This insertion point is called \samp{"include files"}.\\
\textsc{line 6:}  to avoid that the two floating locations \samp{"include files"} and \samp{"class declarations"}
 (described just below) point to the same file position, an empty line is added,\\
\textsc{line 9:}  put one anchor for announcing all classes that we'll encounter as referenced, while
 iterating attributes or methods. Example: if an attribute is an object
 \textit{Planet}, we'll need to write \textit{class Planet;} at this position of
 the file. This insertion point is called \samp{"class declarations"}.\\
\textsc{line 11:}  this function is called on every type encountered while iterating attributes and methods.
 Its role is to populate the \samp{"include files"} and \samp{"class declarations"} areas.\\
\textsc{line 12:}  the type of an object must be declared at the beginning of the header, otherwise
 the compiler will not recognize it : the class is declared \textbf{once only} in
 the insertion point called \samp{"class declarations"}. Use of function \samp{insertTextOnce}
 assures that if this class has already been inserted before, it will not be twice.\\
\textsc{line 13:}  this type is an array, so the declaration of \samp{std::vector} must be included
 to the insertion point called \samp{"include files"},\\
\textsc{line 14:}  this type is a string, so the declaration of \samp{std::string} must be included
 to the insertion point called \samp{"include files"},\\
\textsc{line 19:}  if the class inherits from a parent class, this relationship must be written,\\
\textsc{line 20:}  the parent class must be declared,\\
\textsc{line 26:}  declaration of all attributes,\\
\textsc{line 27:}  does the type of the attribute need some backward declarations?\\
\textsc{line 38:}  accessors to each attribute,\\
\textsc{line 40:}  there are two symbols to swap between writing a sequence of characters and
 interpreting script ; we have used the symbol \textbf{'@'}, and now we illustrate
 the use of tags \textbf{'<\%} and \textbf{'\%>},\\
\textsc{line 41:}  you can melt the two swapping symbol, but it is more difficult to read, so not
 very interesting!\\
\textsc{line 47:}  declaration of all methods,\\
\textsc{line 48:}  each method might be overloaded by subclasses,\\
\textsc{line 49:}  the return type of the method is translated to C++,\\
\textsc{line 50:}  does the return type of the method need some backward declarations?\\
\textsc{line 51:}  expression \samp{getType<"C++">(i.type)} to evaluate is embedded between double
 \textbf{'@'}. The first one allow swapping to the \textit{sequence of characters}
 mode, but there is no characters to write. The second one allows swapping to the
 \textit{script} mode, which is reduced just to evaluate the expression. The two
 final \textbf{'@'} take the same role as seen before.\\
\textsc{line 56:}  parameters of the method are iterated to be written in C++\\
\textsc{line 57:}  if iterator \samp{j} doesn't point to the first parameter, a comma makes a
 separation with the precedent,\\
\textsc{line 60:}  does the type of the parameter need some backward declarations?\\
%##end##"file:GettingStarted/CppObjectHeader.cwt"

Let's continue with the pattern that describes the skeleton of a C++ body file:
%##markup##"file:GettingStarted/CppObjectBody.cwt"
%##begin##"file:GettingStarted/CppObjectBody.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/CppObjectBody.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} \#ifdef WIN32\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \#pragma warning(disable : 4786)\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \#endif\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \\
	\makebox[1cm][r]{\textrm{\tiny    5}} @\\
	\makebox[1cm][r]{\textrm{\tiny    6}} setProtectedArea("include files");\\
	\makebox[1cm][r]{\textrm{\tiny    7}} @\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \#include "@this.name@.h"\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \\
	\makebox[1cm][r]{\textrm{\tiny   10}} @this.name@::@this.name@()@\\
	\makebox[1cm][r]{\textrm{\tiny   11}} local bAtLeastOne = false;\\
	\makebox[1cm][r]{\textrm{\tiny   12}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}if !i.type.isArray \&\& (i.type.name != "string") \{\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[1.6cm][l]{}if bAtLeastOne \{\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[2.4cm][l]{}@, @\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[1.6cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[2.4cm][l]{}@ : @\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[2.4cm][l]{}set bAtLeastOne = true;\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[1.6cm][l]{}@\_@getVariableName(i.name, i.type)@(@\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[1.6cm][l]{}if i.type.isObject \{\\
	\makebox[1cm][r]{\textrm{\tiny   22}} \makebox[2.4cm][l]{}@0L@\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[1.6cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[2.4cm][l]{}switch(i.type.name) \{\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[3.2cm][l]{}case "int":\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[4cm][l]{}@0@\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[4cm][l]{}break;\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[3.2cm][l]{}case "double":\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[4cm][l]{}@0.0@\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[4cm][l]{}break;\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[3.2cm][l]{}case "boolean":\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[4cm][l]{}@false@\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[4cm][l]{}break;\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[1.6cm][l]{}@)@\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   39}} @ \{\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \\
	\makebox[1cm][r]{\textrm{\tiny   42}} @this.name@::\~{}@this.name@() \{\\
	\makebox[1cm][r]{\textrm{\tiny   43}} @\\
	\makebox[1cm][r]{\textrm{\tiny   44}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[0.8cm][l]{}if i.type.isAggregation \&\& i.type.isObject \{\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \makebox[1.6cm][l]{}local sAttributeName = "\_" + getVariableName(i.name, i.type);\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[1.6cm][l]{}local sIndex = "iterate" + normalizeIdentifier(i.name);\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[1.6cm][l]{}if i.type.isArray \{\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[2.4cm][l]{}@    for (std::vector<@i.name@*>::const\_iterator @sIndex@ = @sAttributeName@.begin(); @sIndex@ != @sAttributeName@.end(); ++@sIndex@) \{\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[1.6cm][l]{}delete *@sIndex@;\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   52}} @\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[1.6cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[2.4cm][l]{}@    delete @sAttributeName@;\\
	\makebox[1cm][r]{\textrm{\tiny   55}} @\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   59}} @\}\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \\
	\makebox[1cm][r]{\textrm{\tiny   61}} @\\
	\makebox[1cm][r]{\textrm{\tiny   62}} foreach i in this.listOfMethods \{\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \makebox[0.8cm][l]{}if existVariable(i.type) \{\\
	\makebox[1cm][r]{\textrm{\tiny   64}} \makebox[1.6cm][l]{}@@getType<"C++">(i.type)@@\\
	\makebox[1cm][r]{\textrm{\tiny   65}} \makebox[0.8cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   66}} \makebox[1.6cm][l]{}@void@\\
	\makebox[1cm][r]{\textrm{\tiny   67}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   68}} \makebox[0.8cm][l]{}@ @this.name@::@i.name@(@\\
	\makebox[1cm][r]{\textrm{\tiny   69}} \makebox[0.8cm][l]{}foreach j in i.listOfParameters \{\\
	\makebox[1cm][r]{\textrm{\tiny   70}} \makebox[1.6cm][l]{}if !first(j) \{\\
	\makebox[1cm][r]{\textrm{\tiny   71}} \makebox[2.4cm][l]{}@, @\\
	\makebox[1cm][r]{\textrm{\tiny   72}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   73}} \makebox[1.6cm][l]{}@@getParameterType<"C++">(j.type, j.mode)@ @getVariableName(j.name, j.type)@@\\
	\makebox[1cm][r]{\textrm{\tiny   74}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   75}} \makebox[0.8cm][l]{}@) \{\\
	\makebox[1cm][r]{\textrm{\tiny   76}} @\\
	\makebox[1cm][r]{\textrm{\tiny   77}} \makebox[1.6cm][l]{}setProtectedArea(getMethodID(i));\\
	\makebox[1cm][r]{\textrm{\tiny   78}} @\}\\
	\makebox[1cm][r]{\textrm{\tiny   79}} @\\
	\makebox[1cm][r]{\textrm{\tiny   80}} \}}


\textsc{line 1:}  Visual C++-specific pragma must be added to prevent from intempestive warnings
 about template class instantiation of \samp{std::vector<\textit{T}>} in DEBUG mode!\\
\textsc{line 6:}  the developer will add here all include files he will need for implementation of
 methods,\\
\textsc{line 8:}  the header of this body is compulsory,\\
\textsc{line 11:}  this part concerns the initialization of attributes. Some attributes, such as strings
 and vectors of the STL don't require to be initialized explicitly. It justifies the
 declaration of variable \samp{bAtLeastOne} that is worth \samp{false} as long as
 no attribute has been initialized yet. We'll see why below.\\
\textsc{line 13:}  arrays and strings are skipped,\\
\textsc{line 15:}  if it isn't the first attribute to be initialized, a comma make a separation with
 the precedent,\\
\textsc{line 17:}  if it is the first attribute to be initialized, a colon is expected to announce
 the beginning of initializations\\
\textsc{line 18:}  now, there is at least one attribute to be initialized,\\
\textsc{line 21:}  attribute is populated with the default value corresponding to its type,\\
\textsc{line 44:}  aggregated objects must be deleted before leaving this instance,\\
\textsc{line 49:}  all elements of an aggregated array must be deleted\\
\textsc{line 54:}  the aggregated object is deleted\\
\textsc{line 62:}  implementation of all methods,\\
\textsc{line 63:}  the return type of the method is translated to C++,\\
\textsc{line 69:}  parameters of the method are iterated to be written in C++\\
\textsc{line 70:}  if iterator \samp{j} doesn't point to the first parameter, a comma makes a
 separation with the precedent,\\
\textsc{line 77:}  a protected area is inserted, whose key is the method ID,\\
%##end##"file:GettingStarted/CppObjectBody.cwt"

The leader script has to be improved to reclaim generation of C++ files:
%##markup##"execute_file:GettingStarted/LeaderScript1.cws"
%##begin##"execute_file:GettingStarted/LeaderScript1.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial -path .  -define DESIGN_FILE=GettingStarted/SolarSystem0.sml  -script GettingStarted/LeaderScript1.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript1.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny    3}} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} parseAsBNF("GettingStarted/SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \#include "TreeDecoration.cws"\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \\
	\makebox[1cm][r]{\textrm{\tiny    9}} \#include "SharedFunctions.cws"\\
	\makebox[1cm][r]{\textrm{\tiny   10}} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}traceLine("generating class '" + myClass.name + "' ...");\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}\textbf{generate("GettingStarted/CppObjectHeader.cwt", myClass,}\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[2.6cm][l]{}\textbf{getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/"}\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[2.6cm][l]{}\textbf{+ myClass.name + ".h");}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[0.8cm][l]{}\textbf{generate("GettingStarted/CppObjectBody.cwt", myClass,}\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[2.6cm][l]{}\textbf{getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/"}\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[2.6cm][l]{}\textbf{+ myClass.name + ".cpp");}\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \}}


\textsc{line 9:}  all useful functions for source code generation are loaded here,\\
\textsc{line 10:}  all classes are iterated and their C++ header and body are generated\\
\textsc{line 12:}  instruction \samp{generate} is applied on a \textit{pattern} script and
 its second argument expects a node that will be seen as variable \samp{'this'}
 into the pattern script,\\
\textsc{line 13:}  \samp{getWorkingPath()} is worth the output path passed to the command line via
 the option \samp{'-path'},\\


\textbf{Output:}

\texttt{'Simple Modeling' design file to parse = "GettingStarted/SolarSystem0.sml"\\
file parsed successfully\\
generating class 'Planet' ...\\
generating class 'Earth' ...\\
generating class 'SolarSystem' ...}
%##end##"execute_file:GettingStarted/LeaderScript1.cws"

Let have a look on some generated files:
%##markup##"file:GettingStarted/Cpp/SolarSystem.h"
%##begin##"file:GettingStarted/Cpp/SolarSystem.h"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Cpp/SolarSystem.h":\\
	\makebox[1cm][r]{\textrm{\tiny     }} \#ifndef \_SolarSystem\_h\_\\
	\makebox[1cm][r]{\textrm{\tiny     }} \#define \_SolarSystem\_h\_\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \#include <vector>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \#include <string>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // this line separates the two insertion points, so as to distinguish them!\\
	\makebox[1cm][r]{\textrm{\tiny     }} class Planet;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} class SolarSystem \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}private:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}std::vector<Planet*> \_tpPlanets;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}SolarSystem();\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\~{}SolarSystem();\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}inline std::vector<Planet*> getPlanets() const \{ return \_tpPlanets; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}inline void setPlanets(std::vector<Planet*> tpPlanets) \{ \_tpPlanets = tpPlanets; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}// methods:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}private:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}SolarSystem(const SolarSystem\&);\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}SolarSystem\& operator =(const SolarSystem\&);\\
	\makebox[1cm][r]{\textrm{\tiny     }} \};\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \#endif}

%##end##"file:GettingStarted/Cpp/SolarSystem.h"

%##markup##"file:GettingStarted/Cpp/Planet.cpp"
%##begin##"file:GettingStarted/Cpp/Planet.cpp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/Cpp/Planet.cpp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} \#ifdef WIN32\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \#pragma warning(disable : 4786)\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \#endif\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \\
	\makebox[1cm][r]{\textrm{\tiny    5}} //\#\#protect\#\#"include files"\\
	\makebox[1cm][r]{\textrm{\tiny    6}} //\#\#protect\#\#"include files"\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \\
	\makebox[1cm][r]{\textrm{\tiny    8}} \#include "Planet.h"\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \\
	\makebox[1cm][r]{\textrm{\tiny   10}} Planet::Planet() : \_dDiameter(0.0) \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \\
	\makebox[1cm][r]{\textrm{\tiny   13}} Planet::\~{}Planet() \{\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \\
	\makebox[1cm][r]{\textrm{\tiny   16}} double Planet::getDistanceToSun(int iDay, int iMonth, int iYear) \{\\
	\makebox[1cm][r]{\textrm{\tiny   17}} //\#\#protect\#\#"getDistanceToSun.int.int.int"\\
	\makebox[1cm][r]{\textrm{\tiny   18}} //\#\#protect\#\#"getDistanceToSun.int.int.int"\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \}}


\textsc{line 1:}  Visual C++-specific pragma must be added to prevent from intempestive warnings
 about template class instantiation of \samp{std::vector<\textit{T}>} in DEBUG mode!\\
%##end##"file:GettingStarted/Cpp/Planet.cpp"

\pdfsubsection{JAVA classes}
Some modelers don't separate clearly the design and its implementation, but
theoretically, no language-dependent data has to be included into the design. The
modeling language should be improved to take into account some finer modeling aspects
that lead to choose a mapping (for parameter types, for example) to the implementation
language. The logic of a source code generation process is to factorize as most as possible
the knowledge at the design level. We'll speak longer about it further.

Our design is totally independent from the implementation : a string isn't explicitly
a \samp{const std::string\&} or a \samp{std::string} in C++, but the \textit{pattern script}
decides according to the context whether it is more judicious to choose the first C++ mapping
or the second one.

This independence allows us implementing the same functionalities as in C++, but in JAVA now:
%##markup##"file:GettingStarted/JAVAObject.cwt"
%##begin##"file:GettingStarted/JAVAObject.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/JAVAObject.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} package solarsystem;\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} public class @this.name@ @\\
	\makebox[1cm][r]{\textrm{\tiny    4}} if existVariable(this.parent) \{\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}@extends @this.parent.name@ @\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \}\\
	\makebox[1cm][r]{\textrm{\tiny    7}} @\{\\
	\makebox[1cm][r]{\textrm{\tiny    8}} @\\
	\makebox[1cm][r]{\textrm{\tiny    9}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[0.8cm][l]{}@    private @getType<"JAVA">(i.type)@ \_@getVariableName(i.name, i.type)@;\\
	\makebox[1cm][r]{\textrm{\tiny   11}} @\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   13}} @\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}public @this.name@() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[0.8cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny   17}} @\\
	\makebox[1cm][r]{\textrm{\tiny   18}} foreach i in this.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[0.8cm][l]{}local sVariableName = getVariableName(i.name, i.type);\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[0.8cm][l]{}@    public @getType<"JAVA">(i.type)@ get@normalizeIdentifier(i.name)@() \{ return \_@sVariableName@; \}\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[0.8cm][l]{}public void set@normalizeIdentifier(i.name)@(@getType<"JAVA">(i.type)@ @sVariableName@) \{ \_@sVariableName@ = @sVariableName@; \}\\
	\makebox[1cm][r]{\textrm{\tiny   22}} @\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   24}} @\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[1.6cm][l]{}// methods:\\
	\makebox[1cm][r]{\textrm{\tiny   26}} @\\
	\makebox[1cm][r]{\textrm{\tiny   27}} foreach i in this.listOfMethods \{\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[0.8cm][l]{}@    public @\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[0.8cm][l]{}if existVariable(i.type) \{\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[1.6cm][l]{}@@getType<"JAVA">(i.type)@@\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[0.8cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[1.6cm][l]{}@void@\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[0.8cm][l]{}@ @i.name@(@\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[0.8cm][l]{}foreach j in i.listOfParameters \{\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[1.6cm][l]{}if !first(j) \{\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[2.4cm][l]{}@, @\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[1.6cm][l]{}@@getParameterType<"JAVA">(j.type, j.mode)@ @getVariableName(j.name, j.type)@@\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[0.8cm][l]{}@) \{\\
	\makebox[1cm][r]{\textrm{\tiny   42}} @\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[0.8cm][l]{}setProtectedArea(getMethodID(i));\\
	\makebox[1cm][r]{\textrm{\tiny   44}} @    \}\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \\
	\makebox[1cm][r]{\textrm{\tiny   46}} @\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   48}} @\}}


\textsc{line 4:}  if the class inherits from a parent class, this relationship must be written,\\
\textsc{line 9:}  declaration of all attributes,\\
\textsc{line 18:}  accessors to each attribute,\\
\textsc{line 27:}  declaration of all methods,\\
%##end##"file:GettingStarted/JAVAObject.cwt"

The leader script has to be improved to reclaim generation of JAVA files:
%##markup##"execute_file:GettingStarted/LeaderScript2.cws"
%##begin##"execute_file:GettingStarted/LeaderScript2.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial -path .  -define DESIGN_FILE=GettingStarted/SolarSystem0.sml  -script GettingStarted/LeaderScript2.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript2.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny    3}} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} parseAsBNF("GettingStarted/SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \#include "TreeDecoration.cws"\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \\
	\makebox[1cm][r]{\textrm{\tiny    9}} \#include "SharedFunctions.cws"\\
	\makebox[1cm][r]{\textrm{\tiny   10}} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}traceLine("generating class '" + myClass.name + "' ...");\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectHeader.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".h");\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectBody.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".cpp");\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}\textbf{generate("GettingStarted/JAVAObject.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/JAVA/solarsystem/" + myClass.name + ".java");}\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \}}


\textsc{line 14:}  generates the JAVA implementation of the current design class,\\


\textbf{Output:}

\texttt{'Simple Modeling' design file to parse = "GettingStarted/SolarSystem0.sml"\\
file parsed successfully\\
generating class 'Planet' ...\\
generating class 'Earth' ...\\
generating class 'SolarSystem' ...}
%##end##"execute_file:GettingStarted/LeaderScript2.cws"

Let have a look on some generated files:
%##markup##"file:GettingStarted/JAVA/solarsystem/SolarSystem.java"
%##begin##"file:GettingStarted/JAVA/solarsystem/SolarSystem.java"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/JAVA/solarsystem/SolarSystem.java":\\
	\makebox[1cm][r]{\textrm{\tiny     }} package solarsystem;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} public class SolarSystem \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}private java.util.ArrayList/*<Planet>*/ \_tpPlanets;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public SolarSystem() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public java.util.ArrayList/*<Planet>*/ getPlanets() \{ return \_tpPlanets; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public void setPlanets(java.util.ArrayList/*<Planet>*/ tpPlanets) \{ \_tpPlanets = tpPlanets; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}// methods:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}

%##end##"file:GettingStarted/JAVA/solarsystem/SolarSystem.java"

%##markup##"file:GettingStarted/JAVA/solarsystem/Planet.java"
%##begin##"file:GettingStarted/JAVA/solarsystem/Planet.java"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/JAVA/solarsystem/Planet.java":\\
	\makebox[1cm][r]{\textrm{\tiny     }} package solarsystem;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} public class Planet \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}private double \_dDiameter;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public Planet() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// accessors:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public double getDiameter() \{ return \_dDiameter; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public void setDiameter(double dDiameter) \{ \_dDiameter = dDiameter; \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}// methods:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}public double getDistanceToSun(int iDay, int iMonth, int iYear) \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} //\#\#protect\#\#"getDistanceToSun.int.int.int"\\
	\makebox[1cm][r]{\textrm{\tiny     }} //\#\#protect\#\#"getDistanceToSun.int.int.int"\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}

%##end##"file:GettingStarted/JAVA/solarsystem/Planet.java"

\pdfsection{Expanding a file}
Expanding a file consists of generating code to some determined points of the file. These
points are called \samp{markups} and are noted \textbf{\#\#markup\#\#"}\textit{name-of-the-markup}\textbf{"},
surrounded by comment delimiters.

For example, a valid markup inlayed in a C++ file could be:\\
\samp{//\#\#markup\#\#"factory"}\\
and a valid markup inlayed in an HTML file could be:\\
\samp{<!- -\#\#markup\#\#"classes"- ->}

Some data may accompany the markup. The block of data is put between tags \samp{\#\#data\#\#}:\\
\samp{//\#\#markup\#\#"switch(sText)"}\\
\samp{//\#\#data\#\#}\\
\samp{//Customer}\\
\samp{//Videostore}\\
\samp{//\#\#data\#\#}\\
You obtain the data attached to the current markup key by calling the function \samp{getMarkupValue()}
(see \ref{getMarkupValue()}). This example extends the C++/Java functionalities with a
\textit{switch} statement working on a string expression.


A \textit{pattern} script intended to expand code is launched thanks to the procedure
\samp{expand} that expects three parameters:
\begin{itemize}
	\item the first one is the file name of the script,
	\item the second one is the current context of execution that will be accessed via the
		\samp{this} keyword into the script,
	\item the last one is the name of the file to expand,
\end{itemize}

Each time \CodeWorker\ will encounter a markup, it will call the \textit{pattern} script that
will decide how to populate it. The code generated by the \textit{pattern} script for this
markup is surrounded by tags \textbf{\#\#begin\#\#"}\textit{name-of-the-markup}\textbf{"} and
\textbf{\#\#end\#\#"}\textit{name-of-the-markup}\textbf{"}, automatically added by the
interpreter. If some protected areas were put into the generated code, they are preserved the
next time the expansion is required.

Note that \CodeWorker\ doesn't change what is written outside the markups and their begin/end
delimiters.

Starting from a (very simple) HTML canvas, we'll generate an HTML documentation to our project
\textit{SolarSystem}. Here is the canvas that we would like to keep for all our projects:
%##markup##"file:GettingStarted/defaultDocumentation.html"
%##begin##"file:GettingStarted/defaultDocumentation.html"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/defaultDocumentation.html":\\
	\makebox[1cm][r]{\textrm{\tiny     }} <HTML>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}<HEAD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<TITLE>some title...</TITLE>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}</HEAD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}<BODY>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<H1>some title...</H1>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}some global documentation...\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#markup\#\#"classes presentation"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}</BODY>\\
	\makebox[1cm][r]{\textrm{\tiny     }} </HTML>}

%##end##"file:GettingStarted/defaultDocumentation.html"

We'll copy it to \textit{"GettingStarted/SolarSystem0.html"} to populate it with the
characteristics of our current project. The \textit{pattern} script that will be launched to
expand \textit{"GettingStarted/SolarSystem0.html"} is:
%##markup##"file:GettingStarted/HTMLDocumentation.cwt"
%##begin##"file:GettingStarted/HTMLDocumentation.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/HTMLDocumentation.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} @\\
	\makebox[1cm][r]{\textrm{\tiny    2}} if getMarkupKey() == "classes presentation" \{\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[0.8cm][l]{}foreach i in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[1.6cm][l]{}@\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[1.6cm][l]{}<H2><A href="\#@i.name@">@i.name@</A></H2>\\
	\makebox[1cm][r]{\textrm{\tiny    6}} @\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[1.6cm][l]{}setProtectedArea(i.name + ":presentation");\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[1.6cm][l]{}if !isEmpty(i.listOfAttributes) \{\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[2.4cm][l]{}@\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[1.6cm][l]{}<TABLE border="1" cellpadding="3" cellspacing="0" width="100\%">\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[2.4cm][l]{}<TR BGCOLOR="\#CCCCFF">\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[3.2cm][l]{}<TD><B>Type</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[3.2cm][l]{}<TD><B>Attribute name</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[3.2cm][l]{}<TD><B>Description</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny   16}} @\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[2.4cm][l]{}foreach j in i.listOfAttributes \{\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[3.2cm][l]{}@            <TR>\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \makebox[3.2cm][l]{}<TD>@composeHTMLLikeString(getType<this.language> (j.type))@</TD>\\
	\makebox[1cm][r]{\textrm{\tiny   20}} \makebox[3.2cm][l]{}<TD>@j.name@</TD>\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \makebox[3.2cm][l]{}<TD>\\
	\makebox[1cm][r]{\textrm{\tiny   22}} @\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[3.2cm][l]{}setProtectedArea(i.name + "::" + j.name + ":description");\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[3.2cm][l]{}@\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[3.2cm][l]{}</TD>\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny   27}} @\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[2.4cm][l]{}@        </TABLE>\\
	\makebox[1cm][r]{\textrm{\tiny   30}} @\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[1.6cm][l]{}if !isEmpty(i.listOfMethods) \{\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[2.4cm][l]{}@\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[1.6cm][l]{}<UL>\\
	\makebox[1cm][r]{\textrm{\tiny   35}} @\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[2.4cm][l]{}foreach j in i.listOfMethods \{\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[3.2cm][l]{}@            <LI>@\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[3.2cm][l]{}if existVariable(j.type) \{\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[4cm][l]{}@function @composeHTMLLikeString(getType <this.language>(j.type))@ @\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[3.2cm][l]{}\} else \{\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[4cm][l]{}@procedure@\\
	\makebox[1cm][r]{\textrm{\tiny   42}} \makebox[3.2cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[3.2cm][l]{}@<B>@j.name@</B>(@\\
	\makebox[1cm][r]{\textrm{\tiny   44}} \makebox[3.2cm][l]{}foreach k in j.listOfParameters \{\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[4cm][l]{}if !first(k) \{\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \makebox[4.8cm][l]{}@, @\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[4cm][l]{}@@composeHTMLLikeString(getParameterType <this.language>(k.type, k.mode))@ <I>@getVariableName(k.name, k.type)@</I>@\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[3.2cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[3.2cm][l]{}@)\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[3.2cm][l]{}<BR>\\
	\makebox[1cm][r]{\textrm{\tiny   52}} @\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[3.2cm][l]{}setProtectedArea(i.name + "::" + getMethodID(j) + ":description");\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[3.2cm][l]{}@\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \makebox[2.4cm][l]{}</LI>\\
	\makebox[1cm][r]{\textrm{\tiny   56}} @\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[2.4cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[2.4cm][l]{}@        </UL>\\
	\makebox[1cm][r]{\textrm{\tiny   59}} @\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   61}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \}}


\textsc{line 2:}  the predefined function \samp{getMarkupKey()} returns the name of the markup
 to expand,\\
\textsc{line 3:}  the markup is worth "classes presentation", and so, we'll describe all classes\\
\textsc{line 7:}  a protected area is embedded here, which has to be populated by hand into the
 expanded file for describing the class,\\
\textsc{line 9:}  attributes are presented into a table,\\
\textsc{line 18:}  the language into which types have to be expressed is given by \samp{this.language},
 and is worth "C++" or "JAVA" ; don't forget to convert the type to the HTML syntax,
 because of \textbf{'<'} or \textbf{'>'} to convert respectively to \textbf{'\&lt'}
 or \textbf{'\&gt'} for instance. Use the predefined function
 \samp{composeHTMLLikeString()} to do this process.\\
\textsc{line 23:}  a protected area is embedded here, which has to be populated by hand into the
 expanded file for describing the attribute,\\
\textsc{line 37:}  methods are presented into unordered lists,\\
\textsc{line 53:}  a protected area is embedded here, which has to be populated by hand into the
 expanded file for describing the method,\\
%##end##"file:GettingStarted/HTMLDocumentation.cwt"

Now, we have to change the leader script, so as to take into account the generation of the
documentation:
%##markup##"execute_file:GettingStarted/LeaderScript3.cws"
%##begin##"execute_file:GettingStarted/LeaderScript3.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial -path .  -define DESIGN_FILE=GettingStarted/SolarSystem0.sml  -script GettingStarted/LeaderScript3.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript3.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny    3}} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} parseAsBNF("GettingStarted/SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \#include "TreeDecoration.cws"\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \\
	\makebox[1cm][r]{\textrm{\tiny    9}} \#include "SharedFunctions.cws"\\
	\makebox[1cm][r]{\textrm{\tiny   10}} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}traceLine("generating class '" + myClass.name + "' ...");\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectHeader.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".h");\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectBody.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".cpp");\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}generate("GettingStarted/JAVAObject.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/JAVA/solarsystem/" + myClass.name + ".java");\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \textbf{if !existFile("Scripts/Tutorial/GettingStarted/SolarSystem0.html") \{}\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[0.8cm][l]{}\textbf{copyFile("Scripts/Tutorial/GettingStarted/defaultDocumentation.html", "Scripts/Tutorial/GettingStarted/SolarSystem0.html");}\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \textbf{\}}\\
	\makebox[1cm][r]{\textrm{\tiny   19}} \\
	\makebox[1cm][r]{\textrm{\tiny   20}} local myDocumentationContext;\\
	\makebox[1cm][r]{\textrm{\tiny   21}} insert myDocumentationContext.language = "C++";\\
	\makebox[1cm][r]{\textrm{\tiny   22}} traceLine("generating the HTML documentation...");\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \textbf{setCommentBegin("<!--");}\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \textbf{setCommentEnd("-->");}\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \textbf{expand("GettingStarted/HTMLDocumentation.cwt",}\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \makebox[1.6cm][l]{}\textbf{myDocumentationContext, getWorkingPath()}\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[1.6cm][l]{}\textbf{+ "Scripts/Tutorial/GettingStarted/SolarSystem0.html");}}


\textsc{line 16:}  copy the default empty HTML documentation to \textit{"SolarSystem0.html"} if it doesn't exist yet,\\
\textsc{line 20:}  the \samp{myDocumentationContext} variable will be passed to the procedure \samp{expand()},\\
\textsc{line 21:}  an attribute \samp{language} is added to the \samp{myDocumentationContext} variable,
 which specifies whether types must be expressed in C++ or in JAVA into the HTML
 documentation,\\
\textsc{line 23:}  don't forget to specify comment delimiters that are expected by an HTML file,\\
\textsc{line 25:}  the procedure \samp{expand()} allow populating \textit{"SolarSystem0.html"}
 with the characteristics of the project automatically,\\


\textbf{Output:}

\texttt{'Simple Modeling' design file to parse = "GettingStarted/SolarSystem0.sml"\\
file parsed successfully\\
generating class 'Planet' ...\\
generating class 'Earth' ...\\
generating class 'SolarSystem' ...\\
generating the HTML documentation...}
%##end##"execute_file:GettingStarted/LeaderScript3.cws"

After executing this script, we obtain the following HTML documentation, where protected
areas have to be populated, so as to describe classes and attributes and methods:
%##markup##"file:GettingStarted/SolarSystem0.html"
%##begin##"file:GettingStarted/SolarSystem0.html"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/SolarSystem0.html":\\
	\makebox[1cm][r]{\textrm{\tiny     }} <HTML>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}<HEAD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<TITLE>some title...</TITLE>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}</HEAD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}<BODY>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<H1>some title...</H1>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}some global documentation...\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#markup\#\#"classes presentation"--><!--\#\#begin\#\#"classes presentation"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<H2><A href="\#Planet">Planet</A></H2>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"Planet:presentation"--><!--\#\#protect\#\#"Planet:presentation"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<TABLE border="1" cellpadding="3" cellspacing="0" width="100\%">\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<TR BGCOLOR="\#CCCCFF">\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Type</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Attribute name</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Description</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>double</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>diameter</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"Planet::diameter:description"--><!--\#\#protect\#\#"Planet::diameter:description"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}</TABLE>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<UL>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<LI>function double <B>getDistanceToSun</B>(int <I>iDay</I>, int <I>iMonth</I>, int <I>iYear</I>)\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<BR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"Planet::getDistanceToSun.int.int.int:description"--><!--\#\#protect\#\#"Planet::getDistanceToSun.int.int.int:description"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</LI>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}</UL>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<H2><A href="\#Earth">Earth</A></H2>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"Earth:presentation"--><!--\#\#protect\#\#"Earth:presentation"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<TABLE border="1" cellpadding="3" cellspacing="0" width="100\%">\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<TR BGCOLOR="\#CCCCFF">\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Type</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Attribute name</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Description</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>std::vector\&lt;std::string\&gt;</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>countryNames</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"Earth::countryNames:description"--><!--\#\#protect\#\#"Earth::countryNames:description"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}</TABLE>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<H2><A href="\#SolarSystem">SolarSystem</A></H2>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"SolarSystem:presentation"--><!--\#\#protect\#\#"SolarSystem:presentation"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}<TABLE border="1" cellpadding="3" cellspacing="0" width="100\%">\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<TR BGCOLOR="\#CCCCFF">\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Type</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Attribute name</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD><B>Description</B></TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}<TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>std::vector\&lt;Planet*\&gt;</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>planets</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}<TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#protect\#\#"SolarSystem::planets:description"--><!--\#\#protect\#\#"SolarSystem::planets:description"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[3.2cm][l]{}</TD>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}</TR>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}</TABLE>\\
	\makebox[1cm][r]{\textrm{\tiny     }} <!--\#\#end\#\#"classes presentation"-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}</BODY>\\
	\makebox[1cm][r]{\textrm{\tiny     }} </HTML>}

%##end##"file:GettingStarted/SolarSystem0.html"

We'll suppose that the skeleton of the HTML documentation is acceptable for us. It will evolve
with our design "SolarSystem0.sml": if some classes or some members are added or removed, the
skeleton will take these changes into account. When the reference to a protected area
disappears, because the member it was linked to changes its name or is removed, the protected
area is kept up at the end of the file.

Now, we have to populate protected areas and parts of text that are put outside the markups,
so as to complete our documentation. This work has been done to "SolarSystem1.html".

\pdfsection{Translating a file}

Up to now, we discovered parsing on one side and source code generation on the other side. The
\textit{translation} mode merges the two: it offers to parse a file conforming to a BNF and
to translate it into another format, all in the same \textit{translation} script.

A \textit{translation} script looks like a \textit{BNF-driven} parsing script, but where:
\begin{itemize}
	\item special swapping character \textbf{'@'} or JSP-like tag \textbf{'<\%'},
	\item all functions and procedure intended to source code generation,
\end{itemize}
are allowed into compound statements that are announced by \textbf{'=>'}.

Outputs are written into another file, so the input file is preserved. The procedure that
takes the translation in charge is called \textbf{translate()}.

Little practical example: all our documentation has been written in HTML, but we would like
to translate it to LaTeX, into our own format. Why not?

First step, we must be able to read an HTML file according to a BNF representation. The
corresponding BNF-driven script we have to write is restricted to be able to write our file
"SolarSystem1.html":
%##markup##"file:GettingStarted/HTML-parsing.cwp"
%##begin##"file:GettingStarted/HTML-parsing.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/HTML-parsing.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} \#noCase\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} HTML    ::= \#ignore(HTML) \#continue '<' "HTML" '>' HTMLHeader HTMLBody '<' '/' "HTML" '>' \#empty;\\
	\makebox[1cm][r]{\textrm{\tiny    4}} HTMLHeader    ::= '<' \#continue "HEAD" '>' [\~{}['<' '/' "HEAD" '>']]* '<' '/' "HEAD" '>';\\
	\makebox[1cm][r]{\textrm{\tiny    5}} HTMLBody    ::= '<' \#continue "BODY" '>' HTMLText '<' '/' "BODY" '>';\\
	\makebox[1cm][r]{\textrm{\tiny    6}} HTMLText    ::=\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[1.6cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[2.4cm][l]{}\~{}'<'\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[3.2cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}!['<' '/'] \#continue '<'\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[3.2cm][l]{}\#readIdentifier:sTag HTMLNextOfTag<sTag>\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[1.6cm][l]{}]*;\\
	\makebox[1cm][r]{\textrm{\tiny   13}} HTMLNextOfTag<"H1">    ::=    \#continue '>' HTMLText '<' '/' "H1" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   14}} HTMLNextOfTag<"H2">    ::=    \#continue '>' HTMLText '<' '/' "H2" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   15}} HTMLNextOfTag<"A">    ::= [HTMLAttribute]* \#continue '>' HTMLText '<' '/' 'A' '>';\\
	\makebox[1cm][r]{\textrm{\tiny   16}} HTMLNextOfTag<"TABLE">    ::= [HTMLAttribute]* \#continue '>' [HTMLTag("TR")]* '<' '/' "TABLE" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   17}} HTMLTag(sTag : value)    ::= '<' \#readText(sTag) \#continue HTMLNextOfTag<sTag>;\\
	\makebox[1cm][r]{\textrm{\tiny   18}} HTMLNextOfTag<"TR">    ::= [HTMLAttribute]* \#continue '>' [HTMLTag("TD")]* '<' '/' "TR" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   19}} HTMLNextOfTag<"TD">    ::= [HTMLAttribute]* \#continue '>' HTMLText '<' '/' "TD" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   20}} HTMLNextOfTag<"UL">    ::= [HTMLAttribute]* \#continue '>' [HTMLTag("LI")]* '<' '/' "UL" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   21}} HTMLNextOfTag<"LI">    ::= [HTMLAttribute]* \#continue '>' HTMLText '<' '/' "LI" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   22}} HTMLNextOfTag<"B">    ::=    \#continue '>' HTMLText '<' '/' "B" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   23}} HTMLNextOfTag<"I">    ::=    \#continue '>' HTMLText '<' '/' "I" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   24}} HTMLNextOfTag<"FONT">    ::= [HTMLAttribute]* \#continue '>' HTMLText '<' '/' "FONT" '>';\\
	\makebox[1cm][r]{\textrm{\tiny   25}} HTMLNextOfTag<"BR">    ::=    ['/']? \#continue '>';\\
	\makebox[1cm][r]{\textrm{\tiny   26}} HTMLAttribute    ::= \#readIdentifier ['=' \#continue [STRING\_LITERAL | WORD\_LITERAL]]?;\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \\
	\makebox[1cm][r]{\textrm{\tiny   28}} \\
	\makebox[1cm][r]{\textrm{\tiny   29}} STRING\_LITERAL ::= \#!ignore '$\backslash$"' [\~{}'$\backslash$"']* '$\backslash$"';\\
	\makebox[1cm][r]{\textrm{\tiny   30}} WORD\_LITERAL ::= \#!ignore [\~{}['>' | '/' | ' ' | '$\backslash$t']]+;}


\textsc{line 1:}  we don't care about the case: \textit{<BODY>} and \textit{<Body>} must be recognized
 as identical for instance,\\
\textsc{line 6:}  the clause \samp{HTMLText} reads the value between tags,\\
\textsc{line 11:}  the best way to assure an easy extension of the grammar: to declare a template clause
 for describing the reading of a tag,\\
\textsc{line 17:}  a clause to read a determined tag: the token \samp{\#readText} matches the input
 stream to the evaluated expression passed in parameter and the rest is read by the
 template clause that describes the reading of a tag,\\
%##end##"file:GettingStarted/HTML-parsing.cwp"

Second step, we have to improve the BNF-driven script to add some features for generating
the LaTeX code properly.
Don't be afraid about the length of the source code, but go forward to the notes directly:
%##markup##"file:GettingStarted/HTML2LaTeX.cwp"
%##begin##"file:GettingStarted/HTML2LaTeX.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/HTML2LaTeX.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} \#noCase\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} HTML2LaTeX    ::= \#ignore(HTML) \#continue '<' "HTML" '>' HTMLHeader HTMLBody '<' '/' "HTML" '>' \#empty;\\
	\makebox[1cm][r]{\textrm{\tiny    4}} HTMLHeader    ::= '<' \#continue "HEAD" '>' [\~{}['<' '/' "HEAD" '>']]* '<' '/' "HEAD" '>';\\
	\makebox[1cm][r]{\textrm{\tiny    5}} HTMLBody    ::= '<' \#continue "BODY" '>' HTMLText '<' '/' "BODY" '>';\\
	\makebox[1cm][r]{\textrm{\tiny    6}} HTMLText    ::= \#!ignore\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[1.6cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[2.4cm][l]{}'\&' \#continue \#readIdentifier:sEscape HTMLEscape<sEscape> ';'\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[3.2cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[2.4cm][l]{}\~{}'<':cChar => writeText(cChar);\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[3.2cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[2.4cm][l]{}!['<' blanks '/']\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[2.4cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[3.2cm][l]{}"<!--" \#continue [\~{}"-->"]* "-->"\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \makebox[4cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \makebox[3.2cm][l]{}'<' \#continue \#ignore(HTML) \#readIdentifier:sTag HTMLNextOfTag<sTag>\\
	\makebox[1cm][r]{\textrm{\tiny   17}} \makebox[2.4cm][l]{}]\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \makebox[1.6cm][l]{}]*;\\
	\makebox[1cm][r]{\textrm{\tiny   19}} HTMLEscape<"lt">    ::= => \{@<@\};\\
	\makebox[1cm][r]{\textrm{\tiny   20}} HTMLEscape<"gt">    ::= => \{@>@\};\\
	\makebox[1cm][r]{\textrm{\tiny   21}} HTMLTag(sTag : value)    ::= '<' \#readText(sTag) \#continue HTMLNextOfTag<sTag>;\\
	\makebox[1cm][r]{\textrm{\tiny   22}} HTMLNextOfTag<"H1">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[1.6cm][l]{}\#continue '>' => \{@$\backslash$subsection\{@\}\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[1.6cm][l]{}HTMLText\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \makebox[1.6cm][l]{}'<' '/' "H1" '>' => \{@\}@\};\\
	\makebox[1cm][r]{\textrm{\tiny   26}} HTMLNextOfTag<"H2">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   27}} \makebox[1.6cm][l]{}\#continue '>' => \{@$\backslash$subsubsection\{@\}\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \makebox[1.6cm][l]{}HTMLText\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \makebox[1.6cm][l]{}'<' '/' "H2" '>' => \{@\}@\};\\
	\makebox[1cm][r]{\textrm{\tiny   30}} HTMLNextOfTag<"A">    ::= [HTMLAttribute]* \#continue '>' HTMLText '<' '/' 'A' '>';\\
	\makebox[1cm][r]{\textrm{\tiny   31}} HTMLNextOfTag<"TABLE">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[1.6cm][l]{}[HTMLAttribute]* \#continue '>' => \{\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[2.4cm][l]{}@$\backslash$begin\{table@\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[2.4cm][l]{}newFloatingLocation("table PDF suffix");\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[2.4cm][l]{}@\}\{@\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \makebox[2.4cm][l]{}newFloatingLocation("table columns");\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \makebox[2.4cm][l]{}@\}\{.5\}@\\
	\makebox[1cm][r]{\textrm{\tiny   38}} \makebox[1.6cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \makebox[1.6cm][l]{}=> local sPDFTableSuffix;\\
	\makebox[1cm][r]{\textrm{\tiny   40}} \makebox[1.6cm][l]{}HTMLTableTitle(sPDFTableSuffix)\\
	\makebox[1cm][r]{\textrm{\tiny   41}} \makebox[1.6cm][l]{}[HTMLTableLine(sPDFTableSuffix)]*\\
	\makebox[1cm][r]{\textrm{\tiny   42}} \makebox[1.6cm][l]{}'<' '/' "TABLE" '>' => \{@$\backslash$end\{table@sPDFTableSuffix@\}\\
	\makebox[1cm][r]{\textrm{\tiny   43}} @\};\\
	\makebox[1cm][r]{\textrm{\tiny   44}} HTMLTableTitle(sPDFTableSuffix : node)    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[0.8cm][l]{}'<' "TR" [HTMLAttribute]*\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \makebox[0.8cm][l]{}\#continue '>'\\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[0.8cm][l]{}[HTMLTableCol(sPDFTableSuffix)]*\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[0.8cm][l]{}'<' '/' "TR" '>' => \{\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[1.6cm][l]{}insertText(getFloatingLocation("table PDF suffix"), sPDFTableSuffix);\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[1.6cm][l]{}writeText(endl());\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \makebox[0.8cm][l]{}\};\\
	\makebox[1cm][r]{\textrm{\tiny   52}} HTMLTableCol(sPDFTableSuffix : node) ::=\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[0.8cm][l]{}'<' "TD" [HTMLAttribute]* \#continue '>' => \{\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[1.6cm][l]{}@\{@\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \makebox[1.6cm][l]{}if !sPDFTableSuffix insertText(getFloatingLocation("table columns"), "l");\\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[1.6cm][l]{}else insertText(getFloatingLocation("table columns"), "|l");\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \makebox[1.6cm][l]{}set sPDFTableSuffix += "i";\\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \makebox[0.8cm][l]{}'<' 'B' '>' [\#!ignore [\~{}'<':cChar => writeText(cChar);]*] '<' '/' 'B' '>'\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \makebox[0.8cm][l]{}'<' '/' "TD" '>' => \{@\}@\};\\
	\makebox[1cm][r]{\textrm{\tiny   61}} HTMLTableLine(sPDFTableSuffix : value)    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[1.6cm][l]{}'<' "TR" [HTMLAttribute]* \#continue '>' => \{@$\backslash$line@sPDFTableSuffix@@\}\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \makebox[1.6cm][l]{}[HTMLTag("TD")]* '<' '/' "TR" '>' => \{writeText(endl());\};\\
	\makebox[1cm][r]{\textrm{\tiny   64}} HTMLNextOfTag<"TD">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   65}} \makebox[1.6cm][l]{}[HTMLAttribute]* \#continue '>' => \{@\{@\}\\
	\makebox[1cm][r]{\textrm{\tiny   66}} \makebox[1.6cm][l]{}HTMLCellText '<' '/' "TD" '>' => \{@\}@\};\\
	\makebox[1cm][r]{\textrm{\tiny   67}} HTMLCellText    ::= \#!ignore\\
	\makebox[1cm][r]{\textrm{\tiny   68}} \makebox[1.6cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny   69}} \makebox[2.4cm][l]{}'\&' \#continue \#readIdentifier:sEscape HTMLEscape<sEscape> ';'\\
	\makebox[1cm][r]{\textrm{\tiny   70}} \makebox[3.2cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   71}} \makebox[2.4cm][l]{}['$\backslash$r']? ['$\backslash$n'] => \{@ @\}\\
	\makebox[1cm][r]{\textrm{\tiny   72}} \makebox[3.2cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   73}} \makebox[2.4cm][l]{}\~{}'<':cChar => writeText(cChar);\\
	\makebox[1cm][r]{\textrm{\tiny   74}} \makebox[3.2cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   75}} \makebox[2.4cm][l]{}!['<' blanks '/']\\
	\makebox[1cm][r]{\textrm{\tiny   76}} \makebox[2.4cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny   77}} \makebox[3.2cm][l]{}"<!--" \#continue [\~{}"-->"]* "-->"\\
	\makebox[1cm][r]{\textrm{\tiny   78}} \makebox[4cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny   79}} \makebox[3.2cm][l]{}'<' \#continue \#ignore(HTML) \#readIdentifier:sTag HTMLNextOfTag<sTag>\\
	\makebox[1cm][r]{\textrm{\tiny   80}} \makebox[2.4cm][l]{}]\\
	\makebox[1cm][r]{\textrm{\tiny   81}} \makebox[1.6cm][l]{}]*;\\
	\makebox[1cm][r]{\textrm{\tiny   82}} HTMLNextOfTag<"UL">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   83}} \makebox[1.6cm][l]{}[HTMLAttribute]* \#continue '>' => \{@$\backslash$begin\{itemize\}\\
	\makebox[1cm][r]{\textrm{\tiny   84}} @\}\\
	\makebox[1cm][r]{\textrm{\tiny   85}} \makebox[1.6cm][l]{}[HTMLTag("LI")]*\\
	\makebox[1cm][r]{\textrm{\tiny   86}} \makebox[1.6cm][l]{}'<' '/' "UL" '>' => \{@$\backslash$end\{itemize\}\\
	\makebox[1cm][r]{\textrm{\tiny   87}} @\};\\
	\makebox[1cm][r]{\textrm{\tiny   88}} HTMLNextOfTag<"LI">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   89}} \makebox[1.6cm][l]{}[HTMLAttribute]* \#continue '>' => \{@$\backslash$item @\}\\
	\makebox[1cm][r]{\textrm{\tiny   90}} \makebox[1.6cm][l]{}HTMLText\\
	\makebox[1cm][r]{\textrm{\tiny   91}} \makebox[1.6cm][l]{}'<' '/' "LI" '>' => \{writeText(endl());\};\\
	\makebox[1cm][r]{\textrm{\tiny   92}} HTMLNextOfTag<"B">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   93}} \makebox[1.6cm][l]{}\#continue '>' => \{@$\backslash$textbf\{@\}\\
	\makebox[1cm][r]{\textrm{\tiny   94}} \makebox[1.6cm][l]{}HTMLText\\
	\makebox[1cm][r]{\textrm{\tiny   95}} \makebox[1.6cm][l]{}'<' '/' "B" '>' => \{@\}@\};\\
	\makebox[1cm][r]{\textrm{\tiny   96}} HTMLNextOfTag<"I">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny   97}} \makebox[1.6cm][l]{}\#continue '>' => \{@$\backslash$textbf\{@\}\\
	\makebox[1cm][r]{\textrm{\tiny   98}} \makebox[1.6cm][l]{}HTMLText\\
	\makebox[1cm][r]{\textrm{\tiny   99}} \makebox[1.6cm][l]{}'<' '/' "I" '>' => \{@\}@\};\\
	\makebox[1cm][r]{\textrm{\tiny  100}} HTMLNextOfTag<"FONT">    ::= [HTMLAttribute]* \#continue '>' HTMLText '<' '/' "FONT" '>';\\
	\makebox[1cm][r]{\textrm{\tiny  101}} HTMLNextOfTag<"BR">    ::=    ['/']? \#continue '>' => \{ writeText(endl());\};\\
	\makebox[1cm][r]{\textrm{\tiny  102}} HTMLAttribute    ::= \#readIdentifier ['=' \#continue [STRING\_LITERAL | WORD\_LITERAL]]?;\\
	\makebox[1cm][r]{\textrm{\tiny  103}} \\
	\makebox[1cm][r]{\textrm{\tiny  104}} \\
	\makebox[1cm][r]{\textrm{\tiny  105}} blanks ::= [' '| '$\backslash$t' | '$\backslash$r' | '$\backslash$n']*;\\
	\makebox[1cm][r]{\textrm{\tiny  106}} STRING\_LITERAL ::= \#!ignore '$\backslash$"' [\~{}'$\backslash$"']* '$\backslash$"';\\
	\makebox[1cm][r]{\textrm{\tiny  107}} WORD\_LITERAL ::= \#!ignore [\~{}['>' | '/' | ' ' | '$\backslash$t']]+;}


\textsc{line 6:}  blank characters are interesting, so we refuse to ignore HTML blanks and comments,\\
\textsc{line 8:}  handling of HTML escape sequences, announced by character \textbf{'\&'},\\
\textsc{line 10:}  if not the beginning of a tag, the current character of the input stream
 is put to the output stream,\\
\textsc{line 12:}  token operator '!' doesn't move the position of the input stream, and it continues
 in sequence only if the token expression that follows doesn't match; here, we check
 whether we have reached an end of tag or not,\\
\textsc{line 14:}  we do not ignore comments anymore, so we have to do it my ourselves,\\
\textsc{line 16:}  an embedded tag has been encountered,\\
\textsc{line 19:}  template clauses \samp{HTMLEscape<\textit{T}>} are always valid and just convert
 special characters to their LaTeX representation,\\
\textsc{line 22:}  in the real life, HTML tag \textit{<H1>} could represent a chapter, but the LaTeX
 output file is intended to be included into the reference manual of \CodeWorker\ as
 an illustration ; it will be a part of a section, so chapters are translated as
 sub sections!\\
\textsc{line 26:}  in the real life, HTML tag \textit{<H2>} could represent a section, but for the same
 reason as above, it will be translated as a sub-sub section,\\
\textsc{line 34:}  with HTML, the number of columns the table expects is deduced later. However, a
 latex table (well-formed for a PDF conversion) must know explicetly of how many
 columns it is composed. So, a floating position is attached to the current position
 of the output file. While discovering columns, text will be inserted here and further.\\
\textsc{line 36:}  the format of each column is specified at this place,\\
\textsc{line 39:}  we consider that the first line of the table gives the name of the columns, and we'll
 take the PDF table suffix ('ii' for 2 columns, 'iii' for 3 columns, ...) to write
 lines of the table correctly,\\
\textsc{line 41:}  we translate as many lines of the table as we can read, knowing the PDF suffix,\\
\textsc{line 52:}  the clause is intended to read the name of a column of a table, and to translate it
 to LaTeX, knowing that some text must be inserted into the declarative part of the
 LaTeX table,\\
\textsc{line 67:}  the text into a cell of a table shouldn't contain paragraph jumps (empty line in LaTeX),\\
\textsc{line 71:}  the simplest way to avoid empty lines is to ignore end of lines, and to replace it to
 a space,\\
%##end##"file:GettingStarted/HTML2LaTeX.cwp"

Last step, we have to change the leader script, so as to take into account the translation
of the HTML documentation to the LaTeX one:
%##markup##"execute_file:GettingStarted/LeaderScript4.cws"
%##begin##"execute_file:GettingStarted/LeaderScript4.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial -path .  -define DESIGN_FILE=GettingStarted/SolarSystem0.sml  -script GettingStarted/LeaderScript4.cws}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript4.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny    3}} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} parseAsBNF("GettingStarted/SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \#include "TreeDecoration.cws"\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \\
	\makebox[1cm][r]{\textrm{\tiny    9}} \#include "SharedFunctions.cws"\\
	\makebox[1cm][r]{\textrm{\tiny   10}} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}traceLine("generating class '" + myClass.name + "' ...");\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectHeader.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".h");\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectBody.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".cpp");\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \makebox[0.8cm][l]{}generate("GettingStarted/JAVAObject.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/JAVA/solarsystem/" + myClass.name + ".java");\\
	\makebox[1cm][r]{\textrm{\tiny   15}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   16}} \\
	\makebox[1cm][r]{\textrm{\tiny   17}} local myDocumentationContext;\\
	\makebox[1cm][r]{\textrm{\tiny   18}} insert myDocumentationContext.language = "C++";\\
	\makebox[1cm][r]{\textrm{\tiny   19}} traceLine("generating the HTML documentation...");\\
	\makebox[1cm][r]{\textrm{\tiny   20}} setCommentBegin("<!--");\\
	\makebox[1cm][r]{\textrm{\tiny   21}} setCommentEnd("-->");\\
	\makebox[1cm][r]{\textrm{\tiny   22}} expand("GettingStarted/HTMLDocumentation.cwt",\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \makebox[1.6cm][l]{}myDocumentationContext, getWorkingPath()\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \makebox[1.6cm][l]{}+ "Scripts/Tutorial/GettingStarted/SolarSystem1.html");\\
	\makebox[1cm][r]{\textrm{\tiny   25}} \textbf{translate("GettingStarted/HTML2LaTeX.cwp", project, "GettingStarted/SolarSystem1.html", getWorkingPath() + "Scripts/Tutorial/GettingStarted/SolarSystem.tex");}}


\textsc{line 22:}  the procedure \samp{expand()} will allow populating \textit{"SolarSystem1.html"} with the characteristics of the
 project,\\
\textsc{line 25:}  a context of execution (\samp{project} here) is given as a \samp{this} variable,
 although no parsing will be processed: reading and writing only, no data to keep,\\


\textbf{Output:}

\texttt{'Simple Modeling' design file to parse = "GettingStarted/SolarSystem0.sml"\\
file parsed successfully\\
generating class 'Planet' ...\\
generating class 'Earth' ...\\
generating class 'SolarSystem' ...\\
generating the HTML documentation...}
%##end##"execute_file:GettingStarted/LeaderScript4.cws"

It generates the LaTeX file that composes the next sub section:
%##markup##"include:GettingStarted/SolarSystem.tex"
%##begin##"include:GettingStarted/SolarSystem.tex"
\subsection{Design of a solar system}
We dispose of some classes both in C++ and JAVA that allow building applications working on
notions of planets, stars and solar systems.

		\subsubsection{Planet}

This class represents the characteristics of a planet.

		\begin{tableiii}{l|l|l}{.5}{Type}{Attribute name}{Description}
\lineiii{double}{diameter}{the average diameter of the planet  				}
\end{tableiii}


		\begin{itemize}
\item function double \textbf{getDistanceToSun}(int \textbf{iDay}, int \textbf{iMonth}, int \textbf{iYear})
				


This function returns the distance to the sun at a given trivial earthly date. This function
reclaims more attributes for the planet, but we'll see it later (I'm afraid not!).

			
\end{itemize}


		\subsubsection{Earth}

This class represents our planet, for instantiating our particular solar system for instance,
and working on geopolitical data perhaps!

		\begin{tableiii}{l|l|l}{.5}{Type}{Attribute name}{Description}
\lineiii{std::vector<std::string>}{countryNames}{the name of all countries are put into  				}
\end{tableiii}


		\subsubsection{SolarSystem}

This class represents the solar system, with its constituents, the sun excluded for the
moment.

		\begin{tableiii}{l|l|l}{.5}{Type}{Attribute name}{Description}
\lineiii{std::vector<Planet*>}{planets}{the planets that compose the solar system.  				}
\end{tableiii}


	%##end##"include:GettingStarted/SolarSystem.tex"

\pdfsection{The debugger}
The \samp{-debug} option passed to the command line allows running the interpreter in debug
mode. See chapter \ref{the integrated debugger} for more information about its
functionalities. We'll apply it on our precedent \textit{leader script}:
%##markup##"debug_file:GettingStarted/LeaderScript5.cws"
%##begin##"debug_file:GettingStarted/LeaderScript5.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial -path .  -define DESIGN_FILE=GettingStarted/SolarSystem0.sml  -script GettingStarted/LeaderScript5.cws  -stdin GettingStarted/Debugger.cmd -debug}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript5.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny     }} parseAsBNF("GettingStarted/SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \#include "TreeDecoration.cws"\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \#include "SharedFunctions.cws"\\
	\makebox[1cm][r]{\textrm{\tiny     }} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("generating class '" + myClass.name + "' ...");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectHeader.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".h");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectBody.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".cpp");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}generate("GettingStarted/JAVAObject.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/JAVA/solarsystem/" + myClass.name + ".java");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} local myDocumentationContext;\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myDocumentationContext.language = "C++";\\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("generating the HTML documentation...");\\
	\makebox[1cm][r]{\textrm{\tiny     }} setCommentBegin("<!--");\\
	\makebox[1cm][r]{\textrm{\tiny     }} setCommentEnd("-->");\\
	\makebox[1cm][r]{\textrm{\tiny     }} expand("GettingStarted/HTMLDocumentation.cwt",\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}myDocumentationContext, getWorkingPath()\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}+ "Scripts/Tutorial/GettingStarted/SolarSystem1.html");\\
	\makebox[1cm][r]{\textrm{\tiny     }} translate("GettingStarted/HTML2LaTeX.cwp", project, "GettingStarted/SolarSystem1.html", getWorkingPath() + "Scripts/Tutorial/GettingStarted/SolarSystem.tex");}



\textbf{Output:}

\texttt{"LeaderScript5.cws" at 5: \textbf{if} !getProperty("DESIGN\_FILE")\\
// The controlling sequence stops on the first statement of the leader script.\\
// We go the next instruction:\\
n\\
"LeaderScript5.cws" at 7: \textbf{traceLine}("'Simple Modeling' design file to parse = $\backslash$""\\
// twice more:\\
n2\\
'Simple Modeling' design file to parse = "GettingStarted/SolarSystem0.sml"\\
"LeaderScript5.cws" at 11: \textbf{parseAsBNF}("GettingStarted/SimpleML-parsing.cwp",\\
//let plunge into the BNF-driven script:\\
s\\
"SimpleML-parsing.cwp" at 6: world \textbf{::=} \#ignore(C++) [class\_declaration]* \#empty\\
//We are pointing to the beginning of the rule. Let execute '\#ignore(C++)':\\
s\\
"SimpleML-parsing.cwp" at 6: world ::= \textbf{\#ignore(C++)} [class\_declaration]* \#empty\\
//Let go to the unbounded expression '[class\_declaration]*':\\
s\\
"SimpleML-parsing.cwp" at 6: world ::= \#ignore(C++) \textbf{[class\_declaration}]* \#empty\\
//Now, we have a look to 'class\_declaration':\\
s\\
"SimpleML-parsing.cwp" at 16: class\_declaration ::= \textbf{IDENT}:"class" \#continue\\
//We visit 'INDENT:"class"' and we step over immediatly. Into a BNF-driven script, tokens of a\\
//sequence are iterated step by step, and 'next' runs all the sequence in one shot:\\
s\\
"SimpleML-parsing.cwp" at 112: IDENT ::= \textbf{\#!ignore} ['a'..'z'|'A'..'Z'|'\_']\\
n\\
"SimpleML-parsing.cwp" at 21:           \textbf{IDENT}:sClassName\\
//We visit 'INDENT:sClassName' and we step over immediatly:\\
s\\
"SimpleML-parsing.cwp" at 112: IDENT ::= \textbf{\#!ignore} ['a'..'z'|'A'..'Z'|'\_']\\
n\\
"SimpleML-parsing.cwp" at 25:               => \textbf{insert} project.listOfClasses[sClassName].name = sClassName;\\
//What about all local variables available on the stack?\\
l\\
sClassName\\
//What is the value of 'sClassName'?\\
t sClassName\\
Planet\\
//Now, we are looking at a classical statement of the language, an 'insert' assignment. But\\
//it might be more convenient to see more source code:\\
d 4\\
21:             IDENT:sClassName\\
22: //note: about parsing, classes are modeled into node\\
23: //note: $\backslash$textbf\{project.listOfClasses[\}$\backslash$textit\{sClassName\}$\backslash$textbf\{]\}. Its attribute\\
24: //note: $\backslash$samp\{name\} contains the value of $\backslash$textit\{sClassName\}.\\
25:                 => \textbf{insert} project.listOfClasses[sClassName].name = sClassName;\\
26: //note: if the class inherits from a parent, $\backslash$samp\{$\backslash$textbf\{':'\}\} is necessary followed by\\
27: //note: an identifier (pattern $\backslash$samp\{$\backslash$\#continue\}), and the identifier that matches with\\
28: //note: clause call $\backslash$textit\{IDENT\} is assigned to the local variable $\backslash$samp\{sClassName\},\\
29:             [':' \#continue IDENT:sParentName\\
//What about the call stack?\\
stack\\
"SimpleML-parsing.cwp" at 25:               => \textbf{insert} project.listOfClasses[sClassName].name = sClassName;\\
"SimpleML-parsing.cwp" at 6: world ::= \textbf{\#ignore(C++)} [class\_declaration]* \#empty\\
"LeaderScript5.cws" at 11: \textbf{parseAsBNF}("GettingStarted/SimpleML-parsing.cwp",\\
//Exiting the debug session:\\
q\\
file parsed successfully\\
generating class 'Planet' ...\\
generating class 'Earth' ...\\
generating class 'SolarSystem' ...\\
generating the HTML documentation...}
%##end##"debug_file:GettingStarted/LeaderScript5.cws"

\pdfsection{Scripts coverage and time consuming}
The \samp{-quantify} option passed to the command line allows running the interpreter with the
profiling mode. See chapter \ref{quantifying scripts} for more information about its
functionalities. We'll apply it on our precedent \textit{leader script}:
%##markup##"quantify_file:GettingStarted/LeaderScript6.cws"
%##begin##"quantify_file:GettingStarted/LeaderScript6.cws"

\CodeWorker\ \textit{command line to execute:\\} \samp{ -I Scripts/Tutorial -path .  -define DESIGN_FILE=GettingStarted/SolarSystem0.sml  -script GettingStarted/LeaderScript6.cws  -quantify Scripts/Tutorial/GettingStarted/quantify.html}

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/LeaderScript6.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} if !getProperty("DESIGN\_FILE")\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}error("'-define DESIGN\_FILE=file' expected on the command line");\\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("'Simple Modeling' design file to parse = $\backslash$""\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2cm][l]{}+ getProperty("DESIGN\_FILE") + "$\backslash$"");\\
	\makebox[1cm][r]{\textrm{\tiny     }} parseAsBNF("GettingStarted/SimpleML-parsing.cwp",\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.2cm][l]{}project, getProperty("DESIGN\_FILE"));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \#include "TreeDecoration.cws"\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \#include "SharedFunctions.cws"\\
	\makebox[1cm][r]{\textrm{\tiny     }} foreach myClass in project.listOfClasses \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("generating class '" + myClass.name + "' ...");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectHeader.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".h");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}generate("GettingStarted/CppObjectBody.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/Cpp/" + myClass.name + ".cpp");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}generate("GettingStarted/JAVAObject.cwt", myClass, getWorkingPath() + "Scripts/Tutorial/GettingStarted/JAVA/solarsystem/" + myClass.name + ".java");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} local myDocumentationContext;\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myDocumentationContext.language = "C++";\\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("generating the HTML documentation...");\\
	\makebox[1cm][r]{\textrm{\tiny     }} setCommentBegin("<!--");\\
	\makebox[1cm][r]{\textrm{\tiny     }} setCommentEnd("-->");\\
	\makebox[1cm][r]{\textrm{\tiny     }} expand("GettingStarted/HTMLDocumentation.cwt",\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}myDocumentationContext, getWorkingPath()\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}+ "Scripts/Tutorial/GettingStarted/SolarSystem1.html");\\
	\makebox[1cm][r]{\textrm{\tiny     }} translate("GettingStarted/HTML2LaTeX.cwp", project, "GettingStarted/SolarSystem1.html", getWorkingPath() + "Scripts/Tutorial/GettingStarted/SolarSystem.tex");}



\textbf{Output:}

\texttt{'Simple Modeling' design file to parse = "GettingStarted/SolarSystem0.sml"\\
file parsed successfully\\
generating class 'Planet' ...\\
generating class 'Earth' ...\\
generating class 'SolarSystem' ...\\
generating the HTML documentation...}

\textbf{Profiling results:}

\texttt{-- quantify session --\\
quantify execution time = 184ms\\
User defined functions:\\
\makebox[0.4cm][l]{}populateHeaderDeclarations(...) file "e:/Projects/generator/Scripts/Tutorial/GettingStarted/CppObjectHeader.cwt" at 29: 7 occurences in 0ms\\
\makebox[0.4cm][l]{}getMethodID(...) file "e:/Projects/generator/Scripts/Tutorial/GettingStarted/SharedFunctions.cws" at 98: 3 occurences in 0ms\\
\makebox[0.4cm][l]{}getParameterType(...) file "e:/Projects/generator/Scripts/Tutorial/GettingStarted/SharedFunctions.cws" at 44: 3 occurences in 0ms\\
\makebox[0.4cm][l]{}getType(...) file "e:/Projects/generator/Scripts/Tutorial/GettingStarted/SharedFunctions.cws" at 31: 13 occurences in 0ms\\
\makebox[0.4cm][l]{}getVariableName(...) file "e:/Projects/generator/Scripts/Tutorial/GettingStarted/SharedFunctions.cws" at 76: 26 occurences in 1ms\\
\makebox[0.4cm][l]{}normalizeIdentifier(...) file "e:/Projects/generator/Scripts/Tutorial/GettingStarted/SharedFunctions.cws" at 5: 39 occurences in 0ms\\
Predefined functions:\\
\makebox[0.4cm][l]{}charAt(...): 39 occurrences\\
\makebox[0.4cm][l]{}composeHTMLLikeString(...): 7 occurrences\\
\makebox[0.4cm][l]{}endString(...): 9 occurrences\\
\makebox[0.4cm][l]{}endl(...): 19 occurrences\\
\makebox[0.4cm][l]{}executeStringQuiet(...): 1 occurrences\\
\makebox[0.4cm][l]{}existVariable(...): 11 occurrences\\
\makebox[0.4cm][l]{}findElement(...): 2 occurrences\\
\makebox[0.4cm][l]{}findFirstChar(...): 39 occurrences\\
\makebox[0.4cm][l]{}first(...): 12 occurrences\\
\makebox[0.4cm][l]{}getFloatingLocation(...): 23 occurrences\\
\makebox[0.4cm][l]{}getMarkupKey(...): 1 occurrences\\
\makebox[0.4cm][l]{}getProperty(...): 3 occurrences\\
\makebox[0.4cm][l]{}getWorkingPath(...): 11 occurrences\\
\makebox[0.4cm][l]{}isEmpty(...): 6 occurrences\\
\makebox[0.4cm][l]{}isNegative(...): 39 occurrences\\
\makebox[0.4cm][l]{}newFloatingLocation(...): 12 occurrences\\
\makebox[0.4cm][l]{}not(...): 72 occurrences\\
\makebox[0.4cm][l]{}startString(...): 39 occurrences\\
\makebox[0.4cm][l]{}subString(...): 39 occurrences\\
\makebox[0.4cm][l]{}toUpperString(...): 39 occurrences\\
Procedures:\\
\makebox[0.4cm][l]{}\_\_RAW\_TEXT\_TO\_WRITE(...): 498 occurrences\\
\makebox[0.4cm][l]{}clearVariable(...): 1 occurrences\\
\makebox[0.4cm][l]{}expand(...): 1 occurrences\\
\makebox[0.4cm][l]{}generate(...): 9 occurrences\\
\makebox[0.4cm][l]{}insertTextOnce(...): 24 occurrences\\
\makebox[0.4cm][l]{}parseAsBNF(...): 1 occurrences\\
\makebox[0.4cm][l]{}setCommentBegin(...): 1 occurrences\\
\makebox[0.4cm][l]{}setCommentEnd(...): 1 occurrences\\
\makebox[0.4cm][l]{}setProtectedArea(...): 19 occurrences\\
\makebox[0.4cm][l]{}traceLine(...): 5 occurrences\\
\makebox[0.4cm][l]{}translate(...): 1 occurrences\\
\makebox[0.4cm][l]{}writeText(...): 325 occurrences\\
Covered source code: 83\%\\
-- end of quantify session --}
%##end##"quantify_file:GettingStarted/LeaderScript6.cws"

When the \samp{-quantify} option isn't followed by an HTML file name, the synthetic profiling
results are reported to the console:
\begin{itemize}
	\item each user function appears, recalling the script file where it was defined, and
		giving how many times it was executed followed by the total execution time in
		milliseconds,
	\item each predefined function or procedure appears, giving how many times it was executed,
	\item the proportion of source code that was executed, considering visited scripts only,
\end{itemize}
If a file name was specified, the HTML output file highlights all visited script, so as to
show parts of the code that are executed a lot and those that are less executed. Each visited
line is prefixed by the number of times the controlling sequence has run on it.

Some points to notice:
\begin{itemize}
	\item the function called \samp{not} represents the unary boolean operator \textbf{!},
	\item the instruction called \samp{__RAW_TEXT_TO_WRITE} represents the text of a
		\textit{pattern script} to put into the output stream directly, which is inlayed in
		\textbf{@...@} or in \textbf{\%>...<\%} tags,
	\item the instruction called \samp{writeText} represents an expression of a
		\textit{pattern script} that was inlayed in \textbf{@...@} or in \textbf{<\%...\%>}
		tags,
\end{itemize}

\pdfsection{Translating interpreted scripts to C++ source code}
%==========================================================================

Once the scripts are considered as stable, it might be interesting to convert the interpreter
and all necessary scripts to an executable, for many reasons:
\begin{itemize}
	\item the executable is largely faster than the interpreter, especially on big projects,
	\item a script file could be forgotten while delivering the project to somebody else,
	\item it is more convenient to handle an executable only rather than a set of script
		files and a long command line on the interpreter,
\end{itemize}
The executable is built starting from the corresponding C++ source codes of the script files.
It exists two ways to ask for compiling the \CodeWorker\ script files to C++:
\begin{itemize}
	\item the \textbf{\samp{-c++}} option on the command line: it must be followed by the path
		of the directory where the C++ sources will be generated and the option \samp{-script}
		or \samp{-compile} must be set to specify the leader script to convert to C++,
	\item the \textbf{\samp{compileToCpp()}} procedure (see \ref{compileToCpp()}): the required
		arguments are the leader script to convert to C++ and the directory where the C++ sources
		will be generated,
\end{itemize}
Compiling the project to C++ will convert the leader script and all its dependencies (meaning
that all scripts that may be required by the leader will be compiled to C++) and then two
makefiles will be created (a DSP for Visual C++ and a classical makefile intended to LINUX).
The project takes the name of the leader script.

To compile our \textit{Simple Modeling Language} project to C++, we may choose to proceed as
one of the following:
\begin{itemize}
	\item \CodeWorker\ command line to execute:\\
		\samp{-I Scripts/Tutorial -path .  -compile GettingStarted/LeaderScript6.cws -c++ Scripts/Tutorial/GettingStarted/bin}
	\item instruction to execute in the console or into a script:
%##markup##"execute_hide:removeDirectory(\"Scripts/Tutorial/GettingStarted/bin\");"
%##begin##"execute_hide:removeDirectory(\"Scripts/Tutorial/GettingStarted/bin\");"
%##end##"execute_hide:removeDirectory(\"Scripts/Tutorial/GettingStarted/bin\");"
%##markup##"execute:compileToCpp(\"GettingStarted/LeaderScript6.cws\",\n\t\t\"Scripts/Tutorial/GettingStarted/bin\", \".\");"
%##begin##"execute:compileToCpp(\"GettingStarted/LeaderScript6.cws\",\n\t\t\"Scripts/Tutorial/GettingStarted/bin\", \".\");"
\begin{verbatim}
compileToCpp("GettingStarted/LeaderScript6.cws",
		"Scripts/Tutorial/GettingStarted/bin", ".");
\end{verbatim}
%##end##"execute:compileToCpp(\"GettingStarted/LeaderScript6.cws\",\n\t\t\"Scripts/Tutorial/GettingStarted/bin\", \".\");"
\end{itemize}

The directory called \textit{"Scripts/Tutorial/GettingStarted/bin"} contains the C++ source
files and the makefiles:
%##markup##"execute_hide:local theFiles;scanFiles(theFiles, \"Scripts/Tutorial/GettingStarted/bin\", \"\", true);foreach i in theFiles traceLine(\"\\t\" + i);"
%##begin##"execute_hide:local theFiles;scanFiles(theFiles, \"Scripts/Tutorial/GettingStarted/bin\", \"\", true);foreach i in theFiles traceLine(\"\\t\" + i);"

\texttt{\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CGExternalHandling.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CGRuntime.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CppObjectBody\_cwt.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CppObjectBody\_cwt.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CppObjectHeader\_cwt.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CppObjectHeader\_cwt.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/CppParsingTree.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/DynPackage.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/HTML2LaTeX\_cwp.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/HTML2LaTeX\_cwp.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/HTMLDocumentation\_cwt.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/HTMLDocumentation\_cwt.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/JAVAObject\_cwt.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/JAVAObject\_cwt.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/LeaderScript6.dsp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/LeaderScript6\_cws.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/LeaderScript6\_cws.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/Makefile\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/SimpleML-parsing\_cwp.cpp\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/SimpleML-parsing\_cwp.h\\
\makebox[0.8cm][l]{}Scripts/Tutorial/GettingStarted/bin/UtlException.h}

%##end##"execute_hide:local theFiles;scanFiles(theFiles, \"Scripts/Tutorial/GettingStarted/bin\", \"\", true);foreach i in theFiles traceLine(\"\\t\" + i);"

The main C++ source file is \textit{"LeaderScript6.cpp"} and the executable will be called
\textit{"LeaderScript6.exe"}.


\pdfchapter{The scripting language}

\CodeWorker\ must be seen as a script interpreter that is intended to parse and
to generate any kind of text or source code. This interpreter admits some options
on the command line. Some of them look like those of a compiler.

\CodeWorker\ doesn't provide any Graphical User Interface, but a console
mode allows interactivity with the user.

\index{command line}
\pdfsection{Command line of the interpreter}
The \textit{leader script} is the name given to the script that is executed first by the interpreter.
It exists six ways to pass this leader script to the interpreter via the command line:
\begin{itemize}
	\item the script describes all the processing tasks for parsing text, decorating the graph and
		generating code ; the option of the command line is \samp{-script} to execute the script,
	\item the script describes an extended BNF grammar ; the option of the command line is
		\samp{-parseBNF} for executing the script and parsing the source file,
	\item the script describes how to generate code ; the option of the command line is
		\samp{-generate} to execute the script and to generate the output file,
	\item the script describes how to expand a file ; the option of the command line is
		\samp{-expand} to execute the script and to expand the output file into its markups,
	\item a file contains embedded scripts driving their own expansion ; the option of the command line is
		\samp{-autoexpand} to execute embedded scripts located below each markups, expanding the output file on markups,
	\item the script describes a \textit{source-to-source} translation ; the option of the
		command line is \samp{-translate} to execute the script and to translate the source
		file to the output file,
\end{itemize}

To find easier a file to open for reading among some directories, the option \samp{-I}
specifies a path to explore. It gives more flexibility in sharing input files (both scripts
and user files, excepting generated or expanded files) between directories, and it avoids
relative or absolute paths into scripts.

It is possible to define some properties on the command line, thanks to option \samp{-define}
(or \samp{-D}). These properties are intended to be exploited into scripts.

It is recommended to specify a kind of \textit{working directory} with option \samp{-path}.
The assigned value is accessible into scripts via the function \samp{getWorkingPath()}. This
\textit{working directory} generally indicates the output path for copying or generating
files. The developer of scripts decides how to use it.

\CodeWorker\ interprets scripts efficiently for speed. However, it is more convenient to run
a standalone executable, instead of the interpreter and some script files. Moreover, once
scripts are stable, why not to compile them as an executable to run the project a few times
faster? Option \samp{-c++} allows translating the leader script and all its dependencies to
\textit{C++} source codes, ready-to-compile.

To facilitate the tracking of errors, an integrated debugger is called thanks to the
option \samp{-debug}. It runs into the console, and some classical commands allow taking
the control of the execution and exploring the stack and the variables.

Here are presented all switches that are allowed on the command line:
\begin{tableii}{l|l}{.6}{Switch}{Description}
\lineii{\samp{-args} \textbf{[}\textit{arg}\textbf{]*}}{Pass some arguments to the command line.
		The list of arguments stops at the end of the command line or as soon as an option
		is encountered. The arguments are stored in a global array variable called \samp{\_ARGS}.}
\lineii{\samp{-autoexpand} \textit{file-to-expand}}{The file \textit{file-to-expand} is explored
		for expanding code at markups, executing a \textit{template-based} script inserted
		just below each markup.
		It is identical to execute the script function \textbf{autoexpand(}\textit{file-to-expand}\textbf{, project)}.}
\lineii{\samp{-c++} \textit{generated-project-path}\\ \textit{CodeWorker-path}?}{To translate the leader script and all its
		dependencies in C++ source code, once the execution of the leader script has
		achieved (same job as \samp{compileToCpp()} \ref{compileToCpp()}). The \textit{CodeWorker-path}
		is optional and gives the path through includes and libraries of the software. However, it is now
		recommended to specify \textit{CodeWorker-path} by the switch \samp{-home}.}
\lineii{\samp{-c++2target} \textit{script-file}\\ \textit{generated-project-path} \textit{target-language}?}{
		To translate the leader script and all its dependencies in C++ source code.
		Hence, the C++ is translated to a target language, all that once the execution
		of the leader script has achieved. Do not forget to give the path through
		includes and libraries of CodeWorker, setting the switch \samp{-home}.\\
		A preprocessor definition called \textbf{"c++2target-path"} is automatically
		created. It contains the path of the generated project. Call
		\samp{getProperty("c++2target-path")} to retrieve the path value.\\
		\textit{target-language} is optional if at least one script of the project
		holds the target into its filename, just before the extension. Example:
		"myscript.java.cwt" means that the target language of this script is "java".\\
		A property can follow the name of the target language, separated by a '=' symbol.
		The property is accessible via \samp{getProperty("c++2target-property")}, and
		its nature depends on the target. For instance, in Java, this property represents
		the package the generated classes will belong to. Example: java=org.landscape.mountains.}
\lineii{\samp{-c++external} \textit{filename}}{To generate C++ source code for implementing
		all functions declared as external into scripts.}
\lineii{\samp{-commentBegin} \textit{format}} {To specify the format of a beginning of comment.}
\lineii{\samp{-commentEnd} \textit{format}} {To specify the format of a comment's end.}
\lineii{\samp{-compile} \textit{scriptFile}} {To compile a script file, just
		to check whether the syntax is correct.}
\end{tableii}
\begin{tableii}{l|l}{.6}{Switch}{Description}
\lineii{\samp{-commands} \textit{commandFile}} {To load all arguments processed ordinary on the command-line.
		It must be the only switch or else passed on the command-line.}
\lineii{\samp{-console}} {To open a console session (default mode if no script
		to interpret is specified via \samp{-script} or \samp{-compile} or
		\samp{-generate} or \samp{-expand}.}
\lineii{\samp{-debug} [\textit{remote}]?} {To debug a script in a console while executing it. The optional
		argument \textit{remote} defines parameters for a remote socket control of the debugging session.
		\textit{remote} looks like \textbf{<hostname>:<port>}. If <hostname> is empty, CodeWorker runs as a
		socket server.\\}
\lineii{\samp{-define VAR=}\textit{value}\\ or \samp{-D ...}}{To define some variables, as
        when using the C++ preprocessor or when passing properties to the JAVA compiler.
		These variables are similar to properties, insofar as they aren't exploited during
		the preprocessing of scripts to interpret. This option conforms to the format
		\samp{-define VAR} when no value has to be assigned ; in that case,
		\textit{"true"} is assigned by default to variable \samp{VAR}. The script
		function \textbf{getProperty(}\samp{"VAR"}\textbf{)} gives
		the value of variable \samp{VAR}.\\}
\lineii{\samp{-expand} \textit{pattern-script}\\ \textit{file-to-expand}}{Script
		file \textit{pattern-script} is executed to expand file \textit{file-to-expand}
		into markups.
		It is identical to execute script function \textbf{expand(}\textit{pattern-script}\textbf{, project, }\textit{file-to-expand}\textbf{)}.}
\lineii{\samp{-fast}}{To optimize speed. While processing generation, the output
		file is built into memory, instead of into a temporary file.\\}
\lineii{\samp{-generate} \textit{pattern-script}\\ \textit{file-to-generate}}{Script
		file \textit{pattern-script} is executed to generate file \textit{file-to-generate}.
		It is identical to execute script function \textbf{generate(}\textit{pattern-script}\textbf{, project, }\textit{file-to-generate}\textbf{)}.\\}
\lineii{\samp{-genheader} \textit{text}}{Adds a header at the beginning of all generated
		files, followed by a text (see procedure \samp{setGenerationHeader()} \ref{setGenerationHeader()}).}
\lineii{\samp{-help} or \samp{?}}{Help about the command line.}
\lineii{\samp{-home} \textit{CodeWorker-path}}{Specifies the path to the home directory of CodeWorker.}
\lineii{\samp{-I} \textit{path}}{Specify a path to explore when trying
        to find a file while invoking \samp{include} or \samp{parseFree}
		or \samp{parseAsBNF} or \samp{generate} or \samp{expand} or ... This option may be
		repeated to specify more than one \textit{path}.}
\lineii{\samp{-insert} \textit{variable\_expression}\\ \textit{value}}{Creates a new node in
		the main parse tree \samp{project} and assigns a constant value to it. It is identical
		to execute the statement \samp{\textbf{insert} \textit{variable\_expression} \textbf{= "} \textit{value} \textbf{" ;}}.\\}
\lineii{\samp{-nologo}}{The interpreter doesn't write the copyright in the shell at the beginning.}
\end{tableii}
\begin{tableii}{l|l}{.6}{Switch}{Description}
\lineii{\samp{-nowarn} \textit{warnings}}{Specified warning types are ignored. They are separated by pipe symbols.
		Today, the only recognized type is \textbf{undeclvar}, which prevents the developer against the
		use of a undeclared variable.}
\lineii{\samp{-parseBNF} \textit{BNF-parsing-script}\\ \textit{source-file}}{The script
		file \textit{BNF-parsing-script} parses \textit{source-file} from an extended BNF grammar.
		It is identical to execute the script function \textbf{parseAsBNF(}\textit{BNF-parsing-script}\textbf{, project, }\textit{source-file}\textbf{)}.\\}
\lineii{\samp{-path} \textit{path}}{Output directory, returned by the script
		function \textbf{getWorkingPath()}, and used ordinary to specify where
		to generate or copy a file.}
\lineii{\samp{-quantify} [\textit{outputFile}]?}{To execute scripts into quantify mode that consists of
		measuring the coverage and the time consuming. Results are saved to HTML file \textit{outputFile} or
		displayed to the console if not present.}
\lineii{\samp{-script} \textit{script-file}}{Defines the \textit{leader} script, which will be
        executed first.}
\lineii{\samp{-report} \textit{report-file}\\ \textit{request-flag}}{To generate a report once the execution has achieved.
		The report is saved to file \textit{report-file} and nature of information
		depends on the flag \textit{request-flag}. This flag must be built by computing
		a bitwise OR for one or several of the following integer constants:
		\begin{itemize}
			\item \textbf{1}: provides every output file written by a template-based script (\textit{generate()}, \textit{expand()} or \textit{translate})
			\item \textbf{2}: provides every input file scanned by a BNF parse script (\textit{parseAsBNF()} or \textit{translate()})
			\item \textbf{4}: provides details of coverage recording for every output file using the \textbf{\#coverage} directive
			\item \textbf{8}: provides details of coverage recording for every input file using the \textbf{\#matching} directive
			\item \textbf{16}: provides details of coverage recording for every output file written by a template-based script
			\item \textbf{32}: provides details of coverage recording for every input file scanned by a BNF parse script
		\end{itemize}
		Notice that flags \textit{16} and \textit{32} may become highly time and memory consuming, depending both on
		how many input/output files you have to process and on their size.\\}
\lineii{\samp{-stack} \textit{depth}}{To limit the recursive call of functions, for avoiding an
		overflow stack memory. By default, the \textit{depth} is set to 1000.}
\lineii{\samp{-stdin} \textit{filename}}{To change the standard input for reading from an
		existing file. It may be useful for running a scenario.}
\lineii{\samp{-time}}{To display the execution time expressed in milliseconds, just
		before exiting.}
\end{tableii}
\begin{tableii}{l|l}{.6}{Switch}{Description}
\lineii{\samp{-translate} \textit{translation-script}\\ \textit{source-file} \textit{file-to-generate}}{Script
		file \textit{translation-script} processes a \textit{source-to-source} translation.
		It is identical to execute the script function \textbf{translate(}\textit{translation-script}\textbf{, project, }\textit{source-file}\textbf{, }\textit{file-to-generate}\textbf{)}.\\}
\lineii{\samp{-varexist}}{To trigger a warning when the value of a variable that doesn't
		exist is required into a script.}
\lineii{\samp{-verbose}}{To display internal messages of the interpreter (information).}
\lineii{\samp{-version} \textit{version-name}}{To force interpreted scripts as written in a
		precedent version given by \textit{version-name}.}
\end{tableii}

Note that the interpreter proposes a convenient way for running a common script with arguments:\\
\texttt{codeworker \textit{<script-file>} \textit{<arg1>} ... \textit{<argN>} [\textit{<switch>}]*}

This writing replaces the more verbose:\\
\texttt{codeworker -script \textit{<script-file>} -args \textit{<arg1>} ... \textit{<argN>} [\textit{<switch>}]*}

A console mode is launched when the command line is empty. The console only accepts
scripts written in the common syntax, with common functions and procedures. So, parsing
and generation scripts aren't typed directly on the console.

%--------------------------------------------------------------------------
\index{file extensions!cws}
\index{file extensions!cwt}
\index{file extensions!cwp}
\index{cws}
\index{cwt}
\index{cwp}
\pdfsection{Syntax generalities and statements}

A script in \CodeWorker\ consists of a series of statements that are organized into
\textit{blocks} (also known as \textit{compound statements}). A statement is an instruction
the interpreter has to execute.

A single statement must close with a semicolon (\textbf{';'}). A compound statement is defined
by enclosing instructions between braces (\textbf{'\{\}'}). A \textit{block} can be used
everywhere you can use a single statement and must never end with a semicolon after the
trailing brace.

Comments are indicated either by surrounding the text with \textbf{'/*'} and \textbf{'*/'}
or by preceding the rest of the line to ignore with a double slash (\textbf{'//'}).

It exists three families of scripts here. To facilitate their syntax highlighting in editors,
or to indicate briefly the type of the script, we suggest to employ some file extensions,
depending on the nature of the script. The next table exposes the different extensions used
commonly in CodeWorker.

\begin{tableii}{l|l}{.6}{Extension}{Description}
	\lineii{\textbf{\samp{".cwt"}}}{a \textit{template-based} script, for text generation}
	\lineii{\textbf{\samp{".cwp"}}}{a \textit{extended-BNF} parse script, for parsing text}
	\lineii{\textbf{\samp{".cws"}}}{a \textit{common} script, none of the precedent}
\end{tableii}

The structure of the grammar is so rich that it is a challenge to find an editor, which
offers a syntax highlighting engine powerful enough. \JEdit\ proposes the writing of
production rules to describe it, so it is possible to express the syntax highlighting of
the scripting language.

You'll find a package dedicated to \JEdit\ on the Web site, for the inclusion of these new
highlighting modes. Many thanks to Patrick Brannan for this contribution.

\pdfsubsection{preprocessor directives}
A preprocessor directive always starts with a \textbf{'\#'} symbol and is followed by the name
of the directive.

\index{preprocessor directives!include}
\index{\#include}
\pdfsubsubsection{Including a file}
The \samp{\textbf{\#include} \textit{filename}} directive tells the preprocessor to replace
the directive at the point where it appears by the contents of the file specified by the
constant string \textit{filename}. The preprocessor looks for the file in the current
directory and then searches along the path specified by the \samp{-I} option on the command
line.

\index{preprocessor directives!use}
\index{\#use}
\index{null}
\index{extension!dynamic library}
\index{extension!module}
\index{extension!package}
\index{CW4dl!C++ header file}
\index{CW4dl!C++ namespace}
\pdfsubsubsection{Extending the language via a package}

A \textit{package} is an extension of the scripting language that allows adding new
functions in \CodeWorker\ at runtime. A package is implemented as an executable module,
which exports all new functions the developer wants to make available in the interpreter.

\textbf{Loading of a package}

The preprocessor directive \samp{\#use} tells the interpreter that it must extend itself
with the functions exposed by a package.

The syntax is:
\samp{\textbf{\#use} \textit{package-name}}

Loading a package more than once has no effect.

The name of the package must prefix the name of the function, when calling it:
\samp{\textit{package-name}\textbf{::}\textit{my-function}\textbf{(}\textit{parameters...}\textbf{)}}

\textbf{Example:}\\
\texttt{
\textbf{\#use} PGSQL\\
\textbf{PGSQL::connect}("-U pilot -d emergencyDB");\\
local sRequest = "SELECT solution FROM average_adjustment WHERE damage = 'broken wing'";\\
local listOfSolutions;\\
\textbf{PGSQL::selectList}(sRequest, listOfSolutions);\\
if listOfSolutions.empty()\\
	\makebox[0.4cm][r]{}traceLine("No solution. Suggestion: parachute jump?");\\
else \{\\
	\makebox[0.4cm][r]{}traceLine("Solutions:");\\
	\makebox[0.4cm][r]{}foreach i in listOfSolutions\\
	\makebox[0.8cm][r]{}traceLine("    -" + i);\\
\}\\
\textbf{PGSQL::disconnect}(); // if the plane hasn't crashed yet\\
}

The \samp{PGSQL} package serves here for connecting to and querying a PostGreSQL database.
For this example, the package exports three functions: \textit{PGSQL::connect},
\textit{PGSQL::selectList} and \textit{PGSQL::disconnect}.

\textbf{The executable module}

\CodeWorker\ expects a dynamic library, whose name is deduced from the package name and from
the platform the interpreter is running to.\\
The short name of the dynamic library concatenates \samp{\textbf{"cw"}} at the end of the
package name. The extension of the dynamic library must be \samp{\textbf{".dll"}} under
\textit{Microsoft Windows}, and \samp{\textbf{".so"}} under \textit{Linux}.

You must put the dynamic library at a place where \CodeWorker\ will find it at runtime.\\
\textit{Microsoft Windows} proceeds in the following order to locate the library:
\begin{itemize}
	\item The directory where the executable module for the current process is located.
	\item The current directory. 
	\item The Windows system directory (not recommended - it concerns \CodeWorker\ only).
	\item The Windows directory (not recommended - same reason).
	\item The directories listed in the PATH environment variable.
\end{itemize}
Under \textit{Unix}, a relative path for the shared object refers to the current directory
(according to the man description of \samp{dlopen(3C)}).

So, when \CodeWorker\ reads \samp{\textbf{\#use} PGSQL}, it searches a dynamic library
called \samp{"PGSQL\textbf{cw.dll}"} under \textit{Windows} or \samp{"PGSQL\textbf{cw.so}"}
under \textit{Linux}.

\textbf{Building a package}

This section is intended to those that want to build their own packages, for binding to
a database or to a graphical library ... or just for gluing with their own libraries.

When the interpreter find the preprocessor directive \samp{\textbf{\#use} \textit{package-name}}
in a script, it loads the executable module and executes the exported C-like function
\samp{\textbf{CW4DL_EXPORT_SYMBOL void }\textit{package-name}\textbf{_Init(CW4dl::Interpreter*)}}.

The preprocessor definition \samp{CW4DL_EXPORT_SYMBOL} and the namespace \samp{CW4dl} are
both declared in the C++ header file \samp{"CW4dl.h"}. This header file is located in
the \samp{"include"} directory if you downloaded binaries, and at the root of the project
if you downloaded sources.

The C-like function '\samp{\textit{package-name}\textbf{_Init}()}' MUST be present!
\textit{C-like} means that it is declared extern "C" (done by \textit{CW4DL_EXPORT_SYMBOL}).

Initializing the module that way is useful for registering new functions in the engine,
via the function \samp{createCommand()} of the interpreter (see the header file \samp{"CW4dl.h"}
in the declaration of the class \samp{Interpreter} for learning more about it).

Every function to export must start its declaration with the preprocessor definition
\samp{CW4DL_EXPORT_SYMBOL} (means 'extern "C"', but a little more under \textit{Windows}).

\begin{itemize}
	\item Up to 4 parameters, the signature of such a function looks like:\\
		\texttt{
			\textbf{CW4DL_EXPORT_SYMBOL const char*}\\
			\makebox[0.2cm][r]{}selectList(\textbf{CW4dl::Interpreter*},\\
			\makebox[1.6cm][r]{}\textbf{CW4dl::Parameter} p1, \textbf{CW4dl::Parameter} p2);
		}

		where \textit{selectList} is a function expecting 2 parameters.

		The initializer \samp{PGSQL_Init()} in our example informs the engine about the existence
		of this function \textit{selectList} in the package:\\
		\texttt{createCommand("selectList", VALUE_PARAMETER, NODE_PARAMETER);}\\
		which means that \textit{selectList} expects a string followed by a tree.

		In the body of the function 'selectList(...)', the C++ binding is obtained easily
		by a cast of \samp{CW4dl::Parameter}:
		\begin{itemize}
			\item \samp{(const char*)  p1} for the value parameter \textit{p1},
			\item \samp{(CW4dl::Tree*) p2} for the node  parameter \textit{p2},
		\end{itemize}
	 \item if a function contains strictly more than 4 parameter, its signature changes
		and requires a variable number of parameters:
		\texttt{
			\textbf{CW4DL_EXPORT_SYMBOL const char*}\\
			\makebox[0.2cm][r]{}myFunction(\textbf{CW4dl::Interpreter*},\\
			\makebox[1.6cm][r]{}\textbf{int} nbParams, \textbf{CW4dl::Parameter*} tParams);
		}

		where \samp{tParams} is an array of parameter types, and where 'nbParams' gives
		the size.

		The initializer \samp{PGSQL_Init()} informs the engine about the existence
		of this function in the package differently too:
		\texttt{createCommand("myFunction", 6, tParams);}\\
		which means that \textit{myFunction} has 6 parameters whose types are provided
		in \textit{tParams}.
\end{itemize}

Every function returns \samp{\textbf{const char*}}. The CodeWorker's keyword \samp{\textbf{null}} designates
an atypical tree node. It doesn't accept navigation and reference, only passing by parameter to a function.
On the C++ side, this \textit{null} tree node is seen as a null pointer of kind \textit{CW4dl::Tree*}.

The interpreter	\samp{\textbf{CW4dl::Interpreter}} represents the runtime context of CodeWorker.
It is the unavoidable intermediary between the module you are building and CodeWorker.\\
Use it for:
\begin{itemize}
	\item registering new functions into the CodeWorker's engine,
	\item throwing an error,
	\item handling parse trees,
\end{itemize}

\index{preprocessor directives!line}
\index{\#line}
The \samp{\textbf{\#line}} directive forces to another number the line counter of the script file
being parsed. The line just after the directive is supposed to be worth the number specified after
\samp{\#line}.

\index{preprocessor directives!syntax}
\index{\#syntax}
\index{preprocessor directives!end syntax}
\index{\#end syntax}
\pdfsubsubsection{Changing the syntax of the scripting language}
The \samp{\textbf{\#syntax}} directive tells the preprocessor not to parse the following
instructions as classical statements of the scripting language, but as conforming to another
syntax. It allows adapting the syntax to what you are programming:
\begin{itemize}
	\item If you are programming a kind of \textit{makefile} logic, where you have to check
		whether a file has been changed before another or not (using the function
		\samp{fileLastModification()} \ref{fileLastModification()} for example), it is clear
		that you would prefer to implement it in a \textit{makefile-like} syntax rather than
		in the scripting language's syntax,
	\item If you are programming a kind of \textit{shell} logic, where you have to copy files
		and directories, or re/move them, you would prefer to implement it in a \textit{shell-like}
		syntax rather than in the scripting language's syntax. For instance:\\
		\texttt{traceLine("Creating directory 'CodeWorker'...");\\
				removeDirectory("CodeWorker");\\
				copyFile("readme.txt", "CodeWorker/readme.txt");\\
				...}

		might be written in a \textit{shell-like} syntax, inlayed in the \CodeWorker\ script:\\
		\texttt{\textbf{\#syntax shell:"TinyShell.cwp"}\\
				echo Creating directory 'CodeWorker'...\\
				rmdir CodeWorker\\
				copy readme.txt CodeWorker/readme.txt\\
				...\\
				\textbf{\#end syntax}}
\end{itemize}
The directive admits the following writing:\\
\samp{\textbf{"\#syntax"} [\textit{parsing-mode} [\textbf{':'} \textit{BNF-script-file}]? | \textit{BNF-script-file}]}

How does it work? The piece of source code, which doesn't conform to the syntax of the script
language, is put between the directives \samp{\#syntax ...} and \samp{\#end syntax}. If the
trailing directive isn't found, the remaining of the script is considered as written in a
foreign syntax. Be careful that the trailing directive must start at the beginning of the line
necessary to be recognized and that no spaces are allowed between \samp{\#} and \samp{end}.\\
At runtime, the famous piece of source code is parsed and processed via the BNF script file.

Note that it is possible to attach an identifier (called \textit{parsing-mode} above) to a
script file, and to specify later, in any other script, the \textit{parsing mode} only;
\CodeWorker\ will find the corresponding BNF script file. It avoids to handle a physical name
of the BNF parsing file, where a logical name of parsing mode is more convenient.

\textbf{Example:}

\texttt{
	\makebox[1cm][r]{}// the first time, a parsing mode may be attached to the BNF script file\\
	\makebox[1cm][r]{}\#syntax shell:"TinyShell.cwp"\\
	\makebox[1cm][r]{}...\\
	\makebox[1cm][r]{}\#end syntax\\
	\makebox[1cm][r]{}\\
	\makebox[1cm][r]{}// at the second call, it isn't recommended to use the path of the parsing file\\
	\makebox[1cm][r]{}// it is better to use the parsing mode registered previously\\
	\makebox[1cm][r]{}\#syntax shell\\
	\makebox[1cm][r]{}...\\
	\makebox[1cm][r]{}\#end syntax\\
	\makebox[1cm][r]{}\\
	\makebox[1cm][r]{}// here, I know that I'll call it once only, so I don't care about a parsing mode\\
	\makebox[1cm][r]{}\#syntax "MakeFile.cwp"\\
	\makebox[1cm][r]{}...\\
	\makebox[1cm][r]{}\#end syntax
}

where the parsing script \textit{"TinyShell.cwp"} might be worth:
%##markup##"file:GettingStarted/TinyShell.cwp"
%##begin##"file:GettingStarted/TinyShell.cwp"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "GettingStarted/TinyShell.cwp":\\
	\makebox[1cm][r]{\textrm{\tiny     }} tinyShell    ::=\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#ignore(C++)\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#continue\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}[\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}\#readIdentifier:sCommand\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}\#ignore(blanks) \#continue\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}command<sCommand>\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}]* \#empty;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} //----------------------------//\\
	\makebox[1cm][r]{\textrm{\tiny     }} // commands of the tiny shell //\\
	\makebox[1cm][r]{\textrm{\tiny     }} //----------------------------//\\
	\makebox[1cm][r]{\textrm{\tiny     }} command<"copy">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#continue parameter:sSource parameter:sDestination\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}=> \{copyFile(sSource, sDestination);\};\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} command<"rmdir">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#continue parameter:sDirectory\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}=> \{removeDirectory(sDirectory);\};\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} command<"del">    ::=\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#continue parameter:sFile\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}=> \{deleteFile(sFile);\};\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} //--------------------\\
	\makebox[1cm][r]{\textrm{\tiny     }} // Some useful clauses\\
	\makebox[1cm][r]{\textrm{\tiny     }} //--------------------\\
	\makebox[1cm][r]{\textrm{\tiny     }} parameter:value    ::=\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#readCString:parameter\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\#!ignore \#continue [\~{}[' ' | '$\backslash$t' | '$\backslash$r' | '$\backslash$n']]+:parameter;}

%##end##"file:GettingStarted/TinyShell.cwp"

Of course, the parsing and the processing are implemented in the scripting language, so changing
the syntax will be slower than keeping the default one. However, it allows writing a code
easy to support and to understand.

\index{preprocessor directives!reference}
\index{\#reference}
\index{preprocessor directives!attach}
\index{\#attach}
\pdfsubsubsection{Managing changes in a multi-language generation}

The directives \samp{\#reference} and \samp{\#attach} serve to be notified when a change has
been made into a script for generating in a given language, but not taken back in another
language. For example, you are writing a framework both in C++ and JAVA. You are adding some
new features in C++ or correcting some mistakes. One day, you'll be care not to forget to
update the JAVA generation. In fact, thanks to these directives, a warning will be produced
up to changes will have been put in the other script.

How does it work? Directives must delimit the piece of script you have changed:\\
\samp{
	\textbf{"\#reference"} \textit{key}\\
	...\\
	\textbf{"\#end"} \textit{key}}

The key is an identifier that allows putting more than one \textit{reference} area into a
script file. A \textit{\#reference} area might cover one or more \textit{\#reference}
directives, without confusing about boundaries. The directive must be put at the beginning of
the line.

Here are the directives delimiting the piece of script that should be updated later in
another file:\\
\samp{
	\textbf{"\#attach"} \textit{reference-file} \textbf{':'} \textit{reference-key}\\
	...\\
	\textbf{"\#end"} \textit{reference-key}}

A \textit{\#attach} area might cover one or more \textit{\#reference} or \textit{\#attach}
directives, as a \textit{\#reference} area. The directive must be put at the beginning of the
line.

The first time \CodeWorker\ will encounter the \textit{reference} script file, it will compute
a number that depends on the content of the area. The first time \CodeWorker\ will encounter an
\textit{attached} script file, it will get back the \textit{magic} number of the reference
area, found both by the file name and the key of the reference. And then, at the beginning,
the \textit{reference} and \textit{attached} areas are considered as similar. \CodeWorker\ stores
the magic number of the reference just behind the \samp{\#attach} directive:\\
\samp{
	\textbf{"\#attach"} \textit{reference-file} \textbf{':'} \textit{reference-key} \textbf{','} \textit{reference-number}
}

In fact, a script file that must be updated, so as to store the magic numbers for some attached
areas, takes into account the modifications at the end of the parsing, and only if no error
was encountered. If the \samp{writefileHook()} function (see \ref{writefileHook}) is implemented,
it is called and the script file doesn't change if it returns \samp{false}. If the script file
is read-only, the corresponding \samp{readonlyHook()} function is called (see \ref{readonlyHook}).
If it isn't possible to save the script file, an error is thrown.

When a change occurs in the \textit{reference} area, the next time \CodeWorker\ will encounter
it, the magic number will be recomputed. When an attached piece of script is encountered after
the change, the old magic number of the reference is compared to the new one. If they aren't
the same, a warning is displayed to notify that the attached area hasn't been updated yet.

Once the changes have been taken back into the attached area, the magic number of the reference
must be cut (don't forget the comma too!). And so, the next time this attached area will be
encountered by the interpreter, it will get back the \textit{magic} number of the reference
area. And then, the \textit{reference} area and the \textit{attached} area are considered as
similar once again.

Of course, the use of these directives is quite constraining. However, it is the only way in
\CodeWorker\ to assure that features and corrections have been taken back in all generated
languages.

\index{boolean!literals}
\index{byte!literals}
\index{char!literals}
\index{cconstant tree!literals}
\index{date!literals}
\index{integer!literals}
\index{numeric!literals}
\index{string!literals}
\index{time!literals}
\index{literals!boolean}
\index{literals!byte}
\index{literals!char}
\index{literals!date}
\index{literals!integer}
\index{literals!numeric}
\index{literals!string}
\index{literals!time}
\index{true}
\index{false}
\pdfsubsection{Constant literals}
\CodeWorker\ handles all basic types as strings, and doesn't distinguish a double from a boolean or a date.
A \samp{string} literal is a sequence of characters from the source character set enclosed in double quotation marks (\textbf{" "}).
String literals are used to represent a sequence of characters which, taken together, form a null-terminated string.
The interpretation done of the data depends on the context: function \texttt{increment(index)}
expects that its argument \samp{index} contains a number, but stored as a string.
\begin{itemize}
	\item Floating-point numbers are represented as they are commonly admitted into programming languages: \textit{3.141592} or \textit{5.5E+6}.
	\item Integers are represented without the dot, \textit{64} for instance.
	\item A character literal is represented between single quotes as in C or JAVA; it admits
		classical escape characters.
	\item Bytes are represented as a couple of hexadecimal digits. The \textit{4D} byte is the
		ASCII of the letter \textit{N}.
	\item About boolean types, an empty string \samp{""} means \textit{false}, and any kind of sequence of characters means \textit{true}, such as "1" or "raspberries".
		Two constant literals are provided: keyword \samp{\textbf{true}} is worth
		\textit{"true"} and \samp{\textbf{false}} is an empty string.
	\item dates are written according to a format that looks like \textit{24sep2002}, where:
		\begin{itemize}
			\item day takes 2 digits
			\item month is represented as the 3 first letters of the corresponding english word ; \textit{aug} as \textit{august} and \textit{may} as \textit{may}, for instance
			\item year takes 4 digits: \textit{2002} but never \textit{02}.
		\end{itemize}
	\item the time representation conforms to the format:\\
		\samp{\textit{HH}\textbf{:}\textit{MM}\textbf{:}\textit{SS}\textbf{.}\textit{millis}}
\end{itemize}

A \textit{constant tree} describes a tree as a list of constant trees and expressions, intended
to be assigned to a variable. Example:\\
\texttt{local aVariable = \{"a", \{"yellow", "red"\}, "submarine"\};}

You'll find more information in the sub section \ref{Scope} below.

\pdfsubsection{Variables, declaration and assignment}
Variables serve as containers for the data you use into scripts. Data type is a tree that may
be reduced to a leaf node, which contains a value and that's all.

\index{variables!declaring}
\index{project}
\index{variables!project}
\index{this}
\index{_ARGS}
\index{_REQUEST}
\index{variables!this}
\pdfsubsubsection{Declaring variables}
It isn't necessary to declare a variable before using if for the first time. A variable that
is assigned without being declared is understood as a new sub-node to be added to the current
tree context. The current context is obtained by the read-only variable called \samp{\textbf{this}}.
It corresponds to the main parse tree whose root name is \samp{\textbf{project}} when you are into
the leader script, and to the variable passed by parameter when calling a parsing or pattern
script.

The next table exposes all pre-defined variable names (accessible from anywhere) and their meaning:

\begin{tableii}{l|l}{.8}{Variable Name}{Description}
	\lineii{\textbf{\samp{project}}}{The main parse tree, always present.}
	\lineii{\textbf{\samp{this}}}{It points to the current context variable.}
	\lineii{\textbf{\samp{_ARGS}}}{An array of all custom command-line arguments. Custom arguments are following the script file name or the switch \samp{-args} on the command-line.}
	\lineii{\textbf{\samp{_REQUEST}}}{If the interpreter works as a CGI program, it stores all parameters of the request in a association table. The key is the parameter name, which associates the corresponding value.}
\end{tableii}


A variable that is read without being declared returns an empty string, but doesn't cause the
creation of a sub-node. The danger is that you aren't safe from a spelling mistake. To prevent
it, put the option \samp{-varexist} on the command line and use the function \samp{existVariable()}
to check whether a variable exists or not.

\index{variables!scope}
\index{local}
\index{global}
\index{localref}
\index{constant tree}
\pdfsubsubsection{Scope}
When you declare a local variable, it is valid for use within a specific area of code, called
the \textit{scope}. When the flow of execution leaves the scope, the content of the variable,
a subtree specially allocated during its declaration, is deleted and disappears forever from
the stack. A scope is delimited by a \textit{block}.

To declare a variable to the stack, use the following declaration statement:\\
\samp{
	 \textit{local-variable-statement} ::= \textbf{"local"} \textit{local-variable-declaration} \textbf{';'}\\
	 \textit{local-variable-declaration} ::= \textit{variable} [ \textbf{'='} \textit{assignment-expression} ]?\\
	 \textit{assignment-expression}	::= \textit{constant-tree} | \textit{expression}
	 \textit{constant-tree}	::= \textbf{'\{'} [\textit{assignment-expression} [\textbf{','} \textit{assignment-expression}]* ]? \textbf{'\}'}
}

An extension of the syntax allows the declaration of more than one variable in one shot. A comma separates the
variable declarations:\\
\samp{
	 \textit{local-variable-statement} ::= \textbf{"local"} \textit{local-variable-declaration} [ \textbf{','} \textit{local-variable-declaration} ]* \textbf{';'}
}

The local variable points to a new empty tree, pushed into the stack.
\begin{itemize}
	\item If an expression is present after the local declaration, it is evaluated and
		the string result is assigned to the new local variable.
	\item If a constant tree is present after the local declaration, it is assigned to
		the new local variable. Example:\\
		\texttt{local aVariable = \{"a", \{"yellow", "red"\}, "submarine"\};}\\
		is equivalent to:\\
		\texttt{local aVariable;\\
				pushItem aVariable = "a";\\
				pushItem aVariable;\\
				pushItem aVariable\#back = "yellow";\\
				pushItem aVariable\#back = "red";\\
				pushItem aVariable = "submarine";
		}\\
		where \samp{pushItem} means that a new item has to be added in the array owned
		by \samp{aVariable}, and where \samp{\#last} means accessing to the last item
		of the array.
\end{itemize}

To assign a reference to another variable, instead of either the result of
evaluating an expression or a constant tree, use rather the following declaration statement:\\
\samp{
	\textit{local-ref-statement} ::= \textbf{"localref"} \textit{local-ref-declaration} [ \textbf{','} \textit{local-ref-declaration} ]* \textbf{';'}\\
	\textit{local-ref-declaration} ::= \textit{variable} \textbf{'='} \textit{reference}
}

In the case of a \CodeWorker\ version \textbf{strictly older than \samp{1.13}}, local
variables that are declared in the body of a script or in the scope of a function may
be accessed further in the scope of functions during their timelife. So a different behaviour
may occur with a more recent \CodeWorker\ interpreter.

This stack management had historical reasons, but it is now obsolete and often reflects an
implementation's error. To preserve you from this kind of mistake, a warning may be displayed,
so that scripts strictly older than version \samp{1.13} may continue to run. Specify a
version strictly older than \samp{1.13} to the command line (option \samp{-version}) for
reclaiming that \CodeWorker\ checks and generates a warning.

To correct this kind of mistake in old scripts, the variable should be propagated in an
argument for functions that refer to it.

To declare a global variable, use the \samp{global} statement. The declaration of a \textit{global}
variable can be specified anywhere in scripts. The first time the declaration of a global
variable is encountered, the interpreter registers it as accessible from any point into
scripts. The second time the interpreter encounters a global declaration for the variable,
the latter remains \textit{global} but its content is cleared.\\
Note that if a local variable or an attribute of the current node (\samp{this}) is identical
to the name of an existing \textit{global} variable, the global variable remains hidden while
the flow of control hasn't left the scope that contains the homonym.

the \samp{global} declaration statement looks like:\\
\samp{
	\textit{global-variable-statement} ::= \textbf{"global"} \textit{global-variable-declaration} [ \textbf{','} \textit{global-variable-declaration} ]* \textbf{';'}\\
	\textit{global-variable-declaration} ::= \textit{variable} [ \textbf{'='} \textit{assignment-expression} ]?
}

\index{variables!navigating}
\index{variables!resolving at runtime}
\index{\#evaluateVariable}
\pdfsubsubsection{Navigating along branches}
It is possible to navigate along a branch of the subtree put into the variable. A branch
points to a node of the subtree. The syntax looks generally like:\\
\samp{
	\textit{branch} ::= \textit{variable} [\textbf{'.'} \textit{sub-node}]*
}

If the branch isn't known before runtime, it may be build during the execution.

\textbf{Example:} while parsing an XML file, each time an XML attribute is encountered, one creates the
corresponding attribute into the parse tree. But the name of the attribute is discovered
during the parsing. The directive \samp{\#evaluateVariable(\textit{expression})} allows doing it.
\textit{expression} is evaluated at runtime and provides a branch:\\
\texttt{\#evaluateVariable("a.b.c")} will resolve the path \textit{"a.b.c"} at runtime and
navigate from \textit{a} to textit{c}.

A node may contain an array of nodes, which are indexed by a key that is a constant string.
A branch allows navigating through arrays, and the definitive syntax of branches conforms
to:\\
\samp{
	\textit{branch} ::= \textbf{"\#evaluateVariable"} \textbf{'('} \textit{expression} \textbf{')'}\\
	\makebox[3cm][r] ::= \textit{variable} [\textbf{'.'} \textit{sub-node} | \textit{array-access}]*\\
	\textit{array-access} ::= \textbf{'['} \textit{expression} \textbf{']'}\\
	\makebox[3cm][r] ::= \textbf{'\#'} [\textbf{"front"} | \textbf{"back"} | \textbf{"parent"}] | \textbf{"root"}]\\
	\makebox[3cm][r] ::= \textbf{'\#' '['} \textit{integer-expression} \textbf{']'}
}

We see that there are some ways to access an item node of an array or to change how to
navigate from nodes to nodes:
\index{array!accessing}
\index{\#back}
\index{back!array}
\index{\#front}
\index{front!array}
\index{\#parent}
\index{variable!parent}
\begin{itemize}
	\item \samp{\textit{sub-node} \textbf{'['} \textit{expression} \textbf{']'}} means that
			we'll access the node item associated to the string key resulting of the
			expression's evaluation,
	\item \samp{\textit{sub-node} \textbf{'\#'} \textbf{"front"}} means that the first item
			node of the array is required. If the array is empty, an error occurs.
	\item \samp{\textit{sub-node} \textbf{'\#'} \textbf{"back"}} means that the last item
			node of the array is required. If the array is empty, an error occurs.
	\item \samp{\textit{sub-node} \textbf{'\#'} \textbf{"parent"}} means that one comes back
			up the parent's node of \textit{sub-node}.
	\item \samp{\textit{sub-node} \textbf{'\#'} \textbf{"root"}} means that one comes back
			up the root's node of the tree \textit{sub-node} belongs to.
	\item \samp{\textit{sub-node} \textbf{'\#' '['} <integer-expression> \textbf{']'}} means
			that we'll access the node item located at the position given by the evaluation
			of the expression. The position starts counting to 0. An error is raised if the
			position is out of bounds.
\end{itemize}

\index{array!assignment}
\index{variables!assignment}
\pdfsubsubsection{Assignments}
\CodeWorker\ provides some different ways to put a data into a variable or into the node
pointed to by a branch:
\begin{itemize}
	\item \index{set} \samp{\textbf{set} \textit{variable-branch} [\textbf{'='} | \textbf{'+='}] \textit{assignment-expression}} :
			the expression is evaluated and the resulting string value is assigned to the
			variable, or concatenated if the operator \textbf{'+='} was required. Keyword
			\samp{set} may be omitted. The node to assign is supposed existing yet. If not,
			the assignment is done, but it causes a warning to prevent a spelling mistake on
			the variable's name.
	\item \index{insert} \samp{\textbf{insert} \textit{variable-branch} [[\textbf{'='} | \textbf{'+='}] \textit{assignment-expression}]?} :
			it works like the \samp{set} assignment, except that it is the preferred mode
			to add a new node when the variable doesn't exist yet. If the node already exists,
			of course it isn't added twice, and the assignment if done as expected. If no
			assignment is specified after the variable's name, nothing is assigned to the node.
			So, if the node wasn't existing yet, it contains an empty string. Otherwise,
			the ancient value isn't changed.
	\item \index{ref} \samp{\textbf{ref} \textit{variable} \textbf{'='} \textit{existing-variable-or-branch}} :
			the variable to assign will refer to an existing node. Inspecting the variable
			will cause inspecting the referenced existing node. If the referenced node doesn't
			exist, an error occurs. If you apply the reference to a variable that already
			refers a node, this link is broken instead of propagating the reference to the
			referred node. This operator is very useful during the decoration of the
			parse tree, and leads to transform the tree as a freely-oriented graph.\\
			Be careful not to keep a reference to a local variable once the flow of execution
			has left its scope: the local variable is deleted, and so, the reference points
			to a corrupted part of the memory.\\
			If you intend to assign a reference to a variable into a function and that the
			variable is passed by parameter, don't forget to take the \samp{reference} parameter
			mode:\\
			\texttt{function \textbf{badFunction}(\textit{myVar} : node) \{\\
			\makebox[0.8cm][r]{}...\\
			\makebox[0.8cm][r]{}// \textit{myVar} will keep up a reference to \textit{aNode}\\
			\makebox[0.8cm][r]{}// up to the end of the function:\\
			\makebox[0.8cm][r]{}ref myVar = aNode;\\
			\makebox[0.8cm][r]{}...\\
			\makebox[0.8cm][r]{}// \textit{myVar} is passed as \textit{variable}, so the\\
			\makebox[0.8cm][r]{}// reference is cancelled once the function is left!\\
			\}}

			\texttt{// To keep the reference after leaving the function, change the parameter
			// mode to \samp{reference}:
			function \textbf{goodFunction}(\textit{myVar} : \textbf{reference}) \{\\
			\makebox[0.8cm][r]{}...\\
			\makebox[0.8cm][r]{}// \textit{myVar} will keep up a reference to \textit{aNode}\\
			\makebox[0.8cm][r]{}// up to the end of the function:\\
			\makebox[0.8cm][r]{}ref myVar = aNode;\\
			\makebox[0.8cm][r]{}...\\
			\makebox[0.8cm][r]{}// \textit{myVar} is passed as \textit{reference}, so the\\
			\makebox[0.8cm][r]{}// reference is kept once the function is left!\\
			\}}
	\item \index{setall} \samp{\textbf{setall} \textit{variable-branch} \textbf{'='} \textit{existing-variable-or-branch}} :
			value, attributes and array of the variable to assign are purged, and the subtree,
			to which the existing variable points, is copied integrally to the node to
			assign.
	\item \index{merge} \samp{\textbf{merge} \textit{variable-branch} \textbf{'='} \textit{existing-variable-or-branch}} :
			the subtree, to which the existing variable points, is copied integrally to the
			node to assign, preserving the attributes and the arrays of the assigned node,
			which are updated or completed.
	\item \index{array!pushItem} \index{pushItem} \samp{\textbf{pushItem} \textit{variable-branch} [\textbf{'='} \textit{expression}]?} :
			a new item node is added at the end of the variable's array, whose key is worth
			its position, starting at 0. If the expression exists, then after evaluating it,
			the result is assigned to the item node as a value. If no array was previously
			existing, the item becomes its first component.
\end{itemize}

\index{binary operators}
\index{boolean!expression}
\index{numeric!expression}
\index{string!expression}
\pdfsubsection{Expressions}
\pdfsubsubsection{Presentation}
The BNF representation of an expression looks like:\\
\samp{
	\textit{expression} ::= \textit{boolean-expr} | \textit{ternary-expr}\\
	\textit{boolean-expr} ::= \textit{comparison-expr} [\textit{boolean-op} \textit{comparison-expr}]\\
	\textit{boolean-op} ::= \textbf{'\&'} | \textbf{'\&\&'} | \textbf{'|'} | \textbf{'||'} | \textbf{'$\hat{}$'} | \textbf{'$\hat{}$$\hat{}$'}\\
	\textit{ternary-expr} ::= \textit{comparison-expr} \textbf{'?'} \textit{expression} \textbf{':'} \textit{expression}\\
	\textit{comparison-expr} ::= \textit{concatenation-expr} [\textit{comparison-op} \textit{concatenation-expr} | \textbf{"in"} \textit{constant-set}]\\
	\textit{constant-set} ::= \textbf{'\{'} \textit{constant-string} [\textbf{','} \textit{constant-string}]* \textbf{'\}'}\\
	\textit{comparison-op} ::= \textbf{'<'} | \textbf{'<='} | \textbf{'=='} | \textbf{'='} | \textbf{'!='} | \textbf{'<>'} | \textbf{'>'} | \textbf{'>='}\\
	\textit{concatenation-expr} ::= \textit{stdliteral-expr} [\textbf{'+'} \textit{stdliteral-expr}]*\\
	\textit{stdliteral-expr} ::= \textit{literal-expr}\\
	\makebox[3cm][r] ::= \textbf{'\$'} \textit{arithmetic-expr} \textbf{'\$'}\\
	\textit{literal-expr} ::= \textit{constant-string} | \textit{number}\\
	\makebox[3cm][r] ::= \textbf{"true"} | \textbf{"false"}\\
	\makebox[3cm][r] ::= \textbf{'('} \textit{expression} \textbf{')'}\\
	\makebox[3cm][r] ::= \textbf{'!'} \textit{literal-expr}\\
	\makebox[3cm][r] ::= \textit{preprocessor-expr}\\
	\makebox[3cm][r] ::= \textit{function-call}\\
	\makebox[3cm][r] ::= \textit{variable-or-branch}
}

\samp{
	\textit{arithmetic-expr} ::= \textit{comparith-expr} [\textit{boolean-op} \textit{comparith-expr}]*\\
	\textit{comparith-expr} ::= \textit{sum-expr} [\textit{comparison-op} \textit{sum-expr}]\\
	\textit{sum-expr} ::= \textit{shift-expr} [[\textbf{'+'} | \textbf{'-'}] \textit{shift-expr}]*\\
	\textit{shift-expr} ::= \textit{factor-expr} [[\textbf{"<<"} | \textbf{">>"}] \textit{factor-expr}]*\\
	\textit{factor-expr} ::= \textit{literal-expr} [[\textbf{'*'} | \textbf{'/'} | \textbf{'\%'}] \textit{literal-expr}]*\\
	\makebox[3cm][r] ::= \textbf{'~'} \textit{literal-expr}\\
	\textit{preprocessor-expr} ::= \textbf{'\#'} [\textbf{"LINE"} | \textbf{"FILE"}]
}

where:
\begin{itemize}
	\item The boolean operators \samp{\&} or \samp{\&\&} resolve the logical AND.
	\item The boolean operators \samp{|} or \samp{||} resolve the logical OR.
	\item The comparison operators do the classical resolution, working on the lexicographical
			order. Note that \textit{different of} may be written \samp{!=} or \samp{<>} and
			that the equality is written\samp{=} or \samp{==}. If the comparison succeeds, it
			returns \samp{"true"}, otherwise, it returns an empty string. See section
			\ref{arithmetic expressions} to discover an escape mode for writing arithmetic
			comparisons.
	\item A special comparison operator \samp{\textbf{in}} checks whether the left-hand side
			member belongs to a set of constant strings or not.\\
			\textbf{Example:}\\
			\texttt{\textit{sHTMLTag} \textbf{in \{} 'i'\textbf{,} "kbd" \textbf{\}}}\\
			returns \samp{true} if \textit{sHTMLTag} is worth \samp{'i'} or \samp{"kbd"} and
			\samp{false} in all other cases.
	\item The operator \samp{+} serves to concatenate two string. Becareful not to use this
			operator to ask for an arithmetic addition! See the function \samp{add()} to do
			that or the section \ref{arithmetic expressions} to discover an escape mode for
			writing arithmetic operators.
	\item A constant string must be written between double quotes and escape characters
			are expected as in C, starting with a back-slash.
	\item The syntax of a number is the one admitted commonly. The number is then converted
			to a string.
	\item Constant \samp{true} is worth the constant string \samp{"true"}, and \samp{false}
			is worth the constant string \samp{"false"}.
	\item expressions with parentheses are allowed.
	\item The unary \samp{!} operator resolves the logical NOT, such as an empty value gives
			\samp{"true"} and any kind of other value gives an empty string.
	\item Function calls are described into the section \ref{function}.
	\item The escape mode for arithmetic expression is set/unset via the \textbf{'\$'} symbols
			and allows interpreting arithmetic/comparison operators as usual (\samp{'+'} as an
			addition, \samp{'<'} as a numerical comparison). See section
			\ref{arithmetic expressions} for more information about this escape mode.
	\item some arithmetic operators enable to handles bits: the unary bitwise operator
			\textbf{\samp{\~{}}} and the shift operators \textbf{\samp{<<}} (left shifting)
			and \textbf{\samp{>>}} (right shifting).
	\item The preprocessor expressions give information about the source script:
		\begin{itemize}
			\item \index{\#FILE} \samp{\textbf{\#FILE}}: returns the file name of the script, or an empty
				string if the source script wasn't coming from a file,
			\item \index{\#LINE} \samp{\textbf{\#LINE}}: returns the line number where the directive is
				located into the source script,
		\end{itemize}
\end{itemize}

\index{\$}
\index{arithmetic expressions}
\pdflabel{arithmetic expressions}
\pdfsubsubsection{Arithmetic expressions}
The classical syntax of the interpreter forces expressions to work on sequences of characters.
So, comparison operators apply the lexicographical order and the \samp{'+'} operator concatenates
two strings and the \samp{'*'} operator doesn't exist.

Of course, it exists some functions to handle strings as number and to execute an arithmetic
operation (the \samp{'add()'} or \samp{'mult()'} functions for instance) or a comparison (the
\samp{'isPositive()'} or \samp{'inf()'} functions for instance).

However, it appears clearly more convenient to write arithmetic operations and comparisons in a
natural way, using operators instead of the corresponding functions. So, \CodeWorker\ provides
an escape mode that draws its inspiration from \textit{LaTeX} to express mathematical formulas:
the arithmetic expression are delimited by the symbol \textbf{'\$'}.

\textbf{Example:}
%##markup##"execute:local a = 11;\nlocal b = 7;\ntraceLine(\"Classical mode = '\"\n\t+ inf(add(mult(5, a), 3), sub(mult(a, a), mult(b, b))) + \"'\");\ntraceLine(\"Escape mode = '\" + $5*a + 3 < a*a - b*b$ + \"'\");"
%##begin##"execute:local a = 11;\nlocal b = 7;\ntraceLine(\"Classical mode = '\"\n\t+ inf(add(mult(5, a), 3), sub(mult(a, a), mult(b, b))) + \"'\");\ntraceLine(\"Escape mode = '\" + $5*a + 3 < a*a - b*b$ + \"'\");"
\begin{verbatim}
local a = 11;
local b = 7;
traceLine("Classical mode = '"
	+ inf(add(mult(5, a), 3), sub(mult(a, a), mult(b, b))) + "'");
traceLine("Escape mode = '" + $5*a + 3 < a*a - b*b$ + "'");
\end{verbatim}
\textbf{Output:}

\texttt{Classical mode = 'true'\\
Escape mode = 'true'}

%##end##"execute:local a = 11;\nlocal b = 7;\ntraceLine(\"Classical mode = '\"\n\t+ inf(add(mult(5, a), 3), sub(mult(a, a), mult(b, b))) + \"'\");\ntraceLine(\"Escape mode = '\" + $5*a + 3 < a*a - b*b$ + \"'\");"


\index{statements}
\pdfsubsection{Common statements}

\pdflabel{if}
\index{if}
\pdfsubsubsection{The 'if' statement}
The BNF representation of the \samp{while} statement is:\\
\samp{
	\textit{if-statement} ::= \textbf{"if"} \textit{expression} \textit{then-statement}
								[\textbf{"else"} \textit{else-statement}]?
}

The \samp{if} statement evaluates the expression following immediately. The expression
must be of arithmetic, text, variable or condition type. In both forms of the \samp{if}
syntax, if the expression evaluates to a nonempty string, the statement dependent on the
evaluation is executed; otherwise, it is skipped.

In the \samp{if...else} syntax, the second statement is executed if the result of evaluating
the expression is an empty string. The \samp{else} clause of an \samp{if...else} statement is
associated with the closest previous \samp{if} statement that does not have a corresponding
\samp{else} statement.


\pdflabel{while}
\index{while}
\pdflabel{do}
\index{do}
\index{break}
\index{continue}
\pdfsubsubsection{The 'while'/'do' statements}
The BNF representation of the \samp{while} statement is:\\
\samp{
	\textit{while_statement} ::= \textbf{"while"} \textit{expression} \textit{statement}
}

The \samp{while} statement lets you repeat a statement or compound
statement as long as a specified \textit{expression} becomes an empty
string. The \samp{expression} in a \samp{while} statement is evaluated before
the body of the loop is executed. Therefore, the body of the loop
may be never executed. If \samp{expression} returns an empty string,
the \samp{while} statement terminates and control passes to the next
statement in the program. If \samp{expression} is non-empty, the process
is repeated. The \samp{while} statement can also terminate when a
\samp{\textbf{break}}, or \samp{return} statement is executed within the statement
body. When a \samp{\textbf{continue}} statement is encountered, the control breaks
the flow and jumps to the evaluation of the \samp{expression}.

Note that the \samp{\textbf{break}} and \samp{\textbf{continue}} statements apply to
the first loop statement (\samp{foreach}/\samp{forfile}/\samp{select}, \samp{do}/\samp{while}) they encounter
while leaving instruction blocks.

The BNF representation of the \samp{do} statement is:\\
\samp{
	\textit{do_statement} ::= \textbf{"do"} \textit{statement} \textbf{"while"} \textit{expression} \textbf{';'}
}

The \samp{do-while} statement lets you repeat a statement or compound
statement until a specified \samp{expression} becomes an empty string. The
\textit{expression} in a \samp{do-while} statement is evaluated after the body of the
loop is executed. Therefore, the body of the loop is always executed at
least once. If \textit{expression} returns an empty string, the \samp{do-while}
statement terminates and control passes to the next statement in the
program. If \textit{expression} is non-empty, the process is repeated.
The \samp{do-while} statement can also terminate when a \samp{break}, or \samp{return}
statement is executed within the statement body. When a \samp{continue}
statement is encountered, control is transferred to the evaluation of
the \textit{expression}.


\pdflabel{switch}
\index{switch}
\index{case}
\index{start}
\index{default}
\pdfsubsubsection{The 'switch' statement}

The BNF representation of this statement is:\\
\samp{
	\textit{switch_statement} ::= \textbf{"switch" '('} \textit{expression} \textbf{')' '\{'} (\textit{label_declaration})* (\textbf{"default" ':'} \textit{statement})? \textbf{'\}'}\\
	\textit{label_declaration} ::= [\textbf{"case"} | \textbf{"start"}] \textit{constant_string} \textbf{':'} \textit{statement}
}

The \samp{switch} statement allows selection among multiple sections of
code, depending on the value of an expression. The expression enclosed
in parentheses, the controlling expression, must be of string type.

The \samp{switch} statement causes an unconditional jump to, into, or past
the statement that is the switch body, depending on the value of the
controlling expression, the constant string values of the \samp{case} or \samp{start} labels,
and the presence or absence of a \samp{default} label. The switch body is
normally a compound statement (although this is not a syntactic
requirement). Usually, some of the statements in the \samp{switch} body are
labeled with \samp{case} labels or with \samp{start} labels or with the \samp{default}
label. The default label can appear only once.

The constant-string in the \samp{case} label is compared for equality with the controlling 
expression. The constant-string in the \samp{start} label is compared for equality with the
first characters of the controlling expression. In a given \samp{switch} statement, no two
constant strings in \samp{start} or \samp{case} statements can evaluate to the same value.

The \samp{switch} statement behaviour depends on how the controlling
expression matches with labels. If a \samp{case} label exactly matches with
the controlling expression, control is transferred to the statement
following that label. If failed, \samp{start} labels are iterated into the
lexicographical order, and the control is transferred to the statement
following the first label that matches with the beginning of the controlling expression.
If failed, control is transferred to the \samp{default} statement or, if not present,
an error is thrown.

A \samp{switch} statement can be nested. In such cases, \samp{case} or \samp{start} or
\samp{default} labels associate with the most deeply nested \samp{switch}
statements that enclose them.

Control is not impeded by \samp{case} or \samp{start} or \samp{default} labels. To
stop execution at the end of a part of the compound statement, insert a
\samp{break} statement. This transfers control to the statement after the
\samp{switch} statement.


\pdflabel{foreach}
\index{foreach}
\pdfsubsubsection{The 'foreach' statement}
The BNF representation of this statement is:\\
\samp{
    \textit{foreach_statement} ::= \textbf{"foreach"} \textit{iterator} \textbf{"in"} [\textit{direction}]?\\
	\makebox[3cm][r]{} [\textit{sorted_declaration}]? [\textit{cascading_declaration}]? \textit{list-node} \textit{body_statement}\\
	\textit{direction} ::= \textbf{"reverse"}\\
	\textit{sorted_declaration} ::= \textbf{"sorted"} [\textbf{"no_case"}]? [\textbf{"by_value"}]?\\
	\textit{cascading_declaration} ::= \textbf{"cascading"} [\textbf{"first"} | \textbf{"last"}]?
}

A \textit{foreach} statement iterates all items of the list owned by node \textit{list-node}.
The \textit{iterator} refers to the current item of the list, and the body statement is executed
on it.

Items are iterated either in the order of entrance, or in alphabetical order if
option \samp{sorted} is set. The sort operates on keys, except if the option \samp{by\_value} is set.
The order is inverted if option \samp{reverse} was chosen.
To ignore the case, these options must be followed by \samp{no_case}.
If not, uppercase letters are considered as smaller than any lowercase letter.
%##markup##"execute_file:Documentation/ForeachSampleSorted.cws"
%##begin##"execute_file:Documentation/ForeachSampleSorted.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/ForeachSampleSorted.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} local list;\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert list["silverware"] = "tea spoon";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert list["Mountain"] = "Everest";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert list["SilverWare"] = "Tea Spoon";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert list["Boat"] = "Titanic";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert list["acrobat"] = "Circus";\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("Sorted list in a classical order:");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{foreach i in sorted list \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("$\backslash$t" + key(i));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("Note that uppercases are listed before lowercases." + endl());\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("Sorted list where the case is ignored:");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{foreach i in sorted no\_case list \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("$\backslash$t" + key(i));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("Reverse sorted list:");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{foreach i in reverse sorted list \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("$\backslash$t" + key(i));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} traceLine("Reverse sorted list where the case is ignored:");\\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{foreach i in reverse sorted no\_case list \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("$\backslash$t" + key(i));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}



\textbf{Output:}

\texttt{Sorted list in a classical order:\\
\makebox[0.8cm][l]{}Boat\\
\makebox[0.8cm][l]{}Mountain\\
\makebox[0.8cm][l]{}SilverWare\\
\makebox[0.8cm][l]{}acrobat\\
\makebox[0.8cm][l]{}silverware\\
Note that uppercases are listed before lowercases.\\
\\
Sorted list where the case is ignored:\\
\makebox[0.8cm][l]{}acrobat\\
\makebox[0.8cm][l]{}Boat\\
\makebox[0.8cm][l]{}Mountain\\
\makebox[0.8cm][l]{}SilverWare\\
\makebox[0.8cm][l]{}silverware\\
Reverse sorted list:\\
\makebox[0.8cm][l]{}silverware\\
\makebox[0.8cm][l]{}acrobat\\
\makebox[0.8cm][l]{}SilverWare\\
\makebox[0.8cm][l]{}Mountain\\
\makebox[0.8cm][l]{}Boat\\
Reverse sorted list where the case is ignored:\\
\makebox[0.8cm][l]{}silverware\\
\makebox[0.8cm][l]{}SilverWare\\
\makebox[0.8cm][l]{}Mountain\\
\makebox[0.8cm][l]{}Boat\\
\makebox[0.8cm][l]{}acrobat}
%##end##"execute_file:Documentation/ForeachSampleSorted.cws"

Control may not be sequential into the body statement. \samp{break} and \samp{return} enable
exiting definitely the loop, and \samp{continue} transfers the control to the head of the
\samp{foreach} statement for the next iteration.

Option \samp{cascading} allows propagating \samp{foreach} on item nodes. The way
it works is illustrated by an example:
\begin{alltt}
	foreach i in cascading myObjectModeling.packages ...
\end{alltt}
At the beginning, \samp{i} points to \samp{myObjectModeling.packages\#front} and
the body is executed. Before iterating i to the next item, the \samp{foreach} checks whether
the item node \samp{myObjectModeling.packages\#front} owns attribute \samp{packages} or not.
If yes, it applies recursively \samp{foreach} on \samp{myObjectModeling.packages\#front.packages}.

Option \samp{cascading} avoids writing the following code:
\begin{alltt}
function propagateOnPackages(myPackage : node) {
	foreach i in myPackage {
		// my code to apply on this package
		if existVariable(myPackages.packages)
			propagateOnPackages(myPackages.packages);
	}
}
propagateOnPackages(myObjectModeling.packages);
\end{alltt}
Option \samp{cascading} offers two behaviours:
\begin{itemize}
	\item \samp{first} means that the item is cascaded before running the body,
%##markup##"execute_file:Documentation/ForeachSampleFirst.cws"
%##begin##"execute_file:Documentation/ForeachSampleFirst.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/ForeachSampleFirst.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} local myObjectModeling;\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myObjectModeling.packages["Massif"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} local myPackage;\\
	\makebox[1cm][r]{\textrm{\tiny     }} ref myPackage = myObjectModeling.packages["Massif"];\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Alps"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Himalaya"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Rock Mountains"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myObjectModeling.packages["Silverware"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} ref myPackage = myObjectModeling.packages["Silverware"];\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Spoon"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Fork"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Knife"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{foreach i in cascading first myObjectModeling.packages \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("$\backslash$t" + key(i));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}



\textbf{Output:}

\texttt{\makebox[0.8cm][l]{}Alps\\
\makebox[0.8cm][l]{}Himalaya\\
\makebox[0.8cm][l]{}Rock Mountains\\
\makebox[0.8cm][l]{}Massif\\
\makebox[0.8cm][l]{}Spoon\\
\makebox[0.8cm][l]{}Fork\\
\makebox[0.8cm][l]{}Knife\\
\makebox[0.8cm][l]{}Silverware}
%##end##"execute_file:Documentation/ForeachSampleFirst.cws"
	\item \samp{last} is the default behaviour, as seen in previous examples, and
%##markup##"execute_file:Documentation/ForeachSampleLast.cws"
%##begin##"execute_file:Documentation/ForeachSampleLast.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/ForeachSampleLast.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} local myObjectModeling;\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myObjectModeling.packages["Massif"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} local myPackage;\\
	\makebox[1cm][r]{\textrm{\tiny     }} ref myPackage = myObjectModeling.packages["Massif"];\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Alps"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Himalaya"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Rock Mountains"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myObjectModeling.packages["Silverware"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} ref myPackage = myObjectModeling.packages["Silverware"];\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Spoon"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Fork"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert myPackage.packages["Knife"] = "...";\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{foreach i in cascading last myObjectModeling.packages \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("$\backslash$t" + key(i));\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}



\textbf{Output:}

\texttt{\makebox[0.8cm][l]{}Massif\\
\makebox[0.8cm][l]{}Alps\\
\makebox[0.8cm][l]{}Himalaya\\
\makebox[0.8cm][l]{}Rock Mountains\\
\makebox[0.8cm][l]{}Silverware\\
\makebox[0.8cm][l]{}Spoon\\
\makebox[0.8cm][l]{}Fork\\
\makebox[0.8cm][l]{}Knife}
%##end##"execute_file:Documentation/ForeachSampleLast.cws"
propagates the \samp{foreach} on the current item after executing the body.
\end{itemize}

\pdflabel{forfile}
\index{forfile}
\pdfsubsubsection{The 'forfile' statement}
The BNF representation of this statement is:\\
\samp{
    \textit{forfile_statement} ::= \textbf{"forfile"} \textit{iterator} \textbf{"in"} [\textit{sorted_declaration}]? [\textit{cascading_declaration}]? \textit{file-pattern} \textit{body_statement}\\
	\textit{sorted_declaration} ::= \textbf{"sorted"} [\textbf{"no_case"}]?\\
	\textit{cascading_declaration} ::= \textbf{"cascading"} [\textbf{"first"} | \textbf{"last"}]?
}

A \textit{forfile} statement iterates the name of all files that verify the filter \textit{file-pattern}.
The \textit{iterator} refers to the current item of the list composed of retained file names, and the body statement is executed
on it. Note that the file pattern may begin with a path, which cannot contain jocker characters (\samp{'*'} and \samp{'?'}).

Like for the \samp{foreach} statement, items are iterated either in the order of entrance, or in alphabetical order of keys if
option \samp{sorted} is set. To ignore the case, the option must be followed by \samp{no_case}.
If not, uppercase letters are considered as smaller than any lowercase letter.

Control may not be sequential into the body statement. \samp{break} and \samp{return} enable
exiting definitely the loop, and \samp{continue} transfers the control to the head of the
\samp{forfile} statement for the next iteration.

The option \samp{cascading} allows propagating \samp{forfile} on directories recursively.
The way it works is illustrated by an example:
%##markup##"execute_file:Documentation/ForfileSample.cws"
%##begin##"execute_file:Documentation/ForfileSample.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/ForfileSample.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} local iIndex = 0;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \textbf{forfile i in cascading "*.html" \{}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}if    \$findString(i, "manual\_") < 0\$ \&\&\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.6cm][l]{}\$findString(i, "Bugs") < 0\$ \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[2.4cm][l]{}traceLine(i);\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// if too long, stop the iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}if \$iIndex > 15\$ break;\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}increment(iIndex);\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}



\textbf{Output:}

\texttt{cs/DOTNET.html\\
cs/tests/data/MatchingTest/example.csv.html\\
Documentation/LastChanges.html\\
java/JAVAAPI.html\\
java/data/MatchingTest/example.csv.html\\
Scripts/Tutorial/GettingStarted/defaultDocumentation.html\\
WebSite/AllDownloads.html\\
WebSite/examples/basicInformation.html\\
WebSite/highlighting/basicInformation.html\\
WebSite/repository/highlighting.html\\
WebSite/repository/JEdit/Entity.java.cwt.html\\
WebSite/serewin/ExempleIllustre.html\\
WebSite/tutorials/DesignSpecificModeling/tutorial.html\\
WebSite/tutorials/DesignSpecificModeling/highlighting/demo.cws.html\\
WebSite/tutorials/overview/tinyDSL\_spec.html\\
WebSite/tutorials/overview/scripts2HTML/CodeWorker\_grammar.html}
%##end##"execute_file:Documentation/ForfileSample.cws"

At the beginning, \samp{i} points to the first HTML file of the current directory and
the body is executed. Before iterating i to the next item, the \samp{forfile} checks whether
the directory of the current file owns subfolders or not. If yes, it applies recursively
\samp{forfile} on subfolders.

Option \samp{cascading} offers two behaviours:
\begin{itemize}
	\item \samp{first} means that the subfolders are visited before running the body,
	\item \samp{last} is the default behaviour, as seen in previous examples, and
		propagates the \samp{forfile} on the subfolder after executing the body.
\end{itemize}

\pdflabel{select}
\index{select}
\pdfsubsubsection{The 'select' statement}
The BNF representation of this statement is:\\
\samp{
    \textit{select_statement} ::= \textbf{"select"} \textit{iterator} \textbf{"in"} [\textit{sorted_declaration}]? \textit{node-motif} \textit{body_statement}\\
	\textit{sorted_declaration} ::= \textbf{"sorted"} \textit{first-key} [, \textit{other-key}]*\\
	\textit{first-key} ::= \textit{branch}\\
	\textit{other-key} ::= \textit{branch}
}

A \textit{select} statement iterates a list of nodes that match a motif expression.
The \textit{iterator} refers to the current item of the list composed of retained nodes, and the body statement is executed
on it.

%##markup##"execute_file:Documentation/SelectSample.cws"
%##begin##"execute_file:Documentation/SelectSample.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/SelectSample.cws":\\
	\makebox[1cm][r]{\textrm{\tiny     }} local a;\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b;\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "01";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "02";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "03";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b;\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "11";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "12";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "13";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b;\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "21";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "22";\\
	\makebox[1cm][r]{\textrm{\tiny     }} pushItem a.b\#back.c = "23";\\
	\makebox[1cm][r]{\textrm{\tiny     }} select i in a.b[].c[] \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceLine("i = "+ i);\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}



\textbf{Output:}

\texttt{i = 01\\
i = 02\\
i = 03\\
i = 11\\
i = 12\\
i = 13\\
i = 21\\
i = 22\\
i = 23}
%##end##"execute_file:Documentation/SelectSample.cws"

Like for the \samp{foreach} statement, items are iterated either in the order of entrance, or
according to the sorting result if the option \samp{sorted} is set.

Control may not be sequential into the body statement. \samp{break} and \samp{return} enable
exiting definitely the loop, and \samp{continue} transfers the control to the head of the
\samp{select} statement for the next iteration.

\pdflabel{try}
\pdflabel{catch}
\index{try}
\index{catch}
\pdfsubsubsection{The 'try'/'catch' statement}
The BNF representation of this statement is:\\
\samp{
	\textit{try-catch-statement} ::= \textbf{"try"} \textit{try-statement}
				\textbf{"catch" '('}\textit{error_message_variable}\textbf{')'}
				\textit{catch-statement}
}

Error handling is implemented by using the \samp{try}, \samp{catch}, and \samp{error}
keyword. With error handling, your program can communicate unexpected events to a higher
execution context that is better able to recover from such abnormal events.
These errors are handled by code that is outside the normal flow of control.

The compound statement after the \samp{try} clause is the guarded section of code. An error
is thrown (or raised) when command \samp{error(}\textit{message-text}\samp{)} is called or
when \CodeWorker\ encounters an internal error. The compound statement after the \samp{catch}
clause is the error handler, and catches (handles) the error thrown. The \samp{catch} clause
statement indicates the name of the variable that must receive the error message.

\pdflabel{exit}
\index{exit}
\pdfsubsubsection{The 'exit' statement}
The BNF representation of this statement is:\\
\samp{
    \textit{exit_statement} ::= \textbf{"exit"} \textit{integer-expression} \textbf{";"}
}

A \textit{exit} statement leaves the application and returns an error code, given by the \textit{integer-expression}.

Example:\\
\texttt{exit -1;}

\index{function}
\pdflabel{function}
\pdfsubsection{User-defined functions}
The BNF representation of a user-defined function to implement is:\\
\samp{
	\textit{user-function} ::= \textit{classical-function-definition} | \textit{template-function-definition}\\
	\textit{classical-function-definition} ::= \textit{classical-function-prototype} \textit{compound-statement}\\
	\textit{classical-function-prototype} ::= \textbf{"function"} \textit{function-name} \textbf{'('} \textit{parameters} \textbf{')'}\\
	\textit{template-function-definition} ::= see the next section, \ref{template function}, for more information\\
	\textit{parameters} ::= \textit{parameter} [\textbf{','} \textit{parameter}]*\\
	\textit{parameter} ::= \textit{argument} [\textbf{':'} \textit{parameter-mode} [\textbf{':'} \textit{default-value}]? ]?\\
	\textit{parameter-mode} ::= \textbf{"value"} | \textbf{"node"} | \textbf{"reference"} | \textbf{"index"}\\
	\textit{default-value} ::= \textbf{"project"} | \textbf{"this"} | \textbf{"null"} | \textbf{"true"} | \textbf{"false"} | \textit{constant-string}
}

The scripting language allows the user implementing its own functions. Parameters may be passed
to the body of the function. A value may be returned by the function and, if so, the return
type is necessary a sequence of characters. Of course, functions manage their own stack, and
so, accept recursive calls.

An argument may have a default value if the parameter is missing in a call. All following arguments
must then have default values too. A \textbf{node} argument can't have a constant string as a default
argument, but it can be worth a global variable.

\index{value}
\index{reference}
\index{iterator}
\index{node}
\index{return}
\index{function!parameters}
\pdfsubsubsection{Parameters and return value}

Arguments passed by parameter must be chosen among the following modes:
\begin{itemize}
	\item \samp{value}: if the mode of argument is omitted, this is the default mode ; it
			requires a sequence of characters (a value of node, a constant string or the
			result of a expression),
	\item \samp{node}: a node is passed and it may be changed or inspected in the body.
			The scope of a reference assignment is limited to the scope of the function: once
			the function is left, the variable receives the value of the referenced node. It
			is explained by the fact that the parameter is a new local variable, which refers
			to the node passed as argument. So, a reference assignment is applied on the
			local variable only.
	\item \samp{iterator}: the iterator of a \samp{foreach} statement is expected, for applying
			iterator functions on the argument (\textit{first()} for instance). Not really
			useful and \samp{node} is now sufficient.
	\item \samp{reference}: a node is passed and it may be changed or expected in the body.
			On the contrary of \samp{variable} mode, a reference assignment is propagated
			outside the scope of the function.
\end{itemize}

If you have omitted to return a value from a function, it returns an empty string ; in that
case, you expects to call this function as a procedure and the result isn't exploited. The
special procedure \samp{nop} takes a function call as parameter and allows executing the
function and ignoring the result. It isn't compulsory to use \samp{nop} for calling a function
as a procedure. As in C or C++, you can type the function call followed by a semi-colon and
the result is lost.

It exists two possibilities for returning a value:
\begin{itemize}
	\item to populate an internal local variable whose name is the same as the function name,
	\item to use the \samp{return} statement, followed by the expression to evaluate,
\end{itemize}

If you wish to execute a particular process in any case before leaving a function and:
\begin{itemize}
	\item it exists more than one controlling sequence to leave,
	\item some errors may be raised,
\end{itemize}

\index{finally}
\pdfsubsubsection{The 'finally' statement}

the statement \samp{finally} warrants you that the block of instructions that follows the
keyword will be systematically executed before leaving. This declaration may be placed
anywhere into the body of the function. Its syntax conforms to:\\
\samp{
	\textit{finally-statement} ::= \textbf{"finally"} \textit{compound-statement}
}

\textbf{Example:}
%##markup##"execute_file:Documentation/FinallySample.cws"
%##begin##"execute_file:Documentation/FinallySample.cws"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/FinallySample.cws":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} function f(v : value) \{\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \makebox[0.8cm][l]{}traceLine("BEGIN f(v)");\\
	\makebox[1cm][r]{\textrm{\tiny    3}} \makebox[0.8cm][l]{}finally \{\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \makebox[1.6cm][l]{}traceLine("END f(v)");\\
	\makebox[1cm][r]{\textrm{\tiny    5}} \makebox[0.8cm][l]{}\}\\
	\makebox[1cm][r]{\textrm{\tiny    6}} \makebox[0.8cm][l]{}// the body of the function, with more than\\
	\makebox[1cm][r]{\textrm{\tiny    7}} \makebox[0.8cm][l]{}// one way to exit the function, for example:\\
	\makebox[1cm][r]{\textrm{\tiny    8}} \makebox[0.8cm][l]{}if !v return "empty";\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \makebox[0.8cm][l]{}if v == "1" return "first";\\
	\makebox[1cm][r]{\textrm{\tiny   10}} \makebox[0.8cm][l]{}if v == "2" return "second";\\
	\makebox[1cm][r]{\textrm{\tiny   11}} \makebox[0.8cm][l]{}if v == "3" return "third";\\
	\makebox[1cm][r]{\textrm{\tiny   12}} \makebox[0.8cm][l]{}return "other";\\
	\makebox[1cm][r]{\textrm{\tiny   13}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \\
	\makebox[1cm][r]{\textrm{\tiny   15}} traceLine("...f(1) has been executed and returned '" + f(1) + "'");}


\textsc{line 3:}  the \samp{finally} statement is put anywhere in the body,\\
\textsc{line 4:}  this statement will be executed while exiting the function, even if an exception was
 raised,\\


\textbf{Output:}

\texttt{BEGIN f(v)\\
END f(v)\\
...f(1) has been executed and returned 'first'}
%##end##"execute_file:Documentation/FinallySample.cws"

\index{external}
\index{declare}
\pdfsubsubsection{Unusual function declarations}

It may arrive that a function prototype must be declared before being implemented, because of
a cross-reference with another function for instance. The scripting language offers the forward
declaration to answer this need. To do that, the prototype of the function is written,
preceded by the \samp{declare} keyword:\\
\samp{
	\textit{forward-declaration} ::= \textbf{"declare"} \textit{function-prototype} \textbf{';'}
}

If the body of the function must be implemented in another library and into C++ for example,
the prototype of the function is preceded by the \samp{external} keyword (see section \ref{C++ binding}):\\
\samp{
	\textit{external-declaration} ::= \textbf{"external"} \textit{function-prototype} \textbf{';'}
}

\pdflabel{template function}
\index{template function}
\pdfsubsubsection{Template functions}
\CodeWorker\ proposes a special category of functions called \textit{template functions}.
Because of \CodeWorker\ doesn't provide a typed scripting language, \textit{template} hasn't to
be understood as it is commonly exploited in C++ for instance.

A \textit{template function} represents a set of functions with the
same prototype, except the \textit{dispatching constant}. The \textit{dispatching constant}
is a constant string that extends that name of the function. These functions
\textit{instantiate} the \textit{template function} for a particular \textit{dispatching
constant}. Each instantiated function implements its own body.

The BNF representation of a template function to implement is:\\
\samp{
	\textit{template-function-definition} ::= \textit{instantiated-function-definition} | \textit{generic-function-definition}\\
	\textit{instantiated-function-definition} ::= \textit{instantiated-function-prototype} \textit{compound-statement}\\
	\textit{instantiated-function-prototype} ::= \textbf{"function"} \textit{function-name} \textbf{'<'} \textit{dispatching-constant} \textbf{'>' '('} \textit{parameters} \textbf{')'}\\
	\textit{dispatching-constant} ::= a constant string between double quotes\\
	\textit{generic-function-definition} ::= \textit{generic-function-prototype} [\textit{compound-statement} | \textit{template-based-body}]\\
	\textit{generic-function-prototype} ::= \textbf{"function"} \textit{function-name} \textbf{'<'} \textit{generic-key} \textbf{'>' '('} \textit{parameters} \textbf{')'}\\
	\textit{generic-key} ::= an identifier that matches any dispatching constant with no attached prototype\\
	\textit{template-based-body} ::= \textbf{"\{\{"} \textit{template-based-script} \textbf{"\}\}"}\\
	\textit{template-based-script} ::= a piece of \textit{template-based} script describing the generic implementation
}

A call to a \textit{template function} requires to provide a \textit{dispatching expression}
to determine the \textit{dispatching constant}. The \textit{dispatching expression} will be
evaluated during the execution and \CodeWorker\ will resolve what \textit{instantiated
function} of this template to call: the result of the \textit{dispatching expression} must
match with the \textit{dispatching constant} of the \textit{instantiated function}.
The BNF representation of a call to a template function is:\\
\samp{
	\textit{instantiated-function-call} ::= \textit{function-name} \textbf{'<'} \textit{dispatching-expression} \textbf{'>' '('} \textit{parameters} \textbf{')'}\\
	\textit{parameters} ::= \textit{expression} [\textbf{','} \textit{expression}]*
}

Note that a \textit{dispatching constant} may be empty and such an instantiated function
can be called as a classical function. In fact, classical functions are considered as
\textit{instantiated functions} where the \textit{dispatching constant} is empty.

\textit{template functions} bring generic programming in the language:
let imagine that we need function \samp{getType(myType : node)}, to decline for every
language we could have to generate (C++, Java, ...).
Normally, you'll write the following lines to recover the type depending on the
language for which you are producing the source code:
\begin{verbatim}
if doc_language == "C++" {
	sType = getCppType(myParameterType);
} else if doc_language == "JAVA" {
	sType = getJAVAType(myParameterType);
} else {
	error("unrecognized language '" + doc_language + "'");
}
\end{verbatim}
Thanks to the template functions, you may replace the precedent lines by the next one:
\begin{verbatim}
sType = getType<doc_language>(myParameterType);
\end{verbatim}
with:
\begin{verbatim}
function getType<"JAVA">(myType : node) {
	... // implementation for returning a Java type
}

function getType<"C++">(myType : node) {
	... // implementation for returning a C++ type
}
\end{verbatim}
During the execution, the function \samp{getType<\textbf{T}>(myType : node)} resolves
on what instantiated function it has to dispatch: either \samp{getType<\textbf{"JAVA"}>(myType : node)}
or \samp{getType<\textbf{"C++"}>(myType : node)}, depending on what value is assigned to
variable \textit{doc_language}.

Trying to call an instantiated function that doesn't exist, raises an error at runtime.
However, one might imagine an implementation by default. For instance:
\begin{verbatim}
function getType<T>(myType : node) {
	... // common implementation for any unrecognized language
}
\end{verbatim}

For those that know generic programming with C++ templates, here is a classical example of
using template functions:
%%##markup##"execute:function f<1>() { return 1; }\nfunction f<N>() { return $N*f<$N - 1$>()$; }\nlocal f10 = f<10>();\nif $f10 != 3628800$ error(\"10! should be worth 3628800\");\ntraceLine(\"10! = \" + f10);"
%##begin##"execute:function f<1>() { return 1; }\nfunction f<N>() { return $N*f<$N - 1$>()$; }\nlocal f10 = f<10>();\nif $f10 != 3628800$ error(\"10! should be worth 3628800\");\ntraceLine(\"10! = \" + f10);"
\begin{verbatim}
function f<1>() { return 1; }
function f<N>() { return $N*f<$N - 1$>()$; }
local f10 = f<10>();
if $f10 != 3628800$ error("10! should be worth 3628800");
traceLine("10! = " + f10);
\end{verbatim}
\textbf{Output:}

\texttt{10! = 3628800}

%##end##"execute:function f<1>() { return 1; }\nfunction f<N>() { return $N*f<$N - 1$>()$; }\nlocal f10 = f<10>();\nif $f10 != 3628800$ error(\"10! should be worth 3628800\");\ntraceLine(\"10! = \" + f10);"

To provide more flexibility in the implementation of the template function, depending on
the generic key \textbf{<T>}, the body admits a \textit{template-based} script to implement
the source code of the function.
The specialization of the function for a given template instantiation key is then resolved at runtime.

\textbf{Example:}\\
The template function \samp{f} inserts a new attribute in a tree node. The attribute has the name passed
to the generic key for instantiation, and the value of the instantiation key is assigned to the new attribute.
Then, the function calls itself recursively on the instantiation key without the last character.\\

For instance, the source code of \samp{f<"field">} should be:\\
\texttt{function f<"\textbf{field}">(x : node) \{\\
\makebox[1cm][r]{} insert x.\textbf{field} = "\textbf{field}";\\
\makebox[1cm][r]{} f<"\textit{fiel}">(x); // cut the last character\\
\}
}

\textbf{Code:}\\
\texttt{//a synonym of \textit{f<"">(x : node)}, terminal condition for recusive calls\\
function f(x : node) \{/*does nothing*/\}
\\
function f<T>(x : node) \{\{\\
\makebox[1cm][r]{} // \textbf{'\{\{'} announces a \textit{template-based} script, which\\
\makebox[1cm][r]{} // will generate the correct implementation during the instantiation\\
\makebox[1cm][r]{} \textbf{insert x.@}\textit{T}\textbf{@ = "@}\textit{T}\textbf{@";}\\
\makebox[1cm][r]{} \textbf{f<"@}\textit{T.rsubString(1)}\textbf{@">(x);}\\
\textbf{@}\\
\makebox[1cm][r]{} // \textbf{'\}\}'} announces the end of the \textit{template-based} script\\
\}\}
\\
f<"field">(project);\\
traceObject(project);
}

\textbf{Output:}\\
\texttt{Tracing variable 'project':\\
\makebox[1cm][r]{} field = "field"\\
\makebox[1cm][r]{} fiel = "fiel"\\
\makebox[1cm][r]{} fie = "fie"\\
\makebox[1cm][r]{} fi = "fi"\\
\makebox[1cm][r]{} f = "f"\\
End of variable's trace 'project'.}

\index{method}
\pdflabel{method}
\pdfsubsubsection{Methods}

For more readability, syntactical facilities are offered to call functions on a node as if
this function was a method of the node. For example, it is possible to call function
\samp{leftString} on the node \samp{\textit{a}} like this:
\samp{\textit{a}.leftString(2)}, instead of the classical functional form:
\samp{leftString(\textit{a}, 2)}.

The rule is that every function (user-defined included) whose first argument is passed either
by \samp{value} or by \samp{node} or by \samp{index} (but never by \samp{reference}) can
propose a method call.

In that case, the method call applies on the first argument, which has to be a node.
The BNF representation of a method call is:\\
\samp{
	\textit{method-call} ::= \textit{variable} \textbf{'.'} \textit{function-name} \textbf{'('} \textit{parameters} \textbf{')'}\\
	\textit{parameters} ::= \textit{expression} [\textbf{','} \textit{expression}]*\\
}
where \samp{parameters} have missed the first argument of the function called \textit{function-name}.

It exists some exceptions where the method doesn't apply to the first argument:
\begin{itemize}
	\item \samp{findElement} applies on the second argument,
	\item \samp{replaceString} applies on the third argument,
\end{itemize}
The following methods offer a synonym to the function name:
\begin{itemize}
	\item \samp{empty} is a synonym as a method of the function \samp{isEmpty},
	\item \samp{length} is a synonym for the function \samp{lengthString},
	\item \samp{size} is a synonym for the function \samp{getArraySize},
\end{itemize}


\pdflabel{readonlyHook}
\index{readonlyHook}
\pdfsubsubsection{The 'readonly' hook}
The BNF representation of this statement is:\\
\samp{
	\textit{readonlyHook-statement} ::= \textbf{"readonlyHook" '('} \textit{filename} \textbf{')'}
										\textit{compound-statement}
}

The token \textit{filename} is the argument name that the user chooses for passing the name
of the file to the body of the hook.

This special function allows implementing a hook that will be called each time a
read-only file will be encountered while generating the output file through the
\samp{generate} or \samp{expand} instruction.

Limitations: only one declaration of this hook is authorized, and it can't be declared inside
a parsing or pattern script.

\textbf{Example:}

Common usage: file to generate has to be checked out from a source code control system
(see \samp{system} command to run executables).

\texttt{
\textbf{readonlyHook}(\textit{sFilename}) \{\\
\makebox[0.4cm][l]{}if !getProperty("SSProjectFolder") || !getProperty("SSWorkingFolder") || !getProperty("SSExecutablePath") || !getProperty("SSArchiveDir") \{\\
\makebox[0.8cm][l]{}traceLine("WARNING: properties 'SSProjectFolder' and 'SSWorkingFolder' and 'SSExecutablePath' and 'SSArchiveDir' should be passed to the command line for checking out read-only files from Source Safe");\\
\makebox[0.4cm][l]{}\} else \{\\
\makebox[0.8cm][l]{}if startString(sFilename, getProperty("SSWorkingFolder")) \{\\
\makebox[1.2cm][l]{}local sourceSafe;\\
\makebox[1.2cm][l]{}insert sourceSafe.fileName = sFilename;\\
\makebox[1.2cm][l]{}generate("SourceSafe.cwt", sourceSafe, getEnv("TMP") + "/SourceSafe.bat");\\
\makebox[1.2cm][l]{}if sourceSafe.isOk \{\\
\makebox[1.6cm][l]{}putEnv("SSDIR", getProperty("SSArchiveDir"));\\
\makebox[1.6cm][l]{}traceLine("checking out '" + sFilename + "' from Source Safe archive '" + getProperty("SSArchiveDir") + "'");\\
\makebox[1.6cm][l]{}local sFailed = system(getEnv("TMP") + "/SourceSafe.bat");\\
\makebox[1.6cm][l]{}if sFailed \{\\
\makebox[2.0cm][l]{}traceLine("Check out failed: '" + sFailed + "'");\\
\makebox[1.6cm][l]{}\}\\
\makebox[1.2cm][l]{}\}\\
\makebox[0.8cm][l]{}\} else \{\\
\makebox[1.2cm][l]{}traceLine("Unable to check out '" + sFilename + "': working folder starting with '" + getProperty("SSWorkingFolder") + "' expected");\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.4cm][l]{}\}\\
\}
}

\pdflabel{writefileHook}
\index{writefileHook}
\pdfsubsubsection{The 'write file' hook}

This special function allows implementing a hook that will be called just before writing a
file, after ending a text generation process such as expanding or generating or translating
text.

It is very important to notice that it returns a boolean value. A \samp{true} value means that
the generated text must be written into the file. A \samp{false} boolean value means that the
generated text doesn't have to be written into the file.

\CodeWorker\ always interprets not returning a value explicitly of a function, as
returning an empty string. If you forget to return a value, the generated text will not be
written into the file!

The BNF representation of this statement is:\\
\samp{
	\textit{writefileHook-statement} ::= \textbf{"writefileHook" '('} \textit{filename} \textbf{','} \textit{position} \textbf{','} \textit{creation} \textbf{')'} \textit{compound-statement}
}

\begin{tableiii}{l|l|l}{0.6}{Argument}{Type}{Description}
	\lineiii{\textit{filename}}{\samp{string}}{The argument name that the user chooses for
								passing the file name to the body of the hook.\\}
	\lineiii{\textit{position}}{\samp{int}}{The argument name that the user chooses for
								passing a position where a difference occurs between the new
								generated version of the file and the precedent one.\\
								If the files don't have the same size, the position is worth
								\samp{-1}.\\}
	\lineiii{\textit{creation}}{\samp{boolean}}{The argument name that the user chooses for
								passing whether the file is created or updated.\\
								The argument is worth \samp{true} if the file doesn't exist
								yet.}
\end{tableiii}

Limitations: only one declaration of this hook is authorized, and it can't be declared inside
a parsing or pattern script.

\textbf{Example:}

\texttt{
\textbf{writefileHook}(\textit{sFilename}, \textit{iPosition}, \textit{bCreation}) \{\\
\makebox[0.8cm][l]{}if bCreation \{\\
\makebox[1.6cm][l]{}traceLine("Creating file '" + sFilename + "'!");\\
\makebox[0.8cm][l]{}\} else \{\\
\makebox[1.6cm][l]{}traceLine("Updating file '" + sFilename + "', difference at " + iPosition + "!");\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}return true;\\
\}
}

\pdflabel{stepintoHook}
\index{stepintoHook}
\pdfsubsubsection{The 'step into' hook}

This special function is automatically called before that the extended BNF engine
resolves the production rule of a BNF non-terminal. Combined with \samp{stepoutHook()},
it is very useful for trace and debug tasks.

This hook can be implemented in parse scripts only.

The BNF representation of this statement is:\\
\samp{
	\textit{stepintoHook-statement} ::= \textbf{"stepintoHook" '('} \textit{sClauseName} \textbf{','} \textit{localScope} \textbf{')'} \textit{compound-statement}
}

\begin{tableiii}{l|l|l}{0.6}{Argument}{Type}{Description}
	\lineiii{\textit{sClauseName}}{\samp{string}}{The name of the \textit{non-terminal}.\\}
	\lineiii{\textit{localScope}}{\samp{tree}}{The scope of parameters used into the production rule.\\}
\end{tableiii}

\pdflabel{stepoutHook}
\index{stepoutHook}
\pdfsubsubsection{The 'step out' hook}

This special function is automatically called once the extended BNF engine has finished
the resolution of a BNF non-terminal. Combined with \samp{stepintoHook()}, it is very
useful for trace and debug tasks.

This hook can be implemented in parse scripts only.

The BNF representation of this statement is:\\
\samp{
	\textit{stepoutHook-statement} ::= \textbf{"stepoutHook" '('} \textit{sClauseName} \textbf{','} \textit{localScope} \textbf{','} \textit{bSuccess} \textbf{')'} \textit{compound-statement}
}

\begin{tableiii}{l|l|l}{0.6}{Argument}{Type}{Description}
	\lineiii{\textit{sClauseName}}{\samp{string}}{The name of the \textit{non-terminal}.\\}
	\lineiii{\textit{localScope}}{\samp{tree}}{The scope of local variables and parameters used into the production rule.\\}
	\lineiii{\textit{bSuccess}}{\samp{boolean}}{Whether the resolution of the production rule has succeeded or not.}
\end{tableiii}

\index{statement modifier}
\pdfsubsection{Statement's modifiers}

A statement's modifier is a directive that stands just before a statement, meaning an instruction
or a compound statement.

This directive operates some actions in the scope of the statement and then restores the
behaviour as being before.

This action may be:
\begin{itemize}
	\item to measure the time that is consumed by the execution of the statement,
	\item to redirect into a variable all messages intended to the console during the
		execution of the statement,
	\item to push a new \samp{project} parse tree,
	\item to change the output file during the execution of the statement, while generating
		text,
	\item to redirect the output stream into a variable during the execution of the statement,
		while generating text,
	\item to change the output file during the execution of the statement, while generating
		text, and to apply an expansion mode on it,
\end{itemize}

\pdflabel{delay}
\index{delay}
\index{statement modifier!delay}
\pdfsubsubsection{Statement's modifier 'delay'}

This keyword stands just before an instruction or a compound statement. It executes the statement and then, it
measures the time it has consumed.

Function \samp{getLastDelay} (\ref{getLastDelay()}) gives you the last measured duration.

\textbf{Example:}
%##markup##"execute:local list;\nlocal iIndex = 4;\ndelay while isPositive(decrement(iIndex)) {\n\tpushItem list = \"element \" + iIndex;\n\ttraceLine(\"creating node '\" + list#back + \"'\");\n}\ntraceLine(\"time of execution = \" + getLastDelay() + \" seconds\");"
%##begin##"execute:local list;\nlocal iIndex = 4;\ndelay while isPositive(decrement(iIndex)) {\n\tpushItem list = \"element \" + iIndex;\n\ttraceLine(\"creating node '\" + list#back + \"'\");\n}\ntraceLine(\"time of execution = \" + getLastDelay() + \" seconds\");"
\begin{verbatim}
local list;
local iIndex = 4;
delay while isPositive(decrement(iIndex)) {
	pushItem list = "element " + iIndex;
	traceLine("creating node '" + list#back + "'");
}
traceLine("time of execution = " + getLastDelay() + " seconds");
\end{verbatim}
\textbf{Output:}

\texttt{creating node 'element 3'\\
creating node 'element 2'\\
creating node 'element 1'\\
time of execution = 0.000041625402111162173 seconds}

%##end##"execute:local list;\nlocal iIndex = 4;\ndelay while isPositive(decrement(iIndex)) {\n\tpushItem list = \"element \" + iIndex;\n\ttraceLine(\"creating node '\" + list#back + \"'\");\n}\ntraceLine(\"time of execution = \" + getLastDelay() + \" seconds\");"

\pdflabel{quiet}
\index{quiet}
\index{statement modifier!quiet}
\pdfsubsubsection{Statement modifier 'quiet'}

This keyword stands just before an instruction or a compound statement. It executes the
statement and all messages intended to the console are concatenated into a string, instead of
being displayed. The variable that receives the concatenation of messages is specified after
the \samp{quiet} keyword.

The BNF representation of the \samp{quiet} statement modifier looks like:\\
\samp{
	\textit{quiet_modifier} ::= \textbf{"quiet"} \textbf{'('} \textit{variable} \textbf{')'} \textit{statement}
}

Note that the variable must have been declared before, as a local one or as an attribute of
the parse tree. If this variable doesn't exist while executing the statement, an error is
raised.

\pdflabel{new project}
\index{new_project}
\index{statement modifier!new_project}
\pdfsubsubsection{Statement modifier 'new project'}

This keyword stands just before an instruction or a compound statement. A new \samp{project}
parse tree is created, which is empty and that replaces temporarily the current one.
The statement is executed and, once the controlling sequence leaves the statement, the
temporary parse tree is removed, and the precedent \samp{project} comes back as the current
one.

The BNF representation of the \samp{new_project} statement modifier looks like:\\
\samp{
	\textit{new_project_modifier} ::= \textbf{"new_project"} \textit{statement}
}

This statement modifier is useful to handle a task that doesn't have to interact with the main parse tree.

\pdflabel{file as standard input}
\index{file_as_standard_input}
\index{statement modifier!file_as_standard_input}
\pdfsubsubsection{Statement modifier 'file as standard input'}

This keyword stands just before an instruction or a compound statement. A new standard input
is opened for reading data. Generally, the keyboard is the standard input, but here, it will
be the content of a file that is passed to the argument \textit{filename}. Once the execution
of the statement has completed, the precedent standard input comes back.

The BNF representation of the \samp{file_as_standard_input} statement's modifier looks like:\\
\samp{
	\textit{file_as_standard_input_modifier} ::= \textbf{"file_as_standard_input" '('} \textit{filename} \textbf{')'} \textit{statement}
}

This statement modifier is useful to replay a sequence of commands for the debugger or to drive
the standard input from an external module that puts its instructions into a file for a batch
mode or anything else.

\pdflabel{string as standard input}
\index{string_as_standard_input}
\index{statement modifier!string_as_standard_input}
\pdfsubsubsection{Statement modifier 'string as standard input'}

This keyword stands just before an instruction or a compound statement. A new standard input
is opened for reading data. Generally, the keyboard is the standard input, but here, it will
be the content of the string that is passed to argument. Once the execution of the statement
has completed, the precedent standard input comes back.

The BNF representation of the \samp{string_as_standard_input} statement's modifier looks like:\\
\samp{
	\textit{string_as_standard_input_modifier} ::= \textbf{"string_as_standard_input" '('} \textit{expression} \textbf{')'} \textit{statement}
}

The standard input is the result of evaluating \textit{expression}.

This statement modifier is useful to drive the standard input of \CodeWorker\ from an external
module, such as a JNI library or an external C++ application ( see chapter \ref{external bindings}).

\pdflabel{parsed file}
\index{parsed_file}
\index{statement modifier!parsed_file}
\pdfsubsubsection{Statement modifier 'parsed file'}

This keyword stands just before an instruction or a compound statement that belongs to a
\textit{parsing/translation script} exclusively. A new input file is opened for source scanning,
and replaces temporarily the precedent during the execution of the statement.The statement is
executed and, once the controlling sequence leaves the statement, the input file is closed
properly and the precedent one comes back.

The BNF representation of the \samp{parsed_file} statement modifier looks like:\\
\samp{
	\textit{parsed_file_modifier} ::= \textbf{"parsed_file" '('} \textit{filename} \textbf{')'} \textit{statement}
}

The token \textit{filename} is an expression that is evaluated to give the name of the input
file.

This statement modifier is useful to handle a task that must redirect the text to parse into
another input file. An example could be to emulate the C++ preprocessing on \samp{\#include}
directives.

\pdflabel{parsed string}
\index{parsed_string}
\index{statement modifier!parsed_string}
\pdfsubsubsection{Statement modifier 'parsed string'}

This keyword stands just before an instruction or a compound statement that belongs to a
\textit{parsing/translation script} exclusively. The result of an expression is taken as the source to scan,
and replaces temporarily the precedent input during the execution of the statement.The statement is
executed and, once the controlling sequence leaves the statement the precedent input comes back.

The BNF representation of the \samp{parsed_string} statement modifier looks like:\\
\samp{
	\textit{parsed_string_modifier} ::= \textbf{"parsed_string" '('} \textit{expression} \textbf{')'} \textit{statement}
}

The token \textit{fexpression} is an expression that is evaluated to give the text to scan.

This statement modifier is useful to handle a task that must temporary parse a string.

\pdflabel{generated file}
\index{generated_file}
\index{statement modifier!generated_file}
\pdfsubsubsection{Statement modifier 'generated file'}

This keyword stands just before an instruction or a compound statement that belongs to a
\textit{pattern script} exclusively. A new output file is opened for source code generation, preserving
protected areas as usually, and replaces temporarily the current one during the execution of the
statement. The statement is executed and, once the controlling sequence leaves the statement,
the output file is closed properly and the precedent one takes its place.

The BNF representation of the \samp{generated_file} statement modifier looks like:\\
\samp{
	\textit{generated_file_modifier} ::= \textbf{"generated_file" '('} \textit{filename} \textbf{')'} \textit{statement}
}

The token \textit{filename} is an expression that is evaluated to give the name of the output
file.

This statement modifier is useful to handle a task that must redirect the generated text into
another output file. An example could be to split an HTML text to generate into a few files
for implementing a frame set.

\pdflabel{generated string}
\index{generated_string}
\index{statement modifier!generated_string}
\pdfsubsubsection{Statement modifier 'generated string'}

This keyword stands just before an instruction or a compound statement that belongs to a
\textit{pattern script} exclusively. The output stream is redirected into a variable that
replaces temporarily the current output stream during the execution of the statement.
The statement is executed and, once the controlling sequence leaves the statement,
the variable is populated with the content of the output produced during this scope and the
precedent output stream takes its place.

The BNF representation of the \samp{generated_string} statement modifier looks like:\\
\samp{
	\textit{generated_string_modifier} ::= \textbf{"generated_string" '('} \textit{variable} \textbf{')'} \textit{statement}
}

The \textit{variable} argument gives the name of the variable that will be populated with the
generated text. This variable must already exist, declared on the stack or referring a node of
the current parse tree.

\pdflabel{appended file}
\index{appended_file}
\index{statement modifier!appended_file}
\pdfsubsubsection{Statement modifier 'appended file'}

This keyword stands just before an instruction or a compound statement that belongs to a
\textit{pattern script} exclusively. A new output file is opened for appending source code generation
at the end of the file and replaces temporarily the current one during the execution of the
statement. The statement is executed and, once the controlling sequence leaves the statement,
the output file is closed properly and the precedent one takes its place.

The BNF representation of the \samp{appended_file} statement modifier looks like:\\
\samp{
	\textit{appended_file_modifier} ::= \textbf{"appended_file" '('} \textit{filename} \textbf{')'} \textit{statement}
}

The token \textit{filename} is an expression that is evaluated to give the name of the output
file to append.

%--------------------------------------------------------------------------
\pdfsection{Common functions and procedures}

All functions and procedures that are described below may be encountered in any kind of
scripts : parsing, source code generation and file expanding, process driving, included script
files.

%##markup##"common script functions"
%##begin##"common script functions"
\begin{tableii}{l|l}{.8}{Category \textit{interpreter}}{Function for running a \CodeWorker\ script}
	\lineii{\samp{\textbf{autoexpand}}}{Expands a file on markups, following the directives self-contained in the file.}
	\lineii{\samp{\textbf{executeString}}}{Executes a script given in a string.}
	\lineii{\samp{\textbf{executeStringQuiet}}}{Interprets a string as a script and returns all traces intended to the console.}
	\lineii{\samp{\textbf{expand}}}{Expands a file on markups, following the directives of a template-based script.}
	\lineii{\samp{\textbf{generate}}}{Generates a file, following the directives of a template-based script.}
	\lineii{\samp{\textbf{generateString}}}{Generates a string, following the directives of a template-based script.}
	\lineii{\samp{\textbf{parseAsBNF}}}{Parses a file with a BNF script.}
	\lineii{\samp{\textbf{parseFree}}}{Parses a file with an imperative script.}
	\lineii{\samp{\textbf{parseFreeQuiet}}}{Parses a file with an imperative script, reroute all console messages and returns them as a string.}
	\lineii{\samp{\textbf{parseStringAsBNF}}}{Parses a string with a BNF script.}
	\lineii{\samp{\textbf{traceEngine}}}{Displays the state of the interpreter.}
	\lineii{\samp{\textbf{translate}}}{Performs a \textit{source-to-source translation} or a \textit{program transformation}.}
	\lineii{\samp{\textbf{translateString}}}{Performs a \textit{source-to-source translation} or a \textit{program transformation} on strings.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{string}}{Functions for handling strings}
	\lineii{\samp{\textbf{charAt}}}{Returns the characters present at a given position of a string.}
	\lineii{\samp{\textbf{completeLeftSpaces}}}{Completes a string with spaces to the left so that it reaches a given size.}
	\lineii{\samp{\textbf{completeRightSpaces}}}{Completes a string with spaces to the right so that it reaches a given size.}
	\lineii{\samp{\textbf{composeAdaLikeString}}}{Converts a sequence of characters to a Ada-like string without double quote delimiters.}
	\lineii{\samp{\textbf{composeCLikeString}}}{Converts a sequence of characters to a C-like string without double quote delimiters.}
	\lineii{\samp{\textbf{composeHTMLLikeString}}}{Converts a sequence of characters to an HTML-like text}
	\lineii{\samp{\textbf{composeSQLLikeString}}}{Converts a sequence of characters to a SQL-like string without single quote delimiters.}
	\lineii{\samp{\textbf{coreString}}}{Extracts the core of a string, leaving the beginning and the end.}
	\lineii{\samp{\textbf{countStringOccurences}}}{How many occurences of a string to another.}
	\lineii{\samp{\textbf{cutString}}}{Cuts a string at each separator encountered.}
	\lineii{\samp{\textbf{endString}}}{Compares the end of the string.}
	\lineii{\samp{\textbf{endl}}}{Returns an end-of-line, depending on the operating system.}
	\lineii{\samp{\textbf{equalsIgnoreCase}}}{Compares two strings, ignoring the case.}
	\lineii{\samp{\textbf{executeString}}}{Executes a script given in a string.}
	\lineii{\samp{\textbf{executeStringQuiet}}}{Interprets a string as a script and returns all traces intended to the console.}
	\lineii{\samp{\textbf{findFirstChar}}}{Returns the position of the first character amongst a set, encountered into a string.}
	\lineii{\samp{\textbf{findLastString}}}{Returns the position of the last occurence of a string to another.}
	\lineii{\samp{\textbf{findNextString}}}{Returns the next occurence of a string to another.}
	\lineii{\samp{\textbf{findString}}}{Returns the first occurence of a string to another.}
	\lineii{\samp{\textbf{generateString}}}{Generates a string, following the directives of a template-based script.}
	\lineii{\samp{\textbf{joinStrings}}}{Joins a list of strings, adding a separator between them.}
	\lineii{\samp{\textbf{leftString}}}{Returns the beginning of a string.}
	\lineii{\samp{\textbf{lengthString}}}{Returns the length of a string.}
	\lineii{\samp{\textbf{midString}}}{Returns a substring starting at a point for a given length.}
	\lineii{\samp{\textbf{parseStringAsBNF}}}{Parses a string with a BNF script.}
	\lineii{\samp{\textbf{repeatString}}}{Returns the concatenation of a string repeated a few times.}
	\lineii{\samp{\textbf{replaceString}}}{Replaces a substring with another.}
	\lineii{\samp{\textbf{replaceTabulations}}}{Replaces tabulations with spaces.}
	\lineii{\samp{\textbf{rightString}}}{Returns the end of a string.}
	\lineii{\samp{\textbf{rsubString}}}{Returns the left part of a string, ignoring last characters.}
	\lineii{\samp{\textbf{startString}}}{Checks the beginning of a string.}
	\lineii{\samp{\textbf{subString}}}{Returns a substring, ignoring the first characters.}
	\lineii{\samp{\textbf{toLowerString}}}{Converts a string to lowercase.}
	\lineii{\samp{\textbf{toUpperString}}}{Converts a string to uppercase.}
	\lineii{\samp{\textbf{trim}}}{Eliminates heading and trailing whitespaces.}
	\lineii{\samp{\textbf{trimLeft}}}{Eliminates the leading whitespaces.}
	\lineii{\samp{\textbf{trimRight}}}{Eliminates the trailing whitespaces.}
	\lineii{\samp{\textbf{truncateAfterString}}}{Special truncation of a string.}
	\lineii{\samp{\textbf{truncateBeforeString}}}{Special truncation of a string.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{array}}{Functions handling arrays}
	\lineii{\samp{\textbf{findElement}}}{Checks the existence of an entry key in an array.}
	\lineii{\samp{\textbf{findFirstSubstringIntoKeys}}}{Returns the first entry key of an array, containing a given string.}
	\lineii{\samp{\textbf{findNextSubstringIntoKeys}}}{Returns the next entry key of an array, containing a given string.}
	\lineii{\samp{\textbf{getArraySize}}}{Returns the number of items in an array.}
	\lineii{\samp{\textbf{insertElementAt}}}{Inserts a new element to a list, at a given position.}
	\lineii{\samp{\textbf{invertArray}}}{Inverts the order of items in an array.}
	\lineii{\samp{\textbf{isEmpty}}}{Checks whether a node has items or not.}
	\lineii{\samp{\textbf{removeAllElements}}}{Removes all items of the array.}
	\lineii{\samp{\textbf{removeElement}}}{Removes an item, given its entry key.}
	\lineii{\samp{\textbf{removeFirstElement}}}{Removes the first item of the array.}
	\lineii{\samp{\textbf{removeLastElement}}}{Removes the last item of the array.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{node}}{Functions handling a node}
	\lineii{\samp{\textbf{clearVariable}}}{Removes the subtree and assigns an empty value.}
	\lineii{\samp{\textbf{equalTrees}}}{Compares two subtrees.}
	\lineii{\samp{\textbf{existVariable}}}{Checks the existence of a node.}
	\lineii{\samp{\textbf{getVariableAttributes}}}{Extract all attribute names of a tree node.}
	\lineii{\samp{\textbf{removeRecursive}}}{Removes a given attribute from the subtree.}
	\lineii{\samp{\textbf{removeVariable}}}{Removes a given variable.}
	\lineii{\samp{\textbf{slideNodeContent}}}{Moves the subtree elsewhere on a branch.}
	\lineii{\samp{\textbf{sortArray}}}{Sort an array, considering the entry keys.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{iterator}}{Functions handling an iterator}
	\lineii{\samp{\textbf{createIterator}}}{Creates an iterator pointing to the beginning of a list.}
	\lineii{\samp{\textbf{createReverseIterator}}}{Creates a reverse iterator pointing to the end of a list.}
	\lineii{\samp{\textbf{duplicateIterator}}}{Duplicates an iterator.}
	\lineii{\samp{\textbf{first}}}{Returns \samp{true} if the iterator points to the first item.}
	\lineii{\samp{\textbf{index}}}{Returns the position of an item in a list.}
	\lineii{\samp{\textbf{key}}}{Returns the entry key of the item pointed to by the iterator.}
	\lineii{\samp{\textbf{last}}}{Returns \samp{true} if the iterator points to the last item.}
	\lineii{\samp{\textbf{next}}}{Move an iterator to the next item of a list.}
	\lineii{\samp{\textbf{prec}}}{Move an iterator to the precedent item of a list.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{file}}{Functions handling files}
	\lineii{\samp{\textbf{appendFile}}}{Writes the content of a string to the end of a file}
	\lineii{\samp{\textbf{canonizePath}}}{Builds an absolute path, starting to the current directory.}
	\lineii{\samp{\textbf{changeFileTime}}}{Changes the access and modification times of a file.}
	\lineii{\samp{\textbf{chmod}}}{Changes the permissions of a file.}
	\lineii{\samp{\textbf{copyFile}}}{Copies a file.}
	\lineii{\samp{\textbf{copyGenerableFile}}}{Copies a file with protected areas or expandable markups, only if the hand-typed code differs between source and destination.}
	\lineii{\samp{\textbf{copySmartFile}}}{Copies a file only if the destination differs.}
	\lineii{\samp{\textbf{createVirtualFile}}}{Creates a transient file in memory.}
	\lineii{\samp{\textbf{createVirtualTemporaryFile}}}{Creates a transient file in memory, \CodeWorker\ choosing its name.}
	\lineii{\samp{\textbf{deleteFile}}}{Deletes a file on the disk.}
	\lineii{\samp{\textbf{deleteVirtualFile}}}{Deletes a transient file from memory.}
	\lineii{\samp{\textbf{existFile}}}{Checks the existence of a file.}
	\lineii{\samp{\textbf{existVirtualFile}}}{Checks the existence of a transient file, created in memory.}
	\lineii{\samp{\textbf{exploreDirectory}}}{Browses all files of a directory, recursively or not.}
	\lineii{\samp{\textbf{fileCreation}}}{Returns the creation date of a file.}
	\lineii{\samp{\textbf{fileLastAccess}}}{Returns the last access date of a file.}
	\lineii{\samp{\textbf{fileLastModification}}}{Returns the last modification date of a file.}
	\lineii{\samp{\textbf{fileLines}}}{Returns the number of lines in a file.}
	\lineii{\samp{\textbf{fileMode}}}{Returns the permissions of a file.}
	\lineii{\samp{\textbf{fileSize}}}{Returns the size of a file.}
	\lineii{\samp{\textbf{getGenerationHeader}}}{Returns the comment to put into the header of generated files.}
	\lineii{\samp{\textbf{getShortFilename}}}{Returns the short name of a file}
	\lineii{\samp{\textbf{indentFile}}}{Indents a file, depending on the target language.}
	\lineii{\samp{\textbf{loadBinaryFile}}}{Loads a binary file and stores each byte in a hexadecimal representation of 2 digits.}
	\lineii{\samp{\textbf{loadFile}}}{Returns the content of a file or raises an error if not found.}
	\lineii{\samp{\textbf{loadVirtualFile}}}{Returns the content of a transient file or raises an error if not found.}
	\lineii{\samp{\textbf{pathFromPackage}}}{Converts a package path to a directory path.}
	\lineii{\samp{\textbf{relativePath}}}{Returns the relative path, which allows going from a path to another.}
	\lineii{\samp{\textbf{resolveFilePath}}}{Gives the location of a file with no ambiguity.}
	\lineii{\samp{\textbf{saveBinaryToFile}}}{Saves binary data to a file.}
	\lineii{\samp{\textbf{saveToFile}}}{Saves the content of a string to a file}
	\lineii{\samp{\textbf{scanDirectories}}}{Explores a directory, filtering filenames.}
	\lineii{\samp{\textbf{scanFiles}}}{Returns a flat list of all filenames matching with a filter.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{directory}}{Functions handling directories}
	\lineii{\samp{\textbf{changeDirectory}}}{Changes the current directory (\samp{chdir()} in C).}
	\lineii{\samp{\textbf{copySmartDirectory}}}{Copies files of a directory recursively only when destination files differ from source files.}
	\lineii{\samp{\textbf{createDirectory}}}{Creates a new directory.}
	\lineii{\samp{\textbf{exploreDirectory}}}{Browses all files of a directory, recursively or not.}
	\lineii{\samp{\textbf{getCurrentDirectory}}}{Returns the current directory (\samp{getcwd()} in C).}
	\lineii{\samp{\textbf{removeDirectory}}}{Removes a directory from the disk.}
	\lineii{\samp{\textbf{scanDirectories}}}{Explores a directory, filtering filenames.}
	\lineii{\samp{\textbf{scanFiles}}}{Returns a flat list of all filenames matching with a filter.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{URL}}{Functions working on URL transfers (HTTP,...)}
	\lineii{\samp{\textbf{decodeURL}}}{Decodes an HTTP URL.}
	\lineii{\samp{\textbf{encodeURL}}}{Encodes an URL to HTTP.}
	\lineii{\samp{\textbf{getHTTPRequest}}}{Sends an HTTP's GET request.}
	\lineii{\samp{\textbf{postHTTPRequest}}}{Sends an HTTP's POST request.}
	\lineii{\samp{\textbf{sendHTTPRequest}}}{Sends an HTTP request.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{datetime}}{Functions handling date-time}
	\lineii{\samp{\textbf{addToDate}}}{Change a date by shifting its internal fields days/months/years or time.}
	\lineii{\samp{\textbf{compareDate}}}{Compares two dates.}
	\lineii{\samp{\textbf{completeDate}}}{Extends an incomplete date with \textit{today} characteristics.}
	\lineii{\samp{\textbf{fileCreation}}}{Returns the creation date of a file.}
	\lineii{\samp{\textbf{fileLastAccess}}}{Returns the last access date of a file.}
	\lineii{\samp{\textbf{fileLastModification}}}{Returns the last modification date of a file.}
	\lineii{\samp{\textbf{formatDate}}}{Changes the format of a date.}
	\lineii{\samp{\textbf{getLastDelay}}}{Returns the time consumed to execute a statement.}
	\lineii{\samp{\textbf{getNow}}}{Returns the current date-time.}
	\lineii{\samp{\textbf{setNow}}}{Fixes the current date-time.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{numeric}}{Functions handling numbers}
	\lineii{\samp{\textbf{add}}}{Equivalent admitted writing is \samp{\$a + b\$}.}
	\lineii{\samp{\textbf{ceil}}}{Returns the smallest integer greater that or equal to a number}
	\lineii{\samp{\textbf{decrement}}}{Equivalent admitted writing is \samp{set a = \$a - 1\$;}.}
	\lineii{\samp{\textbf{div}}}{Equivalent admitted writing is \samp{\$a / b\$}.}
	\lineii{\samp{\textbf{equal}}}{Equivalent admitted writing is \samp{\$a == b\$}.}
	\lineii{\samp{\textbf{exp}}}{Returns the exponential of a value.}
	\lineii{\samp{\textbf{floor}}}{Returns the largest integer less that or equal to a number}
	\lineii{\samp{\textbf{increment}}}{Equivalent admitted writing is \samp{set a = \$a + 1\$;}.}
	\lineii{\samp{\textbf{inf}}}{Equivalent admitted writing is \samp{\$a < b\$}.}
	\lineii{\samp{\textbf{isNegative}}}{Equivalent admitted writing is \samp{\$a < 0\$}.}
	\lineii{\samp{\textbf{isPositive}}}{Equivalent admitted writing is \samp{\$a > 0\$}.}
	\lineii{\samp{\textbf{log}}}{Returns the Neperian logarithm.}
	\lineii{\samp{\textbf{mod}}}{Equivalent admitted writing is \samp{\$a \% b\$}.}
	\lineii{\samp{\textbf{mult}}}{Equivalent admitted writing is \samp{\$a * b\$}.}
	\lineii{\samp{\textbf{pow}}}{Raises a number to the power of another.}
	\lineii{\samp{\textbf{sqrt}}}{Calculates the square root.}
	\lineii{\samp{\textbf{sub}}}{Equivalent admitted writing is \samp{\$a - b\$}.}
	\lineii{\samp{\textbf{sup}}}{Equivalent admitted writing is \samp{\$a > b\$}.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{standard}}{Classical functions of any standard library}
	\lineii{\samp{\textbf{UUID}}}{Generates an UUID.}
	\lineii{\samp{\textbf{error}}}{Raises an error message}
	\lineii{\samp{\textbf{inputKey}}}{If any, returns the last key pressed on the standard input.}
	\lineii{\samp{\textbf{inputLine}}}{Wait for the standard input to the console.}
	\lineii{\samp{\textbf{isIdentifier}}}{Checks whether a string is a C-like identifier or not.}
	\lineii{\samp{\textbf{isNumeric}}}{Checks whether a string is a floating-point number or not.}
	\lineii{\samp{\textbf{randomInteger}}}{Generates a pseudorandom number.}
	\lineii{\samp{\textbf{randomSeed}}}{Changes the seed of the pseudorandom generator.}
	\lineii{\samp{\textbf{traceLine}}}{Displays a message to the console, adding a carriage return.}
	\lineii{\samp{\textbf{traceObject}}}{Displays the content of a node to the console.}
	\lineii{\samp{\textbf{traceStack}}}{Displays the stack to the console.}
	\lineii{\samp{\textbf{traceText}}}{Displays a message to the console.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{conversion}}{Type conversion}
	\lineii{\samp{\textbf{byteToChar}}}{Converts a byte (hexadecimal representation of 2 digits) to a character.}
	\lineii{\samp{\textbf{bytesToLong}}}{Converts a 4-bytes sequence to an unsigned long integer in its decimal representation.}
	\lineii{\samp{\textbf{bytesToShort}}}{Converts a 2-bytes sequence to an unsigned short integer in its decimal representation.}
	\lineii{\samp{\textbf{charToByte}}}{Converts a character to a byte (hexadecimal representation of 2 digits).}
	\lineii{\samp{\textbf{charToInt}}}{Converts a character to the integer value of the corresponding ASCII.}
	\lineii{\samp{\textbf{hexaToDecimal}}}{Converts an hexadecimal representation to an integer.}
	\lineii{\samp{\textbf{hostToNetworkLong}}}{Converts a 4-bytes representation of a long integer to the network bytes order.}
	\lineii{\samp{\textbf{hostToNetworkShort}}}{Converts a 2-bytes representation of a short integer to the network bytes order.}
	\lineii{\samp{\textbf{longToBytes}}}{Converts an unsigned long integer in decimal base to its 4-bytes representation.}
	\lineii{\samp{\textbf{networkLongToHost}}}{Converts a 4-bytes representation of a long integer to the host bytes order.}
	\lineii{\samp{\textbf{networkShortToHost}}}{Converts a 2-bytes representation of a short integer to the host bytes order.}
	\lineii{\samp{\textbf{octalToDecimal}}}{Converts an octal representation to a decimal integer.}
	\lineii{\samp{\textbf{shortToBytes}}}{Converts an unsigned short integer in decimal base to its 2-bytes representation.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{system}}{Functions relative to the operating system}
	\lineii{\samp{\textbf{computeMD5}}}{Computes the MD5 of a string.}
	\lineii{\samp{\textbf{environTable}}}{Equivalent of \samp{environ()} in C}
	\lineii{\samp{\textbf{existEnv}}}{Checks the existence of an environment variable.}
	\lineii{\samp{\textbf{getEnv}}}{Returns an environment variable, or raises an error if not exist.}
	\lineii{\samp{\textbf{openLogFile}}}{Opens a log file for logging every console trace.}
	\lineii{\samp{\textbf{putEnv}}}{Puts a value to an environment variable.}
	\lineii{\samp{\textbf{sleep}}}{Suspends the execution for \samp{millis} milliseconds.}
	\lineii{\samp{\textbf{system}}}{Equivalent to the C function \samp{system()}.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{command}}{Relative to the command line}
	\lineii{\samp{\textbf{compileToCpp}}}{Translates a script to C++.}
	\lineii{\samp{\textbf{getIncludePath}}}{Returns the include path passed via the option \samp{-I}.}
	\lineii{\samp{\textbf{getProperty}}}{Returns the value of a property passed via the option \samp{-D}.}
	\lineii{\samp{\textbf{getVersion}}}{Returns the version of the interpreter.}
	\lineii{\samp{\textbf{getWorkingPath}}}{Returns the output directory passed via option \samp{-path}.}
	\lineii{\samp{\textbf{setIncludePath}}}{Changes the option \samp{-I} while running.}
	\lineii{\samp{\textbf{setProperty}}}{Adds/changes a property (option \samp{-D}) while running.}
	\lineii{\samp{\textbf{setVersion}}}{Gives the version of scripts currently interpreted by \textit{CodeWorker}.}
	\lineii{\samp{\textbf{setWorkingPath}}}{Does the job of the option \samp{-path}.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{generation}}{Functions relative to generation}
	\lineii{\samp{\textbf{addGenerationTagsHandler}}}{Adds your own CodeWorker's tags handler}
	\lineii{\samp{\textbf{autoexpand}}}{Expands a file on markups, following the directives self-contained in the file.}
	\lineii{\samp{\textbf{expand}}}{Expands a file on markups, following the directives of a template-based script.}
	\lineii{\samp{\textbf{extractGenerationHeader}}}{Gives the generation header of a generated file, if any.}
	\lineii{\samp{\textbf{generate}}}{Generates a file, following the directives of a template-based script.}
	\lineii{\samp{\textbf{generateString}}}{Generates a string, following the directives of a template-based script.}
	\lineii{\samp{\textbf{getCommentBegin}}}{Returns the current format of a comment's beginning.}
	\lineii{\samp{\textbf{getCommentEnd}}}{Returns the current format of a comment's end.}
	\lineii{\samp{\textbf{getGenerationHeader}}}{Returns the comment to put into the header of generated files.}
	\lineii{\samp{\textbf{getTextMode}}}{Returns the text mode amongst \textbf{"DOS"}, \textbf{"UNIX"} and \textbf{"BINARY"}.}
	\lineii{\samp{\textbf{getWriteMode}}}{Returns how text is written during a generation (insert/overwrite).}
	\lineii{\samp{\textbf{listAllGeneratedFiles}}}{Gives the list of all generated files.}
	\lineii{\samp{\textbf{removeGenerationTagsHandler}}}{Removes a custom generation tags handler}
	\lineii{\samp{\textbf{selectGenerationTagsHandler}}}{Selects your own CodeWorker's tags handler for processing generation tasks}
	\lineii{\samp{\textbf{setCommentBegin}}}{Changes what a beginning of comment looks like, perhaps before expanding a file.}
	\lineii{\samp{\textbf{setCommentEnd}}}{Changes what an end of comment looks like, perhaps before expanding a file.}
	\lineii{\samp{\textbf{setGenerationHeader}}}{Specifies a comment to put at the beginning of every generated file.}
	\lineii{\samp{\textbf{setTextMode}}}{\textbf{"DOS"}, \textbf{"UNIX"} or \textbf{"BINARY"}}
	\lineii{\samp{\textbf{setWriteMode}}}{Selects how to write text during a generation (insert/overwrite).}
	\lineii{\samp{\textbf{translate}}}{Performs a \textit{source-to-source translation} or a \textit{program transformation}.}
	\lineii{\samp{\textbf{translateString}}}{Performs a \textit{source-to-source translation} or a \textit{program transformation} on strings.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{parsing}}{Functions relative to scanning/parsing}
	\lineii{\samp{\textbf{parseAsBNF}}}{Parses a file with a BNF script.}
	\lineii{\samp{\textbf{parseFree}}}{Parses a file with an imperative script.}
	\lineii{\samp{\textbf{parseFreeQuiet}}}{Parses a file with an imperative script, reroute all console messages and returns them as a string.}
	\lineii{\samp{\textbf{parseStringAsBNF}}}{Parses a string with a BNF script.}
	\lineii{\samp{\textbf{translate}}}{Performs a \textit{source-to-source translation} or a \textit{program transformation}.}
	\lineii{\samp{\textbf{translateString}}}{Performs a \textit{source-to-source translation} or a \textit{program transformation} on strings.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{socket}}{Socket operations}
	\lineii{\samp{\textbf{acceptSocket}}}{Listens for a client connection and accepts it.}
	\lineii{\samp{\textbf{closeSocket}}}{Closes a socket descriptor.}
	\lineii{\samp{\textbf{createINETClientSocket}}}{Creates a stream socket connected to the specified port and IP address.}
	\lineii{\samp{\textbf{createINETServerSocket}}}{Creates a server stream socket bound to a specified port.}
	\lineii{\samp{\textbf{receiveBinaryFromSocket}}}{Reads binary data from the socket, knowing the size.}
	\lineii{\samp{\textbf{receiveFromSocket}}}{Reads text or binary data from a socket.}
	\lineii{\samp{\textbf{receiveTextFromSocket}}}{Reads text from a socket, knowing the size.}
	\lineii{\samp{\textbf{sendBinaryToSocket}}}{Writes binary data to a socket.}
	\lineii{\samp{\textbf{sendTextToSocket}}}{Writes text to a socket.}
\end{tableii}
\begin{tableii}{l|l}{.8}{Category \textit{unknown}}{Various types of function}
	\lineii{\samp{\textbf{not}}}{The boolean negation, equivalent to \samp{!a}.}
	\lineii{\samp{\textbf{produceHTML}}}{}
	\lineii{\samp{\textbf{saveProject}}}{Saves the parse tree of the project to XML.}
	\lineii{\samp{\textbf{saveProjectTypes}}}{Factorizes nodes of the projects to distinguish implicit types for node and saves it to XML.}
\end{tableii}
\pdflabel{acceptSocket()}
\index{acceptSocket()}
\pdfsubsection{acceptSocket}
\begin{itemize}
	\item function \textbf{acceptSocket(}\samp{serverSocket} \textbf{:} \textit{int}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{serverSocket}}{\textit{int}}{a server socket previously created via \samp{createINETServerSocket()}}
\end{tableiii}
This function blocks until a client connection arrives, and returns the corresponding
socket descriptor.

Once a connection has been established, use directly the \textit{send}/\textit{receive} functions
or \samp{attachInputToSocket()}/\samp{attachOutputToSocket} for reading/writing
to the socket via a \textit{BNF-parsing}/\textit{template-based} script.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{add()}
\index{add()}
\pdfsubsection{add}
\begin{itemize}
	\item function \textbf{add(}\samp{left} \textbf{:} \textit{double}\textbf{, }\samp{right} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{double}}{left arithmetic member}
	\lineiii{\samp{right}}{\textit{double}}{right arithmetic member}
\end{tableiii}
Returns the result of arithmetic addition \samp{left} \textbf{+} \samp{right}.
Members are converted from strings to numbers, supposed being worth \samp{0} if a parsing error occurs;
then the addition is processed, and the result is converted to a string,
skipping fractional part if all digits after the dot are \textit{0}.

Remember that the symbol \textbf{'+'} means the concatenation of text. Using
this operator instead of function \samp{add} will concatenate digits!
However, it exists an escape mode that allows writing arithmetic expressions
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{left} \textbf{+} \textit{right}\$}
is equivalent to \samp{add(\textit{left}, \textit{right})}.

\textbf{Example:}

\texttt{local a = 3.2;\\
traceLine(a + " + 4.5 = " + add(a, "4.5"));\\
traceLine(a + " + 2.8 = " + add(a, 2.8) + " <- integer value");}

\textbf{Output:}

\texttt{3.2 + 4.5 = 7.7\\
3.2 + 2.8 = 6 <- integer value}


\textbf{See also:}

\samp{sub} \ref{sub()}, \samp{mult} \ref{mult()}, \samp{div} \ref{div()}, \samp{exp} \ref{exp()}, \samp{log} \ref{log()}, \samp{mod} \ref{mod()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{addGenerationTagsHandler()}
\index{addGenerationTagsHandler()}
\pdfsubsection{addGenerationTagsHandler}
\begin{itemize}
	\item function \textbf{addGenerationTagsHandler(}\samp{key} \textbf{:} \textit{string}\textbf{, }\samp{reader} \textbf{:} \textit{script}\textbf{, }\samp{writer} \textbf{:} \textit{script}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{designates the handler}
	\lineiii{\samp{reader}}{\textit{script<BNF>}}{extended-BNF script of the reader}
	\lineiii{\samp{writer}}{\textit{script<pattern>}}{template-based script of the writer}
\end{tableiii}
Adds a new generation tags handler, designated by \samp{key}.

Returns \samp{true} if \samp{key} isn't reserved yet for another generation tags handler.


\textbf{See also:}

\samp{removeGenerationTagsHandler} \ref{removeGenerationTagsHandler()}, \samp{selectGenerationTagsHandler} \ref{selectGenerationTagsHandler()}
\end{itemize}
\pdflabel{addToDate()}
\index{addToDate()}
\pdfsubsection{addToDate}
\begin{itemize}
	\item function \textbf{addToDate(}\samp{date} \textbf{:} \textit{string}\textbf{, }\samp{format} \textbf{:} \textit{string}\textbf{, }\samp{shifting} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{date}}{\textit{string}}{the date to change}
	\lineiii{\samp{format}}{\textit{string}}{the format to apply on the reading of the \samp{shifting} argument}
	\lineiii{\samp{shifting}}{\textit{string}}{the offset values to apply on the date, whose meanings are known by the \samp{offset} argument}
\end{tableiii}
Change a date by applying offset values on its internal representation.
The internal representation holds the year / month / day and hour / minute / second
and millisecond fields. You choose what fields to shift, giving a date
format as the first argument, and an offset value for each fields seen in the
format as the second argument.

The field types have the same syntax as in the function \samp{formatDate}, except
that the field values might be negative.\\
For instance, if the field type is "\%m", the month must occupy 2 digits maximum for a
positive offset, and 3 characters for a negative offset, the first one being the sign.

The offsets are applied in the order they are read, from the left-hand side to the right.

The function returns the value of the date after applying the shift.

\textbf{Example:}

\texttt{traceLine("Substract 2 months and add 20 hours to the current date-time:");\\
local newDate = addToDate(getNow(), "\%m,\%H", "-2,20");\\
traceLine("one manner: " + getNow() + " -> " + newDate);\\
newDate = addToDate(getNow(), "\%m\%H", "-0220");\\
traceLine("another manner: " + getNow() + " -> " + newDate);}

\textbf{Output:}

\texttt{Substract 2 months and add 20 hours to the current date-time:\\
one manner: 01may2006 20:42:00.500 -> 02mar2006 16:42:00.500\\
another manner: 01may2006 20:42:00.500 -> 02mar2006 16:42:00.500}


\textbf{See also:}

\samp{formatDate} \ref{formatDate()}, \samp{compareDate} \ref{compareDate()}, \samp{completeDate} \ref{completeDate()}, \samp{getLastDelay} \ref{getLastDelay()}, \samp{getNow} \ref{getNow()}, \samp{setNow} \ref{setNow()}
\end{itemize}
\pdflabel{appendFile()}
\index{appendFile()}
\pdfsubsection{appendFile}
\begin{itemize}
	\item procedure \textbf{appendFile(}\samp{filename} \textbf{:} \textit{string}\textbf{, }\samp{content} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to append}
	\lineiii{\samp{content}}{\textit{string}}{sequence of characters to write at the end of the file}
\end{tableiii}
Writes the text \samp{content} at the end of the file \samp{filename}.

If the file doesn't exist, the function creates it.


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{autoexpand()}
\index{autoexpand()}
\pdfsubsection{autoexpand}
\begin{itemize}
	\item procedure \textbf{autoexpand(}\samp{outputFileName} \textbf{:} \textit{string}\textbf{, }\samp{this} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{outputFileName}}{\textit{string}}{the existing file to expand}
	\lineiii{\samp{this}}{\textit{treeref}}{the current node that will be accessed with \textit{this} variable}
\end{tableiii}
Expands an existing file whose name is passed to the argument \samp{outputFileName},
executing \textit{template-based} scripts located at each markup. The file contains
its own scripts for expanding code.

Expanding a file consists of generating code into marked out areas only, the rest
of the file remaining the same. The markup is put into a comment, knowing that the
syntax of the comment must conform to the type of the expanded file \samp{outputFileName}.
So, an HTML file expects \textbf{<!- -} and \textbf{- ->}, a JAVA file is waiting
for \textbf{//} and \textbf{"$\backslash$n"}, ... The markup is announced by
\textbf{\#\#markup\#\#} followed by a string that represents the \textit{markup key}.
Don't forget to configure correctly the syntax of comment boundaries with procedures
\samp{setCommentBegin()} (see \ref{setCommentBegin()}) and \samp{setCommentEnd()} (see \ref{setCommentEnd()}).

When the procedure is called, \CodeWorker\ jumps from a markup to another. To
handle a markup, it checks whether text was already generated, put between tags
\textbf{\#\#begin\#\#"\textit{markup-key}"} and \textbf{\#\#end\#\#"\textit{markup-key}"},
added automatically the first time an expansion is required, to demarquate the
portion of code that doesn't belong to the user. Then, it extracts all protected
areas, if any, and it generates code at the position of the markup, adding
\textit{begin}/\textit{end} tags seen before.

The interpreter reclaims the tags \samp{\#\#script\#\#} just after the markup.
It extracts the embedded text, considered as a \samp{template-based} script, eventually
put between comments, and the interpreter executes this embedded script.

Note that some data might be put between tags \samp{\#\#data\#\#}, accessible
in the \textit{template-based} script via the function \samp{getMarkupValue()} (see \ref{getMarkupValue()}).
This block of custom data comes after the \samp{\#\#script\#\#} tag, if present.

Be careful not to confuse this prodedure with \samp{generate()} that doesn't care
about markups and that overwrites the output file completely, except protected
areas of course.


\textbf{See also:}

\samp{expand} \ref{expand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}, \samp{translate} \ref{translate()}, \samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translateString} \ref{translateString()}
\end{itemize}
\pdflabel{bytesToLong()}
\index{bytesToLong()}
\pdfsubsection{bytesToLong}
\begin{itemize}
	\item function \textbf{bytesToLong(}\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{ulong}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{a 4-bytes representation of an unsigned long integer (host bytes order)}
\end{tableiii}
Converts a 4-bytes representation of an unsigned long integer to its decimal representation.
Bytes are ordered in the host order (memory storage).

If the argument \samp{bytes} is malformed, the function raises an error.

\textbf{Example:}

\texttt{traceLine("bytesToLong('FFFFFFFF') = '" + bytesToLong("FFFFFFFF") + "'");}

\textbf{Output:}

\texttt{bytesToLong('FFFFFFFF') = '4294967295'}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{bytesToShort()}
\index{bytesToShort()}
\pdfsubsection{bytesToShort}
\begin{itemize}
	\item function \textbf{bytesToShort(}\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{ushort}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{a 2-bytes representation of an unsigned short integer (host bytes order)}
\end{tableiii}
Converts a 2-bytes representation of an unsigned short integer to its decimal representation.
Bytes are ordered in the host order (memory storage).

If the argument \samp{bytes} is malformed, the function raises an error.

\textbf{Example:}

\texttt{traceLine("bytesToShort('FFFF') = '" + bytesToShort("FFFF") + "'");}

\textbf{Output:}

\texttt{bytesToShort('FFFF') = '65535'}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{byteToChar()}
\index{byteToChar()}
\pdfsubsection{byteToChar}
\begin{itemize}
	\item function \textbf{byteToChar(}\samp{byte} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{byte}}{\textit{string}}{an hexadecimal number of 2 digits exactly}
\end{tableiii}
Converts a byte to a character. A byte is considered as an hexadecimal number of
2 digits exactly.

If the argument \samp{byte} doesn't contain an hexadecimal number of 2 digits,
an error is raised. If \samp{byte} is worth '00', the function returns an empty
string.

\textbf{Example:}

\texttt{traceLine("byteToChar('20') = '" + byteToChar("20") + "'");\\
traceLine("byteToChar('61') = '" + byteToChar("61") + "'");}

\textbf{Output:}

\texttt{byteToChar('20') = ' '\\
byteToChar('61') = 'a'}


\textbf{See also:}

\samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{canonizePath()}
\index{canonizePath()}
\pdfsubsection{canonizePath}
\begin{itemize}
	\item function \textbf{canonizePath(}\samp{path} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{the path to canonize}
\end{tableiii}
Returns the path passed to the argument \samp{path} after having canonized it.

To canonize a path means that:
\begin{itemize}
	\item \samp{\textbf{'..'}} and \samp{\textbf{'.'}} directories are processed,
	\item backslashes are changed to forward slashes,
	\item if the \samp{path} is relative, it is converted to a full path, starting
at the current directory.
\end{itemize}

\textbf{Example:}

\texttt{traceLine("current directory = '" + getCurrentDirectory() + "'");\\
local sPath = "WebSite/downloads/CodeWorker.zip";\\
traceLine(" path   = '" + sPath + "'");\\
traceLine(" result = '" + canonizePath(sPath) + "'");\\
local sCurrentDirectory = getCurrentDirectory();\\
changeDirectory(sCurrentDirectory + "Documentation");\\
traceLine("current directory = '" + getCurrentDirectory() + "'");\\
set sPath = "../Scripts/Tutorial/GettingStarted/tiny.html";\\
traceLine(" path   = '" + sPath + "'");\\
traceLine(" result = '" + canonizePath(sPath) + "'");\\
changeDirectory(sCurrentDirectory);\\
traceLine("current directory = '" + getCurrentDirectory() + "'");\\
set sPath = ".";\\
traceLine(" path   = '" + sPath + "'");\\
traceLine(" result = '" + canonizePath(sPath) + "'");}

\textbf{Output:}

\texttt{current directory = 'E:/projects/generator/'\\
\makebox[0.8cm][l]{}path   = 'WebSite/downloads/CodeWorker.zip'\\
\makebox[0.8cm][l]{}result = 'e:/projects/generator/WebSite/downloads/CodeWorker.zip'\\
current directory = 'E:/projects/generator/Documentation/'\\
\makebox[0.8cm][l]{}path   = '../Scripts/Tutorial/GettingStarted/tiny.html'\\
\makebox[0.8cm][l]{}result = 'e:/projects/generator/Scripts/Tutorial/GettingStarted/tiny.html'\\
current directory = 'E:/projects/generator/'\\
\makebox[0.8cm][l]{}path   = '.'\\
\makebox[0.8cm][l]{}result = 'e:/projects/generator'}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{ceil()}
\index{ceil()}
\pdfsubsection{ceil}
\begin{itemize}
	\item function \textbf{ceil(}\samp{number} \textbf{:} \textit{double}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{double}}{the floating-point number to ceil}
\end{tableiii}
Returns the smallest integer that is greater than or equal to \samp{number}. If
\samp{number} isn't a number, the function returns \textit{0}.

\textbf{Example:}

\texttt{traceLine("ceil(5.369e+1) = " + ceil(5.369e1));}

\textbf{Output:}

\texttt{ceil(5.369e+1) = 54}


\textbf{See also:}

\samp{decrement} \ref{decrement()}, \samp{increment} \ref{increment()}, \samp{floor} \ref{floor()}
\end{itemize}
\pdflabel{changeDirectory()}
\index{changeDirectory()}
\pdfsubsection{changeDirectory}
\begin{itemize}
	\item function \textbf{changeDirectory(}\samp{path} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{path name of the directory}
\end{tableiii}
The function changes the current directory of \CodeWorker\ to the directory
specified by the \samp{path} argument. The parameter must refer to an existing
directory.

\textbf{Example:}

\texttt{traceLine("current directory = '" + getCurrentDirectory() + "'");\\
local sOldDirectory = getCurrentDirectory();\\
local sNewDirectory = sOldDirectory + "Documentation";\\
traceLine("call to changeDirectory('" + sNewDirectory + "')");\\
changeDirectory(sNewDirectory);\\
traceLine("new current directory = '" + getCurrentDirectory() + "'");\\
changeDirectory(sOldDirectory);}

\textbf{Output:}

\texttt{current directory = 'E:/projects/generator/'\\
call to changeDirectory('E:/projects/generator/Documentation')\\
new current directory = 'E:/projects/generator/Documentation/'}


\textbf{See also:}

\samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{changeFileTime()}
\index{changeFileTime()}
\pdfsubsection{changeFileTime}
\begin{itemize}
	\item function \textbf{changeFileTime(}\samp{filename} \textbf{:} \textit{string}\textbf{, }\samp{accessTime} \textbf{:} \textit{string}\textbf{, }\samp{modificationTime} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to set}
	\lineiii{\samp{accessTime}}{\textit{string}}{date-time of the last access}
	\lineiii{\samp{modificationTime}}{\textit{string}}{date-time of the last modification}
\end{tableiii}
The function changes the access and modification times of the file \samp{filename}.
The user ID of the process must be the owner of the file, or the process must
have appropriate privileges.

In case of failure, the function returns a negative integer:
\begin{itemize}
	\item \textbf{-1}: unknown error that shouldn't appear,
	\item \textbf{-2}: permission denied,
	\item \textbf{-3}: too many files have been opened,
	\item \textbf{-4}: file not found,
	\item \textbf{-5}: invalid \textit{times} argument,
\end{itemize}

\textbf{Example:}

\texttt{local oldAccessTime = fileLastAccess("readme.txt");\\
local oldModifTime  = fileLastModification("readme.txt");\\
traceLine("old modification time of 'readme.txt' = '" + oldModifTime + "'");\\
if \$changeFileTime("readme.txt", getNow(), getNow()) < 0\$\\
\makebox[0.8cm][l]{}error("'changeFileTime()' has failed!");\\
local newModifTime  = fileLastModification("readme.txt");\\
traceLine("new modification time of 'readme.txt' = '" + newModifTime + "'");\\
// put the same times as before calling the example:\\
if \$changeFileTime("readme.txt", oldAccessTime, oldModifTime) < 0\$\\
\makebox[0.8cm][l]{}error("'changeFileTime()' has failed!");}

\textbf{Output:}

\texttt{old modification time of 'readme.txt' = '11jan2004 07:04:20'\\
new modification time of 'readme.txt' = '01may2006 20:42:00'}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{charAt()}
\index{charAt()}
\pdfsubsection{charAt}
\begin{itemize}
	\item function \textbf{charAt(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{index} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{index}}{\textit{int}}{the index of the character to extract from \samp{text}}
\end{tableiii}
Returns the character at the specified \samp{index}. An index ranges from \textit{0} to \textbf{lengthString(}\samp{text}\textbf{) - 1}. The first character of the sequence is at index \textit{0}, the next at index \textit{1}, and so on. If the \samp{index} argument is out of bounds (negative or not less than the length of \samp{text}), it returns an empty string.

\textbf{Example:}

\texttt{local sText = "I have but one lamp by which my feet are guided, and that is the lamp of experience. (P. Henry)";\\
traceLine("charAt('" + sText + "', 2) = '" + charAt(sText, 2) + "' <- index = 2 gives the third character of the string");}

\textbf{Output:}

\texttt{charAt('I have but one lamp by which my feet are guided, and that is the lamp of experience. (P. Henry)', 2) = 'h' <- index = 2 gives the third character of the string}


\textbf{See also:}

\samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{charToByte()}
\index{charToByte()}
\pdfsubsection{charToByte}
\begin{itemize}
	\item function \textbf{charToByte(}\samp{char} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{char}}{\textit{string}}{a character}
\end{tableiii}
Converts a character to its hexadecimal representation, taking 2 digits, even if
less than 0x10.

If the argument \samp{char} is empty, the function returns '00'. If it contains
more than one character, an error is raised.

\textbf{Example:}

\texttt{traceLine("charToByte('A') = '" + charToByte("A") + "'");\\
traceLine("charToByte('$\backslash$$\backslash$n') = '" + charToByte("$\backslash$n") + "'");}

\textbf{Output:}

\texttt{charToByte('A') = '41'\\
charToByte('$\backslash$n') = '0A'}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{charToInt()}
\index{charToInt()}
\pdfsubsection{charToInt}
\begin{itemize}
	\item function \textbf{charToInt(}\samp{char} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{char}}{\textit{string}}{a string containing just one char}
\end{tableiii}
Returns the conversion of \samp{char} as an unsigned integer, corresponding to its ASCII form generally. If \samp{char} doesn't contain just one char, it returns an empty string.

\textbf{Example:}

\texttt{traceLine("charToInt('A') = " + charToInt("A") + " <- ASCII code of 'A'");}

\textbf{Output:}

\texttt{charToInt('A') = 65 <- ASCII code of 'A'}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{chmod()}
\index{chmod()}
\pdfsubsection{chmod}
\begin{itemize}
	\item function \textbf{chmod(}\samp{filename} \textbf{:} \textit{string}\textbf{, }\samp{mode} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{file to which change the permission setting}
	\lineiii{\samp{mode}}{\textit{string}}{permission setting as a concatenation of 'R' and/or 'W' and/or 'X'}
\end{tableiii}
The \samp{chmod} function changes the permission setting of the file specified by \samp{filename}.
The permission setting controls \textit{read} and \textit{write} and \textit{execute} access to the file.
The argument \samp{mode} holds the permission setting of the file as a concatenation of chars amongst the following:
\begin{itemize}
    \item \textbf{'R'} for \textbf{r}eading permitted,
    \item \textbf{'W'} for \textbf{w}riting permitted,
    \item \textbf{'X'} for e\textbf{x}ecuting permitted (ignored on \textit{Windows} platform),
\end{itemize}
The function fails when the file given by the argument \samp{filename} is not found, and an error is thrown when the argument \samp{mode} contains an unexpected character.

\textbf{Example:}

\texttt{local bSuccess = chmod("Documentation/CodeWorker.tex", "RW");\\
if !bSuccess error("file 'Documentation/CodeWorker.tex' not found!");\\
traceLine("R + W permitted on file 'Documentation/CodeWorker.tex'");}

\textbf{Output:}

\texttt{R + W permitted on file 'Documentation/CodeWorker.tex'}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{clearVariable()}
\index{clearVariable()}
\pdfsubsection{clearVariable}
\begin{itemize}
	\item procedure \textbf{clearVariable(}\samp{node} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{node}}{\textit{treeref}}{the node to clear}
\end{tableiii}
All attributes of the argument \samp{node} are deleted, its array of nodes is
cleared and its value becomes an empty string. If the node was referring to
another node, the link is cleared.

Please note that the node isn't removed; see \samp{removeVariable()} for that.

\textbf{Example:}

\texttt{local myNode = "the value";\\
insert myNode.a1 = "attribute 1";\\
insert myNode.a2 = "attribute 2";\\
insert myNode.array["1"] = "node 1";\\
insert myNode.array["2"] = "node 2";\\
traceObject(myNode);\\
traceLine("-- the variable 'myNode' is cleared:");\\
clearVariable(myNode);\\
traceObject(myNode);}

\textbf{Output:}

\texttt{Tracing variable 'myNode':\\
\makebox[0.8cm][l]{}"the value"\\
\makebox[0.8cm][l]{}a1 = "attribute 1"\\
\makebox[0.8cm][l]{}a2 = "attribute 2"\\
\makebox[0.8cm][l]{}array\\
\makebox[0.8cm][l]{}array["1", "2"]\\
End of variable's trace 'myNode'.\\
-- the variable 'myNode' is cleared:\\
Tracing variable 'myNode':\\
End of variable's trace 'myNode'.}


\pdflabel{clearNode()}
\index{deprecated!clearNode()}
\textbf{Deprecated form:} \samp{clearNode} has disappeared since version \textit{3.8.7}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{closeSocket()}
\index{closeSocket()}
\pdfsubsection{closeSocket}
\begin{itemize}
	\item procedure \textbf{closeSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a \textit{client}/\textit{server} socket descriptor}
\end{tableiii}
This procedure closes the socket descriptor specified to the argument \samp{socket}.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{compareDate()}
\index{compareDate()}
\pdfsubsection{compareDate}
\begin{itemize}
	\item function \textbf{compareDate(}\samp{date1} \textbf{:} \textit{string}\textbf{, }\samp{date2} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{date1}}{\textit{string}}{a date that conforms to the following format: \samp{"\%d\%b\%Y \%H:\%M:\%S.\%L"}}
	\lineiii{\samp{date2}}{\textit{string}}{second date to compare to \samp{date1}}
\end{tableiii}
The function returns:
\begin{itemize}
	\item a \textbf{negative value} when \samp{\textit{date1} < \textit{date2}},
	\item \textbf{zero} when \samp{\textit{date1} is equal to \textit{date2}},
	\item a \textbf{positive value} when \samp{\textit{date1} > \textit{date2}}.
\end{itemize}
If an argument doesn't conform to the expected syntax for a date
(meaning that it must match with \samp{"\%d\%b\%Y \%H:\%M:\%S.\%L"}),
an error is raised.

\textbf{Example:}

\texttt{local date1 = "19jan2003 20:12:00.000";\\
local date2 = "28dec2012 07:30:00.000";\\
local now = getNow();\\
traceLine("getNow() = '" + now + "'");\\
traceLine("compareDate('" + date1 + "', getNow()) = " + compareDate(date1, now));\\
traceLine("compareDate('" + date2 + "', getNow()) = " + compareDate(date2, now));}

\textbf{Output:}

\texttt{getNow() = '01may2006 20:42:00.500'\\
compareDate('19jan2003 20:12:00.000', getNow()) = -1\\
compareDate('28dec2012 07:30:00.000', getNow()) = 1}


\textbf{See also:}

\samp{formatDate} \ref{formatDate()}, \samp{addToDate} \ref{addToDate()}, \samp{completeDate} \ref{completeDate()}, \samp{getLastDelay} \ref{getLastDelay()}, \samp{getNow} \ref{getNow()}, \samp{setNow} \ref{setNow()}
\end{itemize}
\pdflabel{compileToCpp()}
\index{compileToCpp()}
\pdfsubsection{compileToCpp}
\begin{itemize}
	\item procedure \textbf{compileToCpp(}\samp{scriptFileName} \textbf{:} \textit{string}\textbf{, }\samp{projectDirectory} \textbf{:} \textit{string}\textbf{, }\samp{CodeWorkerDirectory} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{scriptFileName}}{\textit{string}}{the name of a script file to compile to C++}
	\lineiii{\samp{projectDirectory}}{\textit{string}}{the location where to put on the disk the scripts compiled to C++}
	\lineiii{\samp{CodeWorkerDirectory}}{\textit{string}}{the root path of \CodeWorker\ either in development or distributed state}
\end{tableiii}
Compiles the leader script file called \samp{scriptFileName} and all scripts
that might be reclaimed during the execution. The corresponding C++ files are
stored into \samp{projectDirectory} with the makefile (a Visual C++'s \textit{DSP}
file). The path to libraries and the origin of some important include files is
determined thanks to the path to \CodeWorker\ put into \samp{CodeWorkerDirectory}.

The script file cannot be a \textit{pattern script} or a \textit{parsing} script.

If an error occurs, an error message is raised.

\textbf{Example:}

\texttt{local sScriptFile = "GettingStarted/LeaderScript6.cws";\\
local sDirectory  = getWorkingPath() +\\
\makebox[2.4cm][l]{}"Scripts/Tutorial/GettingStarted/bin";\\
removeDirectory(sDirectory);\\
compileToCpp(sScriptFile, sDirectory, ".");\\
local theFiles;\\
if !scanFiles(theFiles, sDirectory, "", true) error("should have worked!");\\
traceLine("generated files:");\\
foreach i in sorted theFiles traceLine("    " + i);}

\textbf{Output:}

\texttt{generated files:\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CGExternalHandling.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CGRuntime.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CppObjectBody\_cwt.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CppObjectBody\_cwt.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CppObjectHeader\_cwt.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CppObjectHeader\_cwt.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/CppParsingTree.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/DynPackage.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/HTML2LaTeX\_cwp.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/HTML2LaTeX\_cwp.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/HTMLDocumentation\_cwt.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/HTMLDocumentation\_cwt.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/JAVAObject\_cwt.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/JAVAObject\_cwt.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/LeaderScript6.dsp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/LeaderScript6\_cws.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/LeaderScript6\_cws.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/Makefile\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/SimpleML-parsing\_cwp.cpp\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/SimpleML-parsing\_cwp.h\\
\makebox[0.8cm][l]{}e:$\backslash$Projects$\backslash$generator/Scripts/Tutorial/GettingStarted/bin/UtlException.h}
\end{itemize}
\pdflabel{completeDate()}
\index{completeDate()}
\pdfsubsection{completeDate}
\begin{itemize}
	\item function \textbf{completeDate(}\samp{date} \textbf{:} \textit{string}\textbf{, }\samp{format} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{date}}{\textit{string}}{a date-time representation to complete}
	\lineiii{\samp{format}}{\textit{string}}{the format that the \samp{date} argument conforms to}
\end{tableiii}
Completes the date passed to the argument \samp{date}, so as it conforms to the
syntax of a date in \CodeWorker\ meaning: \samp{"\%d\%b\%Y \%H:\%M:\%S.\%L"}.

Starting from today date with reset time (\samp{00:00:00.0}), it replaces date-time
characteristics with those of the parameter \samp{date} and returns the result
of the substitutions.

See \ref{formatDate()} to reading the description of a date format.
A format type was added for this function: \textbf{\samp{'\%|'}}.
Once the date has been iterated up to the end, if the format wasn't applied on it completely,
an error occurs, except if \textbf{\samp{'\%|'}} stands at the current position in the format.

\textbf{Example:}

\texttt{traceLine("Today date with reset time = '" + completeDate(getNow(), "\%d\%b\%Y") + "'");\\
local dDateAsNumber = formatDate(getNow(), "\%t");\\
traceLine("Today date (Excel-like) = '" + dDateAsNumber + "'");\\
traceLine("Preceding day = '" + completeDate(\$dDateAsNumber - 1\$, "\%t") + "'");\\
traceLine("15th of the current month = '" + completeDate("15", "\%d") + "'");\\
traceLine("august of this year = '" + completeDate("08", "\%m") + "'");\\
traceLine("15/04 = '" + completeDate("15/04", "\%d/\%m") + "'");\\
traceLine("december 31, 2003 = '" + completeDate("december 31, 2003", "\%B \%d, \%Y") + "'");}

\textbf{Output:}

\texttt{Today date with reset time = '01may2006'\\
Today date (Excel-like) = '38838.862506'\\
Preceding day = '30apr2006 20:42:00.518'\\
15th of the current month = '15may2006'\\
august of this year = '01aug2006'\\
15/04 = '15apr2006'\\
december 31, 2003 = '31dec2003'}


\textbf{See also:}

\samp{formatDate} \ref{formatDate()}, \samp{addToDate} \ref{addToDate()}, \samp{compareDate} \ref{compareDate()}, \samp{getLastDelay} \ref{getLastDelay()}, \samp{getNow} \ref{getNow()}, \samp{setNow} \ref{setNow()}
\end{itemize}
\pdflabel{completeLeftSpaces()}
\index{completeLeftSpaces()}
\pdfsubsection{completeLeftSpaces}
\begin{itemize}
	\item function \textbf{completeLeftSpaces(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{length}}{\textit{int}}{the length to obtain for \samp{text}}
\end{tableiii}
Completes the string given by argument \samp{text} with spaces to the left, so
that the resulting string takes up \samp{length} characters long. If the
argument \samp{text} contains more than \samp{length} characters, it returns
\samp{text}.

\textbf{Example:}

\texttt{traceLine("completeLeftSpaces(1,    3) = '" + completeLeftSpaces(1, 3) + "'");\\
traceLine("completeLeftSpaces(123,  3) = '" + completeLeftSpaces(123, 3) + "'");\\
traceLine("completeLeftSpaces(1234, 3) = '" + completeLeftSpaces(1234, 3) + "'");}

\textbf{Output:}

\texttt{completeLeftSpaces(1,    3) = '  1'\\
completeLeftSpaces(123,  3) = '123'\\
completeLeftSpaces(1234, 3) = '1234'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{completeRightSpaces()}
\index{completeRightSpaces()}
\pdfsubsection{completeRightSpaces}
\begin{itemize}
	\item function \textbf{completeRightSpaces(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{length}}{\textit{int}}{the length to obtain for \samp{text}}
\end{tableiii}
Completes the string given by argument \samp{text} with spaces to the right, so
that the resulting string takes up \samp{length} characters long. If the
argument \samp{text} contains more than \samp{length} characters, it returns
\samp{text}.

\textbf{Example:}

\texttt{traceLine("completeRightSpaces(1,    3) = '" + completeRightSpaces(1, 3) + "'");\\
traceLine("completeRightSpaces(123,  3) = '" + completeRightSpaces(123, 3) + "'");\\
traceLine("completeRightSpaces(1234, 3) = '" + completeRightSpaces(1234, 3) + "'");}

\textbf{Output:}

\texttt{completeRightSpaces(1,    3) = '1  '\\
completeRightSpaces(123,  3) = '123'\\
completeRightSpaces(1234, 3) = '1234'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{composeAdaLikeString()}
\index{composeAdaLikeString()}
\pdfsubsection{composeAdaLikeString}
\begin{itemize}
	\item function \textbf{composeAdaLikeString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of character to convert to a Ada-like string}
\end{tableiii}
Returns the conversion of the sequence of characters given by argument
\samp{text} to a Ada-like string, without double quote delimiters.
If \samp{text} contains a double-quote, it is repeated in the sequence.

\textbf{Example:}

\texttt{local sText = "double-quote $\backslash$" inlayed in the sequence";\\
traceLine("composeAdaLikeString('" + sText + "') = '" + composeAdaLikeString(sText) + "'");}

\textbf{Output:}

\texttt{composeAdaLikeString('double-quote " inlayed in the sequence') = 'double-quote "" inlayed in the sequence'}


\textbf{See also:}

\samp{composeCLikeString} \ref{composeCLikeString()}, \samp{composeHTMLLikeString} \ref{composeHTMLLikeString()}, \samp{composeSQLLikeString} \ref{composeSQLLikeString()}
\end{itemize}
\pdflabel{composeCLikeString()}
\index{composeCLikeString()}
\pdfsubsection{composeCLikeString}
\begin{itemize}
	\item function \textbf{composeCLikeString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of character to convert to a C-like string}
\end{tableiii}
Returns the conversion of the sequence of characters given by argument
\samp{text} to a C-like string, without double quote delimiters. It means that special characters of \samp{text}
 are replaced by their escape sequence, the rest remaining the same.

It recognizes the following escape sequences:
\begin{itemize}
	\item \textbf{'$\backslash$$\backslash$'} as \textit{backslash} ($\backslash$), ASCII value 92,
	\item \textbf{'$\backslash$' '} as \textit{single quotation mark} ('), ASCII value 39,
	\item \textbf{'$\backslash$"'} as \textit{double quotation mark} ("), ASCII value 34,
	\item \textbf{'$\backslash$a'} as \textit{alert} (BEL), ASCII value 7,
	\item \textbf{'$\backslash$b'} as \textit{backspace} (BS), ASCII value 8,
	\item \textbf{'$\backslash$f'} as \textit{formfeed} (FF), ASCII value 12,
	\item \textbf{'$\backslash$n'} as \textit{newline} (LF), ASCII value 10,
	\item \textbf{'$\backslash$r'} as \textit{carriage return} (CR), ASCII value 13,
	\item \textbf{'$\backslash$t'} as \textit{horizontal tab} (HT), ASCII value 9,
	\item \textbf{'$\backslash$v'} as \textit{vertical tab} (VT), ASCII value 11,
\end{itemize}

\textbf{Example:}

\texttt{local sText = "$\backslash$t=tabulation,$\backslash$n=newline";\\
traceLine("composeCLikeString('" + sText + "') = '" + composeCLikeString(sText) + "'");}

\textbf{Output:}

\texttt{composeCLikeString('    =tabulation,\\
=newline') = '$\backslash$t=tabulation,$\backslash$n=newline'}


\textbf{See also:}

\samp{composeAdaLikeString} \ref{composeAdaLikeString()}, \samp{composeHTMLLikeString} \ref{composeHTMLLikeString()}, \samp{composeSQLLikeString} \ref{composeSQLLikeString()}
\end{itemize}
\pdflabel{composeHTMLLikeString()}
\index{composeHTMLLikeString()}
\pdfsubsection{composeHTMLLikeString}
\begin{itemize}
	\item function \textbf{composeHTMLLikeString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of character to convert to an HTML-like string}
\end{tableiii}
Returns the conversion of the sequence of characters given by argument
\samp{tex} to an HTML-like string. It means that special characters of \samp{text}
are replaced by their HTML escape sequence (\textbf{\&...;}), the rest remaining the same.

\textbf{Example:}

\texttt{local sText = "< \& > aren't admitted by HTML";\\
traceLine("composeHTMLLikeString('" + sText + "') = '" + composeHTMLLikeString(sText) + "'");}

\textbf{Output:}

\texttt{composeHTMLLikeString('< \& > aren't admitted by HTML') = '\&lt; \&amp; \&gt; aren\&\#39;t admitted by HTML'}


\textbf{See also:}

\samp{composeCLikeString} \ref{composeCLikeString()}, \samp{composeAdaLikeString} \ref{composeAdaLikeString()}, \samp{composeSQLLikeString} \ref{composeSQLLikeString()}
\end{itemize}
\pdflabel{composeSQLLikeString()}
\index{composeSQLLikeString()}
\pdfsubsection{composeSQLLikeString}
\begin{itemize}
	\item function \textbf{composeSQLLikeString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of character to convert to a SQL-like string}
\end{tableiii}
Returns the conversion of the sequence of characters given by argument
\samp{text} to a SQL-like string, without single quote delimiters. It means that special characters of \samp{text}
 are replaced by their escape sequence, the rest remaining the same.

It recognizes the following escape sequences:
\begin{itemize}
	\item \textbf{'$\backslash$$\backslash$'} as \textit{backslash} ($\backslash$), ASCII value 92,
	\item \textbf{'$\backslash$' '} as \textit{single quotation mark} ('), ASCII value 39,
	\item \textbf{'$\backslash$"'} as \textit{double quotation mark} ("), ASCII value 34,
	\item \textbf{'$\backslash$a'} as \textit{alert} (BEL), ASCII value 7,
	\item \textbf{'$\backslash$b'} as \textit{backspace} (BS), ASCII value 8,
	\item \textbf{'$\backslash$f'} as \textit{formfeed} (FF), ASCII value 12,
	\item \textbf{'$\backslash$n'} as \textit{newline} (LF), ASCII value 10,
	\item \textbf{'$\backslash$r'} as \textit{carriage return} (CR), ASCII value 13,
	\item \textbf{'$\backslash$t'} as \textit{horizontal tab} (HT), ASCII value 9,
	\item \textbf{'$\backslash$v'} as \textit{vertical tab} (VT), ASCII value 11,
\end{itemize}
The function translates the single quote to an escape sequence \textbf{"$\backslash$'"}, instead of
repeating twice the single quote as in the SQL-standard. It presents the advantage
of being more readable, but if you encounters a drawback in using this translation,
apply \samp{replaceString()} to change \textbf{"$\backslash$'"} in \textbf{"''"}.

\textbf{Example:}

\texttt{local sText = "$\backslash$t=tabulation,$\backslash$n=newline,'=single quote,$\backslash$"=double quote";\\
traceLine("composeSQLLikeString('" + sText + "') = '" + composeSQLLikeString(sText) + "'");}

\textbf{Output:}

\texttt{composeSQLLikeString('  =tabulation,\\
=newline,'=single quote,"=double quote') = '$\backslash$t=tabulation,$\backslash$n=newline,''=single quote,$\backslash$"=double quote'}


\textbf{See also:}

\samp{composeCLikeString} \ref{composeCLikeString()}, \samp{composeAdaLikeString} \ref{composeAdaLikeString()}, \samp{composeHTMLLikeString} \ref{composeHTMLLikeString()}
\end{itemize}
\pdflabel{computeMD5()}
\index{computeMD5()}
\pdfsubsection{computeMD5}
\begin{itemize}
	\item function \textbf{computeMD5(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{the string to encrypt in MD5}
\end{tableiii}
Computes the MD5 of a string.

This optimized MD5 implementation conforms to RFC 1321.\\
Source: http://www.cr0.net:8040/code/crypto/md5/\\
Copyright 2001-2004 Christophe Devine

\textbf{Example:}

\texttt{local sSentence = "Garfield squashed 5 spiders yesterday";\\
local sCode = computeMD5(sSentence);\\
if sCode != "B2D989F0C0501E9A9D4A9F1B4D06E2C5" \{\\
\makebox[0.8cm][l]{}error("bad result from 'computeMD5()'!");\\
\}\\
traceLine("computeMD5('" + sSentence + "') = " + sCode);}

\textbf{Output:}

\texttt{computeMD5('Garfield squashed 5 spiders yesterday') = B2D989F0C0501E9A9D4A9F1B4D06E2C5}
\end{itemize}
\pdflabel{copyFile()}
\index{copyFile()}
\pdfsubsection{copyFile}
\begin{itemize}
	\item procedure \textbf{copyFile(}\samp{sourceFileName} \textbf{:} \textit{string}\textbf{, }\samp{destinationFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{sourceFileName}}{\textit{string}}{the name of the file to copy}
	\lineiii{\samp{destinationFileName}}{\textit{string}}{the name of the copy}
\end{tableiii}
This procedure copies a file \samp{sourceFileName} to another location 
\samp{destinationFileName}. It raises an error if something wrong has happened
(either the source file doesn't exist or permissions are insufficient for copy).

\textbf{Example:}

\texttt{deleteFile("Documentation/readme.txt");\\
copyFile("readme.txt", "Documentation/readme.txt");\\
traceLine("file 'readme.txt' has been copied successfully!");}

\textbf{Output:}

\texttt{file 'readme.txt' has been copied successfully!}


\textbf{See also:}

\samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{copyGenerableFile()}
\index{copyGenerableFile()}
\pdfsubsection{copyGenerableFile}
\begin{itemize}
	\item procedure \textbf{copyGenerableFile(}\samp{sourceFileName} \textbf{:} \textit{string}\textbf{, }\samp{destinationFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{sourceFileName}}{\textit{string}}{the name of the file to copy}
	\lineiii{\samp{destinationFileName}}{\textit{string}}{the name of the copy}
\end{tableiii}
This procedure copies a generable file \samp{sourceFileName} to another location 
\samp{destinationFileName} if the files have differences in the hand-typed text.
 It raises an error if something wrong has happened (either the source file doesn't
exist or permissions are insufficient for copy).

A generable file is any source file containing protected areas or expandable markups.


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{copySmartDirectory()}
\index{copySmartDirectory()}
\pdfsubsection{copySmartDirectory}
\begin{itemize}
	\item procedure \textbf{copySmartDirectory(}\samp{sourceDirectory} \textbf{:} \textit{string}\textbf{, }\samp{destinationPath} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{sourceDirectory}}{\textit{string}}{the name of the directory to copy}
	\lineiii{\samp{destinationPath}}{\textit{string}}{the path where to copy the directory}
\end{tableiii}
This procedure copies a directory \samp{sourceDirectory} to another location
\samp{destinationPath} recursively, checking for each file if it doesn't exist yet
or it the content has changed. It avoids copying a file whereas it has no impact,
and then modifying the last changing date of the destination file.

It raises an error if something wrong has happened (the source directory
must exist and permissions must be sufficient to copy if required). Note that
empty directories are ignored.


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{copySmartFile()}
\index{copySmartFile()}
\pdfsubsection{copySmartFile}
\begin{itemize}
	\item function \textbf{copySmartFile(}\samp{sourceFileName} \textbf{:} \textit{string}\textbf{, }\samp{destinationFileName} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{sourceFileName}}{\textit{string}}{the name of the file to copy}
	\lineiii{\samp{destinationFileName}}{\textit{string}}{the name of the copy}
\end{tableiii}
This function copies a file \samp{sourceFileName} to another location 
\samp{destinationFileName} only if either file \samp{destinationFileName}
doesn't exist yet or the content of file \samp{destinationFileName} is
different of the content of file \samp{sourceFileName}. It avoids copying
a file when it has no impact, and then modifying the last changing date of
the destination file. It raises an error if something wrong has happened
(either the file doesn't exist or permissions aren't sufficient to copy when required).

If the function copies the file, and only in that case, it return \samp{true}.

\textbf{Example:}

\texttt{deleteFile("Documentation/readme.txt");\\
traceLine("First call to the 'copySmartFile()': the file is copied");\\
copySmartFile("readme.txt", "Documentation/readme.txt");\\
traceLine("Second call to the 'copySmartFile()': nothing is done");\\
copySmartFile("readme.txt", "Documentation/readme.txt");}

\textbf{Output:}

\texttt{First call to the 'copySmartFile()': the file is copied\\
Second call to the 'copySmartFile()': nothing is done}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{coreString()}
\index{coreString()}
\pdfsubsection{coreString}
\begin{itemize}
	\item function \textbf{coreString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{pos} \textbf{:} \textit{int}\textbf{, }\samp{lastRemoved} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{the string to work on}
	\lineiii{\samp{pos}}{\textit{int}}{the beginning position, inclusive, starting at \textit{0}}
	\lineiii{\samp{lastRemoved}}{\textit{int}}{the number of characters to ignore at the end of \samp{text}}
\end{tableiii}
Returns a substring of argument \samp{text}.
The substring begins at the position specified by argument \samp{pos} and ignores the last characters, which number is specifier by argument \samp{lastRemoved}.
The first character starts at position \textit{0}, the next at position \textit{1}, and so on.

\textbf{Example:}

\texttt{local sSentence = "Do you believe in human being?";\\
traceLine("coreString('" + sSentence + "', 18, 7) = '" + coreString(sSentence, 18, 7) + "'");}

\textbf{Output:}

\texttt{coreString('Do you believe in human being?', 18, 7) = 'human'}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{countStringOccurences()}
\index{countStringOccurences()}
\pdfsubsection{countStringOccurences}
\begin{itemize}
	\item function \textbf{countStringOccurences(}\samp{string} \textbf{:} \textit{string}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{string}}{\textit{string}}{sequence of characters where occurrences of substring \samp{text} are to be counted}
	\lineiii{\samp{text}}{\textit{string}}{substring to count}
\end{tableiii}
Returns the number of times the substring specified by argument \samp{text} is found into the sequence of characters held by argument \samp{string}.

\textbf{Example:}

\texttt{local sSentence = "Do you believe in human being?";\\
traceLine("countStringOccurences('" + sSentence + "', 'in') = " + countStringOccurences(sSentence, "in"));}

\textbf{Output:}

\texttt{countStringOccurences('Do you believe in human being?', 'in') = 2}


\textbf{See also:}

\samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{createDirectory()}
\index{createDirectory()}
\pdfsubsection{createDirectory}
\begin{itemize}
	\item function \textbf{createDirectory(}\samp{path} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{the path of directories to create}
\end{tableiii}
This function creates a new directory and returns whether the operation has succeeded or not.

It fails if the complete path already exists, or if it is invalid.
\end{itemize}
\pdflabel{createINETClientSocket()}
\index{createINETClientSocket()}
\pdfsubsection{createINETClientSocket}
\begin{itemize}
	\item function \textbf{createINETClientSocket(}\samp{remoteAddress} \textbf{:} \textit{string}\textbf{, }\samp{port} \textbf{:} \textit{int}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{remoteAddress}}{\textit{string}}{a remote IP address (Internet namespace)}
	\lineiii{\samp{port}}{\textit{int}}{a remote port number}
\end{tableiii}
This function creates a client socket and connects it to the specified remote \samp{port},
at the specified address IP \samp{remoteAddress}, and returns a new socket
descriptor. The socket is of type \textit{stream}.

Once the creation has achieved, use directly the \textit{send}/\textit{receive} functions
or \samp{attachInputToSocket()}/\samp{attachOutputToSocket} for reading/writing
to the socket via a \textit{BNF-parsing}/\textit{template-based} script.


\textbf{See also:}

\samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{createINETServerSocket()}
\index{createINETServerSocket()}
\pdfsubsection{createINETServerSocket}
\begin{itemize}
	\item function \textbf{createINETServerSocket(}\samp{port} \textbf{:} \textit{int}\textbf{, }\samp{backLog} \textbf{:} \textit{int}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{port}}{\textit{int}}{a local port number}
	\lineiii{\samp{backLog}}{\textit{int}}{maximum queue length for incoming connection (1-5)}
\end{tableiii}
This function creates a server socket bound to \samp{port} and returns a
new socket descriptor. The socket is of type \textit{stream}.

The argument \samp{backLog} specifies the size of the queue connection.
A new connection is refused when the queue is full.

Once the creation has achieved, use the function \samp{acceptSocket()} to wait for
a new client connection (blocking call).


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{createIterator()}
\index{createIterator()}
\pdfsubsection{createIterator}
\begin{itemize}
	\item function \textbf{createIterator(}\samp{i} \textbf{:} \textit{iterator}\textbf{, }\samp{list} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator to initialize}
	\lineiii{\samp{list}}{\textit{treeref}}{the iterator will point to the beginning of this list}
\end{tableiii}
The variable \samp{i} will become an iterator pointing to the first item of the list.

If the list is empty, there is no iterator created and the function returns \samp{false}.

\samp{i} must have been declared before.

\textbf{Example:}

\texttt{local list = \{"parsing", "tool", "and", "code", "generation"\};\\
local it;\\
if !createIterator(it, list) error("shouldn't be the case!");\\
do \{\\
\makebox[0.8cm][l]{}traceLine("$\backslash$t" + it);\\
\} while next(it);}

\textbf{Output:}

\texttt{\makebox[0.8cm][l]{}parsing\\
\makebox[0.8cm][l]{}tool\\
\makebox[0.8cm][l]{}and\\
\makebox[0.8cm][l]{}code\\
\makebox[0.8cm][l]{}generation}


\textbf{See also:}

\samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}, \samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}
\end{itemize}
\pdflabel{createReverseIterator()}
\index{createReverseIterator()}
\pdfsubsection{createReverseIterator}
\begin{itemize}
	\item function \textbf{createReverseIterator(}\samp{i} \textbf{:} \textit{iterator}\textbf{, }\samp{list} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator to initialize}
	\lineiii{\samp{list}}{\textit{treeref}}{the iterator will point to the end of this list}
\end{tableiii}
The variable \samp{i} will become an iterator pointing to the last item of the list
and will iterate in the reverse order.

If the list is empty, there is no iterator created and the function returns \samp{false}.

\samp{i} must have been declared before.

\textbf{Example:}

\texttt{local list = \{"parsing", "tool", "and", "code", "generation"\};\\
local it;\\
if !createReverseIterator(it, list) error("shouldn't be the case!");\\
do \{\\
\makebox[0.8cm][l]{}traceLine("$\backslash$t" + it);\\
\} while next(it);}

\textbf{Output:}

\texttt{\makebox[0.8cm][l]{}generation\\
\makebox[0.8cm][l]{}code\\
\makebox[0.8cm][l]{}and\\
\makebox[0.8cm][l]{}tool\\
\makebox[0.8cm][l]{}parsing}


\textbf{See also:}

\samp{createIterator} \ref{createIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}, \samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}
\end{itemize}
\pdflabel{createVirtualFile()}
\index{createVirtualFile()}
\pdfsubsection{createVirtualFile}
\begin{itemize}
	\item function \textbf{createVirtualFile(}\samp{handle} \textbf{:} \textit{string}\textbf{, }\samp{content} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{handle}}{\textit{string}}{the name of the virtual file to create}
	\lineiii{\samp{content}}{\textit{string}}{the content to put into the virtual file}
\end{tableiii}
This function allows creating a \textit{virtual} file. The \samp{handle} parameter
corresponds to the name given to the \textit{virtual} file, which may be any
sequence of characters. The virtual file is populated with the text assigned to
the \samp{content} argument.

The function always returns \samp{true}, but it may be changed in the future if
some naming rules will be imposed to the handles for instance. Calling the function
to an existing \textit{virtual} file causes the content to be updated with the
new one.

\CodeWorker\ manipulates the concept of file that isn't persistent on a physical
disk, but remains stored in memory. These \textit{virtual} files may be used
everywhere a file is required so as to replace it: copy, parsing or text generation.
When \CodeWorker\ tries to open a file for reading or writing, it starts looking
for a \textit{virtual} file that has the same name.\\
Once a \textit{virtual} file doesn't serve anymore, don't forget to free the
useless memory it takes up by calling the \samp{deleteVirtualFile()} function
(see \ref{deleteVirtualFile()}).

\textbf{Example:}

\texttt{createVirtualFile("littleScript.cws",\\
\makebox[3.2cm][l]{}"a protected area:" + endl() +\\
\makebox[3.2cm][l]{}"@setProtectedArea($\backslash$"umbrella$\backslash$");@finished!");\\
createVirtualFile("littleText.txt", "");\\
generate("littleScript.cws", project, "littleText.txt");\\
traceLine("generated (virtual) file:");\\
traceLine(loadVirtualFile("littleText.txt"));\\
deleteVirtualFile("littleText.txt");\\
deleteVirtualFile("littleScript.cws");}

\textbf{Output:}

\texttt{generated (virtual) file:\\
a protected area:\\
//\#\#protect\#\#"umbrella"\\
//\#\#protect\#\#"umbrella"\\
finished!}


\textbf{See also:}

\samp{createVirtualTemporaryFile} \ref{createVirtualTemporaryFile()}, \samp{deleteVirtualFile} \ref{deleteVirtualFile()}, \samp{existVirtualFile} \ref{existVirtualFile()}, \samp{loadVirtualFile} \ref{loadVirtualFile()}
\end{itemize}
\pdflabel{createVirtualTemporaryFile()}
\index{createVirtualTemporaryFile()}
\pdfsubsection{createVirtualTemporaryFile}
\begin{itemize}
	\item function \textbf{createVirtualTemporaryFile(}\samp{content} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{content}}{\textit{string}}{the content to put into the virtual file}
\end{tableiii}
This function allows creating a \textit{virtual} file, for which the name of the
virtual file must be chosen by the routine. The virtual file is populated with
the text assigned to the \samp{content} argument.

The function returns the name that the routine has composed for this virtual file.
The only difference with the function \samp{createVirtualFile()} (see
\ref{createVirtualFile()}) lies in the way to choose of the virtual file name.
After creating the file, it behaves as any other virtual file.

\textbf{Example:}

\texttt{local sScriptFile = createVirtualTemporaryFile(\\
\makebox[3.2cm][l]{}"a protected area:" + endl() +\\
\makebox[3.2cm][l]{}"@setProtectedArea($\backslash$"umbrella$\backslash$");@finished!");\\
traceLine("Name of the (virtual) script file = '" + sScriptFile + "':");\\
local sGeneratedFile = createVirtualTemporaryFile("");\\
generate(sScriptFile, project, sGeneratedFile);\\
traceLine("generated (virtual) file '" + sGeneratedFile + "':");\\
traceLine(loadVirtualFile(sGeneratedFile));\\
deleteVirtualFile(sGeneratedFile);\\
deleteVirtualFile(sScriptFile);}

\textbf{Output:}

\texttt{Name of the (virtual) script file = '.\~{}\#0':\\
generated (virtual) file '.\~{}\#1':\\
a protected area:\\
//\#\#protect\#\#"umbrella"\\
//\#\#protect\#\#"umbrella"\\
finished!}


\textbf{See also:}

\samp{createVirtualFile} \ref{createVirtualFile()}, \samp{deleteVirtualFile} \ref{deleteVirtualFile()}, \samp{existVirtualFile} \ref{existVirtualFile()}, \samp{loadVirtualFile} \ref{loadVirtualFile()}
\end{itemize}
\pdflabel{cutString()}
\index{cutString()}
\pdfsubsection{cutString}
\begin{itemize}
	\item procedure \textbf{cutString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{separator} \textbf{:} \textit{string}\textbf{, }\samp{list} \textbf{:} \textit{stringlist}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{the sequence of characters to split}
	\lineiii{\samp{separator}}{\textit{string}}{the substring that separates slices}
	\lineiii{\samp{list}}{\textit{stringlist}}{the list that will contain slices}
\end{tableiii}
This procedure looks for slices into the argument \samp{text}, which are
separated by the substring put into argument \samp{separator}. These slices
are pushed into an array node as items called \samp{list}.

If the argument \samp{text} doesn't contain any occurrence  of the argument
\samp{separator}, the argument \samp{list} will contain only one item that
is \samp{text}.

\textbf{Example:}

\texttt{local sText = "a yellow submarine";\\
local listOfItems;\\
traceLine("cutString('" + sText + "', ' ', listOfItems):");\\
cutString(sText, " ", listOfItems);\\
traceObject(listOfItems);}

\textbf{Output:}

\texttt{cutString('a yellow submarine', ' ', listOfItems):\\
Tracing variable 'listOfItems':\\
\makebox[0.8cm][l]{}["0" -> "a", "1" -> "yellow", "2" -> "submarine"]\\
End of variable's trace 'listOfItems'.}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{decodeURL()}
\index{decodeURL()}
\pdfsubsection{decodeURL}
\begin{itemize}
	\item function \textbf{decodeURL(}\samp{URL} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{URL}}{\textit{string}}{readable URL to encode}
\end{tableiii}
Decode an URL from an HTTP request, meaning that the \textbf{'+'} character changes in a space and
all hexadecimal descriptions of bytes (2 digits preceded by \textbf{'\%'}) are
converted to characters.

Note that conversions are transparent while doing HTTP requests.

\textbf{Example:}

\texttt{local sURL = "Roger+Rabbit\%26\%25\%24\%3D\%21\%3F";\\
traceLine("URL before HTTP decoding = '" + sURL + "'");\\
traceLine("URL after HTTP decoding = '" + decodeURL(sURL) + "'");}

\textbf{Output:}

\texttt{URL before HTTP decoding = 'Roger+Rabbit\%26\%25\%24\%3D\%21\%3F'\\
URL after HTTP decoding = 'Roger Rabbit\&\%\$=!?'}


\textbf{See also:}

\samp{encodeURL} \ref{encodeURL()}
\end{itemize}
\pdflabel{decrement()}
\index{decrement()}
\pdfsubsection{decrement}
\begin{itemize}
	\item function \textbf{decrement(}\samp{number} \textbf{:} \textit{doubleref}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{doubleref}}{variable to decrement}
\end{tableiii}
The result of \samp{decrement} operation is the value of argument \samp{number} \textit{minus} one.
While the result is obtained, the variable \samp{number} is decremented.

\textbf{Example:}

\texttt{local iNumber = 32;\\
traceLine("iNumber = " + iNumber);\\
traceLine("decrement(iNumber) = " + decrement(iNumber));\\
// the variable 'number' has been decremented:\\
traceLine("iNumber = " + iNumber);}

\textbf{Output:}

\texttt{iNumber = 32\\
decrement(iNumber) = 31\\
iNumber = 31}


\textbf{See also:}

\samp{increment} \ref{increment()}, \samp{floor} \ref{floor()}, \samp{ceil} \ref{ceil()}
\end{itemize}
\pdflabel{deleteFile()}
\index{deleteFile()}
\pdfsubsection{deleteFile}
\begin{itemize}
	\item function \textbf{deleteFile(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to delete}
\end{tableiii}
Deletes the file whose name is given by parameter \samp{filename}. If the file
cannot be found or if it cannot be deleted, the function returns \samp{false}.

Note that if the file name is a relative path, it is understood as being relative
to the current directory where the interpreter has been launched. So, the
interpreter doesn't search into include directories passed to the command line
(option \samp{-I}), to offer a more secure use.

\textbf{Example:}

\texttt{copyFile("readme.txt", "Documentation/readme.txt");\\
traceLine("Result of deleting file 'Documentation/readme.txt' = '" + deleteFile("Documentation/readme.txt") + "'");}

\textbf{Output:}

\texttt{Result of deleting file 'Documentation/readme.txt' = 'true'}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{deleteVirtualFile()}
\index{deleteVirtualFile()}
\pdfsubsection{deleteVirtualFile}
\begin{itemize}
	\item function \textbf{deleteVirtualFile(}\samp{handle} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{handle}}{\textit{string}}{the name of the virtual file to delete}
\end{tableiii}
This function removes from memory the \textit{virtual} file whose name is given
by the \samp{handle} parameter.

It returns \samp{true} if the virtual file was created before and has been
removed successfully.


\textbf{See also:}

\samp{createVirtualFile} \ref{createVirtualFile()}, \samp{createVirtualTemporaryFile} \ref{createVirtualTemporaryFile()}, \samp{existVirtualFile} \ref{existVirtualFile()}, \samp{loadVirtualFile} \ref{loadVirtualFile()}
\end{itemize}
\pdflabel{div()}
\index{div()}
\pdfsubsection{div}
\begin{itemize}
	\item function \textbf{div(}\samp{dividend} \textbf{:} \textit{double}\textbf{, }\samp{divisor} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{dividend}}{\textit{double}}{the dividend}
	\lineiii{\samp{divisor}}{\textit{double}}{the divisor}
\end{tableiii}
Returns the result of arithmetic division \samp{dividend} \textbf{/} \samp{divisor}.
Members are converted from strings to numbers, supposed being worth \samp{0} if a parsing error occurs;
then the division is processed, and the result is converted to a string,
skipping fractional part if all digits after the dot are \textit{0}.

Remember that the symbol \textbf{'/'} doesn't mean anything in the standard syntax of the
language, so there is no way to confuse for expressing a division.
However, it exists an escape mode that allows writing arithmetic expressions
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{dividend} \textbf{/} \textit{divisor}\$}
is equivalent to \samp{div(\textit{dividend}, \textit{divisor})}.

\textbf{Example:}

\texttt{local a = 3.2;\\
traceLine(a + " / 2 = " + div(a, "2"));\\
traceLine(a + " / 0.2 = " + div(a, 0.2) + " <- integer value");}

\textbf{Output:}

\texttt{3.2 / 2 = 1.6\\
3.2 / 0.2 = 16 <- integer value}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{sub} \ref{sub()}, \samp{mult} \ref{mult()}, \samp{exp} \ref{exp()}, \samp{log} \ref{log()}, \samp{mod} \ref{mod()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{duplicateIterator()}
\index{duplicateIterator()}
\pdfsubsection{duplicateIterator}
\begin{itemize}
	\item function \textbf{duplicateIterator(}\samp{oldIt} \textbf{:} \textit{iterator}\textbf{, }\samp{newIt} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{oldIt}}{\textit{iterator}}{the original iterator to duplicate}
	\lineiii{\samp{newIt}}{\textit{treeref}}{copy of the original iterator}
\end{tableiii}
Duplicates an iterator or returns \samp{false} if \textit{oldIt} isn't an iterator.

\textbf{Example:}

\texttt{local list = \{"parsing", "tool", "and", "code", "generation"\};\\
foreach i in list \{\\
\makebox[0.8cm][l]{}local it;\\
\makebox[0.8cm][l]{}if !duplicateIterator(i, it) error("shouldn't be the case!");\\
\makebox[0.8cm][l]{}traceText("$\backslash$t'" + it + "' - ");\\
\makebox[0.8cm][l]{}if prec(it) traceLine("precedent value = '" + it + "'");\\
\makebox[0.8cm][l]{}else traceLine("no precedent value!");\\
\}}

\textbf{Output:}

\texttt{\makebox[0.8cm][l]{}'parsing' - no precedent value!\\
\makebox[0.8cm][l]{}'tool' - precedent value = 'parsing'\\
\makebox[0.8cm][l]{}'and' - precedent value = 'tool'\\
\makebox[0.8cm][l]{}'code' - precedent value = 'and'\\
\makebox[0.8cm][l]{}'generation' - precedent value = 'code'}


\textbf{See also:}

\samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}
\end{itemize}
\pdflabel{encodeURL()}
\index{encodeURL()}
\pdfsubsection{encodeURL}
\begin{itemize}
	\item function \textbf{encodeURL(}\samp{URL} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{URL}}{\textit{string}}{readable URL to encode}
\end{tableiii}
Encode an URL for an HTTP request, meaning that the space character changes in \textbf{'+'} and
all non-alphanumeric characters are encoded in hexadecimal, preceded by \textbf{'\%'}.

Note that conversions are transparent while doing HTTP requests.

\textbf{Example:}

\texttt{local sURL = "Roger Rabbit\&\%\$=!?";\\
traceLine("URL before HTTP encoding = '" + sURL + "'");\\
traceLine("URL after HTTP encoding = '" + encodeURL(sURL) + "'");}

\textbf{Output:}

\texttt{URL before HTTP encoding = 'Roger Rabbit\&\%\$=!?'\\
URL after HTTP encoding = 'Roger\%20Rabbit\%26\%25\%24\%3D\%21\%3F'}


\textbf{See also:}

\samp{decodeURL} \ref{decodeURL()}
\end{itemize}
\pdflabel{endl()}
\index{endl()}
\pdfsubsection{endl}
\begin{itemize}
	\item function \textbf{endl(}\textbf{) :} \textit{string}

Returns an end of line, value depending on the platform on which the
script is executed. It returns \samp{"$\backslash$r$\backslash$n"} under \textit{Windows},
and \samp{"$\backslash$n"} on any \textit{UNIX} platform.

\textbf{Example:}

\texttt{traceLine("endl() = '" + endl() + "'");\\
traceLine(" length = " + lengthString(endl()));\\
traceLine(" first ASCII character = " + charToInt(charAt(endl(), 0)));}

\textbf{Output:}

\texttt{endl() = '\\
'\\
\makebox[0.8cm][l]{}length = 2\\
\makebox[0.8cm][l]{}first ASCII character = 13}
\end{itemize}
\pdflabel{endString()}
\index{endString()}
\pdfsubsection{endString}
\begin{itemize}
	\item function \textbf{endString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{end} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to test}
	\lineiii{\samp{end}}{\textit{string}}{the postfix}
\end{tableiii}
\samp{"true"} if the argument \samp{end} is a postfix of the character
sequence represented by \samp{text}; \samp{""} otherwise. Note also that
\samp{"true"} will be returned if \samp{end} is an empty string or is
equal to argument \samp{text}.

\textbf{Example:}

\texttt{local sText = "airport";\\
traceLine("endString('" + sText + "', 'port') = '" + endString(sText, "port") + "'");}

\textbf{Output:}

\texttt{endString('airport', 'port') = 'true'}


\textbf{See also:}

\samp{equalsIgnoreCase} \ref{equalsIgnoreCase()}, \samp{findFirstChar} \ref{findFirstChar()}, \samp{findLastString} \ref{findLastString()}, \samp{findNextString} \ref{findNextString()}, \samp{findString} \ref{findString()}, \samp{startString} \ref{startString()}
\end{itemize}
\pdflabel{environTable()}
\index{environTable()}
\pdfsubsection{environTable}
\begin{itemize}
	\item procedure \textbf{environTable(}\samp{table} \textbf{:} \textit{tree}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{table}}{\textit{tree}}{will contain the list of all environment variable names}
\end{tableiii}
The procedure returns the array of all environment variable in the argument \samp{table}.
The name of the environment variable is assigned to the value of the item.

\textbf{Example:}

\texttt{local theTable;\\
environTable(theTable);\\
foreach i in theTable \{\\
\makebox[0.8cm][l]{}if i.startString("PROCESSOR") traceLine(i);\\
\}}

\textbf{Output:}

\texttt{PROCESSOR\_ARCHITECTURE=x86\\
PROCESSOR\_IDENTIFIER=x86 Family 15 Model 2 Stepping 7, GenuineIntel\\
PROCESSOR\_LEVEL=15\\
PROCESSOR\_REVISION=0207}


\textbf{See also:}

\samp{getEnv} \ref{getEnv()}, \samp{existEnv} \ref{existEnv()}, \samp{putEnv} \ref{putEnv()}, \samp{system} \ref{system()}
\end{itemize}
\pdflabel{equal()}
\index{equal()}
\pdfsubsection{equal}
\begin{itemize}
	\item function \textbf{equal(}\samp{left} \textbf{:} \textit{double}\textbf{, }\samp{right} \textbf{:} \textit{double}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{double}}{first number to compare}
	\lineiii{\samp{right}}{\textit{double}}{second number to compare}
\end{tableiii}
Compares two numbers and returns \samp{true} if they are identical.

Sometimes, the operator \textbf{'=='} is suitable to compare numbers, in the
case where their decimal representation are strictly the same. But be careful
that expression \textit{"7.0" == "7"} is \samp{false}!

However, it exists an escape mode that allows writing arithmetic comparisons
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{left} \textbf{==} \textit{right}\$}
is equivalent to \samp{equal(\textit{left}, \textit{right})}.

\textbf{Example:}

\texttt{traceLine("equal(7, '7.0') = '" + equal(7, "7.0") + "'");\\
traceLine("7 == '7.0' = '" + (7 == "7.0") + "'");}

\textbf{Output:}

\texttt{equal(7, '7.0') = 'true'\\
7 == '7.0' = ''}


\textbf{See also:}

\samp{inf} \ref{inf()}, \samp{sup} \ref{sup()}
\end{itemize}
\pdflabel{equalsIgnoreCase()}
\index{equalsIgnoreCase()}
\pdfsubsection{equalsIgnoreCase}
\begin{itemize}
	\item function \textbf{equalsIgnoreCase(}\samp{left} \textbf{:} \textit{string}\textbf{, }\samp{right} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{string}}{first string to compare}
	\lineiii{\samp{right}}{\textit{string}}{second string to compare}
\end{tableiii}
Compares two strings, ignoring the case. It returns \samp{true} when the comparison succeeds.

\textbf{Example:}

\texttt{traceLine("equalsIgnoreCase('BANANA', 'Banana') = '" + equalsIgnoreCase("BANANA", "Banana") + "'");\\
traceLine("equalsIgnoreCase('BANANA', 'APPLE') = '" + equalsIgnoreCase("BANANA", "APPLE") + "'");}

\textbf{Output:}

\texttt{equalsIgnoreCase('BANANA', 'Banana') = 'true'\\
equalsIgnoreCase('BANANA', 'APPLE') = ''}


\textbf{See also:}

\samp{endString} \ref{endString()}
\end{itemize}
\pdflabel{equalTrees()}
\index{equalTrees()}
\pdfsubsection{equalTrees}
\begin{itemize}
	\item function \textbf{equalTrees(}\samp{firstTree} \textbf{:} \textit{treeref}\textbf{, }\samp{secondTree} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{firstTree}}{\textit{treeref}}{a parse tree}
	\lineiii{\samp{secondTree}}{\textit{treeref}}{another parse tree to compare with the first one}
\end{tableiii}
Compares two parse trees and returns \samp{true} if they are identical
(same sub-nodes, same values, same entry keys on arrays of node, repeated
recursively).

\textbf{Example:}

\texttt{local myTree1 = "monkey";\\
insert myTree1.hobbies = "to eat bretzel";\\
insert myTree1["Everest"] = "mountain";\\
insert myTree1["Tea spoon"] = "silverware";\\
local myTree2 = "monkey";\\
insert myTree2.hobbies = "to eat bretzel";\\
insert myTree2["Everest"] = "mountain";\\
insert myTree2["Tea spoon"] = "silverware";\\
traceLine("equalTrees(myTree1, myTree2) = '" + equalTrees(myTree1, myTree2) + "'");}

\textbf{Output:}

\texttt{equalTrees(myTree1, myTree2) = 'true'}


\textbf{See also:}

\samp{slideNodeContent} \ref{slideNodeContent()}
\end{itemize}
\pdflabel{error()}
\index{error()}
\pdfsubsection{error}
\begin{itemize}
	\item procedure \textbf{error(}\samp{errorMessage} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{errorMessage}}{\textit{string}}{an error message to throw}
\end{tableiii}
It raises the argument \samp{errorMessage} as an error that may be caught
into a \samp{try/catch} statement \ref{catch}.

\textbf{Example:}

\texttt{try \{\\
\makebox[0.8cm][l]{}error("I have forced an error!");\\
\makebox[0.8cm][l]{}traceLine("I shouldn't write this message...");\\
\} catch(sError) \{\\
\makebox[0.8cm][l]{}traceLine("I caught the error: '" + sError + "'");\\
\}}

\textbf{Output:}

\texttt{I caught the error: 'I have forced an error!\\
TEX-manual.cwt(508): main scope\\
writeFunctionDescription\\
'}
\end{itemize}
\pdflabel{executeString()}
\index{executeString()}
\pdfsubsection{executeString}
\begin{itemize}
	\item procedure \textbf{executeString(}\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{command} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed via \textit{this} variable}
	\lineiii{\samp{command}}{\textit{string}}{some instructions of the scripting language to execute}
\end{tableiii}
This procedure interprets the argument \samp{command} as instructions to
execute, written in the scripting language.

\textbf{Example:}

\texttt{local myContext;\\
executeString(myContext,\\
\makebox[2.8cm][l]{}"traceLine($\backslash$"Beginning of string execution:$\backslash$");"\\
\makebox[2.8cm][l]{}"insert this.name = $\backslash$"execution$\backslash$";"\\
\makebox[2.8cm][l]{}"traceLine($\backslash$"End of string execution.$\backslash$");");\\
traceLine("What we did during the string execution:");\\
traceObject(myContext);}

\textbf{Output:}

\texttt{Beginning of string execution:\\
End of string execution.\\
What we did during the string execution:\\
Tracing variable 'myContext':\\
\makebox[0.8cm][l]{}name = "execution"\\
End of variable's trace 'myContext'.}


\textbf{See also:}

\samp{executeStringQuiet} \ref{executeStringQuiet()}
\end{itemize}
\pdflabel{executeStringQuiet()}
\index{executeStringQuiet()}
\pdfsubsection{executeStringQuiet}
\begin{itemize}
	\item function \textbf{executeStringQuiet(}\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{command} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed with \textit{this} variable}
	\lineiii{\samp{command}}{\textit{string}}{some instructions of the scripting language to execute}
\end{tableiii}
This function interprets the argument \samp{command} as instructions to
execute, written in the scripting language, but doesn't display messages to the
standard output stream. Messages are put into a string that is returned
by the function.

\textbf{Example:}

\texttt{local myContext;\\
local sMessages = executeStringQuiet(myContext,\\
\makebox[1.6cm][l]{}"traceLine($\backslash$"Beginning of string execution:$\backslash$");"\\
\makebox[1.6cm][l]{}"insert this.name = $\backslash$"execution$\backslash$";"\\
\makebox[1.6cm][l]{}"traceLine($\backslash$"End of string execution.$\backslash$");");\\
traceLine("What we did during the execution:");\\
traceObject(myContext);\\
traceLine("What was intended to the console during the execution:");\\
traceLine(sMessages);}

\textbf{Output:}

\texttt{What we did during the execution:\\
Tracing variable 'myContext':\\
\makebox[0.8cm][l]{}name = "execution"\\
End of variable's trace 'myContext'.\\
What was intended to the console during the execution:\\
Beginning of string execution:\\
End of string execution.\\
}


\textbf{See also:}

\samp{executeString} \ref{executeString()}
\end{itemize}
\pdflabel{existEnv()}
\index{existEnv()}
\pdfsubsection{existEnv}
\begin{itemize}
	\item function \textbf{existEnv(}\samp{variable} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{string}}{the environment variable name}
\end{tableiii}
The function returns \samp{true} if the environment table entry contains
the \samp{variable}.

\textbf{Example:}

\texttt{traceLine("PATH='" + existEnv("PATH")+ "'");}

\textbf{Output:}

\texttt{PATH='true'}


\textbf{See also:}

\samp{getEnv} \ref{getEnv()}, \samp{environTable} \ref{environTable()}, \samp{putEnv} \ref{putEnv()}, \samp{system} \ref{system()}
\end{itemize}
\pdflabel{existFile()}
\index{existFile()}
\pdfsubsection{existFile}
\begin{itemize}
	\item function \textbf{existFile(}\samp{fileName} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{fileName}}{\textit{string}}{the name of a file to check for existence}
\end{tableiii}
Checks whether a file exists or not, looking for include directories passed on
the command line.

This function doesn't work to check the existence of a directory; use \samp{exploreDirectory()} instead.

\textbf{Example:}

\texttt{local sFilename = "Documentation/CodeWorker.pdf";\\
traceLine("Checks existence of file '" + sFilename + "' = '" + existFile(sFilename) + "'");}

\textbf{Output:}

\texttt{Checks existence of file 'Documentation/CodeWorker.pdf' = 'true'}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{existVariable()}
\index{existVariable()}
\pdfsubsection{existVariable}
\begin{itemize}
	\item function \textbf{existVariable(}\samp{variable} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{the name of a variable}
\end{tableiii}
Checks whether a variable exists or not.

\textbf{Example:}

\texttt{local alice;\\
traceLine("The variable 'alice' exists: '" + existVariable(alice) + "'");\\
traceLine("The variable 'wonderful' doesn't exist: '" + existVariable(wonderful) + "'");}

\textbf{Output:}

\texttt{(3,80): warning! you haven't declared the variable 'wonderful' before ; interpreted as 'this.wonderful', but obsolete soon!\\
The variable 'alice' exists: 'true'\\
The variable 'wonderful' doesn't exist: ''}


\textbf{See also:}

\samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{existVirtualFile()}
\index{existVirtualFile()}
\pdfsubsection{existVirtualFile}
\begin{itemize}
	\item function \textbf{existVirtualFile(}\samp{handle} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{handle}}{\textit{string}}{the name of the virtual file to check}
\end{tableiii}
Checks whether a \textit{virtual} file exists or not, meaning that it has been
created via the function \samp{createVirtualFile()}.


\textbf{See also:}

\samp{createVirtualFile} \ref{createVirtualFile()}, \samp{createVirtualTemporaryFile} \ref{createVirtualTemporaryFile()}, \samp{deleteVirtualFile} \ref{deleteVirtualFile()}, \samp{loadVirtualFile} \ref{loadVirtualFile()}
\end{itemize}
\pdflabel{exp()}
\index{exp()}
\pdfsubsection{exp}
\begin{itemize}
	\item function \textbf{exp(}\samp{x} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{x}}{\textit{double}}{the floating-point whose exponential is to compute}
\end{tableiii}
Returns the exponential of \samp{x}.

On underflow, it returns \textit{0}.\\
On overflow, it returns \textit{infinite}.

\textbf{Example:}

\texttt{traceLine("exp(0.693147) = " + \$exp(0.693147)\$);}

\textbf{Output:}

\texttt{exp(0.693147) = 1.9999996388801418}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{sub} \ref{sub()}, \samp{mult} \ref{mult()}, \samp{div} \ref{div()}, \samp{log} \ref{log()}, \samp{mod} \ref{mod()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{expand()}
\index{expand()}
\pdfsubsection{expand}
\begin{itemize}
	\item procedure \textbf{expand(}\samp{patternFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{treeref}\textbf{, }\samp{outputFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{patternFileName}}{\textit{script<pattern>}}{file name or block of instructions of the \textit{pattern script}}
	\lineiii{\samp{this}}{\textit{treeref}}{the current node that will be accessed with \textit{this} variable}
	\lineiii{\samp{outputFileName}}{\textit{string}}{the existing file to expand}
\end{tableiii}
Expands an existing file whose name is passed to the argument \samp{outputFileName},
by executing the \textit{pattern script} \samp{patternFileName} on it.

Expanding a file consists of generating code into marked out areas only, the rest
of the file remaining the same. The markup is put into a comment, knowing that the
syntax of the comment must conform to the type of the expanded file \samp{outputFileName}.
So, an HTML file expects \textbf{<!- -} and \textbf{- ->}, a JAVA file is waiting
for \textbf{//} and \textbf{"$\backslash$n"}, ... The markup is announced by
\textbf{\#\#markup\#\#} followed by a string that represents the \textit{markup key}.
Don't forget to configure correctly the syntax of comment boundaries with procedures
\samp{setCommentBegin()} (see \ref{setCommentBegin()}) and \samp{setCommentEnd()} (see \ref{setCommentEnd()}).

When the procedure is called, \CodeWorker\ jumps from a markup to another. To
handle a markup, it checks whether text was already generated, put between tags
\textbf{\#\#begin\#\#"\textit{markup-key}"} and \textbf{\#\#end\#\#"\textit{markup-key}"},
added automatically the first time an expansion is required, to demarquate the
portion of code that doesn't belong to the user. Then, it extracts all protected
areas, if any, and it generates code at the position of the markup, adding
\textit{begin}/\textit{end} tags seen before.

If the interpreter finds the tag \samp{\#\#script\#\#} just after the markup,
it extracts the embedded text, considered as a script, eventually put between comments.
Otherwise, the interpreter executes the \textit{pattern script}.

Note that some data might be put between tags \samp{\#\#data\#\#}, accessible
in the \textit{template-based} script via the function \samp{getMarkupValue()} (see \ref{getMarkupValue()}).
This block of custom data comes after the \samp{\#\#script\#\#} tag, if present.

The same \textit{pattern script} is called for all markups, so, to distinguish
them and not to generate always the same text, it controls the current markup key
being processed via the function \samp{getMarkupKey()} (see \ref{getMarkupKey()}).

Be careful not to confuse this prodedure with \samp{generate()} that doesn't care
about markups and that overwrites the output file completely, except protected
areas of course.


\textbf{See also:}

\samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}, \samp{translate} \ref{translate()}, \samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translateString} \ref{translateString()}
\end{itemize}
\pdflabel{exploreDirectory()}
\index{exploreDirectory()}
\pdfsubsection{exploreDirectory}
\begin{itemize}
	\item function \textbf{exploreDirectory(}\samp{directory} \textbf{:} \textit{tree}\textbf{, }\samp{path} \textbf{:} \textit{string}\textbf{, }\samp{subfolders} \textbf{:} \textit{bool}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{directory}}{\textit{tree}}{node that will contain the name of all files and folders}
	\lineiii{\samp{path}}{\textit{string}}{the directory to explore}
	\lineiii{\samp{subfolders}}{\textit{bool}}{to explore sub directories recursively}
\end{tableiii}
Explores the directory whose name is passed to the argument \samp{path}. The list
of files is put into the node's array \samp{directory.\textbf{files}} and the
list of directories are put into the node's array \samp{directory.\textbf{directories}}.
Exploring sub directories is required by the argument \samp{subfolders} and each
node of the node's array \samp{directory.\textbf{directories}} repeats the same
process recursively. The key of an array's node is the short name of the file or
the directory and the value of a directory item is the relative path, whereas
the value of a file item is also the short name.

If the directory cannot be found, the variable \samp{directory} doesn't change
and the function returns \samp{false}. If the directory doesn't contain any
file, the attribute \samp{directory.\textit{files}} isn't created. If the
directory doesn't contain any subfolder, the attribute
\samp{directory.\textit{directories}} isn't created.

\textbf{Example:}

\texttt{local theDirectory;\\
local sPathToExplore = project.winBinaries; // Windows package of CodeWorker\\
if !exploreDirectory(theDirectory, sPathToExplore, true) error("unable to find the directory");\\
// the complete path is too long: shorten it\\
traceLine("starting directory = '" + theDirectory.subString(sPathToExplore.length()) + "':");\\
foreach j in theDirectory.files \{\\
\makebox[0.8cm][l]{}traceLine(" '" + j + "'");\\
\}\\
foreach i in cascading theDirectory.directories \{\\
\makebox[0.8cm][l]{}// the complete path is too long: shorten it\\
\makebox[0.8cm][l]{}traceLine("- directory '" + i.subString(sPathToExplore.length()) + "':");\\
\makebox[0.8cm][l]{}foreach j in i.directories \{\\
\makebox[1.6cm][l]{}traceLine(" subfolder '" + key(j) + "'");\\
\makebox[0.8cm][l]{}// the complete path is too long: shorten it\\
\makebox[1.6cm][l]{}traceLine("     path '" + j.subString(sPathToExplore.length()) + "'");\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}if key(i) == "GettingStarted" \{\\
\makebox[1.6cm][l]{}traceLine(" ... a lot of files!");\\
\makebox[0.8cm][l]{}\} else \{\\
\makebox[1.6cm][l]{}foreach j in i.files \{\\
\makebox[2.4cm][l]{}traceLine(" '" + j + "'");\\
\makebox[1.6cm][l]{}\}\\
\makebox[0.8cm][l]{}\}\\
\}}

\textbf{Output:}

\texttt{starting directory = '/':\\
\makebox[0.8cm][l]{}'GettingStarted.bat'\\
\makebox[0.8cm][l]{}'readme.txt'\\
- directory '/bin/':\\
\makebox[0.8cm][l]{}'CodeWorker.exe'\\
\makebox[0.8cm][l]{}'libcurl.dll'\\
- directory '/include/':\\
\makebox[0.8cm][l]{}'CGCompiler.h'\\
\makebox[0.8cm][l]{}'CGExternalHandling.h'\\
\makebox[0.8cm][l]{}'CGRuntime.h'\\
\makebox[0.8cm][l]{}'CppParsingTree.h'\\
\makebox[0.8cm][l]{}'CW4dl.h'\\
\makebox[0.8cm][l]{}'DynPackage.h'\\
\makebox[0.8cm][l]{}'ExternalValueNode.h'\\
\makebox[0.8cm][l]{}'UtlException.h'\\
- directory '/Scripts/':\\
\makebox[0.8cm][l]{}subfolder 'Tutorial'\\
\makebox[1.6cm][l]{}path '/Scripts/Tutorial/'\\
- directory '/Scripts/Tutorial/':\\
\makebox[0.8cm][l]{}subfolder 'GettingStarted'\\
\makebox[1.6cm][l]{}path '/Scripts/Tutorial/GettingStarted/'\\
- directory '/Scripts/Tutorial/GettingStarted/':\\
\makebox[0.8cm][l]{}... a lot of files!}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{extractGenerationHeader()}
\index{extractGenerationHeader()}
\pdfsubsection{extractGenerationHeader}
\begin{itemize}
	\item function \textbf{extractGenerationHeader(}\samp{filename} \textbf{:} \textit{string}\textbf{, }\samp{generator} \textbf{:} \textit{stringref}\textbf{, }\samp{version} \textbf{:} \textit{stringref}\textbf{, }\samp{date} \textbf{:} \textit{stringref}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{generated file to check}
	\lineiii{\samp{generator}}{\textit{stringref}}{name of the application that has generated the file}
	\lineiii{\samp{version}}{\textit{stringref}}{version of the generator}
	\lineiii{\samp{date}}{\textit{stringref}}{date/time of the generation}
\end{tableiii}
Looks for a generation header into the file passed to the argument \samp{filename}.
It returns the comment that was put into the header (see procedure
\samp{setGenerationHeader()} \ref{setGenerationHeader()}) during the generation,
after having assigned the output parameters:
\begin{itemize}
	\item \samp{generator} with the name of the application that have generated the file, \textit{"CodeWorker"} normally,
	\item \samp{version} with the version of the generator, the version of \CodeWorker\ normally,
	\item \samp{date} with the date and time of the generation, conforming to
		\samp{"\%d\%b\%Y \%H:\%M:\%S"}; \textit{12dec2002 10:00:23} for example,
\end{itemize}

The generation header is inlayed in the comment delimeters and conforms to the
format:\\
\begin{itemize}
	\item if the comment holds on a single line:\\
		\samp{\textit{begin-comment} \textbf{"\#\#generation header\#\#CodeWorker\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textit{version-number} \textbf{"\#\#"} \textit{generation-date} \textbf{"\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textbf{'"'} \textit{comment} \textbf{'"'} \textit{end-comment}}
	\item if the comment holds on more than one line:\\
		\samp{\textit{begin-comment} \textbf{"\#\#generation header\#\#CodeWorker\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textit{version-number} \textbf{"\#\#"} \textit{generation-date} \textbf{"\#\#"} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textbf{"\#\#header start\#\#"} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textit{line\tiny{1}} \textit{end-comment}}\\
		\samp{...}\\
		\samp{\textit{begin-comment} \textit{line\tiny{n}} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textbf{"\#\#header end\#\#"} \textit{end-comment}}
\end{itemize}

\textbf{Example:}

\texttt{setGenerationHeader("Popeye's Village$\backslash$nGozo and Comino");\\
local sScriptFile = "GettingStarted/Tiny-JAVA.cwt";\\
local sFileName = "Documentation/" + project.listOfClasses\#back.name + ".java";\\
generate(sScriptFile, project.listOfClasses\#back, sFileName);\\
local sGenerator;\\
local sVersion;\\
local sDateTime;\\
traceLine("comment of the generation header = '" + extractGenerationHeader(sFileName, sGenerator, sVersion, sDateTime) + "'");\\
traceLine("generator = '" + sGenerator + "'");\\
traceLine("version = '" + sVersion + "'");\\
traceLine("date = '" + sDateTime + "'");\\
setGenerationHeader("");}

\textbf{Output:}

\texttt{comment of the generation header = 'Popeye's Village\\
Gozo and Comino'\\
generator = 'CodeWorker'\\
version = '3.10.4'\\
date = '30may2005 19:16:43'}


\textbf{See also:}

\samp{setGenerationHeader} \ref{setGenerationHeader()}, \samp{getGenerationHeader} \ref{getGenerationHeader()}
\end{itemize}
\pdflabel{fileCreation()}
\index{fileCreation()}
\pdfsubsection{fileCreation}
\begin{itemize}
	\item function \textbf{fileCreation(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to ask for its creation time}
\end{tableiii}
Returns the date-time of creation of file whose name is passed to the argument \samp{filename}.

If an error occurs, it returns one code among the following:
\begin{itemize}
	\item \textbf{"-1"}: unknown error that shouldn't appear,
	\item \textbf{"-2"}: permission denied,
	\item \textbf{"-3"}: too many files have been opened,
	\item \textbf{"-4"}: file not found,
\end{itemize}

\textbf{Example:}

\texttt{local sFileName = "Documentation/CodeWorker.tex";\\
local sCreationTime = fileCreation(sFileName);\\
if startString(sCreationTime, "-") error("error code = " + sCreationTime + "!");\\
traceLine("creation of '" + sFileName + "' = " + sCreationTime);}

\textbf{Output:}

\texttt{creation of 'Documentation/CodeWorker.tex' = 17mar2004 22:32:18}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{fileLastAccess()}
\index{fileLastAccess()}
\pdfsubsection{fileLastAccess}
\begin{itemize}
	\item function \textbf{fileLastAccess(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to ask for its last access time}
\end{tableiii}
Returns the date-time of last access to file whose name is passed to the argument \samp{filename}.

If an error occurs, it returns one code among the following:
\begin{itemize}
	\item \textbf{"-1"}: unknown error that shouldn't appear,
	\item \textbf{"-2"}: permission denied,
	\item \textbf{"-3"}: too many files have been opened,
	\item \textbf{"-4"}: file not found,
\end{itemize}

\textbf{Example:}

\texttt{local sFileName = "Documentation/CodeWorker.tex";\\
local sLastAccessTime = fileLastAccess(sFileName);\\
if startString(sLastAccessTime, "-") error("error code = " + sLastAccessTime + "!");\\
traceLine("last access to '" + sFileName + "' = " + sLastAccessTime);}

\textbf{Output:}

\texttt{last access to 'Documentation/CodeWorker.tex' = 01may2006 13:58:49}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{fileLastModification()}
\index{fileLastModification()}
\pdfsubsection{fileLastModification}
\begin{itemize}
	\item function \textbf{fileLastModification(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to ask for its last modification time}
\end{tableiii}
Returns the date-time of last modification to file whose name is passed to the argument \samp{filename}.

If an error occurs, it returns one code among the following:
\begin{itemize}
	\item \textbf{"-1"}: unknown error that shouldn't appear,
	\item \textbf{"-2"}: permission denied,
	\item \textbf{"-3"}: too many files have been opened,
	\item \textbf{"-4"}: file not found,
\end{itemize}

\textbf{Example:}

\texttt{local sFileName = "Documentation/CodeWorker.tex";\\
local sLastModificationTime = fileLastModification(sFileName);\\
if startString(sLastModificationTime, "-") error("error code = " + sLastModificationTime + "!");\\
traceLine("last modification of '" + sFileName + "' = " + sLastModificationTime);}

\textbf{Output:}

\texttt{last modification of 'Documentation/CodeWorker.tex' = 30apr2006 04:52:48}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{fileLines()}
\index{fileLines()}
\pdfsubsection{fileLines}
\begin{itemize}
	\item function \textbf{fileLines(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file where to count lines}
\end{tableiii}
Returns the number of lines that the file passed to the argument \samp{filename}
contains.

If the file cannot be found nor opened, the function returns \samp{-1}.

\textbf{Example:}

\texttt{local theFiles;\\
if !scanFiles(theFiles, "Generation", "*.cw?", true) error("impossible to scan the directory");\\
local iLines = 0;\\
foreach i in theFiles iLines = \$iLines + fileLines(i)\$;\\
traceLine("total of script lines to generate $\backslash$"CodeWorker$\backslash$" = " + iLines);}

\textbf{Output:}

\texttt{total of script lines to generate "CodeWorker" = 8705}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{fileMode()}
\index{fileMode()}
\pdfsubsection{fileMode}
\begin{itemize}
	\item function \textbf{fileMode(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{file to ask for its permission setting}
\end{tableiii}
The \samp{chmod} function returns the permission setting of the file specified by \samp{filename}.
The permission setting controls \textit{read} and \textit{write} and \textit{execute} access to the file.
The returned value holds the permission setting of the file as a concatenation of chars amongst the following:
\begin{itemize}
    \item \textbf{'R'} for \textbf{r}eading permitted,
    \item \textbf{'W'} for \textbf{w}riting permitted,
    \item \textbf{'X'} for e\textbf{x}ecuting permitted (ignored on \textit{Windows} platform),
\end{itemize}
If an error occurs, the function returns one code among the following:
\begin{itemize}
	\item \textbf{"-1"}: unknown error that shouldn't appear,
	\item \textbf{"-2"}: permission denied,
	\item \textbf{"-3"}: too many files have been opened,
	\item \textbf{"-4"}: file not found,
\end{itemize}

\textbf{Example:}

\texttt{local sPermission = fileMode("Documentation/CodeWorker.tex");\\
if startString(sPermission, "-") error("error code = " + sPermission);\\
traceLine("permission on file 'Documentation/CodeWorker.tex' = '" + sPermission + "'");}

\textbf{Output:}

\texttt{permission on file 'Documentation/CodeWorker.tex' = 'RW'}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{fileSize()}
\index{fileSize()}
\pdfsubsection{fileSize}
\begin{itemize}
	\item function \textbf{fileSize(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file to ask for its size}
\end{tableiii}
Returns the size of the file whose name is passed to the argument \samp{filename}.

If an error occurs, it returns one code among the following:
\begin{itemize}
	\item \textbf{-1}: unknown error that shouldn't appear,
	\item \textbf{-2}: permission denied,
	\item \textbf{-3}: too many files have been opened,
	\item \textbf{-4}: file not found,
\end{itemize}

\textbf{Example:}

\texttt{local sFileName = "Documentation/CodeWorker.tex";\\
local iSize = fileSize(sFileName);\\
if isNegative(iSize) error("error code = " + iSize + "!");\\
traceLine("size of '" + sFileName + "' = " + iSize + " characters");}

\textbf{Output:}

\texttt{size of 'Documentation/CodeWorker.tex' = 918752 characters}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{findElement()}
\index{findElement()}
\pdfsubsection{findElement}
\begin{itemize}
	\item function \textbf{findElement(}\samp{value} \textbf{:} \textit{string}\textbf{, }\samp{variable} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{value}}{\textit{string}}{a key as an array entry}
	\lineiii{\samp{variable}}{\textit{treeref}}{a variable that contains an array of nodes}
\end{tableiii}
This function looks for a key, given by argument \samp{value}, as an entry of
the nodes array passed to argument \samp{variable}. If the key is found, the
function returns \samp{true}, and and empty string otherwise.

\textbf{Example:}

\texttt{local list;\\
insert list["everest"] = "everest";\\
insert list["karakorum"] = "karakorum";\\
insert list["kilimanjaro"] = "kilimanjaro";\\
insert list["twin peaks"] = "twin peaks";\\
traceLine("findElement('kilimanjaro', list) = '" + findElement("kilimanjaro", list) + "'");}

\textbf{Output:}

\texttt{findElement('kilimanjaro', list) = 'true'}


\pdflabel{method findElement()}
\index{method!findElement()}
\textbf{Method:} \textit{variable}.\samp{findElement}(\textit{value})


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{findFirstChar()}
\index{findFirstChar()}
\pdfsubsection{findFirstChar}
\begin{itemize}
	\item function \textbf{findFirstChar(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{someChars} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{the string to explore}
	\lineiii{\samp{someChars}}{\textit{string}}{a set of individual characters}
\end{tableiii}
Returns the location into \samp{text} of the first character encountered that
belongs to the set of characters passed to argument \samp{someChars}. The
position starts counting at \samp{0}. If no occurrence has been found, the
negative value \samp{-1} is returned.

\textbf{Example:}

\texttt{local sText = "looking for a token: $\backslash$"...$\backslash$" f(a,b) \{...\}";\\
traceLine("sText = '" + composeCLikeString(sText) + "'");\\
traceLine("findFirstChar(sText, '$\backslash$"(\{') = " + findFirstChar(sText, "$\backslash$"(\{"));}

\textbf{Output:}

\texttt{sText = 'looking for a token: $\backslash$"...$\backslash$" f(a,b) \{...\}'\\
findFirstChar(sText, '"(\{') = 21}


\textbf{See also:}

\samp{endString} \ref{endString()}, \samp{findFirstChar} \ref{findFirstChar()}, \samp{findLastString} \ref{findLastString()}, \samp{findNextString} \ref{findNextString()}, \samp{findString} \ref{findString()}, \samp{startString} \ref{startString()}
\end{itemize}
\pdflabel{findFirstSubstringIntoKeys()}
\index{findFirstSubstringIntoKeys()}
\pdfsubsection{findFirstSubstringIntoKeys}
\begin{itemize}
	\item function \textbf{findFirstSubstringIntoKeys(}\samp{substring} \textbf{:} \textit{string}\textbf{, }\samp{array} \textbf{:} \textit{treeref}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{substring}}{\textit{string}}{a sequence of characters to search into keys of a node's array}
	\lineiii{\samp{array}}{\textit{treeref}}{a variable that contains an array of nodes}
\end{tableiii}
This function returns the position of the first item, such as its corresponding
entry key into the list owned by\samp{variable} contains the substring passed
to argument \samp{substring}. The position starts counting at \samp{0}.

 If no item is found, the negative value \samp{-1} is returned.

\textbf{Example:}

\texttt{local list;\\
insert list["everest"] = 0;\\
insert list["karakorum"] = 1;\\
insert list["kilimanjaro"] = 2;\\
insert list["twin peaks"] = 3;\\
traceLine("findFirstSubstringIntoKeys('k', list) = " + findFirstSubstringIntoKeys("k", list));}

\textbf{Output:}

\texttt{findFirstSubstringIntoKeys('k', list) = 1}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{findLastString()}
\index{findLastString()}
\pdfsubsection{findLastString}
\begin{itemize}
	\item function \textbf{findLastString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{find} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to explore}
	\lineiii{\samp{find}}{\textit{string}}{a substring to find into \samp{text}}
\end{tableiii}
Returns the position of the last occurrence of the substring \samp{find} into
the sequence of characters passed to argument \samp{text}. The position starts
counting to \samp{0}.

If the substring \samp{find} doesn't belong to \samp{text}, the negative value
\samp{-1} is returned.

\textbf{Example:}

\texttt{local sText = "the lamp of experience";\\
traceLine("sText = '" + sText + "'");\\
traceLine("findLastString(sText, 'p') = '" + findLastString(sText, "p") + "'");}

\textbf{Output:}

\texttt{sText = 'the lamp of experience'\\
findLastString(sText, 'p') = '14'}


\textbf{See also:}

\samp{findFirstChar} \ref{findFirstChar()}, \samp{endString} \ref{endString()}, \samp{findNextString} \ref{findNextString()}, \samp{findString} \ref{findString()}, \samp{startString} \ref{startString()}
\end{itemize}
\pdflabel{findNextString()}
\index{findNextString()}
\pdfsubsection{findNextString}
\begin{itemize}
	\item function \textbf{findNextString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{find} \textbf{:} \textit{string}\textbf{, }\samp{position} \textbf{:} \textit{int}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to explore}
	\lineiii{\samp{find}}{\textit{string}}{a substring to find into \samp{text}}
	\lineiii{\samp{position}}{\textit{int}}{the position in the string (starting at 0) the search must begin}
\end{tableiii}
Returns the lowest beginning index of the substring \samp{find} that matches
the sequence of characters passed to argument \samp{text}, starting the search at \samp{position} included. The index starts
counting to \samp{0}.

If the substring \samp{find} doesn't belong to \samp{text} (starting at \samp{position}), the negative value
\samp{-1} is returned.

\textbf{Example:}

\texttt{local sText = "the lamp of experience";\\
traceLine("sText = '" + sText + "'");\\
traceLine("findNextString(sText, 'p', 8) = '" + findNextString(sText, "p", 8) + "'");}

\textbf{Output:}

\texttt{sText = 'the lamp of experience'\\
findNextString(sText, 'p', 8) = '14'}


\textbf{See also:}

\samp{findFirstChar} \ref{findFirstChar()}, \samp{endString} \ref{endString()}, \samp{findLastString} \ref{findLastString()}, \samp{findString} \ref{findString()}, \samp{startString} \ref{startString()}
\end{itemize}
\pdflabel{findNextSubstringIntoKeys()}
\index{findNextSubstringIntoKeys()}
\pdfsubsection{findNextSubstringIntoKeys}
\begin{itemize}
	\item function \textbf{findNextSubstringIntoKeys(}\samp{substring} \textbf{:} \textit{string}\textbf{, }\samp{array} \textbf{:} \textit{treeref}\textbf{, }\samp{next} \textbf{:} \textit{int}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{substring}}{\textit{string}}{a sequence of characters to search into keys of a node's array}
	\lineiii{\samp{array}}{\textit{treeref}}{a variable that contains an array of nodes}
	\lineiii{\samp{next}}{\textit{int}}{the position after which looking for the next item}
\end{tableiii}
Returns the position of the next item of list passed to argument \samp{variable},
whose entry key contains the substring given by argument \samp{substring}. The
next item is searched after position passed to argument \samp{next}. The
position starts counting at \samp{0}.

 If no item is found, the negative value \samp{-1} is returned.

\textbf{Example:}

\texttt{local list;\\
insert list["everest"] = 0;\\
insert list["karakorum"] = 1;\\
insert list["kilimanjaro"] = 2;\\
insert list["twin peaks"] = 3;\\
traceLine("findNextSubstringIntoKeys('k', list, 1) = " + findNextSubstringIntoKeys("k", list, 1));}

\textbf{Output:}

\texttt{findNextSubstringIntoKeys('k', list, 1) = 2}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{findString()}
\index{findString()}
\pdfsubsection{findString}
\begin{itemize}
	\item function \textbf{findString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{find} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to explore}
	\lineiii{\samp{find}}{\textit{string}}{a substring to find into \samp{text}}
\end{tableiii}
Returns the position of the first occurrence of the substring \samp{find} into
the sequence of characters passed to argument \samp{text}. The position starts
counting to \samp{0}.

If the substring \samp{find} doesn't belong to \samp{text}, the negative value
\samp{-1} is returned.

\textbf{Example:}

\texttt{local sText = "the lamp of experience";\\
traceLine("sText = '" + sText + "'");\\
traceLine("findString(sText, 'of') = '" + findString(sText, "of") + "'");}

\textbf{Output:}

\texttt{sText = 'the lamp of experience'\\
findString(sText, 'of') = '9'}


\textbf{See also:}

\samp{findFirstChar} \ref{findFirstChar()}, \samp{endString} \ref{endString()}, \samp{findLastString} \ref{findLastString()}, \samp{findNextString} \ref{findNextString()}, \samp{startString} \ref{startString()}
\end{itemize}
\pdflabel{first()}
\index{first()}
\pdfsubsection{first}
\begin{itemize}
	\item function \textbf{first(}\samp{i} \textbf{:} \textit{iterator}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator of a \samp{foreach} statement or pointing to a list}
\end{tableiii}
Returns \samp{true} if the iterator argument \samp{i} points to the first item
of the iterated list.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
foreach i in myTree \{\\
\makebox[0.8cm][l]{}if first(i) traceLine("The first item key of the list is '" + key(i) + "'");\\
\}}

\textbf{Output:}

\texttt{The first item key of the list is 'Everest'}


\textbf{See also:}

\samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}, \samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}
\end{itemize}
\pdflabel{floor()}
\index{floor()}
\pdfsubsection{floor}
\begin{itemize}
	\item function \textbf{floor(}\samp{number} \textbf{:} \textit{double}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{double}}{the floating-point number to floor}
\end{tableiii}
Returns the largest integer that is less than or equal to \samp{number}. If
\samp{number} isn't a number, the function returns \textit{0}.

\textbf{Example:}

\texttt{traceLine("floor(5.369e+1) = " + floor(5.369e1));}

\textbf{Output:}

\texttt{floor(5.369e+1) = 53}


\textbf{See also:}

\samp{decrement} \ref{decrement()}, \samp{increment} \ref{increment()}, \samp{ceil} \ref{ceil()}
\end{itemize}
\pdflabel{formatDate()}
\index{formatDate()}
\pdfsubsection{formatDate}
\begin{itemize}
	\item function \textbf{formatDate(}\samp{date} \textbf{:} \textit{string}\textbf{, }\samp{format} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{date}}{\textit{string}}{a date-time representation to transform}
	\lineiii{\samp{format}}{\textit{string}}{the format that will be applied to the \samp{date} argument}
\end{tableiii}
Converts a date to another format, or extracts just a part of the date. The date
is passed to argument \samp{date}, and the format given by \samp{format}.

Each field of the format specification is a single character or a format type
signifying a particular \textit{format option}. A \textit{format option}
starts with a percent sign. If a percent sign is followed by a character that
has no meaning as a format type, an error is raised. To print a percent-sign
character, use \textbf{'\%\%'}.

The format type determines how the associated argument, at the current location
to the date, must be interpreted:
\begin{itemize}
	\item \textbf{'\%d'} means that a 2-digits day of the month must be written,
	\item \textbf{'\%e'} means that a day of the month must be written, such as
		\textit{1} but not \textit{01}
	\item \textbf{'\%j'} means that the day of the year must be written,
	\item \textbf{'\%m'} means that a 2-digits month must be written,
	\item \textbf{'\%B'} means that the complete english name of the month must
		be written,
	\item \textbf{'\%b'} means that the truncated english name of the month must
		be written: only the 3 first characters,
	\item \textbf{'\%Y'} means that a 4-digits year must be written,
	\item \textbf{'\%y'} means that a 2-digits year must be written,
	\item \textbf{'\%t'} means that the number of days since 30dec1899 must be written (\textit{WingZ} format),
	\item \textbf{'\%w'} means that the weekday must be written as an integer
		(\samp{0-6}; \samp{0} is \textit{sunday}),
	\item \textbf{'\%W'} means that the weekday must be written as the complete english name,
	\item \textbf{'\%H'} means that a 2-digits hour must be written,
	\item \textbf{'\%I'} means that a 2-digits hour (12 max) must be written,
	\item \textbf{'\%p'} means that \samp{"AM"} / \samp{"PM"} must be written,
	\item \textbf{'\%M'} means that a 2-digits minute must be written,
	\item \textbf{'\%S'} means that a 2-digits second must be written,
	\item \textbf{'\%L'} means that a 3-digits millisecond must be written,
	\item \textbf{'\%D'} is equivalent to \samp{'\%m/\%d/\%y'},
	\item \textbf{'\%r'} is equivalent to \samp{'\%I:\%M:\%S \%p'},
	\item \textbf{'\%T'} is equivalent to \samp{'\%H:\%M:\%S'},
\end{itemize}
An error occurs if a temporal argument doesn't belong to those listed above, or if
the date to format doesn't conform to \samp{"\%d\%b\%Y \%H:\%M:\%S.\%L"}.

\textbf{Example:}

\texttt{traceLine("release of the documentation = '" + getNow() + "'");\\
traceLine("a new format = '" + formatDate(getNow(), "\%B \%d, \%Y") + "'");\\
traceLine("the hour only = '" + formatDate(getNow(), "\%H") + "'");}

\textbf{Output:}

\texttt{release of the documentation = '01may2006 20:42:00.500'\\
a new format = 'may 01, 2006'\\
the hour only = '20'}


\textbf{See also:}

\samp{addToDate} \ref{addToDate()}, \samp{compareDate} \ref{compareDate()}, \samp{completeDate} \ref{completeDate()}, \samp{getLastDelay} \ref{getLastDelay()}, \samp{getNow} \ref{getNow()}, \samp{setNow} \ref{setNow()}
\end{itemize}
\pdflabel{generate()}
\index{generate()}
\pdfsubsection{generate}
\begin{itemize}
	\item procedure \textbf{generate(}\samp{patternFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{treeref}\textbf{, }\samp{outputFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{patternFileName}}{\textit{script<pattern>}}{file name of the \textit{pattern script}}
	\lineiii{\samp{this}}{\textit{treeref}}{the current node that will be accessed via \textit{this} variable}
	\lineiii{\samp{outputFileName}}{\textit{string}}{the output file to generate}
\end{tableiii}
Generates a file whose name is passed to the argument \samp{outputFileName},
by executing the \textit{pattern script} \samp{patternFileName} on it.

Up to version \samp{\textit{2.18}}, the \textit{pattern script} was
necessary passed as a script file name. Since version \samp{\textit{2.19}},
the function admits to embed the script in the place of the corresponding
argument \samp{patternFileName}, inlaying the script in brackets:\\
\texttt{\textit{//generation of an HTML file, which shows the title and the content\\
//of some financial market news previously extracted}\\
\textbf{generate(\\
\{}<html>\\
\makebox[0.4cm][r]{} <body>\\
@\\
foreach i in this.news \{\\
	\makebox[0.8cm][r]{} @@composeHTMLLikeString(i.title)@<br>@endl()@@\\
	\makebox[0.8cm][r]{} @<table><tr><td>@endl()@@\\
	\makebox[1.2cm][r]{} @@composeHTMLLikeString(i.body) + endl()@@\\
	\makebox[0.8cm][r]{} @</td></tr></table>@endl()@@\\
\}\\
@\makebox[0.4cm][r]{} </body>\\
</html>\\
@\textbf{\}, project, "news.html");}}

\begin{itemize}
	\item It avoids the writing of 2 files, as it was unavoidable before:\\
\texttt{generate("news2HTML.cwt", project, "news.html");}
	\item such as \samp{"news2HTML.cwt"}, which contains:\\
\texttt{<html>\\
\makebox[0.4cm][r]{} <body>\\
@\\
foreach i in this.news \{\\
	\makebox[0.8cm][r]{} @@composeHTMLLikeString(i.title)@<br>@endl()@@\\
	\makebox[0.8cm][r]{} @<table><tr><td>@endl()@@\\
	\makebox[1.2cm][r]{} @@composeHTMLLikeString(i.body) + endl()@@\\
	\makebox[0.8cm][r]{} @</td></tr></table>@endl()@@\\
\}\\
@\makebox[0.4cm][r]{} </body>\\
</html>}
\end{itemize}

Generating a file consists of extracting the protected areas from the output
file, before overwriting it with the text generated by the \textit{pattern script}.
It is possible to put a header of generation at the beginning of the file that
will specify some information such as the name of the generating tool
(\CodeWorker\ normally) and the version of the generator and the date of generation
and a custom field of data. This header of generation (see \samp{setGenerationHeader()}
\ref{setGenerationHeader()}) isn't taken into account while comparing the new
generated text with the precedent version of the file on disk.

If the output file may contain some protected areas, don't forget to configure
correctly the syntax of comment boundaries with procedures \samp{setCommentBegin()}
(see \ref{setCommentBegin()}) and \samp{setCommentEnd()} (see \ref{setCommentEnd()}).

Be careful not to use this prodedure instead of \samp{expand()}. Expansion
saves all text, except into markups, while generation saves protected areas only
and overwrites the rest!


\textbf{See also:}

\samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generateString} \ref{generateString()}, \samp{translate} \ref{translate()}, \samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translateString} \ref{translateString()}
\end{itemize}
\pdflabel{generateString()}
\index{generateString()}
\pdfsubsection{generateString}
\begin{itemize}
	\item procedure \textbf{generateString(}\samp{patternFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{treeref}\textbf{, }\samp{outputString} \textbf{:} \textit{stringref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{patternFileName}}{\textit{script<pattern>}}{file name of the \textit{pattern script}}
	\lineiii{\samp{this}}{\textit{treeref}}{the current node that will be accessed via \textit{this} variable}
	\lineiii{\samp{outputString}}{\textit{stringref}}{the output text to generate}
\end{tableiii}
Generates a sequence of characters, which is stored into the argument \samp{outputString},
by executing the \textit{pattern script} \samp{patternFileName} on it.

Generating a sequence of characters consists of extracting the protected areas from the
\samp{outputString} string, before overwriting it with the text generated by the \textit{pattern script}.
It is possible to put a header of generation at the beginning of the file that
will specify some information such as the name of the generating tool
(\CodeWorker\ normally) and the version of the generator and the date of generation
and a custom field of data. This header of generation (see \samp{setGenerationHeader()}
\ref{setGenerationHeader()}) isn't taken into account while comparing the new
generated text with the precedent version of the file on disk.

If the output string may contain some protected areas, don't forget to configure
correctly the syntax of comment boundaries with procedures \samp{setCommentBegin()}
(see \ref{setCommentBegin()}) and \samp{setCommentEnd()} (see \ref{setCommentEnd()}).


\textbf{See also:}

\samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{translate} \ref{translate()}, \samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translateString} \ref{translateString()}
\end{itemize}
\pdflabel{getArraySize()}
\index{getArraySize()}
\pdfsubsection{getArraySize}
\begin{itemize}
	\item function \textbf{getArraySize(}\samp{variable} \textbf{:} \textit{treeref}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{any node of a tree}
\end{tableiii}
Returns the number of items the argument \samp{variable} contains
into its embedded array, or \textit{0} if the array doesn't exist.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
traceLine("getArraySize(myTree) = '" + getArraySize(myTree) + "'");}

\textbf{Output:}

\texttt{getArraySize(myTree) = '2'}


\pdflabel{method size()}
\index{method!size()}
\textbf{Method:} \textit{variable}.\samp{size}()


\pdflabel{getVariableSize()}
\index{deprecated!getVariableSize()}
\textbf{Deprecated form:} \samp{getVariableSize} has disappeared since version \textit{1.30}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{getCommentBegin()}
\index{getCommentBegin()}
\pdfsubsection{getCommentBegin}
\begin{itemize}
	\item function \textbf{getCommentBegin(}\textbf{) :} \textit{string}

Returns the value of a beginning of comment, which is exploited by the procedures
taking in charge the source code generation, such as \samp{expand} or \samp{generate}.
\CodeWorker\ must know the format of comments recognized by the output file,
to be able to extract or put protected areas, or to detect \textit{expansion
markups}.

The beginning of comment assigned by default is worth \textbf{'//'}. This is
the symbol of C++ and JAVA comments that are the most frequently files
encountered for generation. Use the procedure \samp{setCommentBegin} to change
it.

Some languages accept more than one format of comment. It is the case of C++ or
JAVA or non-standard HTML (\textit{Microsoft} extended HTML with the
non-recommended tag \textit{'<COMMENT'} that the \textit{W3C} hasn't admitted).
\CodeWorker\ can't handle more than one beginning of comment format for an
output file, but you'll haven't to suffer about it, because you have the control
on writing the markups into the output file, and so, to conform to a unique
representation of comments.

Be careful that if the beginning and the end of comments haven't been assigned
correctly before generating a file, the protected areas will not be extracted,
and so, lost for ever!

\textbf{Example:}

\texttt{traceLine("This example is running while processing the documentation, so we are expecting a LaTeX comment: '" + getCommentBegin() + "'");}

\textbf{Output:}

\texttt{This example is running while processing the documentation, so we are expecting a LaTeX comment: '//'}


\textbf{See also:}

\samp{getCommentEnd} \ref{getCommentEnd()}, \samp{setCommentBegin} \ref{setCommentBegin()}, \samp{setCommentEnd} \ref{setCommentEnd()}
\end{itemize}
\pdflabel{getCommentEnd()}
\index{getCommentEnd()}
\pdfsubsection{getCommentEnd}
\begin{itemize}
	\item function \textbf{getCommentEnd(}\textbf{) :} \textit{string}

Returns the value of an end of comment, which is exploited by the procedures
taking in charge the source code generation, such as \samp{expand} or \samp{generate}.
\CodeWorker\ must know the format of comments recognized by the output file,
to be able to extract or put protected areas, or to detect \textit{expansion
markups}.

The end of comment assigned by default is worth \textbf{'$\backslash$r$\backslash$n'}. This is
the symbol of C++ and JAVA comments that are the most frequently files
encountered for generation. Use the procedure \samp{setCommentEnd} to change
it.

Some languages accept more than one format of comment. It is the case of C++ or
JAVA or non-standard HTML (\textit{Microsoft} extended HTML with the
non-recommended tag \textit{'/COMMENT>'} that the \textit{W3C} hasn't admitted).
\CodeWorker\ can't handle more than one end of comment format for an
output file, but you'll haven't to suffer about it, because you have the control
on writing the markups into the output file, and so, to conform to a unique
representation of comments.

Be careful that if the beginning and the end of comments haven't been assigned
correctly before generating a file, the protected areas will not be extracted,
and so, lost for ever!

\textbf{Example:}

\texttt{traceLine("This example is running while processing the documentation, so we are expecting a LaTeX comment: '" + composeCLikeString(getCommentEnd()) + "'");}

\textbf{Output:}

\texttt{This example is running while processing the documentation, so we are expecting a LaTeX comment: '$\backslash$n'}


\textbf{See also:}

\samp{getCommentBegin} \ref{getCommentBegin()}, \samp{setCommentBegin} \ref{setCommentBegin()}, \samp{setCommentEnd} \ref{setCommentEnd()}
\end{itemize}
\pdflabel{getCurrentDirectory()}
\index{getCurrentDirectory()}
\pdfsubsection{getCurrentDirectory}
\begin{itemize}
	\item function \textbf{getCurrentDirectory(}\textbf{) :} \textit{string}

Returns the current directory’s name as a fully qualified path, where separators
are always forward slashes \textbf{/} like in UNIX. Note that the current
directory is closed by a separator.

The function returns an empty string if the path is longer than 1024 characters.

\textbf{Example:}

\texttt{traceLine("current directory = '" + getCurrentDirectory() + "'");}

\textbf{Output:}

\texttt{current directory = 'E:/projects/generator/'}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{getEnv()}
\index{getEnv()}
\pdfsubsection{getEnv}
\begin{itemize}
	\item function \textbf{getEnv(}\samp{variable} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{string}}{the environment variable name}
\end{tableiii}
The function returns the environment table entry containing the \samp{variable}.
An error message is thrown if \samp{variable} is not found in the
environment table.

See function \samp{existEnv()} to check the existence before getting.\\
Use the \samp{putenv} function to modify the value of an environment variable.

\textbf{Example:}

\texttt{traceLine("PATH='" + getEnv("PATH")+ "'");}

\textbf{Output:}

\texttt{PATH='E:$\backslash$Win32App$\backslash$MikTeX$\backslash$miktex$\backslash$bin;C:$\backslash$Perl$\backslash$bin$\backslash$;C:$\backslash$WINNT$\backslash$system32;C:$\backslash$WINNT;C:$\backslash$WINNT$\backslash$System32$\backslash$Wbem;C:$\backslash$Program Files$\backslash$Fichiers communs$\backslash$Adaptec Shared$\backslash$System;C:$\backslash$PROGRA\~{}1$\backslash$ATT$\backslash$Graphviz$\backslash$bin;C:$\backslash$PROGRA\~{}1$\backslash$ATT$\backslash$Graphviz$\backslash$bin$\backslash$tools;E:$\backslash$Projects$\backslash$Generator$\backslash$Release'}


\textbf{See also:}

\samp{environTable} \ref{environTable()}, \samp{existEnv} \ref{existEnv()}, \samp{putEnv} \ref{putEnv()}, \samp{system} \ref{system()}
\end{itemize}
\pdflabel{getGenerationHeader()}
\index{getGenerationHeader()}
\pdfsubsection{getGenerationHeader}
\begin{itemize}
	\item function \textbf{getGenerationHeader(}\textbf{) :} \textit{string}

Returns the comment that is added automatically to each file generated with the
procedure \samp{generate}. Defining a comment for the generation header may be
required by passing the option \samp{-genheader} on the command line or by
calling the procedure \samp{setGenerationHeader()}.

The generation header is inlayed in the comment delimeters and conforms to the
format:\\
\begin{itemize}
	\item if the comment holds on a single line:\\
		\samp{\textit{begin-comment} \textbf{"\#\#generation header\#\#CodeWorker\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textit{version-number} \textbf{"\#\#"} \textit{generation-date} \textbf{"\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textbf{'"'} \textit{comment} \textbf{'"'} \textit{end-comment}}
	\item if the comment holds on more than one line:\\
		\samp{\textit{begin-comment} \textbf{"\#\#generation header\#\#CodeWorker\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textit{version-number} \textbf{"\#\#"} \textit{generation-date} \textbf{"\#\#"} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textbf{"\#\#header start\#\#"} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textit{line\tiny{1}} \textit{end-comment}}\\
		\samp{...}\\
		\samp{\textit{begin-comment} \textit{line\tiny{n}} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textbf{"\#\#header end\#\#"} \textit{end-comment}}
\end{itemize}

\textbf{Example:}

\texttt{if !getGenerationHeader() traceLine("no generation header required for the moment");\\
setGenerationHeader("Popeye's Village$\backslash$nKnights of Malta");\\
traceLine("new generation header = '" + getGenerationHeader() + "'");\\
local sFileName = "GettingStarted/Tiny-JAVA.cwt";\\
traceLine("script to execute:");\\
local sContent = replaceString("$\backslash$r", "", loadFile(sFileName));\\
local lines;\\
cutString(sContent, "$\backslash$n", lines);\\
foreach i in lines if !startString(i, "//")\\
\makebox[0.8cm][l]{}traceLine("$\backslash$t" + i);\\
traceLine("class to generate = '" + project.listOfClasses\#front.name + "'");\\
local sOutputText;\\
generateString(sFileName, project.listOfClasses\#front, sOutputText);\\
traceLine("generated text:");\\
traceLine(sOutputText);\\
setGenerationHeader("");}

\textbf{Output:}

\texttt{no generation header required for the moment\\
new generation header = 'Popeye's Village\\
Knights of Malta'\\
script to execute:\\
\makebox[0.8cm][l]{}package tiny;\\
\makebox[0.8cm][l]{}\\
\makebox[0.8cm][l]{}public class @\\
\makebox[0.8cm][l]{}this.name@ @\\
\makebox[0.8cm][l]{}if existVariable(this.parent) \{\\
\makebox[1.6cm][l]{}@ extends @this.parent.name@ @\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}@\{\\
\makebox[1.6cm][l]{}// attributes:\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}function getJAVAType(myAttribute : node) \{\\
\makebox[1.6cm][l]{}local sType = myAttribute.class.name;\\
\makebox[1.6cm][l]{}if myAttribute.isArray \{\\
\makebox[2.4cm][l]{}set sType = "java.util.ArrayList/*<" + sType + ">*/";\\
\makebox[1.6cm][l]{}\}\\
\makebox[1.6cm][l]{}return sType;\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}\\
\makebox[0.8cm][l]{}foreach i in this.listOfAttributes \{\\
\makebox[1.6cm][l]{}@   private @getJAVAType(i)@ \_@i.name@ = null;\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}@\\
\makebox[1.6cm][l]{}//constructor:\\
\makebox[1.6cm][l]{}public @this.name@() \{\\
\makebox[1.6cm][l]{}\}\\
\makebox[0.8cm][l]{}\\
\makebox[1.6cm][l]{}// accessors:\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}foreach i in this.listOfAttributes \{\\
\makebox[1.6cm][l]{}@   public @getJAVAType(i)@ get@toUpperString(i.name)@() \{ return \_@i.name@; \}\\
\makebox[1.6cm][l]{}public void set@toUpperString(i.name)@(@getJAVAType(i)@ @i.name@) \{ \_@i.name@ = @i.name@; \}\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}setProtectedArea("Methods");\\
\makebox[0.8cm][l]{}@\}\\
\makebox[0.8cm][l]{}\\
class to generate = 'Planet'\\
generated text:\\
//\#\#generation header\#\#CodeWorker\#\#4.2\#\#01may2006 13:58:52\#\#\\
//\#\#header start\#\#\\
//Popeye's Village\\
//Knights of Malta\\
//\#\#header end\#\#\\
package tiny;\\
\\
public class Planet \{\\
\makebox[0.8cm][l]{}// attributes:\\
\makebox[0.8cm][l]{}private  \_diameter = null;\\
\\
\makebox[0.8cm][l]{}//constructor:\\
\makebox[0.8cm][l]{}public Planet() \{\\
\makebox[0.8cm][l]{}\}\\
\\
\makebox[0.8cm][l]{}// accessors:\\
\makebox[0.8cm][l]{}public  getDIAMETER() \{ return \_diameter; \}\\
\makebox[0.8cm][l]{}public void setDIAMETER( diameter) \{ \_diameter = diameter; \}\\
//\#\#protect\#\#"Methods"\\
//\#\#protect\#\#"Methods"\\
\}\\
}


\textbf{See also:}

\samp{setGenerationHeader} \ref{setGenerationHeader()}, \samp{extractGenerationHeader} \ref{extractGenerationHeader()}
\end{itemize}
\pdflabel{getHTTPRequest()}
\index{getHTTPRequest()}
\pdfsubsection{getHTTPRequest}
\begin{itemize}
	\item function \textbf{getHTTPRequest(}\samp{URL} \textbf{:} \textit{string}\textbf{, }\samp{HTTPSession} \textbf{:} \textit{tree}\textbf{, }\samp{arguments} \textbf{:} \textit{tree}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{URL}}{\textit{string}}{URL of the HTTP server}
	\lineiii{\samp{HTTPSession}}{\textit{tree}}{an object to describe the HTTP session}
	\lineiii{\samp{arguments}}{\textit{tree}}{list of the arguments to GET; the key contains the name of the argument and the element gives the value}
\end{tableiii}
This function sends an HTTP's GET request to the HTTP server pointed to by the parameter
\samp{URL} with the list of arguments put into the the parameter \samp{arguments}.

The function returns the document read from the HTTP server.

The function \samp{sendHTTPRequest()} (see \ref{sendHTTPRequest()}) describes
the structure of the HTTP session object.


\textbf{See also:}

\samp{postHTTPRequest} \ref{postHTTPRequest()}, \samp{sendHTTPRequest} \ref{sendHTTPRequest()}
\end{itemize}
\pdflabel{getIncludePath()}
\index{getIncludePath()}
\pdfsubsection{getIncludePath}
\begin{itemize}
	\item function \textbf{getIncludePath(}\textbf{) :} \textit{string}

It returns the include path passed to the command line with one or more times
the setting of option \samp{-I}, or the latest include path set via the procedure
\samp{setIncludePath()}.

The include path is a concatenation of paths separated by semi-commas (	extbf{';'}).

\textbf{Example:}

\texttt{traceLine("getIncludePath():");\\
local list;\\
cutString(getIncludePath(), ';', list);\\
foreach i in list traceLine(i);}

\textbf{Output:}

\texttt{getIncludePath():\\
e:$\backslash$Projects$\backslash$generator$\backslash$Generation/\\
e:$\backslash$Projects$\backslash$Generator/\\
e:$\backslash$Projects$\backslash$generator$\backslash$Scripts$\backslash$Tutorial/}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getVersion} \ref{getVersion()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setProperty} \ref{setProperty()}, \samp{setVersion} \ref{setVersion()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{getLastDelay()}
\index{getLastDelay()}
\pdfsubsection{getLastDelay}
\begin{itemize}
	\item function \textbf{getLastDelay(}\textbf{) :} \textit{double}

The function returns the last duration that was measured by a statement modifier
\samp{delay} (see \ref{delay}). The duration is expressed in seconds, eventually
with a floating point.

If the function is called during the execution while measuring the time consuming
(controlling sequence under a \samp{delay} statement modifier), it returns the
time elapsed since the beginning of the time-keeping.

\textbf{Example:}

\texttt{local list;\\
local iIndex = 4;\\
delay while isPositive(decrement(iIndex)) \{\\
\makebox[0.8cm][l]{}pushItem list = "element " + iIndex;\\
\makebox[0.8cm][l]{}traceLine("creating node '" + list\#back + "'");\\
\}\\
traceLine("time of execution = " + getLastDelay() + " seconds");}

\textbf{Output:}

\texttt{creating node 'element 3'\\
creating node 'element 2'\\
creating node 'element 1'\\
time of execution = 0.000041904767226002189 seconds}


\textbf{See also:}

\samp{formatDate} \ref{formatDate()}, \samp{addToDate} \ref{addToDate()}, \samp{compareDate} \ref{compareDate()}, \samp{completeDate} \ref{completeDate()}, \samp{getNow} \ref{getNow()}, \samp{setNow} \ref{setNow()}
\end{itemize}
\pdflabel{getNow()}
\index{getNow()}
\pdfsubsection{getNow}
\begin{itemize}
	\item function \textbf{getNow(}\textbf{) :} \textit{string}

Returns the current date-time, conforming to the format:\\
\samp{\%d\%b\%Y \%H:\%M:\%S.\%L}

For explanations about \textit{format types}, see function \samp{formatDate}
at \ref{formatDate()}.

\textbf{Example:}

\texttt{traceLine("now is '" + getNow() + "'");}

\textbf{Output:}

\texttt{now is '01may2006 20:42:00.500'}


\pdflabel{today()}
\index{deprecated!today()}
\textbf{Deprecated form:} \samp{today} has disappeared since version \textit{2.09}


\textbf{See also:}

\samp{formatDate} \ref{formatDate()}, \samp{addToDate} \ref{addToDate()}, \samp{compareDate} \ref{compareDate()}, \samp{completeDate} \ref{completeDate()}, \samp{getLastDelay} \ref{getLastDelay()}, \samp{setNow} \ref{setNow()}
\end{itemize}
\pdflabel{getProperty()}
\index{getProperty()}
\pdfsubsection{getProperty}
\begin{itemize}
	\item function \textbf{getProperty(}\samp{define} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{define}}{\textit{string}}{name of a property}
\end{tableiii}
Returns the value of a property that:
\begin{itemize}
	\item was passed to the command line via the option \samp{'-D'} or \samp{'-define'},
	\item was built by the procedure \samp{setProperty()},
\end{itemize}

\textbf{Example:}

\texttt{traceLine("getProperty('documentation') = '" + getProperty("documentation") + "'");}

\textbf{Output:}

\texttt{getProperty('documentation') = ''}


\pdflabel{getDefineTarget()}
\index{deprecated!getDefineTarget()}
\textbf{Deprecated form:} \samp{getDefineTarget} has disappeared since version \textit{1.30}


\textbf{See also:}

\samp{getIncludePath} \ref{getIncludePath()}, \samp{getVersion} \ref{getVersion()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setProperty} \ref{setProperty()}, \samp{setVersion} \ref{setVersion()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{getShortFilename()}
\index{getShortFilename()}
\pdfsubsection{getShortFilename}
\begin{itemize}
	\item function \textbf{getShortFilename(}\samp{pathFilename} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{pathFilename}}{\textit{string}}{a file name with its path}
\end{tableiii}
Returns the short name of a file, meaning without the path.
It is composed of a radical + an extension.

\textbf{Example:}

\texttt{traceLine("getShortFilename('src/steakhouse$\backslash$$\backslash$chicken.cpp') = $\backslash$"" + getShortFilename("src/steakhouse$\backslash$$\backslash$chicken.cpp") + "$\backslash$"");}

\textbf{Output:}

\texttt{getShortFilename('src/steakhouse$\backslash$chicken.cpp') = "chicken.cpp"}
\end{itemize}
\pdflabel{getTextMode()}
\index{getTextMode()}
\pdfsubsection{getTextMode}
\begin{itemize}
	\item function \textbf{getTextMode(}\textbf{) :} \textit{string}

Returns the mode of text that has been retained for parsing and source code generation:
\begin{itemize}
	\item \textbf{"DOS"}: the default value if the interpreter is running under a \textit{Windows} platform,
	\item \textbf{"UNIX"}: the default value if the interpreter isn't running under a \textit{Windows} platform,
	\item \textbf{"BINARY"}: not exploited yet, but intended to specify later that
		the parsing and the source code generation are applied on binary files,
\end{itemize}
The impact of having samp{"DOS"} instead of any other mode is that special
comments, which announce markup keys and protected areas, will finish by
"$\backslash$r$\backslash$n" when the end of comment is a newline '$\backslash$n'.

\textbf{Example:}

\texttt{traceLine("This documentation is generated under '" + getTextMode() + "' text mode");}

\textbf{Output:}

\texttt{This documentation is generated under 'DOS' text mode}


\textbf{See also:}

\samp{setTextMode} \ref{setTextMode()}
\end{itemize}
\pdflabel{getVariableAttributes()}
\index{getVariableAttributes()}
\pdfsubsection{getVariableAttributes}
\begin{itemize}
	\item function \textbf{getVariableAttributes(}\samp{variable} \textbf{:} \textit{treeref}\textbf{, }\samp{list} \textbf{:} \textit{tree}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{the variable to explore}
	\lineiii{\samp{list}}{\textit{tree}}{will contain the name and type (reference to another node or not) of each attribute}
\end{tableiii}
Populates a list with all attribute names of a tree node.
The name of branches just below the node \samp{variable} are put into \samp{list}.

The attribute's name is a key in the list and there is no value assigned to the item,
except for attributes that point to another node (a reference). In that case, the
item is worth the complete name of the referenced node.

The function returns the number of attributes found, or a negative value (-1) if the
tree node \samp{variable} doesn't exist.

Note: use \samp{\#evaluateVariable()} to navigate along a tree node, where the
complete name is determined at runtime.

\textbf{Example:}

\texttt{local videostores;\\
insert videostores["Italia"].names["Video Coliseum"].town = "Roma";\\
local movies;\\
insert movies["Lock, Stock \& Two Smoking Barrels"].director = "Guy Ritchie";\\
ref movies\#front.shop = videostores["Italia"].names["Video Coliseum"];\\
local attributeNames;\\
getVariableAttributes(movies\#front, attributeNames);\\
foreach i in attributeNames \{\\
\makebox[0.8cm][l]{}if i traceLine("movies\#front." + key(i) + " -> " + i);\\
\makebox[0.8cm][l]{}else traceLine("movies\#front." + key(i) + " = $\backslash$"" + composeCLikeString(\#evaluateVariable("movies\#front." + key(i))) + "$\backslash$"");\\
\}}

\textbf{Output:}

\texttt{movies\#front.director = "Guy Ritchie"\\
movies\#front.shop -> videostores["Italia"].names["Video Coliseum"]}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{getVersion()}
\index{getVersion()}
\pdfsubsection{getVersion}
\begin{itemize}
	\item function \textbf{getVersion(}\textbf{) :} \textit{string}

Returns the \textit{version number} of the \CodeWorker\ interpreter or, if a
\textit{version name} has been passed to the command line via the option
\samp{-version}, the version of old scripts being executed.

\textbf{Example:}

\texttt{traceLine("The version of the interpreter is '" + getVersion() + "'");}

\textbf{Output:}

\texttt{The version of the interpreter is '4.2'}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getIncludePath} \ref{getIncludePath()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setProperty} \ref{setProperty()}, \samp{setVersion} \ref{setVersion()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{getWorkingPath()}
\index{getWorkingPath()}
\pdfsubsection{getWorkingPath}
\begin{itemize}
	\item function \textbf{getWorkingPath(}\textbf{) :} \textit{string}

Returns the output directory that has been assigned to the option
\textbf{-path} on the command line.

\textbf{Example:}

\texttt{traceLine("'-path' = '" + getWorkingPath() + "'");}

\textbf{Output:}

\texttt{'-path' = 'e:$\backslash$Projects$\backslash$generator/'}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getIncludePath} \ref{getIncludePath()}, \samp{getVersion} \ref{getVersion()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setProperty} \ref{setProperty()}, \samp{setVersion} \ref{setVersion()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{getWriteMode()}
\index{getWriteMode()}
\pdfsubsection{getWriteMode}
\begin{itemize}
	\item function \textbf{getWriteMode(}\textbf{) :} \textit{string}

Returns how text is written during a generation or during an implicit copy
while translating: \samp{"insert"} or \samp{"overwrite"} mode (default mode).


\textbf{See also:}

\samp{setWriteMode} \ref{setWriteMode()}
\end{itemize}
\pdflabel{hexaToDecimal()}
\index{hexaToDecimal()}
\pdfsubsection{hexaToDecimal}
\begin{itemize}
	\item function \textbf{hexaToDecimal(}\samp{hexaNumber} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{hexaNumber}}{\textit{string}}{an hexadecimal integer to convert to a decimal number}
\end{tableiii}
Converts an hexadecimal integer, passed to the argument \samp{hexaNumber}, to a
signed decimal integer and returns the result. If \samp{hexaNumber} doesn't conform to
the syntax of an hexadecimal number (\samp{\textit{hexaNumber} ::= \#!ignore [\textbf{'0'..'9'} | \#noCase \textbf{'A'..'F'}]+}),
the function raises an error.

\textbf{Example:}

\texttt{traceLine("hexaToDecimal('FE8') = " + hexaToDecimal("FE8"));}

\textbf{Output:}

\texttt{hexaToDecimal('FE8') = 4072}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{hostToNetworkLong()}
\index{hostToNetworkLong()}
\pdfsubsection{hostToNetworkLong}
\begin{itemize}
	\item function \textbf{hostToNetworkLong(}\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{a 4-bytes representation of a long integer sorted in the host bytes order}
\end{tableiii}
Converts a 4-bytes representation of a long integer to the network bytes order.
\CodeWorker\ stores a byte as a 2-hexadecimal digits; the function raises
an error if the argument \samp{bytes} is malformed.

Use \samp{longToBytes()} and \samp{bytesToLong()} to swap between decimal
and host binary representation of a long integer.

\textbf{Example:}

\texttt{traceLine("hostToNetworkLong('89ABCDEF') = '" + hostToNetworkLong("89ABCDEF") + "'");}

\textbf{Output:}

\texttt{hostToNetworkLong('89ABCDEF') = 'EFCDAB89'}


\textbf{See also:}

\samp{networkLongToHost} \ref{networkLongToHost()}, \samp{hostToNetworkShort} \ref{hostToNetworkShort()}, \samp{networkShortToHost} \ref{networkShortToHost()}
\end{itemize}
\pdflabel{hostToNetworkShort()}
\index{hostToNetworkShort()}
\pdfsubsection{hostToNetworkShort}
\begin{itemize}
	\item function \textbf{hostToNetworkShort(}\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{a 2-bytes representation of a short integer sorted in the host bytes order}
\end{tableiii}
Converts a 2-bytes representation of a short integer to the network bytes order.
\CodeWorker\ stores a byte as a 2-hexadecimal digits; the function raises
an error if the argument \samp{bytes} is malformed.

Use \samp{shortToBytes()} and \samp{bytesToShort()} to swap between decimal
and host binary representation of a short integer.

\textbf{Example:}

\texttt{traceLine("hostToNetworkShort('12EF') = '" + hostToNetworkShort("12EF") + "'");}

\textbf{Output:}

\texttt{hostToNetworkShort('12EF') = 'EF12'}


\textbf{See also:}

\samp{hostToNetworkLong} \ref{hostToNetworkLong()}, \samp{networkLongToHost} \ref{networkLongToHost()}, \samp{networkShortToHost} \ref{networkShortToHost()}
\end{itemize}
\pdflabel{increment()}
\index{increment()}
\pdfsubsection{increment}
\begin{itemize}
	\item function \textbf{increment(}\samp{number} \textbf{:} \textit{doubleref}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{doubleref}}{variable to increment}
\end{tableiii}
The result of \samp{increment} operation is the value of argument \samp{number} \textit{minus} one.
While the result is obtained, the variable \samp{number} is incremented.

\textbf{Example:}

\texttt{local iNumber = 32;\\
traceLine("iNumber = " + iNumber);\\
traceLine("increment(iNumber) = " + increment(iNumber));\\
// the variable 'number' has been incremented:\\
traceLine("iNumber = " + iNumber);}

\textbf{Output:}

\texttt{iNumber = 32\\
increment(iNumber) = 33\\
iNumber = 33}


\textbf{See also:}

\samp{decrement} \ref{decrement()}, \samp{floor} \ref{floor()}, \samp{ceil} \ref{ceil()}
\end{itemize}
\pdflabel{indentFile()}
\index{indentFile()}
\pdfsubsection{indentFile}
\begin{itemize}
	\item function \textbf{indentFile(}\samp{file} \textbf{:} \textit{string}\textbf{, }\samp{mode} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{file}}{\textit{string}}{name of a file to indent}
	\lineiii{\samp{mode}}{\textit{string}}{\textbf{default value:} \textit{""}\\
type of text to indent}
\end{tableiii}
Indents the file passed to parameter \samp{file}, forcing the indentation mode via the
argument \samp{mode}. If the argument is empty or omited, the file extension drives the
indentation mode:
\begin{itemize}
	\item \textit{cpp}, \textit{cxx}, \textit{h}, \textit{hxx}: will indent as expected for a \textbf{C++} format,
	\item \textit{java}: will indent as expected for a \textbf{JAVA} format,
\end{itemize}
More format will be recognized in the future.

The function returns \samp{true} if the file needed to be indented,
meaning that it has changed after processing the indentation.

\textbf{Example:}

\texttt{traceLine("We'll indent file 'Documentation/IndentSample.cpp' containing:");\\
copyFile("Documentation/IndentSample.txt", "Documentation/IndentSample.cpp");\\
traceLine(loadFile("Documentation/IndentSample.cpp"));\\
traceLine("File changed after indenting = '" + indentFile("Documentation/IndentSample.cpp") + "'");\\
traceLine("File 'Documentation/IndentSample.cpp' after indentation:");\\
traceLine(loadFile("Documentation/IndentSample.cpp"));}

\textbf{Output:}

\texttt{We'll indent file 'Documentation/IndentSample.cpp' containing:\\
int f(int i) \{\\
switch (i) \{\\
\makebox[0.8cm][l]{}case 2:\\
case 3:\\
if (i == 2) \{\\
h();\\
\makebox[0.8cm][l]{}\}\\
g(i - 1);\\
\makebox[0.8cm][l]{}break;\\
\makebox[1.6cm][l]{}\}\\
\}\\
\\
File changed after indenting = 'true'\\
File 'Documentation/IndentSample.cpp' after indentation:\\
int f(int i) \{\\
\makebox[0.8cm][l]{}switch (i) \{\\
\makebox[1.6cm][l]{}case 2:\\
\makebox[1.6cm][l]{}case 3:\\
\makebox[2.4cm][l]{}if (i == 2) \{\\
\makebox[3.2cm][l]{}h();\\
\makebox[2.4cm][l]{}\}\\
\makebox[2.4cm][l]{}g(i - 1);\\
\makebox[2.4cm][l]{}break;\\
\makebox[0.8cm][l]{}\}\\
\}\\
}


\textbf{See also:}

\samp{indentText} \ref{indentText()}
\end{itemize}
\pdflabel{index()}
\index{index()}
\pdfsubsection{index}
\begin{itemize}
	\item function \textbf{index(}\samp{i} \textbf{:} \textit{iterator}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator of a \samp{foreach} statement}
\end{tableiii}
Returns the position of the item the iterator points to.
The position in the list begins counting at 0.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
foreach i in myTree \{\\
\makebox[0.8cm][l]{}traceLine("The item '" + key(i) + "' is at position " + index(i) + "");\\
\}}

\textbf{Output:}

\texttt{The item 'Everest' is at position 0\\
The item 'Tea spoon' is at position 1}


\textbf{See also:}

\samp{first} \ref{first()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}, \samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}
\end{itemize}
\pdflabel{inf()}
\index{inf()}
\pdfsubsection{inf}
\begin{itemize}
	\item function \textbf{inf(}\samp{left} \textbf{:} \textit{double}\textbf{, }\samp{right} \textbf{:} \textit{double}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{double}}{the first member}
	\lineiii{\samp{right}}{\textit{double}}{the second member}
\end{tableiii}
Compares two numbers and returns \samp{true} if the first member given by
argument \samp{left} is strictly smaller than the second member passed to
argument \samp{right}.

Don't use the operator \samp{'<'} to compare numbers in the classical syntax of
the interpreter: it only checks the lexicographical order. So, \textit{'12 < 3'} is \samp{true}.
However, it exists an escape mode that allows writing arithmetic comparisons
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{left} \textbf{<} \textit{right}\$}
is equivalent to \samp{inf(\textit{left}, \textit{right})}.

\textbf{Example:}

\texttt{traceLine("inf(3, 12) = '" + inf(3, 12) + "'");\\
traceLine("3 < 12 = '" + (3 < 12) + "'");}

\textbf{Output:}

\texttt{inf(3, 12) = 'true'\\
3 < 12 = ''}


\textbf{See also:}

\samp{equal} \ref{equal()}, \samp{sup} \ref{sup()}
\end{itemize}
\pdflabel{inputKey()}
\index{inputKey()}
\pdfsubsection{inputKey}
\begin{itemize}
	\item function \textbf{inputKey(}\samp{echo} \textbf{:} \textit{bool}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{echo}}{\textit{bool}}{asks for echoing the standard input on the console}
\end{tableiii}
Returns a character extracted from the standard input, the keyboard generally.
If no key was pressed, it returns an empty string.

See statement modifiers \samp{file_as_standard_input} (\ref{file as standard input}) and
\samp{string_as_standard_input} (\ref{string as standard input}) to change
the source of the standard input.

If the source of the standard input is the keyboard, the argument \samp{echo}
has no effects. Otherwise, the input text is displayed into the console only if
\samp{echo} is worth \samp{true}.
\end{itemize}
\pdflabel{inputLine()}
\index{inputLine()}
\pdfsubsection{inputLine}
\begin{itemize}
	\item function \textbf{inputLine(}\samp{echo} \textbf{:} \textit{bool}\textbf{, }\samp{prompt} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{echo}}{\textit{bool}}{asks for echoing the standard input on the console}
	\lineiii{\samp{prompt}}{\textit{string}}{\textbf{default value:} \textit{""}\\
text to prompt at the beginning of the line}
\end{tableiii}
Returns a line that was extracted from the standard input, the keyboard generally.
See statement modifiers \samp{file_as_standard_input} (\ref{file as standard input}) and
\samp{string_as_standard_input} (\ref{string as standard input}) to change
the source of the standard input.

If the \samp{prompt} argument is populated and different of an empty string,
the corresponding text is displayed at the beginning of the line.

If the source of the standard input is the keyboard, the argument \samp{echo}
has no effects. Otherwise, the input text is displayed into the console only if
\samp{echo} is worth \samp{true}.

\textbf{Example:}

\texttt{traceText("Please enter something> ");\\
local sKeyboardText = inputLine(true);\\
traceLine("The user said: '" + sKeyboardText + "'");}

\textbf{Output:}

\texttt{Please enter something> These characters were typed by hand on the keyboard!\\
The user said: 'These characters were typed by hand on the keyboard!'}
\end{itemize}
\pdflabel{insertElementAt()}
\index{insertElementAt()}
\pdfsubsection{insertElementAt}
\begin{itemize}
	\item procedure \textbf{insertElementAt(}\samp{list} \textbf{:} \textit{treeref}\textbf{, }\samp{key} \textbf{:} \textit{string}\textbf{, }\samp{position} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{list}}{\textit{treeref}}{an array of nodes}
	\lineiii{\samp{key}}{\textit{string}}{the entry key of the element to insert}
	\lineiii{\samp{position}}{\textit{int}}{where to insert the new element, starting at 0}
\end{tableiii}
Insert a new element to \samp{list}, at a position given by the argument \samp{position}.
The argument \samp{key} indicates the key of this element, which is built empty.

If the key is an empty string, then the key is supposed to be worth the size of the list automatically.

You can access the new element by writing either:\\
\texttt{list\textbf{\#}[\textit{position}]}\\
or\\
\texttt{list[\textit{key}]}

\textbf{Example:}

\texttt{local list;\\
insert list["twin peaks"] = "twin peaks";\\
insert list["everest"] = "everest";\\
traceLine("before inserting the kilimanjaro:");\\
foreach i in list traceLine("$\backslash$t" + i);\\
insertElementAt(list, "kilimanjaro", 1);\\
list\#[1] = "kilimanjaro"; // assign a value to the new element\\
traceLine("after inserting the kilimanjaro at the second place:");\\
foreach i in list traceLine("$\backslash$t" + i);}

\textbf{Output:}

\texttt{before inserting the kilimanjaro:\\
\makebox[0.8cm][l]{}twin peaks\\
\makebox[0.8cm][l]{}everest\\
after inserting the kilimanjaro at the second place:\\
\makebox[0.8cm][l]{}twin peaks\\
\makebox[0.8cm][l]{}kilimanjaro\\
\makebox[0.8cm][l]{}everest}
\end{itemize}
\pdflabel{invertArray()}
\index{invertArray()}
\pdfsubsection{invertArray}
\begin{itemize}
	\item procedure \textbf{invertArray(}\samp{array} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{array}}{\textit{treeref}}{the array to handle}
\end{tableiii}
Inverts the elements of the array passed to the well-named argument \samp{array},
such as the first item becomes the last one, and the last item the first one.

\textbf{Example:}

\texttt{local list;\\
insert list["twin peaks"] = "twin peaks";\\
insert list["karakorum"] = "karakorum";\\
insert list["everest"] = "everest";\\
insert list["kilimanjaro"] = "kilimanjaro";\\
traceLine("before inverting the array:");\\
foreach i in list traceLine("$\backslash$t" + i);\\
invertArray(list);\\
traceLine("after inverting the array:");\\
foreach i in list traceLine("$\backslash$t" + i);}

\textbf{Output:}

\texttt{before inverting the array:\\
\makebox[0.8cm][l]{}twin peaks\\
\makebox[0.8cm][l]{}karakorum\\
\makebox[0.8cm][l]{}everest\\
\makebox[0.8cm][l]{}kilimanjaro\\
after inverting the array:\\
\makebox[0.8cm][l]{}kilimanjaro\\
\makebox[0.8cm][l]{}everest\\
\makebox[0.8cm][l]{}karakorum\\
\makebox[0.8cm][l]{}twin peaks}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{isEmpty} \ref{isEmpty()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{isEmpty()}
\index{isEmpty()}
\pdfsubsection{isEmpty}
\begin{itemize}
	\item function \textbf{isEmpty(}\samp{array} \textbf{:} \textit{treeref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{array}}{\textit{treeref}}{any node of a tree}
\end{tableiii}
Returns \samp{\textbf{true}} if the argument \samp{array} embeds an
array of trees, and \samp{\textbf{false}} otherwise.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
traceLine("isEmpty(myTree) = '" + isEmpty(myTree) + "'");}

\textbf{Output:}

\texttt{isEmpty(myTree) = ''}


\pdflabel{method empty()}
\index{method!empty()}
\textbf{Method:} \textit{array}.\samp{empty}()


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{removeVariable} \ref{removeVariable()}
\end{itemize}
\pdflabel{isIdentifier()}
\index{isIdentifier()}
\pdfsubsection{isIdentifier}
\begin{itemize}
	\item function \textbf{isIdentifier(}\samp{identifier} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{identifier}}{\textit{string}}{an identifier is a string composed of letters and underscores ; digits are admitted too, except at the first place}
\end{tableiii}
This predicate checks whether the string passed by parameter is an identifier
or not.

\textbf{Example:}

\texttt{traceLine("isIdentifier('atom') = '" + isIdentifier("atom") + "'");\\
traceLine("isIdentifier('\$money') = '" + isIdentifier("\$money") + "'");}

\textbf{Output:}

\texttt{isIdentifier('atom') = 'true'\\
isIdentifier('\$money') = ''}
\end{itemize}
\pdflabel{isNegative()}
\index{isNegative()}
\pdfsubsection{isNegative}
\begin{itemize}
	\item function \textbf{isNegative(}\samp{number} \textbf{:} \textit{double}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{double}}{a number to check}
\end{tableiii}
This predicate checks whether the number passed by parameter is strictly
negative or not.

If the argument isn't recognized as a number, the number is supposed to be worth
\samp{0}, so the function returns \samp{false}.

Be careful if you choose the expression \samp{'< 0'} to compare numbers in the
classical syntax of the interpreter: it only checks the lexicographical order.
So, \textit{'+0.0 <= 0'} is \samp{false}!
However, it exists an escape mode that allows writing arithmetic comparisons
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{number} \textbf{<= 0}\$}
is equivalent to \samp{isNegative(\textit{number})}.

\textbf{Example:}

\texttt{traceLine("isNegative(0) = '" + isNegative(0) + "'");\\
traceLine("isNegative(-1) = '" + isNegative(-1) + "'");}

\textbf{Output:}

\texttt{isNegative(0) = ''\\
isNegative(-1) = 'true'}


\textbf{See also:}

\samp{isPositive} \ref{isPositive()}
\end{itemize}
\pdflabel{isNumeric()}
\index{isNumeric()}
\pdfsubsection{isNumeric}
\begin{itemize}
	\item function \textbf{isNumeric(}\samp{number} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{string}}{a floating-point number in text representation}
\end{tableiii}
This predicate checks whether the string passed by parameter is a floating-point
or not.

\textbf{Example:}

\texttt{traceLine("isNumeric('atom') = '" + isNumeric("atom") + "'");\\
traceLine("isNumeric('3.14') = '" + isNumeric("3.14") + "'");}

\textbf{Output:}

\texttt{isNumeric('atom') = ''\\
isNumeric('3.14') = 'true'}
\end{itemize}
\pdflabel{isPositive()}
\index{isPositive()}
\pdfsubsection{isPositive}
\begin{itemize}
	\item function \textbf{isPositive(}\samp{number} \textbf{:} \textit{double}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{double}}{a number to check}
\end{tableiii}
This predicate checks whether the number passed by parameter is strictly
positive or not.

If the argument isn't recognized as a number, the number is supposed to be worth
\samp{0}, so the function returns \samp{false}.

Be careful if you choose the expression \samp{'> 0'} to compare numbers in the
classical syntax of the interpreter: it only checks the lexicographical order.
So, \textit{'-0.0 >= 0'} is \samp{false}!
However, it exists an escape mode that allows writing arithmetic comparisons
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{number} \textbf{>= 0}\$}
is equivalent to \samp{isPositive(\textit{number})}.

\textbf{Example:}

\texttt{traceLine("isPositive(0) = '" + isPositive(0) + "'");\\
traceLine("isPositive(1) = '" + isPositive(1) + "'");}

\textbf{Output:}

\texttt{isPositive(0) = ''\\
isPositive(1) = 'true'}


\textbf{See also:}

\samp{isNegative} \ref{isNegative()}
\end{itemize}
\pdflabel{joinStrings()}
\index{joinStrings()}
\pdfsubsection{joinStrings}
\begin{itemize}
	\item function \textbf{joinStrings(}\samp{list} \textbf{:} \textit{tree}\textbf{, }\samp{separator} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{list}}{\textit{tree}}{the list that contains the strings to join}
	\lineiii{\samp{separator}}{\textit{string}}{the sequence of chars that separates the strings}
\end{tableiii}
This function returns the concatenation of all strings put into \samp{list},
putting a separator between each of them.

If the list is empty, the function will return an empty string.

\textbf{Example:}

\texttt{local listOfItems = \{"a", "yellow", "submarine"\};\\
traceLine("joinStrings(\{'a', 'yellow', 'submarine'\}, './.'):");\\
traceLine(joinStrings(listOfItems, "./."));}

\textbf{Output:}

\texttt{joinStrings(\{'a', 'yellow', 'submarine'\}, './.'):\\
a./.yellow./.submarine}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{key()}
\index{key()}
\pdfsubsection{key}
\begin{itemize}
	\item function \textbf{key(}\samp{i} \textbf{:} \textit{iterator}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator of a \samp{foreach} statement or pointing to a list}
\end{tableiii}
Returns the key that allows accessing the current item of the iterated list.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
foreach i in myTree \{\\
\makebox[0.8cm][l]{}traceLine("key = '" + key(i) + "' value = '" + i + "'");\\
\}}

\textbf{Output:}

\texttt{key = 'Everest' value = 'mountain'\\
key = 'Tea spoon' value = 'silverware'}


\textbf{See also:}

\samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}, \samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}
\end{itemize}
\pdflabel{last()}
\index{last()}
\pdfsubsection{last}
\begin{itemize}
	\item function \textbf{last(}\samp{i} \textbf{:} \textit{iterator}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator of a \samp{foreach} statement or pointing to a list}
\end{tableiii}
Returns \samp{true} if the iterator argument \samp{i} points to the last item
of the iterated list.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
foreach i in myTree \{\\
\makebox[0.8cm][l]{}if last(i) traceLine("The last item key of the list is '" + key(i) + "'");\\
\}}

\textbf{Output:}

\texttt{The last item key of the list is 'Tea spoon'}


\textbf{See also:}

\samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{prec} \ref{prec()}, \samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}
\end{itemize}
\pdflabel{leftString()}
\index{leftString()}
\pdfsubsection{leftString}
\begin{itemize}
	\item function \textbf{leftString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{length}}{\textit{int}}{a positive number}
\end{tableiii}
Returns the first characters that belong to the string passed to the argument
\samp{text}. The number of characters to take is given by argument
\samp{length}. If the string contains less than \samp{length} characters, the
function returns all of them.

\textbf{Example:}

\texttt{traceLine("leftString('airport', 3) = '" + leftString("airport", 3) + "'");\\
traceLine("leftString('airport', 8) = '" + leftString("airport", 8) + "'");}

\textbf{Output:}

\texttt{leftString('airport', 3) = 'air'\\
leftString('airport', 8) = 'airport'}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{lengthString()}
\index{lengthString()}
\pdfsubsection{lengthString}
\begin{itemize}
	\item function \textbf{lengthString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
\end{tableiii}
Returns the length of the sequence of characters represented by argument \samp{text}.

\textbf{Example:}

\texttt{local sText = "A rabbit ran in the garden"; // size of this string is 26 characters\\
traceLine("lengthString($\backslash$"" + sText + "$\backslash$") = " + lengthString(sText));}

\textbf{Output:}

\texttt{lengthString("A rabbit ran in the garden") = 26}


\pdflabel{method length()}
\index{method!length()}
\textbf{Method:} \textit{text}.\samp{length}()


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{listAllGeneratedFiles()}
\index{listAllGeneratedFiles()}
\pdfsubsection{listAllGeneratedFiles}
\begin{itemize}
	\item procedure \textbf{listAllGeneratedFiles(}\samp{files} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{files}}{\textit{treeref}}{populated with the names of all files generated since the interpreter has launched}
\end{tableiii}
Populates the parameter \samp{files} with the list of all output files generated
since the interpreter has launched.

The array \samp{files} indexes each node with the name of the generated output file,
and each node owns a branch called \samp{scripts}.\\
This branch gives the list of all template-based scripts that have contributed to the
generation of the output file (often one script only, but could be more).\\
The key index and the value of the nodes in the array \samp{scripts} are worth the script file names.

The procedure raises an error if the tree parameter \samp{files} doesn't exist.

\textbf{Example:}

\texttt{local allOutputFiles;\\
listAllGeneratedFiles(allOutputFiles);\\
traceLine("List of all generated files:");\\
foreach i in allOutputFiles \{\\
\makebox[0.8cm][l]{}// A lot of output files are generated before building\\
\makebox[0.8cm][l]{}// this document, such as C++ sources of CodeWorker:\\
\makebox[0.8cm][l]{}// they are ignored\\
\makebox[0.8cm][l]{}if i.endString(".cpp") || i.endString(".h") continue;\\
\makebox[0.8cm][l]{}// Other files are displayed:\\
\makebox[0.8cm][l]{}traceLine(" * '" + i.key() + "'");\\
\makebox[0.8cm][l]{}traceText("     -> \{");\\
\makebox[0.8cm][l]{}foreach j in i.scripts \{\\
\makebox[1.6cm][l]{}if !j.first() traceText(", ");\\
\makebox[1.6cm][l]{}traceText('$\backslash$"' + j + '$\backslash$"');\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}traceLine('\}');\\
\}}

\textbf{Output:}

\texttt{List of all generated files:\\
\makebox[0.8cm][l]{}* '.\#f2'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Generation/LaTeX2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Documentation/GeneratingExamples.cwt'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Documentation/GeneratingExamplesBuilder.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Documentation/ParsingExamples.cws'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Documentation/ParsingExamplesBuilder.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Scripts/Tutorial/GettingStarted/JAVA/solarsystem/Earth.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/JAVAObject.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Scripts/Tutorial/GettingStarted/JAVA/solarsystem/Planet.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/JAVAObject.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Scripts/Tutorial/GettingStarted/JAVA/solarsystem/SolarSystem.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/JAVAObject.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Scripts/Tutorial/GettingStarted/SolarSystem.tex'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/HTML2LaTeX.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Scripts/Tutorial/GettingStarted/SolarSystem0.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/HTMLDocumentation.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/Scripts/Tutorial/GettingStarted/SolarSystem1.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/HTMLDocumentation.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/WebSite/ScriptsRepository.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Generation/WebSite.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/Projects/generator/WebSite/repository/CodeWorker\_grammar.cwp'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Generation/CWgrammar\_expander.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/Documentation/SolarSystem.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/generator/Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/Scripts/Tutorial/GettingStarted/Tiny0.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Scripts/Tutorial/GettingStarted/Tiny-HTML.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/Scripts/Tutorial/GettingStarted/tiny/A.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/Scripts/Tutorial/GettingStarted/tiny/B.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/Scripts/Tutorial/GettingStarted/tiny/C.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/Scripts/Tutorial/GettingStarted/tiny/D.java'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/examples/cdcatalog.cwt'\\
\makebox[1.6cm][l]{}-> \{"e:/projects/generator/WebSite/repository/GenBeautifier.cwp", "e:/projects/generator/WebSite/repository/XSLtoCodeWorker.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/examples/cdcatalog.html'\\
\makebox[1.6cm][l]{}-> \{"e:/projects/generator/WebSite/examples/cdcatalog.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/examples/ejb-jar\_2\_0-parser.cwp'\\
\makebox[1.6cm][l]{}-> \{"e:/projects/generator/WebSite/repository/DTDtoBNF.cwt"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/CWML.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/CWscript2HTML.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/CodeWorker\_grammar.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/DTDparser.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/DTDtoBNF-example1.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/DTDtoBNF.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/RawProfiling-example1.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/RawProfilingCpp.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/RawProfilingCppTransformation.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/RawProfilingHpp.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/RawProfilingLeader.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/XMLparser-example1.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/XMLparser.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/XSLparser.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/XSLtoBNF-example1.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/XSLtoCodeWorker.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/basicInformation.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/classDiagram.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/classDiagramGraphViz.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/hitCounter.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/hitCounterParser.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}\\
\makebox[0.8cm][l]{}* 'e:/projects/generator/WebSite/highlighting/hitCounterUpdate.html'\\
\makebox[1.6cm][l]{}-> \{"e:/Projects/Generator/WebSite/repository/CWscript2HTML.cwp"\}}
\end{itemize}
\pdflabel{loadBinaryFile()}
\index{loadBinaryFile()}
\pdfsubsection{loadBinaryFile}
\begin{itemize}
	\item function \textbf{loadBinaryFile(}\samp{file} \textbf{:} \textit{string}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{file}}{\textit{string}}{name of the binary file to load}
	\lineiii{\samp{length}}{\textit{int}}{\textbf{default value:} \textit{-1}\\
number of bytes to read}
\end{tableiii}
Returns the binary content of the file whose name is passed to argument \samp{file},
or the \textit{length} first bytes only if this facultative argument isn't
negative.
The content concatenates a sequence of hexadecimal digits, so a byte is stored in
2 characters:\\
\samp{\textit{binary-content} ::= [\textit{byte}]*;\\
	\textit{byte} ::= [\textbf{'0'..'9'} | \textbf{'A'..'F'} | \textbf{'a'..'f'}]2;}

If the file doesn't exist or can't be read with success, an error occurs.

\textbf{Example:}

\texttt{local sContent = loadBinaryFile("readme.txt");\\
local sFormatedContent;\\
local iLine = 0;\\
while sContent \&\& \$iLine < 10\$ \{\\
\makebox[0.8cm][l]{}sFormatedContent += leftString(sContent, 40) + endl();\\
\makebox[0.8cm][l]{}sContent = sContent.subString(40);\\
\makebox[0.8cm][l]{}increment(iLine);\\
\}\\
traceLine("the first 200 bytes of 'readme.txt' are:" + endl() + sFormatedContent);}

\textbf{Output:}

\texttt{the first 200 bytes of 'readme.txt' are:\\
2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F\\
2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F\\
2F2F2F2F2F2F2F2F2F2F0D0A2F2F202020202020\\
20202020202020202020202020436F6465576F72\\
6B65722020202020202020202020202020202020\\
2F2F0D0A2F2F2020202020202020202020202020\\
20202020202D2D2D2D2D2D2D2D2D2D2020202020\\
2020202020202020202020202F2F0D0A2F2F2F2F\\
2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F\\
2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F2F\\
}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{loadFile()}
\index{loadFile()}
\pdfsubsection{loadFile}
\begin{itemize}
	\item function \textbf{loadFile(}\samp{file} \textbf{:} \textit{string}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{file}}{\textit{string}}{name of the file to load}
	\lineiii{\samp{length}}{\textit{int}}{\textbf{default value:} \textit{-1}\\
number of characters to read}
\end{tableiii}
Returns the content of the file whose name is passed to argument \samp{file},
or the \textit{length} first characters only if this facultative argument isn't
negative.

If the file doesn't exist or couldn't be read with success, an error occurs.

\textbf{Example:}

\texttt{local sText = loadFile("readme.txt");\\
sText = sText.leftString(200);\\
traceLine("the 200 first characters of 'readme.txt' are:" + endl() + sText);}

\textbf{Output:}

\texttt{the 200 first characters of 'readme.txt' are:\\
//////////////////////////////////////////////////\\
//                   CodeWorker                 //\\
//                   ----------                 //\\
////////////////////////////////////////////}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{loadVirtualFile()}
\index{loadVirtualFile()}
\pdfsubsection{loadVirtualFile}
\begin{itemize}
	\item function \textbf{loadVirtualFile(}\samp{handle} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{handle}}{\textit{string}}{the name of the virtual file to load}
\end{tableiii}
Returns the content of the \textit{virtual} file whose name is passed to argument \samp{file}.

If the \textit{virtual} file doesn't exist or couldn't be read with success, an error occurs.


\textbf{See also:}

\samp{createVirtualFile} \ref{createVirtualFile()}, \samp{createVirtualTemporaryFile} \ref{createVirtualTemporaryFile()}, \samp{deleteVirtualFile} \ref{deleteVirtualFile()}, \samp{existVirtualFile} \ref{existVirtualFile()}
\end{itemize}
\pdflabel{log()}
\index{log()}
\pdfsubsection{log}
\begin{itemize}
	\item function \textbf{log(}\samp{x} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{x}}{\textit{double}}{the floating-point whose logarithm is to compute}
\end{tableiii}
Returns the logarithm of \samp{x}.

If \samp{x} is negative, it throws an error.\\
If \samp{x} is 0, it returns \textit{infinite}.

\textbf{Example:}

\texttt{traceLine("log(5.369e+14)/log(10) = " + \$log(5.369e+14)/log(10)\$);\\
traceLine("log(0) = " + log(0));}

\textbf{Output:}

\texttt{log(5.369e+14)/log(10) = 14.729893403963237\\
log(0) = -1.\#INF00000000e+000}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{sub} \ref{sub()}, \samp{mult} \ref{mult()}, \samp{div} \ref{div()}, \samp{exp} \ref{exp()}, \samp{mod} \ref{mod()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{longToBytes()}
\index{longToBytes()}
\pdfsubsection{longToBytes}
\begin{itemize}
	\item function \textbf{longToBytes(}\samp{long} \textbf{:} \textit{ulong}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{long}}{\textit{ulong}}{an unsigned long integer using the decimal base}
\end{tableiii}
Converts an unsigned long integer in decimal base to its 4-bytes representation.
Bytes are ordered in the host order (memory storage).

\textbf{Example:}

\texttt{traceLine("longToBytes(65535) = '" + longToBytes(65535) + "'");}

\textbf{Output:}

\texttt{longToBytes(65535) = 'FFFF0000'}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{octalToDecimal} \ref{octalToDecimal()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{midString()}
\index{midString()}
\pdfsubsection{midString}
\begin{itemize}
	\item function \textbf{midString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{pos} \textbf{:} \textit{int}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{pos}}{\textit{int}}{a position into argument \samp{text}}
	\lineiii{\samp{length}}{\textit{int}}{the number of characters to extract}
\end{tableiii}
Returns a substring located into the string \samp{text} to the position passed
to the argument \samp{pos}. The position starts counting at \samp{0}. The
substring will be extracted for a size given by parameter \samp{length}, or
less if it has reached the end of the string.

If the argument \samp{pos} is greater than the length of \samp{text}, the
function returns an empty string.

\textbf{Example:}

\texttt{local sText = "Banks offer weapons without bullets";\\
traceLine("midString('" + sText + "', 12, 7) = '" + midString(sText, 12, 7) + "'");}

\textbf{Output:}

\texttt{midString('Banks offer weapons without bullets', 12, 7) = 'weapons'}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{mod()}
\index{mod()}
\pdfsubsection{mod}
\begin{itemize}
	\item function \textbf{mod(}\samp{dividend} \textbf{:} \textit{int}\textbf{, }\samp{divisor} \textbf{:} \textit{int}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{dividend}}{\textit{int}}{the first operand}
	\lineiii{\samp{divisor}}{\textit{int}}{the second operand}
\end{tableiii}
Returns the remainder when the first operand is divided by the second. It
applies the modulus operator.
Members are converted from strings to integers, supposed being worth \samp{0} if a parsing error occurs;
then the modulus is processed, and the result is converted to a string.

Remember that the symbol \textbf{'\%'} doesn't mean anything in the standard syntax of the
language, so there is no way to confuse for expressing a modulus operator.
However, it exists an escape mode that allows writing arithmetic expressions
between \textbf{'\$'} symbols, as formulae under \textit{LaTeX}. So, \samp{\$\textit{dividend} \textbf{\%} \textit{divisor}\$}
is equivalent to \samp{mod(\textit{dividend}, \textit{divisor})}.

\textbf{Example:}

\texttt{traceLine("mod(5, 2) = '" + mod(5, 2) + "'");}

\textbf{Output:}

\texttt{mod(5, 2) = '1'}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{sub} \ref{sub()}, \samp{mult} \ref{mult()}, \samp{div} \ref{div()}, \samp{exp} \ref{exp()}, \samp{log} \ref{log()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{mult()}
\index{mult()}
\pdfsubsection{mult}
\begin{itemize}
	\item function \textbf{mult(}\samp{left} \textbf{:} \textit{double}\textbf{, }\samp{right} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{double}}{the first operand}
	\lineiii{\samp{right}}{\textit{double}}{the second operand}
\end{tableiii}
Returns the result of arithmetic multiplication \samp{left} \textbf{*} \samp{right}.
Members are converted from strings to numbers, supposed being worth \samp{0} if a parsing error occurs;
then the multiplication is processed, and the result is converted to a string,
skipping fractional part if all digits after the dot are \textit{0}.

Remember that the symbol \textbf{'*'} doesn't mean anything in the standard syntax of the
language, so there is no way to confuse for expressing a multiplication.
However, it exists an escape mode that allows writing arithmetic expressions
between \textbf{'\$'} symbols, as formulae under \textit{LaTeX}. So, \samp{\$\textit{left} \textbf{*} \textit{right}\$}
is equivalent to \samp{mult(\textit{left}, \textit{right})}.

\textbf{Example:}

\texttt{traceLine("mult(5.5, 2) = '" + mult(5.5, 2) + "'");}

\textbf{Output:}

\texttt{mult(5.5, 2) = '11'}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{sub} \ref{sub()}, \samp{div} \ref{div()}, \samp{exp} \ref{exp()}, \samp{log} \ref{log()}, \samp{mod} \ref{mod()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{networkLongToHost()}
\index{networkLongToHost()}
\pdfsubsection{networkLongToHost}
\begin{itemize}
	\item function \textbf{networkLongToHost(}\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{a 4-bytes representation of a long integer sorted in the network bytes order}
\end{tableiii}
Converts a 4-bytes representation of a long integer to the host bytes order.
\CodeWorker\ stores a byte as a 2-hexadecimal digits; the function raises
an error if the argument \samp{bytes} is malformed.

Use \samp{longToBytes()} and \samp{bytesToLong()} to swap between decimal
and host binary representation of a long integer.

\textbf{Example:}

\texttt{traceLine("networkLongToHost('EFCDAB89') = '" + networkLongToHost("EFCDAB89") + "'");}

\textbf{Output:}

\texttt{networkLongToHost('EFCDAB89') = '89ABCDEF'}


\textbf{See also:}

\samp{hostToNetworkLong} \ref{hostToNetworkLong()}, \samp{hostToNetworkShort} \ref{hostToNetworkShort()}, \samp{networkShortToHost} \ref{networkShortToHost()}
\end{itemize}
\pdflabel{networkShortToHost()}
\index{networkShortToHost()}
\pdfsubsection{networkShortToHost}
\begin{itemize}
	\item function \textbf{networkShortToHost(}\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{a 2-bytes representation of a short integer sorted in the network bytes order}
\end{tableiii}
Converts a 2-bytes representation of a short integer to the host bytes order.
\CodeWorker\ stores a byte as a 2-hexadecimal digits; the function raises
an error if the argument \samp{bytes} is malformed.

Use \samp{shortToBytes()} and \samp{bytesToShort()} to swap between decimal
and host binary representation of a short integer.

\textbf{Example:}

\texttt{traceLine("networkShortToHost('EF12') = '" + networkShortToHost("EF12") + "'");}

\textbf{Output:}

\texttt{networkShortToHost('EF12') = '12EF'}


\textbf{See also:}

\samp{hostToNetworkLong} \ref{hostToNetworkLong()}, \samp{networkLongToHost} \ref{networkLongToHost()}, \samp{hostToNetworkShort} \ref{hostToNetworkShort()}
\end{itemize}
\pdflabel{next()}
\index{next()}
\pdfsubsection{next}
\begin{itemize}
	\item function \textbf{next(}\samp{i} \textbf{:} \textit{iterator}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator of a \samp{foreach} statement or pointing to items of a list}
\end{tableiii}
The iterator will now point to the next item of the list and returns \samp{true} if exists.


\textbf{See also:}

\samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{prec} \ref{prec()}, \samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}
\end{itemize}
\pdflabel{not()}
\index{not()}
\pdfsubsection{not}
\begin{itemize}
	\item function \textbf{not(}\samp{expression} \textbf{:} \textit{bool}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{expression}}{\textit{bool}}{any kind of expression}
\end{tableiii}
This function does the same work as the unary operator \textbf{'!'}: it returns
\samp{true} if the evaluation of the \samp{expression} is an empty string, and
\samp{false} otherwise.

\textbf{Example:}

\texttt{local myVariable;\\
traceLine("not(existVariable(myVariable)) = '" + not(existVariable(myVariable)) + "'");}

\textbf{Output:}

\texttt{not(existVariable(myVariable)) = ''}
\end{itemize}
\pdflabel{octalToDecimal()}
\index{octalToDecimal()}
\pdfsubsection{octalToDecimal}
\begin{itemize}
	\item function \textbf{octalToDecimal(}\samp{octalNumber} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{octalNumber}}{\textit{string}}{an octal integer to convert to a decimal number}
\end{tableiii}
Converts an octal integer, passed to the argument \samp{octalNumber}, to a
signed decimal integer and returns the result. If \samp{octalNumber} doesn't conform to
the syntax of an octal number (\samp{\textit{octalNumber} ::= \#!ignore [\textbf{'0'..'8'}]+}),
the function raises an error.

\textbf{Example:}

\texttt{traceLine("octalToDecimal('765') = " + octalToDecimal("765"));}

\textbf{Output:}

\texttt{octalToDecimal('765') = 501}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{shortToBytes} \ref{shortToBytes()}
\end{itemize}
\pdflabel{openLogFile()}
\index{openLogFile()}
\pdfsubsection{openLogFile}
\begin{itemize}
	\item procedure \textbf{openLogFile(}\samp{filename} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the file where log information will be put}
\end{tableiii}
Creates (or erases if already exists) a log file, which remains valid upto the end of the execution.
Each \textit{trace} function (\samp{traceLine()}, \samp{traceText()}, \samp{traceStack()})
will write in the log file.\\
This function is very convenient for debugging a CGI script, where the standard
output is devoted to the result page.

Note that passing an empty filename stops the log mechanism.
\end{itemize}
\pdflabel{parseAsBNF()}
\index{parseAsBNF()}
\pdfsubsection{parseAsBNF}
\begin{itemize}
	\item procedure \textbf{parseAsBNF(}\samp{BNFFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{inputFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{BNFFileName}}{\textit{script<BNF>}}{the name of the \textit{BNF-driven} parsing script}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed with \samp{this} variable}
	\lineiii{\samp{inputFileName}}{\textit{string}}{the file to parse}
\end{tableiii}
Parses an input file whose name is given by the argument \samp{inputFileName}.
It executes the \samp{BNF-driven} script called \samp{BNFFileName}; see section
\ref{BNF syntax} for more information.


\textbf{See also:}

\samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translate} \ref{translate()}, \samp{translateString} \ref{translateString()}, \samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}
\end{itemize}
\pdflabel{parseFree()}
\index{parseFree()}
\pdfsubsection{parseFree}
\begin{itemize}
	\item procedure \textbf{parseFree(}\samp{designFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{inputFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{designFileName}}{\textit{script<free>}}{the name of the parsing script that reads tokens in a procedural way}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed with \textit{this} variable}
	\lineiii{\samp{inputFileName}}{\textit{string}}{the file to parse}
\end{tableiii}
Parses an input file whose name is given by the argument \samp{inputFileName}.
It executes the \samp{procedural-driven} script called \samp{designFileName}; see section
\ref{Reading tokens for parsing} for more information.


\pdflabel{loadDesign()}
\index{deprecated!loadDesign()}
\textbf{Deprecated form:} \samp{loadDesign} has disappeared since version \textit{1.6}


\textbf{See also:}

\samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translate} \ref{translate()}, \samp{translateString} \ref{translateString()}, \samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}
\end{itemize}
\pdflabel{parseFreeQuiet()}
\index{parseFreeQuiet()}
\pdfsubsection{parseFreeQuiet}
\begin{itemize}
	\item function \textbf{parseFreeQuiet(}\samp{designFileName} \textbf{:} \textit{string}\textbf{, }\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{inputFileName} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{designFileName}}{\textit{string}}{the name of the parsing script that reads tokens in a procedural way}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed with \textit{this} variable}
	\lineiii{\samp{inputFileName}}{\textit{string}}{the file to parse}
\end{tableiii}
This function parses the file passed to argument \samp{inputFileName}, following
the instructions of the procedure-driven parsing script given by parameter
\samp{designFileName}, but doesn't display messages to the standard output
stream. Messages are put into a string that is returned by the function.

\textbf{Example:}

\texttt{local sScript = "GettingStarted/SimpleML-token-reading.cws";\\
local sDesign = "GettingStarted/SolarSystem0.sml";\\
traceLine("sScript = '" + sScript + "'");\\
traceLine("sDesign = '" + sDesign + "'");\\
traceLine("messages of parseFreeQuiet(sScript, project, sDesign):");\\
traceLine(parseFreeQuiet(sScript, project, sDesign));}

\textbf{Output:}

\texttt{sScript = 'GettingStarted/SimpleML-token-reading.cws'\\
sDesign = 'GettingStarted/SolarSystem0.sml'\\
messages of parseFreeQuiet(sScript, project, sDesign):\\
the file has been read successfully\\
}


\textbf{See also:}

\samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translate} \ref{translate()}, \samp{translateString} \ref{translateString()}, \samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}
\end{itemize}
\pdflabel{parseStringAsBNF()}
\index{parseStringAsBNF()}
\pdfsubsection{parseStringAsBNF}
\begin{itemize}
	\item procedure \textbf{parseStringAsBNF(}\samp{BNFFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{content} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{BNFFileName}}{\textit{script<BNF>}}{the name of the \textit{BNF-driven} parsing script}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed with \samp{this} variable}
	\lineiii{\samp{content}}{\textit{string}}{the text to parse}
\end{tableiii}
Parses a text, which is given by the argument \samp{content} as a sequence of characters.
It executes the \samp{BNF-driven} script called \samp{BNFFileName}; see section
\ref{BNF syntax} for more information.


\textbf{See also:}

\samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{translate} \ref{translate()}, \samp{translateString} \ref{translateString()}, \samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}
\end{itemize}
\pdflabel{pathFromPackage()}
\index{pathFromPackage()}
\pdfsubsection{pathFromPackage}
\begin{itemize}
	\item function \textbf{pathFromPackage(}\samp{package} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{package}}{\textit{string}}{a package path}
\end{tableiii}
Converts a package path to a directory path. A \textit{package path} is a
sequence of identifiers separated by dots. All dots (\textbf{'.'}) encountered
are replaced by a path separator (\textbf{'$\backslash\backslash$} under
\textit{Windows} and \textbf{'/'} on \textit{UNIX} platforms). A path
separator is added at the end.

\textbf{Example:}

\texttt{traceLine("pathFromPackage('java.solarsystem') = '" + pathFromPackage("java.solarsystem") + "'");}

\textbf{Output:}

\texttt{pathFromPackage('java.solarsystem') = 'java/solarsystem/'}
\end{itemize}
\pdflabel{postHTTPRequest()}
\index{postHTTPRequest()}
\pdfsubsection{postHTTPRequest}
\begin{itemize}
	\item function \textbf{postHTTPRequest(}\samp{URL} \textbf{:} \textit{string}\textbf{, }\samp{HTTPSession} \textbf{:} \textit{treeref}\textbf{, }\samp{arguments} \textbf{:} \textit{treeref}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{URL}}{\textit{string}}{URL of the HTTP server}
	\lineiii{\samp{HTTPSession}}{\textit{treeref}}{an object to describe the HTTP session}
	\lineiii{\samp{arguments}}{\textit{treeref}}{list of the arguments to POST; the key contains the name of the argument and the element gives the value}
\end{tableiii}
This function sends an HTTP's POST request to the HTTP server pointed to by the parameter
\samp{URL} with the list of arguments put into the the parameter \samp{arguments}.

The function returns the document read from the HTTP server.

The function \samp{sendHTTPRequest()} (see \ref{sendHTTPRequest()}) describes
the structure of the HTTP session object.


\textbf{See also:}

\samp{getHTTPRequest} \ref{getHTTPRequest()}, \samp{sendHTTPRequest} \ref{sendHTTPRequest()}
\end{itemize}
\pdflabel{pow()}
\index{pow()}
\pdfsubsection{pow}
\begin{itemize}
	\item function \textbf{pow(}\samp{x} \textbf{:} \textit{double}\textbf{, }\samp{y} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{x}}{\textit{double}}{the base}
	\lineiii{\samp{y}}{\textit{double}}{the exponent}
\end{tableiii}
Returns value of the argument \samp{x} raised to the power of the second
argument \samp{y}. The arguments are converted to numerics, being worth
\textit{0} when a conversion fails. The power is then processed, and the
result is converted to a string, skipping fractional part if all digits after
the dot are \textit{0}.

\textbf{Example:}

\texttt{traceLine("pow(3, 4) = " + pow(3, 4));}

\textbf{Output:}

\texttt{pow(3, 4) = 81}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{sub} \ref{sub()}, \samp{mult} \ref{mult()}, \samp{div} \ref{div()}, \samp{exp} \ref{exp()}, \samp{log} \ref{log()}, \samp{mod} \ref{mod()}
\end{itemize}
\pdflabel{prec()}
\index{prec()}
\pdfsubsection{prec}
\begin{itemize}
	\item function \textbf{prec(}\samp{i} \textbf{:} \textit{iterator}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{i}}{\textit{iterator}}{iterator of a \samp{foreach} statement or pointing to items of a list}
\end{tableiii}
The iterator will now point to the precedent item of the list and returns \samp{true} if exists.


\textbf{See also:}

\samp{first} \ref{first()}, \samp{index} \ref{index()}, \samp{last} \ref{last()}, \samp{key} \ref{key()}, \samp{next} \ref{next()}, \samp{createIterator} \ref{createIterator()}, \samp{createReverseIterator} \ref{createReverseIterator()}, \samp{duplicateIterator} \ref{duplicateIterator()}
\end{itemize}
\pdflabel{produceHTML()}
\index{produceHTML()}
\pdfsubsection{produceHTML}
\begin{itemize}
	\item procedure \textbf{produceHTML(}\samp{scriptFileName} \textbf{:} \textit{string}\textbf{, }\samp{HTMLFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{scriptFileName}}{\textit{string}}{a script file of \CodeWorker\ to highlight}
	\lineiii{\samp{HTMLFileName}}{\textit{string}}{the HTML file that represents the highlighted script}
\end{tableiii}
This procedure proposes to highlight a script written for \CodeWorker\ and
to provide the resulting colored script into an HTML file. Only \textbf{'@'}
and the text to put into the ouput stream are highlighted.

\textbf{Example:}

\texttt{produceHTML("Scripts/Tutorial/GettingStarted/Tiny-JAVA.cwt", getWorkingPath() + "Scripts/Tutorial/GettingStarted/Tiny-JAVAhighlight.html");\\
traceLine("the script file has been highlighted into 'Tiny-JAVAhighlight.html'");}

\textbf{Output:}

\texttt{the script file has been highlighted into 'Tiny-JAVAhighlight.html'}


\textbf{Known bugs:}

The procedure needs to be improved, so as to highlight tokens and keywords of the
language too. It doesn't work yet on BNF-driven scripts intended to a translation.
\end{itemize}
\pdflabel{putEnv()}
\index{putEnv()}
\pdfsubsection{putEnv}
\begin{itemize}
	\item procedure \textbf{putEnv(}\samp{name} \textbf{:} \textit{string}\textbf{, }\samp{value} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{name}}{\textit{string}}{name of the variable environment}
	\lineiii{\samp{value}}{\textit{string}}{new value to assign to the variable environment}
\end{tableiii}
If variable \samp{name} is already part of the environment, its value is
replaced by \samp{value}; otherwise, the new variable and its value are added
to the environment. You can remove a variable from the environment by specifying
an empty string.

This procedure affects only the environment that is local to the current
process; you cannot use them to modify the \textit{command-level} environment.
That is, these functions operate only on data structures accessible to the
run-time library and not on the environment \samp{"segment"} created for a
process by the operating system. When the current process terminates, the
environment reverts to the level of the calling process (in most cases, the
operating-system level). However, the modified environment can be passed to
any new processes created by the instruction \samp{system}, and these new
processes get any new items added by \samp{putEnv}.

\textbf{Example:}

\texttt{putEnv("JUST\_FOR\_FUN", "I'd like to finish reading my newspaper");\\
traceLine("getEnv('JUST\_FOR\_FUN') = '" + getEnv("JUST\_FOR\_FUN") + "'");}

\textbf{Output:}

\texttt{getEnv('JUST\_FOR\_FUN') = 'I'd like to finish reading my newspaper'}


\textbf{See also:}

\samp{getEnv} \ref{getEnv()}, \samp{environTable} \ref{environTable()}, \samp{existEnv} \ref{existEnv()}, \samp{system} \ref{system()}
\end{itemize}
\pdflabel{randomInteger()}
\index{randomInteger()}
\pdfsubsection{randomInteger}
\begin{itemize}
	\item function \textbf{randomInteger(}\textbf{) :} \textit{int}

Generates a pseudorandom number.


\textbf{See also:}

\samp{randomSeed} \ref{randomSeed()}
\end{itemize}
\pdflabel{randomSeed()}
\index{randomSeed()}
\pdfsubsection{randomSeed}
\begin{itemize}
	\item procedure \textbf{randomSeed(}\samp{seed} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{seed}}{\textit{int}}{a new seed for generating pseudorandom integers}
\end{tableiii}
Sets the seed for generating a series of pseudorandom integers. To change the seed
to a given starting point, choose any positive value different of \samp{1} as the seed argument.
A value of \samp{1} reinitializes the generator. Any negative value let \CodeWorker\ choose
a random seed for you.


\textbf{See also:}

\samp{randomInteger} \ref{randomInteger()}
\end{itemize}
\pdflabel{receiveBinaryFromSocket()}
\index{receiveBinaryFromSocket()}
\pdfsubsection{receiveBinaryFromSocket}
\begin{itemize}
	\item function \textbf{receiveBinaryFromSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
	\lineiii{\samp{length}}{\textit{int}}{number of bytes to read}
\end{tableiii}
This function waits for \samp{length} bytes to read from \samp{socket}, and
returns a sequence of bytes (\CodeWorker\ represents a byte with 2 hexadecimal digits).

If an error occurs, the function returns an empty string.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{receiveFromSocket()}
\index{receiveFromSocket()}
\pdfsubsection{receiveFromSocket}
\begin{itemize}
	\item function \textbf{receiveFromSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{, }\samp{isText} \textbf{:} \textit{boolref}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
	\lineiii{\samp{isText}}{\textit{boolref}}{the function will populate this parameter with \samp{true} if read bytes designate a string and \samp{false} if they are binary data}
\end{tableiii}
This function waits for bytes to read from \samp{socket} and returns them.
If an error occurs, the function returns an empty string.

The function sets \samp{isText} to:\\
\begin{itemize}
	\item \samp{true} if it has received a text,
	\item \samp{false} if it has received binary data: the returned string is
		then a sequence of bytes (\CodeWorker\ represents a byte with 2 hexadecimal digits),
\end{itemize}


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{receiveTextFromSocket()}
\index{receiveTextFromSocket()}
\pdfsubsection{receiveTextFromSocket}
\begin{itemize}
	\item function \textbf{receiveTextFromSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
	\lineiii{\samp{length}}{\textit{int}}{size of the text to read}
\end{tableiii}
This function waits for \samp{length} bytes to read from \samp{socket}, and
returns a string.

If an error occurs, the function returns an empty string.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{relativePath()}
\index{relativePath()}
\pdfsubsection{relativePath}
\begin{itemize}
	\item function \textbf{relativePath(}\samp{path} \textbf{:} \textit{string}\textbf{, }\samp{reference} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{the path to give as relative to \samp{reference}}
	\lineiii{\samp{reference}}{\textit{string}}{a path that serves as the reference to determine the relative path}
\end{tableiii}
Returns the relative path that allow going to the well-named \samp{path},
considering the \samp{reference} path as the starting point (like a current
directory). Under the \textit{Windows} platform, if the two arguments don't
hold on the same drive, the absolute path of the first argument is returned.

Note that the arguments are converted to canonical paths (see \samp{canonicalPath()} \samp{canonicalPath()} for more information).

\textbf{Example:}

\texttt{local sPath = getCurrentDirectory() + "Documentation/CodeWorker.pdf";\\
traceLine("path = '" + sPath + "'");\\
local sReference = "WebSite/downloads";\\
traceLine("reference = '" + sReference + "'");\\
traceLine("result = '" + relativePath(sPath, sReference) + "'");}

\textbf{Output:}

\texttt{path = 'E:/projects/generator/Documentation/CodeWorker.pdf'\\
reference = 'WebSite/downloads'\\
result = '../../Documentation/CodeWorker.pdf'}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{removeAllElements()}
\index{removeAllElements()}
\pdfsubsection{removeAllElements}
\begin{itemize}
	\item procedure \textbf{removeAllElements(}\samp{variable} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{an array of nodes}
\end{tableiii}
Removes all elements of the array pointed to by \samp{variable}.

\textbf{Example:}

\texttt{local myTree = "monkey";\\
pushItem myTree["Everest"];\\
pushItem myTree["Tea spoon"];\\
traceLine("the array 'myTree' has " + myTree.size() + " elements");\\
traceLine("all elements are removed");\\
removeAllElements(myTree);\\
traceLine("Is the array 'myTree' empty now? = '" + myTree.empty() + "'");}

\textbf{Output:}

\texttt{the array 'myTree' has 2 elements\\
all elements are removed\\
Is the array 'myTree' empty now? = 'true'}


\textbf{See also:}

\samp{removeElement} \ref{removeElement()}, \samp{removeFirstElement} \ref{removeFirstElement()}, \samp{removeLastElement} \ref{removeLastElement()}
\end{itemize}
\pdflabel{removeDirectory()}
\index{removeDirectory()}
\pdfsubsection{removeDirectory}
\begin{itemize}
	\item function \textbf{removeDirectory(}\samp{path} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{the directory to remove}
\end{tableiii}
The function removes the directory specified by \samp{path}. The directory must
not be the current working directory or the root directory.

The function returns \samp{false} if the path is invalid or cannot be deleted.

\textbf{Example:}

\texttt{local sDirectory  = getWorkingPath() + "Scripts/Tutorial/GettingStarted/bin";\\
if !removeDirectory(sDirectory) error("impossible to remove '" + sDirectory + "'");}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{resolveFilePath} \ref{resolveFilePath()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{removeElement()}
\index{removeElement()}
\pdfsubsection{removeElement}
\begin{itemize}
	\item procedure \textbf{removeElement(}\samp{variable} \textbf{:} \textit{treeref}\textbf{, }\samp{key} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{an array of nodes}
	\lineiii{\samp{key}}{\textit{string}}{the entry key of the element to remove}
\end{tableiii}
Removes the element whose entry key is passed to the argument \samp{key} from
the array of nodes called \samp{variable}.

\textbf{Example:}

\texttt{local myTree = "monkey";\\
pushItem myTree["Everest"];\\
pushItem myTree["Tea spoon"];\\
traceLine("the array 'myTree' has " + myTree.size() + " elements");\\
traceLine("element 'Tea spoon' is removed");\\
removeElement(myTree, "Tea spoon");\\
traceLine("the array 'myTree' has " + myTree.size() + " elements now");}

\textbf{Output:}

\texttt{the array 'myTree' has 2 elements\\
element 'Tea spoon' is removed\\
the array 'myTree' has 1 elements now}


\textbf{See also:}

\samp{removeAllElements} \ref{removeAllElements()}, \samp{removeFirstElement} \ref{removeFirstElement()}, \samp{removeLastElement} \ref{removeLastElement()}
\end{itemize}
\pdflabel{removeFirstElement()}
\index{removeFirstElement()}
\pdfsubsection{removeFirstElement}
\begin{itemize}
	\item procedure \textbf{removeFirstElement(}\samp{list} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{list}}{\textit{treeref}}{an array of nodes}
\end{tableiii}
Removes the first element from the array of nodes called \samp{list}.

Nothing occurs if \samp{list} doesn't exist or is empty.

\textbf{Example:}

\texttt{local myTree = "monkey";\\
pushItem myTree["Everest"];\\
pushItem myTree["Tea spoon"];\\
traceLine("the array 'myTree' has " + myTree.size() + " elements");\\
traceLine("the first element is removed:");\\
removeFirstElement(myTree);\\
traceObject(myTree);}

\textbf{Output:}

\texttt{the array 'myTree' has 2 elements\\
the first element is removed:\\
Tracing variable 'myTree':\\
\makebox[0.8cm][l]{}"monkey"\\
\makebox[0.8cm][l]{}["Tea spoon"]\\
End of variable's trace 'myTree'.}


\textbf{See also:}

\samp{removeAllElements} \ref{removeAllElements()}, \samp{removeElement} \ref{removeElement()}, \samp{removeLastElement} \ref{removeLastElement()}
\end{itemize}
\pdflabel{removeGenerationTagsHandler()}
\index{removeGenerationTagsHandler()}
\pdfsubsection{removeGenerationTagsHandler}
\begin{itemize}
	\item function \textbf{removeGenerationTagsHandler(}\samp{key} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{designates the handler to remove}
\end{tableiii}
Removes the current generation tags handler amongst those previously registered
thanks to the function \samp{addGenerationTagsHandler()}.
If the current generation tags handler is worth this one, no custom handler is selected.

Returns \samp{true} if \samp{key} designates a registered handler.


\textbf{See also:}

\samp{addGenerationTagsHandler} \ref{addGenerationTagsHandler()}, \samp{selectGenerationTagsHandler} \ref{selectGenerationTagsHandler()}
\end{itemize}
\pdflabel{removeLastElement()}
\index{removeLastElement()}
\pdfsubsection{removeLastElement}
\begin{itemize}
	\item procedure \textbf{removeLastElement(}\samp{list} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{list}}{\textit{treeref}}{an array of nodes}
\end{tableiii}
Removes the last element from the array of nodes called \samp{list}.

Nothing occurs if \samp{list} doesn't exist or is empty.

\textbf{Example:}

\texttt{local myTree = "monkey";\\
pushItem myTree["Everest"];\\
pushItem myTree["Tea spoon"];\\
traceLine("the array 'myTree' has " + myTree.size() + " elements");\\
traceLine("the last element is removed:");\\
removeLastElement(myTree);\\
traceObject(myTree);}

\textbf{Output:}

\texttt{the array 'myTree' has 2 elements\\
the last element is removed:\\
Tracing variable 'myTree':\\
\makebox[0.8cm][l]{}"monkey"\\
\makebox[0.8cm][l]{}["Everest"]\\
End of variable's trace 'myTree'.}


\textbf{See also:}

\samp{removeAllElements} \ref{removeAllElements()}, \samp{removeElement} \ref{removeElement()}, \samp{removeFirstElement} \ref{removeFirstElement()}
\end{itemize}
\pdflabel{removeRecursive()}
\index{removeRecursive()}
\pdfsubsection{removeRecursive}
\begin{itemize}
	\item procedure \textbf{removeRecursive(}\samp{variable} \textbf{:} \textit{treeref}\textbf{, }\samp{attribute} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{points to a node of a parse tree}
	\lineiii{\samp{attribute}}{\textit{string}}{the name of an attribute to remove}
\end{tableiii}
Removes recursively the attribute called \samp{attribute} from a parse tree
given by \samp{variable}. It checks also recursively the nodes put into arrays.

\textbf{Example:}

\texttt{local myTree = "to keep";\\
insert myTree.toKeep = "to keep";\\
insert myTree.toRemove = "to remove";\\
insert myTree.toKeep.toRemove = "to remove";\\
insert myTree.list["keep"].toKeep = "to keep";\\
insert myTree.list["remove"].toRemove = "to remove";\\
removeRecursive(myTree, "toRemove");\\
local theGoal = "to keep";\\
insert theGoal.toKeep = "to keep";\\
insert theGoal.list["remove"] = "";\\
insert theGoal.list["keep"].toKeep = "to keep";\\
if !equalTrees(myTree, theGoal) error("removeRecursive() doesn't work!");\\
traceLine("the attribute 'toRemove' has been removed from 'myTree' recursively");}

\textbf{Output:}

\texttt{the attribute 'toRemove' has been removed from 'myTree' recursively}
\end{itemize}
\pdflabel{removeVariable()}
\index{removeVariable()}
\pdfsubsection{removeVariable}
\begin{itemize}
	\item procedure \textbf{removeVariable(}\samp{node} \textbf{:} \textit{treeref}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{node}}{\textit{treeref}}{the node to remove from the tree}
\end{tableiii}
All attributes of the argument \samp{node} are deleted, its array of nodes is
cleared and its value becomes an empty string. If the node was referring to
another node, the link is cleared. Once these task are completed, the variable
\samp{node} is removed from the tree it belongs to (as an attribute or an
element).

Note that trying to remove a local variable throws an error.

\textbf{Example:}

\texttt{local myTree;\\
insert myTree.nodeToRemove = "the value";\\
localref myNode = myTree.nodeToRemove;\\
insert myNode.a1 = "attribute 1";\\
insert myNode.a2 = "attribute 2";\\
insert myNode.array["1"] = "node 1";\\
insert myNode.array["2"] = "node 2";\\
traceObject(myNode);\\
traceLine("-- the variable 'myNode' is removed:");\\
removeVariable(myNode);\\
traceObject(myTree);}

\textbf{Output:}

\texttt{Tracing variable 'myTree.nodeToRemove':\\
\makebox[0.8cm][l]{}"the value"\\
\makebox[0.8cm][l]{}a1 = "attribute 1"\\
\makebox[0.8cm][l]{}a2 = "attribute 2"\\
\makebox[0.8cm][l]{}array\\
\makebox[0.8cm][l]{}array["1", "2"]\\
End of variable's trace 'myTree.nodeToRemove'.\\
-- the variable 'myNode' is removed:\\
Tracing variable 'myTree':\\
End of variable's trace 'myTree'.}


\textbf{See also:}

\samp{existVariable} \ref{existVariable()}, \samp{clearVariable} \ref{clearVariable()}, \samp{findFirstSubstringIntoKeys} \ref{findFirstSubstringIntoKeys()}, \samp{findElement} \ref{findElement()}, \samp{findNextSubstringIntoKeys} \ref{findNextSubstringIntoKeys()}, \samp{getArraySize} \ref{getArraySize()}, \samp{getVariableAttributes} \ref{getVariableAttributes()}, \samp{invertArray} \ref{invertArray()}, \samp{isEmpty} \ref{isEmpty()}
\end{itemize}
\pdflabel{repeatString()}
\index{repeatString()}
\pdfsubsection{repeatString}
\begin{itemize}
	\item function \textbf{repeatString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{occurrences} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{the string to repeat}
	\lineiii{\samp{occurrences}}{\textit{int}}{number of times the string must be repeated}
\end{tableiii}
Returns the result of repeating the sequence of characters passed to argument
\samp{text} a number of times given by the parameter \samp{occurrences}.

\textbf{Example:}

\texttt{traceLine("repeatString('Hungry!', 3') = '" + repeatString("Hungry!", 3) + "'");}

\textbf{Output:}

\texttt{repeatString('Hungry!', 3') = 'Hungry!Hungry!Hungry!'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{replaceString()}
\index{replaceString()}
\pdfsubsection{replaceString}
\begin{itemize}
	\item function \textbf{replaceString(}\samp{old} \textbf{:} \textit{string}\textbf{, }\samp{new} \textbf{:} \textit{string}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{old}}{\textit{string}}{the substring to be replaced}
	\lineiii{\samp{new}}{\textit{string}}{the string replacing the old one}
	\lineiii{\samp{text}}{\textit{string}}{the sequence of characters to handle}
\end{tableiii}
Returns the result of replacing all occurrences of substring passed to argument
\samp{old} by the substring \samp{new}, when found into \samp{text}.

\textbf{Example:}

\texttt{local sText = "first in, first out";\\
traceLine("replaceString('fir', 'la', '" + sText + "') = '" + replaceString("fir", "la", sText) + "'");}

\textbf{Output:}

\texttt{replaceString('fir', 'la', 'first in, first out') = 'last in, last out'}


\pdflabel{method replaceString()}
\index{method!replaceString()}
\textbf{Method:} \textit{text}.\samp{replaceString}(\textit{old}, \textit{new})


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{replaceTabulations()}
\index{replaceTabulations()}
\pdfsubsection{replaceTabulations}
\begin{itemize}
	\item function \textbf{replaceTabulations(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{tab} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters where spaces must be inserted instead of tabulations}
	\lineiii{\samp{tab}}{\textit{int}}{size of a tabulation}
\end{tableiii}
Returns the result of replacing all tabulations (character \textbf{'$\backslash$t'}) of
the string passed to argument \samp{text} by spaces. The maximum of spaces to
insert instead of tabulation is given by the parameter \samp{tab}.

Notice that spaces to insert are determined according to the position of the
tabulation in the string and the beginning of the \textit{line} (it means that
\textbf{'$\backslash$n'} characters are taken into account) and the tabulation size. So,
this function isn't equivalent to \samp{replaceString()} \ref{replaceString()}.

\textbf{Example:}

\texttt{local sText = " a   little  joke";\\
traceLine("replaceTabulations(sText, 4)       = '" + replaceTabulations(sText, 4) + "'");\\
traceLine("replaceString('$\backslash$t', "    ", sText) = '" + replaceString("$\backslash$t", "    ", sText) + "'");}

\textbf{Output:}

\texttt{replaceTabulations(sText, 4)       = '    a   little  joke'\\
replaceString(' ', , sText) = '    a    little    joke'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{resolveFilePath()}
\index{resolveFilePath()}
\pdfsubsection{resolveFilePath}
\begin{itemize}
	\item function \textbf{resolveFilePath(}\samp{filename} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{the path of the file to resolve}
\end{tableiii}
Searches the file \samp{filename} in the current directory and, if fails, it
continues searching it in the include directories (\samp{'-I'} switch on the
command line).

It returns the location of the file in directories, removing any ambiguity.\\
If the file doesn't exist, the function returns an empty string.\\
If \samp{filename} points to a virtual file, the function returns \samp{filename}.\\

\textbf{Example:}

\texttt{local sIncludePath = getIncludePath();\\
setIncludePath(sIncludePath + ";Documentation");\\
traceLine("resolveFilePath('CodeWorker.tex') = '" + resolveFilePath("CodeWorker.tex") + "'");\\
setIncludePath(sIncludePath);}

\textbf{Output:}

\texttt{resolveFilePath('CodeWorker.tex') = 'Documentation/CodeWorker.tex'}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{scanDirectories} \ref{scanDirectories()}
\end{itemize}
\pdflabel{rightString()}
\index{rightString()}
\pdfsubsection{rightString}
\begin{itemize}
	\item function \textbf{rightString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{length}}{\textit{int}}{a positive number}
\end{tableiii}
Returns the last characters that belong to the string passed to the argument
\samp{text}. The number of characters to take is given by argument
\samp{length}. If the string contains less than \samp{length} characters, the
function returns all of them.

\textbf{Example:}

\texttt{traceLine("rightString('airport', 4) = '" + rightString("airport", 4) + "'");\\
traceLine("rightString('airport', 8) = '" + rightString("airport", 8) + "'");}

\textbf{Output:}

\texttt{rightString('airport', 4) = 'port'\\
rightString('airport', 8) = 'airport'}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rsubString} \ref{rsubString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{rsubString()}
\index{rsubString()}
\pdfsubsection{rsubString}
\begin{itemize}
	\item function \textbf{rsubString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{pos} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{pos}}{\textit{int}}{a position starting at 0, and relative to the end of the \samp{text} string}
\end{tableiii}
Returns the sequence of characters passed to argument \samp{text} after skipping
the last \samp{pos} characters. It is a \textit{reverse} subString().

\textbf{Example:}

\texttt{local sText = "The lamp of experience";\\
traceLine("sText = '" + sText + "'");\\
traceLine("rsubString(sText, 5) = '" + rsubString(sText, 5) + "'");}

\textbf{Output:}

\texttt{sText = 'The lamp of experience'\\
rsubString(sText, 5) = 'The lamp of exper'}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{subString} \ref{subString()}
\end{itemize}
\pdflabel{saveBinaryToFile()}
\index{saveBinaryToFile()}
\pdfsubsection{saveBinaryToFile}
\begin{itemize}
	\item procedure \textbf{saveBinaryToFile(}\samp{filename} \textbf{:} \textit{string}\textbf{, }\samp{content} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the binary file to write into}
	\lineiii{\samp{content}}{\textit{string}}{sequence of bytes (2 hexadecimal digits) to write into the file}
\end{tableiii}
Saves the binary \samp{content} to the file \samp{filename}.
The parameter \samp{content} concatenates a sequence of hexadecimal digits, so a byte is stored in
2 characters:\\
\samp{\textit{binary-content} ::= [\textit{byte}]*;\\
	\textit{byte} ::= [\textbf{'0'..'9'} | \textbf{'A'..'F'} | \textbf{'a'..'f'}]2;}\\

The hexadecimal pairs of digit are converted to binary (8 bits) before writing the content.

If the file cannot be created, an error is raised. If the file already exists,
its content is replaced by the new binary content.


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveToFile} \ref{saveToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{saveProject()}
\index{saveProject()}
\pdfsubsection{saveProject}
\begin{itemize}
	\item procedure \textbf{saveProject(}\samp{XMLFileName} \textbf{:} \textit{string}\textbf{, }\samp{nodeToSave} \textbf{:} \textit{tree}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{XMLFileName}}{\textit{string}}{an output file that will contain the XML description of the main parse tree called \samp{project}}
	\lineiii{\samp{nodeToSave}}{\textit{tree}}{\textbf{default value:} \textit{project}\\
the node to save to XML; if omitted, it is about the global variable \samp{project}}
\end{tableiii}
Saves the parse tree of the project as an XML file. Each element of the XML
hierarchy takes the name of the corresponding attribute in the parse tree.

When a value is assigned to an attribute, it is reported into an XML attribute
called \samp{__VALUE}. When an attribute represents an array of nodes, all
nodes are inlayed in the body of the XML element like it: each node is put
into an XML element called \samp{__ARRAY_ENTRY} where the XML attribute
\samp{__KEY} contains the entry key.

\textbf{Example:}

\texttt{parseAsBNF("Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp", project, "Scripts/Tutorial/GettingStarted/Tiny.tml");\\
saveProject(getWorkingPath() +\\
\makebox[2.4cm][l]{}"Scripts/Tutorial/GettingStarted/Tiny-tree.xml");\\
traceLine(loadFile("Scripts/Tutorial/GettingStarted/Tiny-tree.xml"));}

\textbf{Output:}

\texttt{this file has been parsed successfully\\
<project>\\
\makebox[0.8cm][l]{}<listOfClasses>\\
\makebox[1.6cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="A">\\
\makebox[2.4cm][l]{}<name \_\_VALUE="A" />\\
\makebox[1.6cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[1.6cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="B">\\
\makebox[2.4cm][l]{}<name \_\_VALUE="B" />\\
\makebox[2.4cm][l]{}<parent \_\_REFERENCE="project.listOfClasses[\&quot;A\&quot;]" />\\
\makebox[1.6cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[1.6cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="C">\\
\makebox[2.4cm][l]{}<name \_\_VALUE="C" />\\
\makebox[2.4cm][l]{}<listOfAttributes>\\
\makebox[3.2cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="0">\\
\makebox[4cm][l]{}<class \_\_REFERENCE="project.listOfClasses[\&quot;B\&quot;]" />\\
\makebox[4cm][l]{}<isArray \_\_VALUE="true" />\\
\makebox[4cm][l]{}<name \_\_VALUE="b" />\\
\makebox[3.2cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[2.4cm][l]{}</listOfAttributes>\\
\makebox[1.6cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[1.6cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="D">\\
\makebox[2.4cm][l]{}<name \_\_VALUE="D" />\\
\makebox[2.4cm][l]{}<listOfAttributes>\\
\makebox[3.2cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="0">\\
\makebox[4cm][l]{}<class \_\_REFERENCE="project.listOfClasses[\&quot;A\&quot;]" />\\
\makebox[4cm][l]{}<name \_\_VALUE="a" />\\
\makebox[3.2cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[3.2cm][l]{}<\_\_ARRAY\_ENTRY \_\_KEY="1">\\
\makebox[4cm][l]{}<class \_\_REFERENCE="project.listOfClasses[\&quot;C\&quot;]" />\\
\makebox[4cm][l]{}<isArray \_\_VALUE="true" />\\
\makebox[4cm][l]{}<name \_\_VALUE="c" />\\
\makebox[3.2cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[2.4cm][l]{}</listOfAttributes>\\
\makebox[1.6cm][l]{}</\_\_ARRAY\_ENTRY>\\
\makebox[0.8cm][l]{}</listOfClasses>\\
</project>\\
}


\textbf{See also:}

\samp{saveProjectTypes} \ref{saveProjectTypes()}
\end{itemize}
\pdflabel{saveProjectTypes()}
\index{saveProjectTypes()}
\pdfsubsection{saveProjectTypes}
\begin{itemize}
	\item procedure \textbf{saveProjectTypes(}\samp{XMLFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{XMLFileName}}{\textit{string}}{an output file that will contain the XML description of the structure of the main parse tree called \samp{project}}
\end{tableiii}
Factorizes nodes of the parse tree of the project to distinguish an implicit
type for nodes, depending on their locations into the graph. The typed tree is
saved as an XML file.

\textbf{Example:}

\texttt{parseAsBNF("Scripts/Tutorial/GettingStarted/Tiny-BNFparsing1.cwp", project, "Scripts/Tutorial/GettingStarted/Tiny.tml");\\
saveProjectTypes(getWorkingPath() +\\
\makebox[3.2cm][l]{}"Scripts/Tutorial/GettingStarted/Tiny-types.xml");\\
traceLine(loadFile("Scripts/Tutorial/GettingStarted/Tiny-types.xml"));}

\textbf{Output:}

\texttt{this file has been parsed successfully\\
<project>\\
\makebox[0.8cm][l]{}<listOfClasses>\\
\makebox[1.6cm][l]{}<\_\_ARRAY\_TYPE name="compulsory" parent="optional[25\%]">\\
\makebox[2.4cm][l]{}<listOfAttributes>\\
\makebox[3.2cm][l]{}<\_\_ARRAY\_TYPE class="compulsory" isArray="optional[66\%]" name="compulsory">\\
\makebox[3.2cm][l]{}</\_\_ARRAY\_TYPE>\\
\makebox[2.4cm][l]{}</listOfAttributes>\\
\makebox[1.6cm][l]{}</\_\_ARRAY\_TYPE>\\
\makebox[0.8cm][l]{}</listOfClasses>\\
</project>\\
}


\textbf{Known bugs:}

Sometimes, when a type is encountered twice in very different locations of the
parse tree, a mistake on the proportion of presence may occur. It will be
corrected later.


\textbf{See also:}

\samp{saveProject} \ref{saveProject()}
\end{itemize}
\pdflabel{saveToFile()}
\index{saveToFile()}
\pdfsubsection{saveToFile}
\begin{itemize}
	\item procedure \textbf{saveToFile(}\samp{filename} \textbf{:} \textit{string}\textbf{, }\samp{content} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{filename}}{\textit{string}}{name of the text file to write into}
	\lineiii{\samp{content}}{\textit{string}}{sequence of characters to write into the file}
\end{tableiii}
Saves the text \samp{content} to the file \samp{filename}.

If the file cannot be created, an error is raised. If the file already exists,
its content is replaced by the new text content.


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{scanFiles} \ref{scanFiles()}
\end{itemize}
\pdflabel{scanDirectories()}
\index{scanDirectories()}
\pdfsubsection{scanDirectories}
\begin{itemize}
	\item function \textbf{scanDirectories(}\samp{directory} \textbf{:} \textit{tree}\textbf{, }\samp{path} \textbf{:} \textit{string}\textbf{, }\samp{pattern} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{directory}}{\textit{tree}}{node that will contain the name of filtered files and folders}
	\lineiii{\samp{path}}{\textit{string}}{the directory from where to start the exploration}
	\lineiii{\samp{pattern}}{\textit{string}}{the filter to apply on files to keep}
\end{tableiii}
Explores the directory whose name is passed to the argument \samp{path} and 
filters all files that validate the \samp{pattern}. The list of files is put
into the node's array \samp{directory.\textbf{files}} and the list of
directories are put into the node's array \samp{directory.\textbf{directories}}.
The argument \samp{subfolders} requires exploring sub-directories and each
node of the node's array \samp{directory.\textbf{directories}} repeats the same
process recursively. The key of an array's node is the short name of the file or
the directory and the value of a directory item is the relative path, whereas
the value of a file item is also the short name.

If the directory cannot be found, the variable \samp{directory} doesn't change
and the function returns \samp{false}. If the directory doesn't contain any
file, the attribute \samp{directory.\textit{files}} isn't created. If the
directory doesn't contain any subfolder, the attribute
\samp{directory.\textit{directories}} isn't created.

\textbf{Example:}

\texttt{local theDirectory;\\
local sPathToExplore = project.winBinaries; // Windows package of CodeWorker\\
if !scanDirectories(theDirectory, sPathToExplore, "Leader*.cws") error("unable to find the directory");\\
// the complete path is too long: shorten it\\
traceLine("starting directory = '" + theDirectory.subString(sPathToExplore.length()) + "':");\\
foreach j in theDirectory.files \{\\
\makebox[0.8cm][l]{}traceLine(" '" + j + "'");\\
\}\\
foreach i in cascading theDirectory.directories \{\\
\makebox[0.8cm][l]{}// the complete path is too long: shorten it\\
\makebox[0.8cm][l]{}traceLine("- directory '" + i.subString(sPathToExplore.length()) + "':");\\
\makebox[0.8cm][l]{}foreach j in i.directories \{\\
\makebox[1.6cm][l]{}traceLine(" subfolder '" + key(j) + "'");\\
\makebox[0.8cm][l]{}// the complete path is too long: shorten it\\
\makebox[1.6cm][l]{}traceLine("     path '" + j.subString(sPathToExplore.length()) + "'");\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}foreach j in i.files \{\\
\makebox[1.6cm][l]{}traceLine(" '" + j + "'");\\
\makebox[0.8cm][l]{}\}\\
\}}

\textbf{Output:}

\texttt{starting directory = '/':\\
- directory '/bin/':\\
- directory '/include/':\\
- directory '/Scripts/':\\
\makebox[0.8cm][l]{}subfolder 'Tutorial'\\
\makebox[1.6cm][l]{}path '/Scripts/Tutorial/'\\
- directory '/Scripts/Tutorial/':\\
\makebox[0.8cm][l]{}subfolder 'GettingStarted'\\
\makebox[1.6cm][l]{}path '/Scripts/Tutorial/GettingStarted/'\\
- directory '/Scripts/Tutorial/GettingStarted/':\\
\makebox[0.8cm][l]{}'LeaderScript0.cws'\\
\makebox[0.8cm][l]{}'LeaderScript1.cws'\\
\makebox[0.8cm][l]{}'LeaderScript2.cws'\\
\makebox[0.8cm][l]{}'LeaderScript3.cws'\\
\makebox[0.8cm][l]{}'LeaderScript4.cws'\\
\makebox[0.8cm][l]{}'LeaderScript5.cws'\\
\makebox[0.8cm][l]{}'LeaderScript6.cws'}


\textbf{See also:}

\samp{changeDirectory} \ref{changeDirectory()}, \samp{canonizePath} \ref{canonizePath()}, \samp{copySmartDirectory} \ref{copySmartDirectory()}, \samp{exploreDirectory} \ref{exploreDirectory()}, \samp{getCurrentDirectory} \ref{getCurrentDirectory()}, \samp{relativePath} \ref{relativePath()}, \samp{removeDirectory} \ref{removeDirectory()}, \samp{resolveFilePath} \ref{resolveFilePath()}
\end{itemize}
\pdflabel{scanFiles()}
\index{scanFiles()}
\pdfsubsection{scanFiles}
\begin{itemize}
	\item function \textbf{scanFiles(}\samp{files} \textbf{:} \textit{tree}\textbf{, }\samp{path} \textbf{:} \textit{string}\textbf{, }\samp{pattern} \textbf{:} \textit{string}\textbf{, }\samp{subfolders} \textbf{:} \textit{bool}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{files}}{\textit{tree}}{node that will contain files that validate the \samp{pattern}}
	\lineiii{\samp{path}}{\textit{string}}{the directory where to scan files}
	\lineiii{\samp{pattern}}{\textit{string}}{the filter to apply on files to keep}
	\lineiii{\samp{subfolders}}{\textit{bool}}{to scan sub directories recursively}
\end{tableiii}
Explores the directory \samp{path} and filters all files that validate the \samp{pattern}
given by parameter. Files are put into the node's array called \samp{files} with
their relative path, which is assigned to the value of the item. The scan is
applied on subfolders if the argument \samp{subfolders} passes \samp{true}.

The \samp{pattern} argument accepts the standard jocker characters (\textbf{'*'} and
\textbf{'?'}). If empty, \samp{pattern} is considered as being worth "*".

The function returns \samp{true} if the directory to scan exists.

\textbf{Example:}

\texttt{local files;\\
local sDirectory = "Scripts/Tutorial/GettingStarted";\\
if !scanFiles(files, sDirectory, "Leader*.cws", true) error("impossible to find the directory");\\
traceLine("filtering recursively all files that conform to 'Leader*.cws'");\\
foreach i in files \{\\
\makebox[0.8cm][l]{}traceLine(" " + subString(i, lengthString(sDirectory)));\\
\}}

\textbf{Output:}

\texttt{filtering recursively all files that conform to 'Leader*.cws'\\
\makebox[0.8cm][l]{}/LeaderScript0.cws\\
\makebox[0.8cm][l]{}/LeaderScript1.cws\\
\makebox[0.8cm][l]{}/LeaderScript2.cws\\
\makebox[0.8cm][l]{}/LeaderScript3.cws\\
\makebox[0.8cm][l]{}/LeaderScript4.cws\\
\makebox[0.8cm][l]{}/LeaderScript5.cws\\
\makebox[0.8cm][l]{}/LeaderScript6.cws}


\textbf{See also:}

\samp{copyFile} \ref{copyFile()}, \samp{appendFile} \ref{appendFile()}, \samp{changeFileTime} \ref{changeFileTime()}, \samp{chmod} \ref{chmod()}, \samp{copyGenerableFile} \ref{copyGenerableFile()}, \samp{copySmartFile} \ref{copySmartFile()}, \samp{deleteFile} \ref{deleteFile()}, \samp{existFile} \ref{existFile()}, \samp{fileCreation} \ref{fileCreation()}, \samp{fileLastAccess} \ref{fileLastAccess()}, \samp{fileLastModification} \ref{fileLastModification()}, \samp{fileLines} \ref{fileLines()}, \samp{fileMode} \ref{fileMode()}, \samp{fileSize} \ref{fileSize()}, \samp{loadBinaryFile} \ref{loadBinaryFile()}, \samp{loadFile} \ref{loadFile()}, \samp{saveBinaryToFile} \ref{saveBinaryToFile()}, \samp{saveToFile} \ref{saveToFile()}
\end{itemize}
\pdflabel{selectGenerationTagsHandler()}
\index{selectGenerationTagsHandler()}
\pdfsubsection{selectGenerationTagsHandler}
\begin{itemize}
	\item function \textbf{selectGenerationTagsHandler(}\samp{key} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{designates the handler to take}
\end{tableiii}
Selects the current generation tags handler amongst those previously registered
thanks to the function \samp{addGenerationTagsHandler()}.
If the parameter \samp{key} is worth \textit{false} (empty string), the default
generation tags handler is used.

Returns \samp{true} if \samp{key} designates a registered handler.


\textbf{See also:}

\samp{addGenerationTagsHandler} \ref{addGenerationTagsHandler()}, \samp{removeGenerationTagsHandler} \ref{removeGenerationTagsHandler()}
\end{itemize}
\pdflabel{sendBinaryToSocket()}
\index{sendBinaryToSocket()}
\pdfsubsection{sendBinaryToSocket}
\begin{itemize}
	\item function \textbf{sendBinaryToSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{, }\samp{bytes} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
	\lineiii{\samp{bytes}}{\textit{string}}{a sequence of bytes to write}
\end{tableiii}
This function writes binary data to a socket and returns \samp{true} if it has achieved successfully.

The function raises an error if a byte passed to \samp{bytes} is malformed:
\CodeWorker\ expects 2 hexadecimal digits to represent a byte.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{sendHTTPRequest()}
\index{sendHTTPRequest()}
\pdfsubsection{sendHTTPRequest}
\begin{itemize}
	\item function \textbf{sendHTTPRequest(}\samp{URL} \textbf{:} \textit{string}\textbf{, }\samp{HTTPSession} \textbf{:} \textit{treeref}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{URL}}{\textit{string}}{URL of the HTTP server}
	\lineiii{\samp{HTTPSession}}{\textit{treeref}}{an object to describe the HTTP session}
\end{tableiii}
This function sends an HTTP request to the HTTP server pointed to by the argument
\samp{URL}, and returns the document read from the HTTP server.

If the request fails, an error message is thrown.

The well-named argument \samp{HTTPSession} specifies some information into devoted attributes:
\begin{itemize}
	\item \textbf{agent} \textit{(optional)} is the browser name, "\CodeWorker\" by default,
	\item \textbf{referer} \textit{(optional)},
	\item \textbf{proxy} \textit{(optional)}:
		\begin{itemize}
			\item \textbf{proxy.host} \textit{(compulsory)},
			\item \textbf{proxy.port} \textit{(compulsory)},
			\item \textbf{proxy.userpwd} \textit{(optional)} is worth "\textit{user}\textbf{:}\textit{password}",
		\end{itemize}
	\item \textbf{cookies} \textit{(optional)} is a list of nodes such as:
		\begin{itemize}
			\item \textbf{name} \textit{(compulsory)},
			\item \textbf{value} \textit{(optional)} is worth \samp{""} by default,
			\item \textbf{path} \textit{(optional)}, populated from the HTTP header (see below)
			\item \textbf{domain} \textit{(optional)}, populated from the HTTP header (see below)
			\item \textbf{expires} \textit{(optional)} for a permanent cookie, populated from the HTTP header (see below)
		\end{itemize}
\end{itemize}

After processing the request successfully, you'll find information about the returned data.\\
If the data is a binary format, such as an archive or an image, the field \samp{HTTPSession\textbf{.binary_data}}
is worth \samp{true}.\\
If the data is a textual format, the detail of the received header lines are filled in
the array \samp{HTTPSession\textbf{.header_lines}}. The array \samp{HTTPSession\textbf{.cookies}}
is updated with the cookies extracted from the header.
The entry nodes of the array \samp{HTTPSession\textbf{.header_lines}} are indexed with the name of
the header directive. These entry nodes just contain the list of all header values attached to such a directive.

\textbf{Example:}\\
\texttt{
HTTP/1.1 200 OK\\
Cache-Control: private\\
Date: Wed, 10 Mar 2004 13:41:03 GMT\\
Server: Microsoft-IIS/6.0\\
Set-Cookie: SESSIONID=Garfield; expires=Wed, 10-Mar-2004 15:03:19 GMT; path=/\\
Set-Cookie' PREFERENCES=yellow; domain=jupiter; path=/\\
Content-Type: text/html\\
Content-Length: 4469
}

These fields are then injected in the array \samp{HTTPSession\textbf{.header_lines}}.
The header directive \samp{Set-Cookie} appears twice, but gives rise to only one entry node:
\samp{HTTPSession.header_lines[\textbf{"Set-Cookie"}]}. This entry node is a list containing
two elements. The first one defines all characteristics of \samp{SESSIONID} and
the second one provides the characteristics of the cookie \samp{PREFERENCES}.\\
Here, a piece of code that displays the header lines:\\
\texttt{foreach i in theSession.header_lines {\\
\makebox[0.4cm][r]{}foreach j in i {\\
\makebox[0.8cm][r]{}traceLine("'" + i.key() + "' = '" + j + "'");\\
\makebox[0.4cm][r]{}}\\
}
}

\textbf{Output:}\\
\texttt{
	'HTTP/1.1 200 OK' = ''\\
	'Cache-Control' = 'private'\\
	'Date' = 'Wed, 10 Mar 2004 13:41:03 GMT'\\
	'Server' = 'Microsoft-IIS/6.0'\\
	'Set-Cookie' = 'SESSIONID=Garfield; expires=Wed, 10-Mar-2004 15:03:19 GMT; path=/'\\
	'Set-Cookie' = 'PREFERENCES=yellow; domain=jupiter; path=/'\\
	'Content-Type' = 'text/html'\\
	'Content-Length' = '4469'
}


\textbf{See also:}

\samp{getHTTPRequest} \ref{getHTTPRequest()}, \samp{postHTTPRequest} \ref{postHTTPRequest()}
\end{itemize}
\pdflabel{sendTextToSocket()}
\index{sendTextToSocket()}
\pdfsubsection{sendTextToSocket}
\begin{itemize}
	\item function \textbf{sendTextToSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
	\lineiii{\samp{text}}{\textit{string}}{the text to write}
\end{tableiii}
This function writes a text to a socket and returns \samp{true} if it has achieved successfully.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{setCommentBegin()}
\index{setCommentBegin()}
\pdfsubsection{setCommentBegin}
\begin{itemize}
	\item procedure \textbf{setCommentBegin(}\samp{commentBegin} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{commentBegin}}{\textit{string}}{a sequence of characters that represents the beginning of a comment for an output file to handle}
\end{tableiii}
Sets the value of a beginning of comment, which is exploited by the procedures
taking in charge the source code generation, such as \samp{expand} or \samp{generate}.
\CodeWorker\ must know the format of comments recognized by the output file,
to be able to extract or put protected areas, or to detect \textit{expansion
markups}.
This procedure should be called \samp{before} calling the source code generation,
otherwise the new value is ignored by the preprocessing of output files that
looks for protected areas and markups.

The beginning of comment assigned by default is worth \textbf{'//'}. This is
the symbol of C++ and JAVA comments that are the most frequently files
encountered for generation. However, depending on the output file to generate,
you'll change the beginning of comment to:
\begin{itemize}
	\item \textbf{'/*'} to work on a C file,
	\item \textbf{'- -'} to work on a ADA file,
	\item \textbf{'<!- -'} to work on a HTML or XML file,
	\item \textbf{'\%'} to work on a LaTeX file,
\end{itemize}

Note that if the beginning of comments is set to an empty string, protected areas
aren't extracted and the expand mode does nothing.

The function \samp{getCommentBegin} allows asking for the last assigned value.

\textbf{Example:}

\texttt{setCommentBegin("<!--");\\
traceLine("An HTML-XML comment: '" + getCommentBegin() + "'");\\
setCommentBegin("\%");\\
traceLine("A LaTeX comment: '" + getCommentBegin() + "'");}

\textbf{Output:}

\texttt{An HTML-XML comment: '<!--'\\
A LaTeX comment: '\%'}


\textbf{See also:}

\samp{getCommentBegin} \ref{getCommentBegin()}, \samp{getCommentEnd} \ref{getCommentEnd()}, \samp{setCommentEnd} \ref{setCommentEnd()}
\end{itemize}
\pdflabel{setCommentEnd()}
\index{setCommentEnd()}
\pdfsubsection{setCommentEnd}
\begin{itemize}
	\item procedure \textbf{setCommentEnd(}\samp{commentEnd} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{commentEnd}}{\textit{string}}{a sequence of characters that represents the end of a comment for an output file to handle}
\end{tableiii}
Sets the value of an end of comment, which is exploited by the procedures
taking in charge the source code generation, such as \samp{expand} or \samp{generate}.
\CodeWorker\ must know the format of comments recognized by the output file,
to be able to extract or put protected areas, or to detect \textit{expansion
markups}.
This procedure should be called \samp{before} calling the source code generation,
otherwise the new value is ignored by the preprocessing of output files that
looks for protected areas and markups.

The end of comment assigned by default is worth \textbf{'$\backslash$r$\backslash$n'}. This is
the symbol of C++ and JAVA comments that are the most frequently files
encountered for generation. However, depending on the output file to generate,
you'll change the end of comment to:
\begin{itemize}
	\item \textbf{'*/'} to work on a C file,
	\item \textbf{'-->'} to work on a HTML or XML file,
\end{itemize}

The function \samp{getCommentEnd} allows asking for the last assigned value.

\textbf{Example:}

\texttt{setCommentEnd("-->");\\
traceLine("An HTML-XML comment ends with: '" + getCommentEnd() + "'");\\
setCommentEnd("$\backslash$n");\\
traceLine("A LaTeX comment ends with: '" + composeCLikeString(getCommentEnd()) + "'");}

\textbf{Output:}

\texttt{An HTML-XML comment ends with: '-->'\\
A LaTeX comment ends with: '$\backslash$n'}


\textbf{See also:}

\samp{getCommentBegin} \ref{getCommentBegin()}, \samp{getCommentEnd} \ref{getCommentEnd()}, \samp{setCommentBegin} \ref{setCommentBegin()}
\end{itemize}
\pdflabel{setGenerationHeader()}
\index{setGenerationHeader()}
\pdfsubsection{setGenerationHeader}
\begin{itemize}
	\item procedure \textbf{setGenerationHeader(}\samp{comment} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{comment}}{\textit{string}}{comment to put into the header}
\end{tableiii}
If the text passed to the argument \samp{comment} isn't empty, a comment is added
automatically to each file generated with the procedure \samp{generate}. Passing
the option \samp{-genheader} on the command line may require the functionality.

This generation header is inlayed in the comment delimeters and conforms to the
format:\\
\begin{itemize}
	\item if the comment holds on a single line:\\
		\samp{\textit{begin-comment} \textbf{"\#\#generation header\#\#CodeWorker\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textit{version-number} \textbf{"\#\#"} \textit{generation-date} \textbf{"\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textbf{'"'} \textit{comment} \textbf{'"'} \textit{end-comment}}
	\item if the comment holds on more than one line:\\
		\samp{\textit{begin-comment} \textbf{"\#\#generation header\#\#CodeWorker\#\#"}}\\
		\makebox[1cm][r]{} \samp{\textit{version-number} \textbf{"\#\#"} \textit{generation-date} \textbf{"\#\#"} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textbf{"\#\#header start\#\#"} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textit{line\tiny{1}} \textit{end-comment}}\\
		\samp{...}\\
		\samp{\textit{begin-comment} \textit{line\tiny{n}} \textit{end-comment}}\\
		\samp{\textit{begin-comment} \textbf{"\#\#header end\#\#"} \textit{end-comment}}
\end{itemize}
Changing the generation header doesn't lead to modify the generated file necessary:
the header is ignored while comparing two files.

\textbf{Example:}

\texttt{setGenerationHeader("Popeye's Village$\backslash$nOlive hates spinash");\\
traceLine("new generation header = '" + getGenerationHeader() + "'");\\
local sFileName = "GettingStarted/Tiny-JAVA.cwt";\\
traceLine("script to execute:");\\
local sContent = replaceString("$\backslash$r", "", loadFile(sFileName));\\
local lines;\\
cutString(sContent, "$\backslash$n", lines);\\
foreach i in lines if !startString(i, "//")\\
\makebox[0.8cm][l]{}traceLine("$\backslash$t" + i);\\
traceLine("class to generate = '" + project.listOfClasses\#[1].name + "'");\\
local sOutputText;\\
generateString(sFileName, project.listOfClasses\#[1], sOutputText);\\
traceLine("generated text:");\\
traceLine(sOutputText);\\
setGenerationHeader("");}

\textbf{Output:}

\texttt{new generation header = 'Popeye's Village\\
Olive hates spinash'\\
script to execute:\\
\makebox[0.8cm][l]{}package tiny;\\
\makebox[0.8cm][l]{}\\
\makebox[0.8cm][l]{}public class @\\
\makebox[0.8cm][l]{}this.name@ @\\
\makebox[0.8cm][l]{}if existVariable(this.parent) \{\\
\makebox[1.6cm][l]{}@ extends @this.parent.name@ @\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}@\{\\
\makebox[1.6cm][l]{}// attributes:\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}function getJAVAType(myAttribute : node) \{\\
\makebox[1.6cm][l]{}local sType = myAttribute.class.name;\\
\makebox[1.6cm][l]{}if myAttribute.isArray \{\\
\makebox[2.4cm][l]{}set sType = "java.util.ArrayList/*<" + sType + ">*/";\\
\makebox[1.6cm][l]{}\}\\
\makebox[1.6cm][l]{}return sType;\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}\\
\makebox[0.8cm][l]{}foreach i in this.listOfAttributes \{\\
\makebox[1.6cm][l]{}@   private @getJAVAType(i)@ \_@i.name@ = null;\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}@\\
\makebox[1.6cm][l]{}//constructor:\\
\makebox[1.6cm][l]{}public @this.name@() \{\\
\makebox[1.6cm][l]{}\}\\
\makebox[0.8cm][l]{}\\
\makebox[1.6cm][l]{}// accessors:\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}foreach i in this.listOfAttributes \{\\
\makebox[1.6cm][l]{}@   public @getJAVAType(i)@ get@toUpperString(i.name)@() \{ return \_@i.name@; \}\\
\makebox[1.6cm][l]{}public void set@toUpperString(i.name)@(@getJAVAType(i)@ @i.name@) \{ \_@i.name@ = @i.name@; \}\\
\makebox[0.8cm][l]{}@\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}setProtectedArea("Methods");\\
\makebox[0.8cm][l]{}@\}\\
\makebox[0.8cm][l]{}\\
class to generate = 'Earth'\\
generated text:\\
//\#\#generation header\#\#CodeWorker\#\#4.2\#\#01may2006 13:58:52\#\#\\
//\#\#header start\#\#\\
//Popeye's Village\\
//Olive hates spinash\\
//\#\#header end\#\#\\
package tiny;\\
\\
public class Earth  extends Planet \{\\
\makebox[0.8cm][l]{}// attributes:\\
\makebox[0.8cm][l]{}private  \_countryNames = null;\\
\\
\makebox[0.8cm][l]{}//constructor:\\
\makebox[0.8cm][l]{}public Earth() \{\\
\makebox[0.8cm][l]{}\}\\
\\
\makebox[0.8cm][l]{}// accessors:\\
\makebox[0.8cm][l]{}public  getCOUNTRYNAMES() \{ return \_countryNames; \}\\
\makebox[0.8cm][l]{}public void setCOUNTRYNAMES( countryNames) \{ \_countryNames = countryNames; \}\\
//\#\#protect\#\#"Methods"\\
//\#\#protect\#\#"Methods"\\
\}\\
}


\textbf{See also:}

\samp{extractGenerationHeader} \ref{extractGenerationHeader()}, \samp{getGenerationHeader} \ref{getGenerationHeader()}
\end{itemize}
\pdflabel{setIncludePath()}
\index{setIncludePath()}
\pdfsubsection{setIncludePath}
\begin{itemize}
	\item procedure \textbf{setIncludePath(}\samp{path} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{a concatenation of paths separated by \textbf{';'}}
\end{tableiii}
It changes the include path passed to the command line with one or more times
the setting of the option \samp{-I}.

The include path expects a concatenation of paths separated by semi-commas (\textbf{';'}).

\textbf{Example:}

\texttt{local sOldPath = getIncludePath();\\
setIncludePath("Here/is;better/than;before");\\
traceLine("one changes the path: '" + getIncludePath() + "'");\\
setIncludePath(sOldPath);}

\textbf{Output:}

\texttt{one changes the path: 'Here/is/;better/than/;before/'}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getIncludePath} \ref{getIncludePath()}, \samp{getVersion} \ref{getVersion()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setProperty} \ref{setProperty()}, \samp{setVersion} \ref{setVersion()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{setNow()}
\index{setNow()}
\pdfsubsection{setNow}
\begin{itemize}
	\item procedure \textbf{setNow(}\samp{constantDateTime} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{constantDateTime}}{\textit{string}}{the current date-time is fixed to this value}
\end{tableiii}
Fixes the current date-time to the value passed to argument \samp{constantDateTime},
 conforming to the format:\\
\samp{\%d\%b\%Y \%H:\%M:\%S.\%L}

The procedure doesn't change the system time. \textit{now} is just frozen for the
scripting language when calling \samp{getNow()}. One passes an empty date-time to
unfreeze the time.

For explanations about \textit{format types}, see function \samp{formatDate}
at \ref{formatDate()}.

\textbf{Example:}

\texttt{// the time is already frozen for building the documentation\\
local sOldFrozenTime = getNow();\\
traceLine("now = " + getNow());\\
traceLine("one freezes the time to '19jan2003 06:30:00.100'");\\
setNow("19jan2003 06:30:00.100");\\
traceLine("now = '" + getNow() + "' is frozen to this value");\\
setNow(sOldFrozenTime);}

\textbf{Output:}

\texttt{now = 01may2006 20:42:00.500\\
one freezes the time to '19jan2003 06:30:00.100'\\
now = '19jan2003 06:30:00.100' is frozen to this value}


\textbf{See also:}

\samp{formatDate} \ref{formatDate()}, \samp{addToDate} \ref{addToDate()}, \samp{compareDate} \ref{compareDate()}, \samp{completeDate} \ref{completeDate()}, \samp{getLastDelay} \ref{getLastDelay()}, \samp{getNow} \ref{getNow()}
\end{itemize}
\pdflabel{setProperty()}
\index{setProperty()}
\pdfsubsection{setProperty}
\begin{itemize}
	\item procedure \textbf{setProperty(}\samp{define} \textbf{:} \textit{string}\textbf{, }\samp{value} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{define}}{\textit{string}}{name of a property}
	\lineiii{\samp{value}}{\textit{string}}{value to assign to the property}
\end{tableiii}
It assigns the value held by the argument \samp{value} to a property whose name
is given by parameter \samp{define}. It is equivalent of writing
\samp{'-D \textit{define}=\textit{value}'} on the command line.

An error is raised if the \samp{define} argument is an empty string.

\textbf{Example:}

\texttt{setProperty("JUST\_FOR\_FUN", "Monty Python");\\
traceLine("getProperty('JUST\_FOR\_FUN') = '" + getProperty("JUST\_FOR\_FUN") + "'");}

\textbf{Output:}

\texttt{getProperty('JUST\_FOR\_FUN') = 'Monty Python'}


\pdflabel{setDefineTarget()}
\index{deprecated!setDefineTarget()}
\textbf{Deprecated form:} \samp{setDefineTarget} has disappeared since version \textit{1.30}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getIncludePath} \ref{getIncludePath()}, \samp{getVersion} \ref{getVersion()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setVersion} \ref{setVersion()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{setTextMode()}
\index{setTextMode()}
\pdfsubsection{setTextMode}
\begin{itemize}
	\item procedure \textbf{setTextMode(}\samp{textMode} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{textMode}}{\textit{string}}{text mode (binary or not)}
\end{tableiii}

Sets the mode of text that must be retained for parsing and source code generation. The
argument \samp{textMode} is worth one of the following values:
\begin{itemize}
	\item \textbf{"DOS"}: the default value if the interpreter is running under a \textit{Windows} platform,
	\item \textbf{"UNIX"}: the default value if the interpreter isn't running under a \textit{Windows} platform,
	\item \textbf{"BINARY"}: not exploited yet, but intended to specify later that
		the parsing and the source code generation are applied on binary files,
\end{itemize}
An exception is raised if the argument \samp{textMode} passes a bad value.

The impact of choosing samp{"DOS"} instead of any other mode is that special
comments, which announce markup keys and protected areas, will finish by
"$\backslash$r$\backslash$n" when the end of comment is a newline '$\backslash$n'.

\textbf{Example:}

\texttt{local sTextMode = getTextMode();\\
traceLine("This documentation is generated under '" + sTextMode + "' text mode");\\
setTextMode("BINARY");\\
traceLine("Now, it is generated under '" + getTextMode() + "'!");\\
setTextMode(sTextMode);}

\textbf{Output:}

\texttt{This documentation is generated under 'DOS' text mode\\
Now, it is generated under 'BINARY'!}


\textbf{See also:}

\samp{getTextMode} \ref{getTextMode()}
\end{itemize}
\pdflabel{setVersion()}
\index{setVersion()}
\pdfsubsection{setVersion}
\begin{itemize}
	\item procedure \textbf{setVersion(}\samp{version} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{version}}{\textit{string}}{version number of scripts}
\end{tableiii}
Indicates to the \CodeWorker\ interpreter that scripts must be considered
as written in an older version of the scripting language, given by the parameter
\samp{version}.

It allows \CodeWorker\ to behave as if it was an ancient interpreter and
eventually, to adapt deprecated forms.

\textbf{Example:}

\texttt{local sVersion = getVersion();\\
traceLine("The version of scripts is '" + sVersion + "'");\\
setVersion("1.5.2");\\
traceLine("Now, the version of scripts is '" + getVersion() + "'");\\
setVersion(sVersion);}

\textbf{Output:}

\texttt{The version of scripts is '4.2'\\
Now, the version of scripts is '1.5.2'}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getIncludePath} \ref{getIncludePath()}, \samp{getVersion} \ref{getVersion()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setProperty} \ref{setProperty()}, \samp{setWorkingPath} \ref{setWorkingPath()}
\end{itemize}
\pdflabel{setWorkingPath()}
\index{setWorkingPath()}
\pdfsubsection{setWorkingPath}
\begin{itemize}
	\item procedure \textbf{setWorkingPath(}\samp{path} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{path}}{\textit{string}}{the new working path}
\end{tableiii}
Changes the output directory that was assigned to the option
\textbf{-path} on the command line.

\textbf{Example:}

\texttt{local sOldWorkingPath = getWorkingPath();\\
setWorkingPath("WebSite/");\\
traceLine("'old path' = '" + sOldWorkingPath + "'");\\
traceLine("'new path' = '" + getWorkingPath() + "'");\\
setWorkingPath(sOldWorkingPath);}

\textbf{Output:}

\texttt{'old path' = 'e:$\backslash$Projects$\backslash$generator/'\\
'new path' = 'WebSite/'}


\textbf{See also:}

\samp{getProperty} \ref{getProperty()}, \samp{getIncludePath} \ref{getIncludePath()}, \samp{getVersion} \ref{getVersion()}, \samp{getWorkingPath} \ref{getWorkingPath()}, \samp{setIncludePath} \ref{setIncludePath()}, \samp{setProperty} \ref{setProperty()}, \samp{setVersion} \ref{setVersion()}
\end{itemize}
\pdflabel{setWriteMode()}
\index{setWriteMode()}
\pdfsubsection{setWriteMode}
\begin{itemize}
	\item procedure \textbf{setWriteMode(}\samp{mode} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{mode}}{\textit{string}}{is worth \samp{"insert"} or \samp{"overwrite"}}
\end{tableiii}
Selects how to write text during a generation and how to apply an implicit copy
during a translation.

By default, a text is written in overwrite mode (\samp{mode} = \samp{"overwrite"}):
if the file cursor doesn't point to the end of the current output file, the new text
overwrites the old one and the remaining, if any, is inserted at the end.\\
The insert mode (\samp{mode} = \samp{"insert"}) causes a shift of the old text, so
as to preserve it.


\textbf{See also:}

\samp{getWriteMode} \ref{getWriteMode()}
\end{itemize}
\pdflabel{shortToBytes()}
\index{shortToBytes()}
\pdfsubsection{shortToBytes}
\begin{itemize}
	\item function \textbf{shortToBytes(}\samp{short} \textbf{:} \textit{ushort}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{short}}{\textit{ushort}}{an unsigned short integer using the decimal base}
\end{tableiii}
Converts an unsigned short integer in decimal base to its 2-bytes representation.
Bytes are ordered in the host order (memory storage).

\textbf{Example:}

\texttt{traceLine("shortToBytes(255) = '" + shortToBytes(255) + "'");}

\textbf{Output:}

\texttt{shortToBytes(255) = 'FF00'}


\textbf{See also:}

\samp{byteToChar} \ref{byteToChar()}, \samp{bytesToLong} \ref{bytesToLong()}, \samp{bytesToShort} \ref{bytesToShort()}, \samp{charToByte} \ref{charToByte()}, \samp{charToInt} \ref{charToInt()}, \samp{hexaToDecimal} \ref{hexaToDecimal()}, \samp{longToBytes} \ref{longToBytes()}, \samp{octalToDecimal} \ref{octalToDecimal()}
\end{itemize}
\pdflabel{sleep()}
\index{sleep()}
\pdfsubsection{sleep}
\begin{itemize}
	\item procedure \textbf{sleep(}\samp{millis} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{millis}}{\textit{int}}{how many milliseconds the execution must be suspended}
\end{tableiii}
The procedure suspends the execution for \samp{millis} milliseconds.
\end{itemize}
\pdflabel{slideNodeContent()}
\index{slideNodeContent()}
\pdfsubsection{slideNodeContent}
\begin{itemize}
	\item procedure \textbf{slideNodeContent(}\samp{orgNode} \textbf{:} \textit{treeref}\textbf{, }\samp{destNode} \textbf{:} \textit{treexpr}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{orgNode}}{\textit{treeref}}{points to a node of a parse tree}
	\lineiii{\samp{destNode}}{\textit{treexpr}}{a branch starting at the \samp{orgNode} node}
\end{tableiii}
Moves the entire content (both attributes and array nodes) of the node passed
to the argument \samp{orgNode}, so as to put it at the extremity of a new
branch, added to the original node \samp{orgNode} once its content has been
taken off.

For instance, \samp{slideNodeContent(\textit{pExpr}, \textit{left})} means
that the content of \textit{pExpr} slides to \textit{pExpr.left}.

\textbf{Example:}

\texttt{local pExpr;\\
// a given parsing leads to populate an expression:\\
insert pExpr.operator = "*";\\
insert pExpr.left = 3.141592;\\
insert pExpr.right = "X";\\
traceLine("'pExpr' represents '3.141592 * X'");\\
// the parsing continues and reveals that the precedent\\
// expression was the left part of a bigger arithmetic\\
// expression:\\
traceLine("After moving, the content of 'pExpr' becomes the left hand:");\\
slideNodeContent(pExpr, left);\\
traceLine("'    - 'pExpr' contains only the sub-node 'left'");\\
traceLine("'    - 'pExpr.left' represents '3.141592 * X'");\\
insert pExpr.operator = "+";\\
insert pExpr.right = "Y";\\
traceLine("'pExpr' describes now '(3.141592 * X) + Y'");}

\textbf{Output:}

\texttt{'pExpr' represents '3.141592 * X'\\
After moving, the content of 'pExpr' becomes the left hand:\\
'   - 'pExpr' contains only the sub-node 'left'\\
'   - 'pExpr.left' represents '3.141592 * X'\\
'pExpr' describes now '(3.141592 * X) + Y'}


\textbf{See also:}

\samp{equalTrees} \ref{equalTrees()}
\end{itemize}
\pdflabel{sortArray()}
\index{sortArray()}
\pdfsubsection{sortArray}
\begin{itemize}
	\item procedure \textbf{sortArray(}\samp{array} \textbf{:} \textit{tree}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{array}}{\textit{tree}}{the array node to sort}
\end{tableiii}
Sort an array in the lexicographical order of the entry keys.

\textbf{Example:}

\texttt{local  myArray;\\
insert myArray["Garfield"];\\
insert myArray["Tea spoon"];\\
insert myArray["Everest"];\\
traceLine("Sort the array 'myArray':");\\
sortArray(myArray);\\
foreach i in myArray \{\\
\makebox[0.8cm][l]{}traceLine("$\backslash$t$\backslash$"" + i.key() + "$\backslash$"");\\
\}}

\textbf{Output:}

\texttt{Sort the array 'myArray':\\
\makebox[0.8cm][l]{}"Everest"\\
\makebox[0.8cm][l]{}"Garfield"\\
\makebox[0.8cm][l]{}"Tea spoon"}
\end{itemize}
\pdflabel{sqrt()}
\index{sqrt()}
\pdfsubsection{sqrt}
\begin{itemize}
	\item function \textbf{sqrt(}\samp{x} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{x}}{\textit{double}}{the number we want to calculate the square root}
\end{tableiii}
Calculates the square root of \samp{x}.

An invalid number causes the function to throw an error.

\textbf{Example:}

\texttt{traceLine("sqrt(25) = " + sqrt(25));}

\textbf{Output:}

\texttt{sqrt(25) = 5}
\end{itemize}
\pdflabel{startString()}
\index{startString()}
\pdfsubsection{startString}
\begin{itemize}
	\item function \textbf{startString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{start} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to test}
	\lineiii{\samp{start}}{\textit{string}}{the prefix}
\end{tableiii}
\samp{"true"} if the argument \samp{start} is a prefix of the character
sequence represented by \samp{text}; \samp{""} otherwise. Note also that
\samp{"true"} will be returned if \samp{start} is an empty string or is
equal to argument \samp{text}.

\textbf{Example:}

\texttt{local sText = "airport";\\
traceLine("startString('" + sText + "', 'air') = '" + startString(sText, "air") + "'");}

\textbf{Output:}

\texttt{startString('airport', 'air') = 'true'}


\textbf{See also:}

\samp{findFirstChar} \ref{findFirstChar()}, \samp{endString} \ref{endString()}, \samp{findLastString} \ref{findLastString()}, \samp{findNextString} \ref{findNextString()}, \samp{findString} \ref{findString()}
\end{itemize}
\pdflabel{sub()}
\index{sub()}
\pdfsubsection{sub}
\begin{itemize}
	\item function \textbf{sub(}\samp{left} \textbf{:} \textit{double}\textbf{, }\samp{right} \textbf{:} \textit{double}\textbf{) :} \textit{double}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{double}}{first arithmetic member}
	\lineiii{\samp{right}}{\textit{double}}{second arithmetic member}
\end{tableiii}
Returns the result of arithmetic subtraction \samp{left} \textbf{-} \samp{right}.
Members are converted from strings to numbers, supposed being worth \samp{0} if a parsing error occurs;
then the subtraction is processed, and the result is converted to a string,
skipping fractional part if all digits after the dot are \textit{0}.

Remember that the symbol \textbf{'-'} doesn't mean anything in the standard syntax of the
language, so there is no way to confuse for expressing a subtraction.
However, it exists an escape mode that allows writing arithmetic expressions
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{left} \textbf{-} \textit{right}\$}
is equivalent to \samp{sub(\textit{left}, \textit{right})}.

\textbf{Example:}

\texttt{local a = 4.5;\\
traceLine(a + " - 2.8 = " + sub(a, "2.8"));\\
traceLine(a + " - 2.5 = " + sub(a, 2.5) + " <- integer value");}

\textbf{Output:}

\texttt{4.5 - 2.8 = 1.7\\
4.5 - 2.5 = 2 <- integer value}


\textbf{See also:}

\samp{add} \ref{add()}, \samp{mult} \ref{mult()}, \samp{div} \ref{div()}, \samp{exp} \ref{exp()}, \samp{log} \ref{log()}, \samp{mod} \ref{mod()}, \samp{pow} \ref{pow()}
\end{itemize}
\pdflabel{subString()}
\index{subString()}
\pdfsubsection{subString}
\begin{itemize}
	\item function \textbf{subString(}\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{pos} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters}
	\lineiii{\samp{pos}}{\textit{int}}{a position starting at 0, and relative to the beginning of the \samp{text} string}
\end{tableiii}
Returns the sequence of characters passed to argument \samp{text} after skipping
the first \samp{pos} characters.

\textbf{Example:}

\texttt{local sText = "The lamp of experience";\\
traceLine("sText = '" + sText + "'");\\
traceLine("subString(sText, 4) = '" + subString(sText, 4) + "'");}

\textbf{Output:}

\texttt{sText = 'The lamp of experience'\\
subString(sText, 4) = 'lamp of experience'}


\textbf{See also:}

\samp{charAt} \ref{charAt()}, \samp{coreString} \ref{coreString()}, \samp{cutString} \ref{cutString()}, \samp{joinStrings} \ref{joinStrings()}, \samp{leftString} \ref{leftString()}, \samp{lengthString} \ref{lengthString()}, \samp{midString} \ref{midString()}, \samp{rightString} \ref{rightString()}, \samp{rsubString} \ref{rsubString()}
\end{itemize}
\pdflabel{sup()}
\index{sup()}
\pdfsubsection{sup}
\begin{itemize}
	\item function \textbf{sup(}\samp{left} \textbf{:} \textit{double}\textbf{, }\samp{right} \textbf{:} \textit{double}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{left}}{\textit{double}}{the first member}
	\lineiii{\samp{right}}{\textit{double}}{the second member}
\end{tableiii}
Compares two numbers and returns \samp{true} if the first member given by
argument \samp{left} is strictly greater than the second member passed to
argument \samp{right}.

Don't use the operator \samp{'>'} to compare numbers in the classical syntax of
the interpreter: it only checks the lexicographical order. So, \textit{'3 > 12'} is \samp{true}.
However, it exists an escape mode that allows writing arithmetic comparisons
between \textbf{'\$'} symbols, as formula under \textit{LaTeX}. So, \samp{\$\textit{left} \textbf{>} \textit{right}\$}
is equivalent to \samp{inf(\textit{left}, \textit{right})}.

\textbf{Example:}

\texttt{traceLine("sup(12, 3) = '" + sup(12, 3) + "'");\\
traceLine("12 > 3 = '" + (12 > 3) + "'");}

\textbf{Output:}

\texttt{sup(12, 3) = 'true'\\
12 > 3 = ''}


\textbf{See also:}

\samp{equal} \ref{equal()}, \samp{inf} \ref{inf()}
\end{itemize}
\pdflabel{system()}
\index{system()}
\pdfsubsection{system}
\begin{itemize}
	\item function \textbf{system(}\samp{command} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{command}}{\textit{string}}{the command interpreter will execute it}
\end{tableiii}
This function passes \samp{command} to the command interpreter, which executes
the string as an operating-system command. If \samp{command} is empty, the
function simply checks to see whether the command interpreter exists and returns
an empty string. If an error occurs, it returns the corresponding error message.

\textbf{Example:}

\texttt{local sScript = getWorkingPath() + "Documentation/System.cws";\\
local sCommand;\\
if existFile("CodeWorker.exe") set sCommand = "CodeWorker.exe";\\
else set sCommand = "Release$\backslash$$\backslash$CodeWorker";\\
set sCommand += " -script " + sScript;\\
local sOutput = getWorkingPath() + "Documentation/System.out";\\
traceLine("another $\backslash$"CodeWorker$\backslash$" is launched from here,");\\
local sError = system(sCommand + " > " + sOutput);\\
if sError error(sError);\\
traceLine("and executes the following script:");\\
traceLine(loadFile(sScript));\\
traceLine("the trace was put into a file:");\\
traceLine(loadFile(sOutput));}

\textbf{Output:}

\texttt{another "CodeWorker" is launched from here,\\
and executes the following script:\\
traceLine("This text comes from an external $\backslash$"CodeWorker$\backslash$"");\\
\\
the trace was put into a file:\\
CodeWorker v4.2 (LGPL), parses and generates source code easily;\\
Copyright (C) 1996-2006 Cedric Lemaire; see 'http://www.codeworker.org'.\\
This text comes from an external "CodeWorker"\\
}


\textbf{See also:}

\samp{getEnv} \ref{getEnv()}, \samp{environTable} \ref{environTable()}, \samp{existEnv} \ref{existEnv()}, \samp{putEnv} \ref{putEnv()}
\end{itemize}
\pdflabel{toLowerString()}
\index{toLowerString()}
\pdfsubsection{toLowerString}
\begin{itemize}
	\item function \textbf{toLowerString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{string to make in lower case}
\end{tableiii}
Converts each uppercase letter in \samp{text} to lowercase, and returns the result. Other characters are not affected

\textbf{Example:}

\texttt{local sText = "BE AFRAID ABOUT the $\backslash$"WORLD COMPANY$\backslash$"";\\
traceLine("toLowerString('" + sText + "') = '" + toLowerString(sText) + "'");}

\textbf{Output:}

\texttt{toLowerString('BE AFRAID ABOUT the "WORLD COMPANY"') = 'be afraid about the "world company"'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{toUpperString()}
\index{toUpperString()}
\pdfsubsection{toUpperString}
\begin{itemize}
	\item function \textbf{toUpperString(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{string to capitalize}
\end{tableiii}
Converts each lowercase letter in \samp{text} to uppercase, and returns the result. Other characters are not affected.

\textbf{Example:}

\texttt{local sText = "THINK different, LEARN about other civilizations";\\
traceLine("toUpperString('" + sText + "') = '" + toUpperString(sText) + "'");}

\textbf{Output:}

\texttt{toUpperString('THINK different, LEARN about other civilizations') = 'THINK DIFFERENT, LEARN ABOUT OTHER CIVILIZATIONS'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{traceEngine()}
\index{traceEngine()}
\pdfsubsection{traceEngine}
\begin{itemize}
	\item procedure \textbf{traceEngine(}\textbf{)}

Traces some states about the interpreter and the current script.


\textbf{See also:}

\samp{traceLine} \ref{traceLine()}, \samp{traceObject} \ref{traceObject()}, \samp{traceStack} \ref{traceStack()}, \samp{traceText} \ref{traceText()}
\end{itemize}
\pdflabel{traceLine()}
\index{traceLine()}
\pdfsubsection{traceLine}
\begin{itemize}
	\item procedure \textbf{traceLine(}\samp{line} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{line}}{\textit{string}}{a string expression to display to the console}
\end{tableiii}
Evaluates the expression passed to argument \samp{line}, and displays the
resulting string to the console. An end of line is added automatically.

In case of \textit{quiet} execution, there is no output to the console,
but the line will be kept:
\begin{itemize}
	\item for processing if used through the JNI interface, to raise all
			messages to the JAVA application that exploit the \CodeWorker\
			library,
	\item for concatenating it into a string that collects all messages and
			that returns it after calling function \samp{executeStringQuiet}
			(see \ref{executeStringQuiet()}),
\end{itemize}

\textbf{Example:}

\texttt{traceLine("A text to display, and then");\\
traceLine("I go to the next line");}

\textbf{Output:}

\texttt{A text to display, and then\\
I go to the next line}


\textbf{See also:}

\samp{traceEngine} \ref{traceEngine()}, \samp{traceObject} \ref{traceObject()}, \samp{traceStack} \ref{traceStack()}, \samp{traceText} \ref{traceText()}
\end{itemize}
\pdflabel{traceObject()}
\index{traceObject()}
\pdfsubsection{traceObject}
\begin{itemize}
	\item procedure \textbf{traceObject(}\samp{object} \textbf{:} \textit{tree}\textbf{, }\samp{depth} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{object}}{\textit{tree}}{a tree node, means any kind of variable}
	\lineiii{\samp{depth}}{\textit{int}}{\textbf{default value:} \textit{0}\\
display depth of the tree}
\end{tableiii}
Displays all sub-nodes (called \textit{attributes}) and the node item's array,
 if any, belonging to an object passed to argument \samp{object}.

The value assigned to the object is displayed too, when it isn't an empty
string. If an array of nodes exists, then all entry keys are display, followed
by the value assigned to the item node if not empty.

\textbf{Example:}

\texttt{local myTree = "monkey";\\
insert myTree.hobbies = "to eat bretzel";\\
insert myTree["Everest"] = "mountain";\\
insert myTree["Tea spoon"] = "silverware";\\
traceObject(myTree);}

\textbf{Output:}

\texttt{Tracing variable 'myTree':\\
\makebox[0.8cm][l]{}"monkey"\\
\makebox[0.8cm][l]{}hobbies = "to eat bretzel"\\
\makebox[0.8cm][l]{}["Everest" -> "mountain", "Tea spoon" -> "silverware"]\\
End of variable's trace 'myTree'.}


\textbf{See also:}

\samp{traceLine} \ref{traceLine()}, \samp{traceEngine} \ref{traceEngine()}, \samp{traceStack} \ref{traceStack()}, \samp{traceText} \ref{traceText()}
\end{itemize}
\pdflabel{traceStack()}
\index{traceStack()}
\pdfsubsection{traceStack}
\begin{itemize}
	\item procedure \textbf{traceStack(}\textbf{)}

Displays the stack of local variables recursively.

In case of \textit{quiet} execution, there is no output to the console,
but the entire call stack description will be kept:
\begin{itemize}
	\item for processing if used through the JNI interface, raising all
			messages to the JAVA application that exploit the \CodeWorker\
			library,
	\item for concatenating it into a string that collects all messages and
			that returns it after calling function \samp{executeStringQuiet}
			(see \ref{executeStringQuiet()}),
\end{itemize}

\textbf{Example:}

\texttt{traceStack();}

\textbf{Output:}

\texttt{\#\#stack\#\# script:\\
\#\#stack\#\# block:\\
theDocumentation\\
theDocumentation:\\
iNotDocumentedCounter = "0"\\
iNotDocumentedParameter = "0"\\
iNoExampleCounter = "41"\\
iNoSeeAlsoCounter = "20"\\
iFunctionCounter = "204"\\
listOfCommands\\
\makebox[0.8cm][l]{}listOfCommands["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]\\
\#\#stack\#\# script:}


\textbf{See also:}

\samp{traceLine} \ref{traceLine()}, \samp{traceEngine} \ref{traceEngine()}, \samp{traceObject} \ref{traceObject()}, \samp{traceText} \ref{traceText()}
\end{itemize}
\pdflabel{traceText()}
\index{traceText()}
\pdfsubsection{traceText}
\begin{itemize}
	\item procedure \textbf{traceText(}\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a string expression to display to the console}
\end{tableiii}
Evaluates the expression passed to argument \samp{line}, and displays the
resulting string to the console. On the contrary of \samp{traceLine}, there
is no carriage return at the end.

In case of \textit{quiet} execution, there is no output to the console,
but the text will be kept:
\begin{itemize}
	\item for processing if used through the JNI interface, to raise all
			messages to the JAVA application that exploit the \CodeWorker\
			library,
	\item for concatenating it into a string that collects all messages and
			that returns it after calling function \samp{executeStringQuiet}
			(see \ref{executeStringQuiet()}),
\end{itemize}

\textbf{Example:}

\texttt{traceText("A text to display, ");\\
traceText("but I refuse to go to line!");\\
traceLine("");}

\textbf{Output:}

\texttt{A text to display, but I refuse to go to line!}


\textbf{See also:}

\samp{traceLine} \ref{traceLine()}, \samp{traceEngine} \ref{traceEngine()}, \samp{traceObject} \ref{traceObject()}, \samp{traceStack} \ref{traceStack()}
\end{itemize}
\pdflabel{translate()}
\index{translate()}
\pdfsubsection{translate}
\begin{itemize}
	\item procedure \textbf{translate(}\samp{patternFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{inputFileName} \textbf{:} \textit{string}\textbf{, }\samp{outputFileName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{patternFileName}}{\textit{script<translate>}}{file name of the \textit{pattern script}, which merges both the BNF syntax and the source code generation tags}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed via \textit{this} variable}
	\lineiii{\samp{inputFileName}}{\textit{string}}{the input file to parse}
	\lineiii{\samp{outputFileName}}{\textit{string}}{the output file to generate}
\end{tableiii}
Parses an input file whose name is given by the argument \samp{inputFileName}
and generates a translated file given by the argument \samp{outputFileName},
following the instructions of the \textit{pattern script} called \samp{patternFileName}.

The pattern script merges the BNF syntax presented section \ref{BNF syntax} with
the source code generation syntax described section \ref{source code generation}.


\textbf{See also:}

\samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}, \samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translateString} \ref{translateString()}
\end{itemize}
\pdflabel{translateString()}
\index{translateString()}
\pdfsubsection{translateString}
\begin{itemize}
	\item function \textbf{translateString(}\samp{patternFileName} \textbf{:} \textit{script}\textbf{, }\samp{this} \textbf{:} \textit{tree}\textbf{, }\samp{inputString} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{patternFileName}}{\textit{script<translate>}}{file name of the \textit{pattern script}, which merges both the BNF syntax and the source code generation tags}
	\lineiii{\samp{this}}{\textit{tree}}{the current node that will be accessed via \textit{this} variable}
	\lineiii{\samp{inputString}}{\textit{string}}{the input string to parse}
\end{tableiii}
Parses the input string given by the argument \samp{inputString}
and returns the output string resulting of the translation,
following the instructions of the \textit{pattern script} called \samp{patternFileName}.

The pattern script merges the BNF syntax presented section \ref{BNF syntax} with
the source code generation syntax described section \ref{source code generation}.


\textbf{See also:}

\samp{parseAsBNF} \ref{parseAsBNF()}, \samp{parseFree} \ref{parseFree()}, \samp{parseFreeQuiet} \ref{parseFreeQuiet()}, \samp{parseStringAsBNF} \ref{parseStringAsBNF()}, \samp{translate} \ref{translate()}, \samp{expand} \ref{expand()}, \samp{autoexpand} \ref{autoexpand()}, \samp{generate} \ref{generate()}, \samp{generateString} \ref{generateString()}
\end{itemize}
\pdflabel{trim()}
\index{trim()}
\pdfsubsection{trim}
\begin{itemize}
	\item function \textbf{trim(}\samp{string} \textbf{:} \textit{stringref}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{string}}{\textit{stringref}}{variable that contains the characters to be trimmed}
\end{tableiii}
This function trims heading and trailing whitespace characters from the referenced
argument \samp{string} and returns the number of characters that were removed.
It removes newline, space, and tab characters.

\textbf{Example:}

\texttt{local sText = "    Spaces for sale!    ";\\
traceLine("trim(sText) = '" + trim(sText) + "'");}

\textbf{Output:}

\texttt{trim(sText) = '8'}


\pdflabel{trimString()}
\index{deprecated!trimString()}
\textbf{Deprecated form:} \samp{trimString} has disappeared since version \textit{1.40}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{trimLeft()}
\index{trimLeft()}
\pdfsubsection{trimLeft}
\begin{itemize}
	\item function \textbf{trimLeft(}\samp{string} \textbf{:} \textit{stringref}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{string}}{\textit{stringref}}{variable that contains the characters to be trimmed}
\end{tableiii}
This function trims leading whitespace characters from the argument
\samp{string} and returns the number of characters that were removed. It
removes newline, space, and tab characters.

\textbf{Example:}

\texttt{local sText = "    Spaces for sale!    ";\\
traceLine("trimLeft(sText) = '" + trimLeft(sText) + "'");}

\textbf{Output:}

\texttt{trimLeft(sText) = '4'}


\pdflabel{trimLeftString()}
\index{deprecated!trimLeftString()}
\textbf{Deprecated form:} \samp{trimLeftString} has disappeared since version \textit{1.40}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{trimRight()}
\index{trimRight()}
\pdfsubsection{trimRight}
\begin{itemize}
	\item function \textbf{trimRight(}\samp{string} \textbf{:} \textit{stringref}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{string}}{\textit{stringref}}{variable that contains the characters to be trimmed}
\end{tableiii}
This function trims trailing whitespace characters from the referenced argument
\samp{string} and returns the number of characters that were removed. It
removes newline, space, and tab characters.

\textbf{Example:}

\texttt{local sText = "    Spaces for sale!    ";\\
traceLine("trimRight(sText) = '" + trimRight(sText) + "'");}

\textbf{Output:}

\texttt{trimRight(sText) = '4'}


\pdflabel{trimRightString()}
\index{deprecated!trimRightString()}
\textbf{Deprecated form:} \samp{trimRightString} has disappeared since version \textit{1.40}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{truncateAfterString()}
\index{truncateAfterString()}
\pdfsubsection{truncateAfterString}
\begin{itemize}
	\item function \textbf{truncateAfterString(}\samp{variable} \textbf{:} \textit{treeref}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{this parameter passes a string to handle and receives its truncation}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to find into the value held by \samp{variable}}
\end{tableiii}
This function:
\begin{itemize}
	\item searches the sequence of characters passed to the argument \samp{text}
		into the string given by the parameter \samp{variable},
	\item assigns the substring standing on the right of \samp{text} (so,
		\samp{text} is excluded) to the parameter \samp{variable},
	\item returns the left part of the substring that hasn't been assigned.
\end{itemize}

If the sequence of characters \samp{text} isn't found into the value of
\samp{variable}, the function returns an empty string, and the variable doesn't
change.

\textbf{Example:}

\texttt{local sVariable = "my tongue fell out with my teeth";\\
traceLine("sentence = '" + sVariable + "'");\\
local sResult = truncateAfterString(sVariable, "out");\\
traceLine("Now, the variable is worth '" + sVariable + "'");\\
traceLine("And the result = '" + sResult + "'");}

\textbf{Output:}

\texttt{sentence = 'my tongue fell out with my teeth'\\
Now, the variable is worth ' with my teeth'\\
And the result = 'my tongue fell out'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateBeforeString} \ref{truncateBeforeString()}
\end{itemize}
\pdflabel{truncateBeforeString()}
\index{truncateBeforeString()}
\pdfsubsection{truncateBeforeString}
\begin{itemize}
	\item function \textbf{truncateBeforeString(}\samp{variable} \textbf{:} \textit{treeref}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{variable}}{\textit{treeref}}{this parameter passes a string to handle and receives its truncation}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to find into the value held by \samp{variable}}
\end{tableiii}
This function:
\begin{itemize}
	\item searches the sequence of characters passed to the argument \samp{text}
		into the string given by the parameter \samp{variable},
	\item assigns the substring standing on the left of \samp{text} (so,
		\samp{text} is excluded) to the parameter \samp{variable},
	\item returns the right part of the substring that hasn't been assigned.
\end{itemize}

If the sequence of characters \samp{text} isn't found into the value of
\samp{variable}, the function returns an empty string, and the variable doesn't
change.

\textbf{Example:}

\texttt{local sVariable = "my tongue fell out with my teeth";\\
traceLine("sentence = '" + sVariable + "'");\\
local sResult = truncateBeforeString(sVariable, "out");\\
traceLine("Now, the variable is worth '" + sVariable + "'");\\
traceLine("And the result = '" + sResult + "'");}

\textbf{Output:}

\texttt{sentence = 'my tongue fell out with my teeth'\\
Now, the variable is worth 'my tongue fell '\\
And the result = 'out with my teeth'}


\textbf{See also:}

\samp{countStringOccurences} \ref{countStringOccurences()}, \samp{completeLeftSpaces} \ref{completeLeftSpaces()}, \samp{completeRightSpaces} \ref{completeRightSpaces()}, \samp{repeatString} \ref{repeatString()}, \samp{replaceString} \ref{replaceString()}, \samp{replaceTabulations} \ref{replaceTabulations()}, \samp{toLowerString} \ref{toLowerString()}, \samp{toUpperString} \ref{toUpperString()}, \samp{trimLeft} \ref{trimLeft()}, \samp{trimRight} \ref{trimRight()}, \samp{trim} \ref{trim()}, \samp{truncateAfterString} \ref{truncateAfterString()}
\end{itemize}
\pdflabel{UUID()}
\index{UUID()}
\pdfsubsection{UUID}
\begin{itemize}
	\item function \textbf{UUID(}\textbf{) :} \textit{string}

This function generates an UUID and returns it as a string. An UUID is a 128-bit
universally unique id, used by Microsoft and being proposed as an internet standard.

\textbf{Example:}

\texttt{traceLine("generation of an UUID = '" + UUID() + "'");\\
traceLine("generation of another one = '" + UUID() + "'");}

\textbf{Output:}

\texttt{generation of an UUID = '1c0482f3-6364-4cbd-80d4-2258e344e0e2'\\
generation of another one = 'ef54a214-454d-4696-99dd-c9c12b6d650f'}
\end{itemize}
%##end##"common script functions"

%--------------------------------------------------------------------------
\pdflabel{BNF syntax}
\index{parsing!BNF syntax}
\index{scripts!BNF syntax}
\pdfsection{The extended BNF syntax for parsing}
A BNF description of a grammar is more flexible and more synthetic than a procedural
description of parsing. \CodeWorker\ accepts parsing scripts that conform to a BNF.

BNF is the acronym of \textit{\textbf{B}ackus-\textbf{N}aur \textbf{F}orm}, and consists
of describing a grammar with production rules. The first production rule that is encountered into the
script and that isn't a special one (beginning with a \textbf{'\#'} like the {\#empty} clause),
is chosen as the main non-terminal to match with the input stream, when the \textit{BNF-driven}
script is executed.

A non-terminal (often called a \textit{clause} in the documentation) breaks down into terminals and other non-terminals.
Defining how to break down a non-terminal is called a production rule.
A clause is valid as soon as the production rule matches its part of the input stream.

The syntax of a clause looks like:\\
\samp{
	[\textbf{"\#overload"}]? \textit{<clause\_specifier>} \textit{<preprocessing>} \textbf{"::="} \textit{<sequence>} [\textbf{'|'} \textit{<sequence>}]* \textbf{';'}\\
}\\
where:\\
\samp{
	\textit{<preprocessing>} ::= \textbf{"\#!ignore"} | \textbf{"\#ignore"} [\textbf{'('} \textit{<ignore-mode>} \textbf{')'}]? \textbf{';'}\\
	\textit{<ignore-mode>} ::= \textbf{"blanks"} | \textbf{"C++"} | \textbf{"JAVA"} | \textbf{"HTML"} | \textbf{"LaTeX"};
	\textit{<sequence>} ::= \textit{non-terminal} | \textit{terminal};
	\textit{<terminal>} ::= \textit{symbol of the language: a constant character or string}
}

\index{parsing!alternation}
A sequence is a set of terminals and non-terminals that must match the input stream, starting at the current position.
A production rule may propose alternatives: if a sequence doesn't match, the engine tries
the next one (the alternation symbol \textbf{'|'} separates the sequences).

A regular expression asks for reading tokens into the input stream. If tokens are put in sequence, one
behind the other, they are evaluated from the left to the right and all of them must match the
input stream. For example, \samp{"class" '\{'} is a sequence of 2 non-terminals, which requires that
the input stream first matches with \textit{"class"} and then is followed by \textit{'\{'}.

\index{\#overload}
Putting \samp{\textbf{\#overload}} just before the declaration of a production rule means that the
non-terminal was already defined and that it must be replaced by this new rule when called.
Example:\\
\texttt{
	\textit{nonterminal} ::= "bye";\\
	...\\
	\#overload \textit{nonterminal} ::= "bye" | "quit" | "exit";\\
}

Now, calling \textit{nonterminal} executes the second production rule. Use the directive \samp{\textbf{\#super}}
to call the overloaded clause. The precedent overloading might be written:\\
\texttt{
	...\\
	\#overload \textit{nonterminal} ::= \#super::\textit{nonterminal} | "quit" | "exit";\\
}

\samp{\#overload} takes an important place in the reuse of BNF scripts. A parser might be built
as reusing a scanner, where some non-terminals only have to be extended, for populating a parse
tree for instance.

\index{\#transformRules}
The statement \samp{\textbf{\#transformRules}} provides also a convenient way to reuse a BNF script.

It defines a rule that describes how to transform the header (left member) and the production
rule (right member) of a non-terminal declaration.

Example:\\
\texttt{
	INTEGER ::= \#ignore ['0'..'9']*;
}

\textit{INTEGER} is the header and \textit{\#ignore ['0'..'9']*} is the production rule.

During the compilation of a BNF parse script, before processing the declaration of a non-terminal,
the compiler checks whether a transforming rule validates the name of the non-terminal. If so,
both the header of the declaration and the production rule are translated, following the
directives of the rule.

The \textit{\#transformRules} statement must be put in the BNF script, before the production
rules to transform.

The syntax the statement \samp{\textbf{\#transformRules}} looks like:\\
\samp{
	\textit{transform-rules}	::= \textbf{"\#transformRules"} \textit{filter} \textit{header-transformation} \textit{prod-rule-transformation}\\
	\textit{filter} ::= \textit{expression}\\
	\textit{header-transformation} ::= \textbf{'{'} \textit{translation-script} \textbf{'}'}
	\textit{prod-rule-transformation} ::= \textbf{'{'} \textit{translation-script} \textbf{'}'}
}

The \textit{filter} is a boolean expression, applied on the name of the production rule.
The variable \textbf{x} contains the name of the production rule.

\textit{header-transformation} consists on a translation script, which describes how to
transform the header. If the block remains empty, the header doesn't change.

\textit{prod-rule-transformation} consists on a translation script, which describes how to
transform the production rule. If the block remains empty, the header doesn't change.

Example:

This example describes how to transform each production rule, whose name ends
with \samp{"expr"}.

\samp{or\_expr ::= and\_expr ["\&\&" and\_expr]*;}\\
becomes\\
\samp{or\_expr\textbf{(myExpr : node)} ::= and\_expr\textbf{(myExpr.left)} ["\&\&"\textbf{:myExpr.operator} and\_expr\textbf{(myExpr.right)}]*;}

The original production rules are just scanning the input, and the example shows
how to transform them for populating a node of the parse tree.

\texttt{
	\textbf{\#transformRules}\\
	\makebox[0.8cm][r]{}// The filter accepts production rules that have a name\\
	\makebox[0.8cm][r]{}// ending with \textit{"expr"} only.\\
	\makebox[0.8cm][r]{}// Note that the variable \textit{\textbf{x}} holds the name\\
	\makebox[0.8cm][r]{}// of the production rule.\\
	\makebox[0.8cm][r]{}\textbf{x}.endString("expr")\\
	\makebox[0.8cm][r]{}\\
	\makebox[0.8cm][r]{}\\ A script for transforming the header of the production rule:\\
	\makebox[0.8cm][r]{}\{\\
		\makebox[1.6cm][r]{}// By default, copies the input to the output\\
		\makebox[1.6cm][r]{}\#implicitCopy\\
		\makebox[1.6cm][r]{}// Writes the declaration of the parameter \textit{myExpr}\\
		\makebox[1.6cm][r]{}// after the non-terminal and copies the rest.\\
		\makebox[1.6cm][r]{}header ::= \#readIdentifier\\
			\makebox[2.4cm][r]{}=> \{@(myExpr : node)@\}\\
			\makebox[2.4cm][r]{}->\#empty;\\
	\makebox[0.8cm][r]{}\}\\
	\makebox[0.8cm][r]{}\\
	\makebox[0.8cm][r]{}\\ A script for transforming the production rule itself:\\
	\makebox[0.8cm][r]{}\{\\
		\makebox[1.6cm][r]{}\#implicitCopy\\
		\makebox[1.6cm][r]{}// - Pass the left member of the expression to populate,\\
		\makebox[1.6cm][r]{}// to the first non-terminal,\\
		\makebox[1.6cm][r]{}// - assign the operator to the expression,\\
		\makebox[1.6cm][r]{}// - Pass the right member of the expression to populate,\\
		\makebox[1.6cm][r]{}// to the first non-terminal.\\
		\makebox[1.6cm][r]{}// In any case, the rest of the production rule remains\\
		\makebox[1.6cm][r]{}// invariant.\\
		\makebox[1.6cm][r]{}prodrule ::= [\\
				\makebox[3.2cm][r]{}\#readIdentifier\\
				\makebox[3.2cm][r]{}=>\{@(myExpr.left)@\}\\
				\makebox[3.2cm][r]{}->[\\
					\makebox[4.0cm][r]{}"'" \#readChar "'" => \{@:myExpr.operator@\}\\
					\makebox[3.6cm][r]{}|\\
					\makebox[4.0cm][r]{}\#readCString => \{@:myExpr.operator@\}\\
				\makebox[3.2cm][r]{}]\\
				\makebox[3.2cm][r]{}\#readIdentifier\\
				\makebox[3.2cm][r]{}=>\{@(myExpr.right)@\}\\
			\makebox[2.4cm][r]{}]?\\
			\makebox[2.4cm][r]{}]->\#empty;\\
	\makebox[0.8cm][r]{}\}
}

\pdfsubsection{BNF tokens}

Below are described all BNF tokens that \CodeWorker\ recognizes:
\begin{itemize}
	\item \pdflabel{BNF constant string} \index{BNF token!constant string} a \textit{constant string}:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{A C-like string, written between double quotes and that
				admits escape sequences:\\
				\samp{"\textit{C-like\_string}"}\\}
			\lineii{\textbf{Matching}}{The token \samp{"\textit{C-like\_string}"} is valid if
				it matches the sequence of characters that starts at the current position of
				the input stream. And then, the position moves just after the string.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readIfEqualTo("\textit{C-like\_string}")}\\}
			\lineii{\textbf{Example}}{\samp{"bottle"} means that the sequence of 6 characters
				that starts at the current position of the input stream must match with
				\textit{bottle}.}
		\end{tableii}
	\item \pdflabel{BNF constant character} \index{BNF token!constant character} a \textit{constant character}:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{A C-like character, written between single quotes and that
				admits escape sequences:\\
				\samp{'\textit{C-like\_char}'}\\}
			\lineii{\textbf{Matching}}{The token \samp{"\textit{C-like\_char}"} is valid if
				it matches the character that stands at the current position of
				the input stream. And then, the position moves to the next character.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readIfEqualTo("\textit{C-like\_char}")}\\}
			\lineii{\textbf{Example}}{\samp{'('} means that the current character of the
				input stream must be an opening parenthesis.}
		\end{tableii}
	\item \pdflabel{BNF range of characters} \index{BNF token!range of characters} an \textit{range of characters}:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Two C-like characters, written between single quotes,
				which admit escape sequences, and separated by \textbf{..}:\\
				\samp{'\textit{lower\_char\_boundary}'\textbf{..}'\textit{upper\_char\_boundary}'}\\}
			\lineii{\textbf{Matching}}{The token \samp{'\textit{lower\_char\_boundary}'\textbf{..}'\textit{upper\_char\_boundary}'}
				is valid if the character that stands at the current position of the input
				stream is comprise between the two boundaries (included). And then, the
				position moves to the next character.\\
				Note that \samp{'\textit{lower\_char\_boundary}'} must be smaller than
				\samp{'\textit{upper\_char\_boundary}'} considering the ASCII order.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to the boolean expression:\\
				\texttt{
					(peekChar() >= "\textit{lower\_char\_boundary}") \&\&
					(peekChar() <= "\textit{upper\_char\_boundary}") \&\&
					readChar()}\\}
			\lineii{\textbf{Example}}{\samp{'a'..'z'} means that the current character of the
				input stream must be a lower case letter with no accent.}
		\end{tableii}
	\item \pdflabel{BNF complementary} \index{BNF token!complementary} the \textit{complementary} of an expression:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{An expression preceded by the symbol \textbf{$\hat{}$} or \textbf{\~{}}:\\
				\samp{\textbf{$\hat{}$}\textit{expression}} or \samp{\textbf{\~}\textit{expression}}\\}
			\lineii{\textbf{Matching}}{The token is valid when the expression failed to match
				the input stream at the current position. And then, position of the input
				stream moves to the next character.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to the function:\\
				\texttt{function validateThisSpecialComplementary() \{\\
						\makebox[0.8cm][r]{}local iLocation = getInputLocation();\\
						\makebox[0.8cm][r]{}if /*evaluate the expression*/ \{\\
						\makebox[1.6cm][r]{}	setInputLocation(iLocation);\\
						\makebox[1.6cm][r]{}	return false;\\
						\makebox[0.8cm][r]{}\} else readChar();\\
						\makebox[0.8cm][r]{}return true;\\
					\}}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\~}"bottle"} means that the 6 next characters of the
				input stream must be different from \textit{bottle}. If so, the position of
				the input stream moves to the next character.}
		\end{tableii}
	\item \pdflabel{BNF negation} \index{BNF token!negation} the \textit{negation} of an expression:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{An expression preceded by the symbol \textbf{'!'}:\\
				\samp{\textbf{!}\textit{expression}}\\}
			\lineii{\textbf{Matching}}{The token is valid when the expression failed to match
				the input stream at the current position. On the contrary of the complementary,
				the position of the input stream \textbf{doesn't move} to the next character.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to the function:\\
				\texttt{function validateThisSpecialNegation() \{\\
						\makebox[0.8cm][r]{}local iLocation = getInputLocation();\\
						\makebox[0.8cm][r]{}if /*evaluate the expression*/ \{\\
						\makebox[1.6cm][r]{}	setInputLocation(iLocation);\\
						\makebox[1.6cm][r]{}	return false;\\
						\makebox[0.8cm][r]{}\}\\
						\makebox[0.8cm][r]{}return true;\\
					\}}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{!}"bottle"} means that the 6 next characters of the
				input stream must be different from \textit{bottle}.}
		\end{tableii}
	\item \pdflabel{BNF reading a character} \index{BNF token!reading a character} \index{\#readChar} reading a character:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readChar} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readChar}\\}
			\lineii{\textbf{Matching}}{If the end of the input stream hasn't been reached yet,
				the token is valid and the position of the input stream points to the next
				character.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readChar()}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readChar} means that the position points
				to the next character if the end of the input stream hasn't been reached yet.}
		\end{tableii}
	\item \pdflabel{BNF reading a byte} \index{BNF token!reading a byte} \index{\#readByte} reading a byte:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readByte} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readByte}\\}
			\lineii{\textbf{Matching}}{If the end of the input stream hasn't been reached yet,
				the token is valid and the position of the input stream points to the next
				character/byte. It scans a byte, which is converted to a 2-hexadecimal digits.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readByte()}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readByte}:sByte means that the position points
				to the next character if the end of the input stream hasn't been reached yet and, if
				the byte \textit{0x0F} was at the current position, the variable \textit{sByte}
				is worth \textit{"0F"}.}
		\end{tableii}
	\item \pdflabel{BNF reading a sequence of bytes} \index{BNF token!reading some bytes} \index{\#readBytes} reading a sequence of bytes:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readBytes} preceded by the symbol \textbf{'\#'},\\
				and followed by an expression, whose result is a positive integer that
				specifies how many bytes have to be scanned:\\
				\samp{\textbf{\#}readBytes\textbf{(}\textit{integer-expression}\textbf{)}}\\}
			\lineii{\textbf{Matching}}{If the end of the input stream hasn't been reached yet,
				the token is valid and the position of the input stream points after the next \textit{integer-expression}
				bytes. It scans \samp{\textit{N}} bytes (\samp{\textit{N}} resulting of the evaluation of \samp{\textit{integer-expression}}),
				which are converted to a  sequence of 2-hexadecimal digits.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readBytes(\textit{N})}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readBytes\textbf{(}\textit{4}\textbf{)}:sBytes} means that the position points
				to the next four bytes if the end of the input stream hasn't been reached yet.
				If the sequence of bytes \textit{0x0F0E0D0C} was at the current position, the variable \textit{sBytes}
				is worth \textit{"0F0E0D0C"}.}
		\end{tableii}
	\item \pdflabel{BNF reading a sequence of characters} \index{BNF token!reading some chars} \index{\#readChars} reading a sequence of characters:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readChars} preceded by the symbol \textbf{'\#'},\\
				and followed by an expression, whose result is a positive integer that
				specifies how many characters have to be scanned:\\
				\samp{\textbf{\#}readChars\textbf{(}\textit{integer-expression}\textbf{)}}\\}
			\lineii{\textbf{Matching}}{If the end of the input stream hasn't been reached yet,
				the token is valid and the position of the input stream points after the next \textit{integer-expression}
				characters. It scans \samp{\textit{N}} characters, \samp{\textit{N}} resulting of the evaluation of \samp{\textit{integer-expression}}).\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readChars(\textit{N})}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readChars\textbf{(}\textit{4}\textbf{)}:sChars} means that the position points
				to the next four characters if the end of the input stream hasn't been reached yet.
				If the sequence of characters \textit{"cats and dogs"} was at the current position, the variable \textit{sChars}
				is worth \textit{"cats"}.}
		\end{tableii}
	\item \pdflabel{BNF reading a constant char} \index{BNF token!reading a C-like constant char} \index{\#readCChar} reading a C-like constant character:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readCChar} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readCChar}\\}
			\lineii{\textbf{Matching}}{
				The non-terminal BNF symbol \samp{\#readCChar} reads a C-like constant character. In case of assignement
				of the scanned value to a variable, only the constant character is returned, without the single quotes.
				A C-like character stands between single quotes and admits the escape character
				\textbf{$\backslash$}.\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readCChar:\textit{sValue1} \textbf{\#}readCChar:\textit{sValue2}}
				applied to \textit{'A''$\backslash$n'} will move the
				position of the input stream after the second trailing single quote. The variable
				\textit{sValue1} will contain the letter \samp{A} and \textit{sValue2} will contain the \textit{newline} characters.}
		\end{tableii}
	\item \pdflabel{BNF reading a string} \index{BNF token!reading C-like string} \index{\#readCString} reading a C-like string:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readCString} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readCString}\\}
			\lineii{\textbf{Matching}}{The token is valid if the character that stands at the
				current position of the input stream is a double quote (\textbf{"}) and that
				if all following characters up to the trailing double quote are recognized as
				C-like characters (meaning also that the escape sequences are as presented for
				the function \samp{composeCLikeString()} \ref{composeCLikeString()}).\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readString(\textit{sString})}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readCString:\textit{sValue}} applied to
				\textit{"Popeye's village$\backslash$nOlive hates spinash"} will move the
				position of the input stream after the trailing double quote. The variable
				\textit{sValue} will contain the string without double quotes and such as
				the escape sequences are converted to their ASCII representation.}
		\end{tableii}
	\item \pdflabel{BNF reading an identifier} \index{BNF token!reading an identifier} \index{\#readIdentifier} reading an identifier:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readIdentifier} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readIdentifier}\\}
			\lineii{\textbf{Matching}}{The token is valid if the characters that stand
				starting at the current position of the input stream match the following
				BNF sequence:\\
				\samp{\#!ignore ['a'..'z'|'A'..'Z'|'_'] ['a'..'z'|'A'..'Z'|'_'|'0'..'9']*}//}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readIdentifier()}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readIdentifier} applied to
				\textit{mushroom12,carpet} will move the position of the input stream on
				the comma after reading \textit{mushroom12}.}
		\end{tableii}
	\item \pdflabel{BNF reading insignificant characters} \index{BNF token!reading insignificant chars} \index{\#skipIgnore} reading insignificant characters:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{\samp{\textbf{"\#skipIgnore"} [\textbf{'('} \textit{<ignore-mode>} \textbf{')'}]?}\\
				where \textit{<ignore-mode>} specifies what is an insignificant character (see \samp{\#ignore}).\\}
			\lineii{\textbf{Matching}}{It reads insignificant characters, such as blanks and
				comments, as specified via the BNF directive \samp{\#ignore(...)}. this BNF
				directive is always valid, even if the parsing has already reached the end
				of file or if there are no insignificant characters.//}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{skipIgnore()}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}skipIgnore} applied to
				\textit{/*mushroom12,carpet*/.fish} will move the position of the input stream on
				the dot before \textit{fish} (if \samp{\#ignore(C++) was set before, for instance}).}
		\end{tableii}
	\item \pdflabel{BNF reading up to the first insignificant character} \index{BNF token!reading significant chars} \index{\#readUptoIgnore} reading up to the first insignificant characters:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{\samp{\textbf{"\#readUptoIgnore"} [\textbf{'('} \textit{<ignore-mode>} \textbf{')'}]?}\\
				where \textit{<ignore-mode>} specifies what is an insignificant character (see \samp{\#ignore}).\\}
			\lineii{\textbf{Matching}}{It reads all significant characters, up to encountering a whitespace or
				a comment, which style was specified via the BNF directive \samp{\#ignore(...)}. this BNF
				directive is valid if it reads at least one significant character.//}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readUptoIgnore \textbf{\#}readUptoIgnore} applied to
				\textit{mushroom12/*comment*/carpet fish} will read \textit{"mushroom12"} (first directive) and
				\textit{"carpet"} (second call) before moving the position of the input stream on
				the whitespace that stands before \textit{fish} (if \samp{\#ignore(C++) was set before, for instance}).}
		\end{tableii}
	\item \pdflabel{BNF reading an integer} \index{BNF token!reading an integer} \index{\#readInteger} reading an integer:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readInteger} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readInteger}\\}
			\lineii{\textbf{Matching}}{The token is valid if the characters that stand
				starting at the current position of the input stream match the following
				BNF sequence:\\
				\samp{\#!ignore ['-']? ['0'..'9']+}//}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readInteger(sInteger)}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readInteger} applied to
				\textit{12.34} will move the position of the input stream on
				the dot after reading \textit{12}.}
		\end{tableii}
	\item \pdflabel{BNF reading a numeric} \index{BNF token!reading a numeric} \index{\#readNumeric} reading a numeric:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readNumeric} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}readNumeric}\\}
			\lineii{\textbf{Matching}}{The token is valid if the characters that stand
				starting at the current position of the input stream match the following
				BNF sequence:\\
				\samp{\#!ignore [\#readInteger ['.' ['0'..'9']*]? | '.' ['0'..'9']*] [['e' | 'E'] ['+' | '-']? ['0'..'9']+]?}//}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readNumber(sNumber)}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readNumeric} applied to
				\textit{12.34E+3mushrooms} will move the position of the input stream at the
				beginning of \textit{mushrooms}.}
		\end{tableii}
	\item \pdflabel{BNF reading the evaluation of an expression} \index{BNF token!reading the evaluation of an expression} \index{\#readText} matching the result of a classical string expression:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{readText} preceded by the symbol
				\textbf{'\#'}, and followed by the classical string expression to match,
				between parenthesis:\\
				\samp{\textbf{\#}readText(\textit{classical-expression})}\\}
			\lineii{\textbf{Matching}}{The token is valid if the classical expression matches the
				input stream at the current position. If so, the position moves just after
				the expression that matched.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{readIfEqualTo(\textit{classical-expression})}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}readText(sName)} where \textit{sName = "horse"}
				means that the next 5 characters encountered to the input stream at the current
				position must match \textit{"horse"}, which is the result of the evaluation
				of the expression.}
		\end{tableii}
		\textit{Classical string expression} is seen in opposite of \textit{expressions of tokens},
		as being a classical expression of the scripting language (concatenation, call of
		functions, reference to variables, ...) and not a combination of tokens.
	\item \pdflabel{BNF checking the validity of an expression} \index{BNF token!checking the validity of an expression} \index{\#check} checking the validity of a classical string expression:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{check} preceded by the symbol
				\textbf{'\#'}, and followed by the classical string expression to check,
				between parenthesis:\\
				\samp{\textbf{\#}check(\textit{classical-expression})}\\}
			\lineii{\textbf{Matching}}{The token is valid if the classical expression returns
				a populated string. The position of the input stream is never impacted by this
				clause.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{if \textit{classical-expression} // call the rest of the sequence}}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}check(\textit{sID == "struct"}) '\{' [attribute]* '\}'}
				means that if \textit{sID} is equal to \textit{"struct"}, we try to match the
				reading of attributes embedded between braces. The checking has no effect on the
				current position of the input stream.}
		\end{tableii}
		\textit{Classical string expression} is seen in opposite of \textit{expressions of tokens},
		as being a classical expression of the scripting language (concatenation, call of
		functions, reference to variables, ...) and not a combination of tokens.
	\item \pdflabel{BNF end of file} \index{BNF token!end of file} \index{\#empty} checking whether the end of the stream has been reached or not:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{Keyword \samp{empty} preceded by the symbol \textbf{'\#'}:\\
				\samp{\textbf{\#}empty}\\}
			\lineii{\textbf{Matching}}{The token is valid if the position of the input stream
				points to the end.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to the function:\\
				\texttt{function validateEndOfFile() \{\\
						\makebox[0.8cm][r]{}if readChar() \{\\
						\makebox[1.6cm][r]{}	goBack();\\
						\makebox[1.6cm][r]{}	return false;\\
						\makebox[0.8cm][r]{}\}\\
						\makebox[0.8cm][r]{}return true;\\
					\}}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{\#}empty} is valid if the end of the
				input stream has been reached.}
		\end{tableii}
	\item \pdflabel{BNF repeating a token} \index{BNF token!repeating a token} repeating an expression:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax/matching}}{The expression is put between brackets and followed by
				symbols that determine the multiplicity:
				\begin{itemize}
					\item \samp{\textbf{[}\textit{expression}\textbf{]}}: the expression must
						match the input stream once (and perhaps more, but it isn't checked);
						in fact, it is used to impose the priority of token evaluation (for
						adding the \samp{\textbf{'|'}} operator to ask for a \textit{'OR'}),
					\item \samp{\textbf{[}\textit{expression}\textbf{]?}}: the expression may
						be absent or present once (and perhaps more, but it isn't checked);
						this token is always \samp{true},
					\item \samp{\textbf{[}\textit{expression}\textbf{]*}}: the expression may
						be absent or matches as long as possible; this token is always \samp{true},
					\item \samp{\textbf{[}\textit{expression}\textbf{]+}}: the expression must
						match at least once and as long as possible; it is equivalent to the
						sequence \samp{\textbf{[}\textit{expression}\textbf{]}} \samp{\textbf{[}\textit{expression}\textbf{]*}}
					\item \samp{\textbf{[}\textit{expression}\textbf{]}\textit{iterations}}:
						the expression must be repeated \textit{iterations} times (and perhaps
						more, but it isn't checked),
					\item \samp{\textbf{[}\textit{expression}\textbf{]}\textit{begin}..\textit{end}}:
						the expression must be repeated a number of times included in the range
						[\textit{begin}, \textit{end}] (and perhaps more than \textit{end},
						but it isn't checked); boundaries are constant integers,
					\item \samp{\textbf{[}\textit{expression}\textbf{]}\textit{begin}..\textbf{*}}:
						the expression must be repeated at least \textit{begin} times and as
						long as possible, \textit{begin} being a constant integer; note that the star might be replaced by \textbf{'n'},
					\item \index{\#repeat} \samp{\textbf{[}\textit{expression}\textbf{]\#repeat(}\textit{begin-expr}\textbf{)}}:
						the expression must be repeated \textit{begin-expr} times exactly; \textit{begin-expr}
						is an arithmetic expression evaluated just before processing the regular
						expression, and returning a positive integer,
					\item \samp{\textbf{[}\textit{expression}\textbf{]\#repeat(}\textit{begin-expr}\textbf{, }\textit{end-expr}\textbf{)}}:
						the expression must be repeated at least \textit{begin-expr} times but not more
						than \textit{end-expr} times (could be more, but not checked);
						\textit{begin-expr} and \textit{end-expr} are arithmetic expressions
						evaluated just before processing the regular expression;
						they both return a positive integer,
				\end{itemize}}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to do a loop, controlling
				the iterations according to the required multiplicity, and returning
				\samp{true} or \samp{false}.\\}
		\end{tableii}
	\item \pdflabel{BNF finding a token} \index{BNF token!finding a token} \index{->} finding the next occurrence of a given BNF expression:

			\textbf{Common syntax:} \samp{\textbf{->}\textit{BNF-expression}}

			\textbf{Matching:} The token is valid if the \textit{BNF expression} is found
				somewhere into the input stream. The, the cursor jumps to the end of the sub sentence scanned by the \textit{BNF expression}.

				The BNF operator \samp{\textbf{'->'}} admits a syntax extension, for the adjustment of its internal
				mechanism.

				\samp{\textbf{->}\textit{A}} jumps just after the the first matching of \textit{A} in the sentence.
				It processes the equivalent piece of \textit{extended-BNF} script:\\
				\texttt{
					=> local iLocation;\\
					\textbf{\~[}\textit{A} => iLocation = getInputLocation();\textbf{]*}\\
					=> setInputLocation(iLocation);\\
				}

				To intervene on the boundaries of the repeated sequence \samp{\textbf{[}\textit{A} ...\textbf{]*}},
				an extension was added to the syntax: \samp{\textbf{->}\textit{boundaries} A}, where
				\textit{boundaries} gives the multiplicity of the bracketed sequence (\samp{'?'}, \samp{'+'},
				 \samp{'2..*'}, \samp{\#repeat(iBegin, iEnd)} ...).\\
				Note: the boundaries must be declared just after the arrow.

				The text covered by \samp{\textbf{->}\textit{A}} includes the unmatched characters plus the sub sentence
				scanned by \textit{A}, so \samp{\textbf{->}\textit{A}\textbf{:}\textit{v}} assigns the complete
				covered text to the variable \textit{v}. This is sometimes a drawback: perhaps do you want to take
				the unmatched character or the sub sentence scanned by \textit{A}.\\
				So now, you can specify the variables intended to receive these intermediate values:\\
				\samp{\textbf{->(:}\textit{varBefore} \textbf{-:}\textit{varAfter}\textbf{)}\textit{A}\textbf{:}\textit{varTotal}}\\
				Note: the intermediate variables are declared just before the BNF symbol \textit{A}, after the boundaries if any.

				\textbf{Example:}\\
				We will apply \samp{\textbf{[->(:}\textit{varBefore} \textbf{-:}\textit{varAfter}\textbf{)} \#readNumeric\textbf{]:}\textit{varTotal}}
				on the sentence \samp{"Garfield.laziness 99.99 percent"}:
				\begin{itemize}
					\item \textit{varBefore} = "Garfield.laziness "
					\item \textit{varAfter} = "99.99"
					\item \textit{varTotal} = "Garfield.laziness 99.99"
				\end{itemize}

				The last extension brought to the jump operator \samp{\textbf{->}\textit{A}}
				is to allow the execution of a BNF sequence at the beginning of the sub sequence
				 matched by \textit{A}. This BNF sequence is declared into the parenthesis used
				for the intermediate variables, behind these variables, if any:\\
				\samp{\textbf{->(:}\textit{varBefore} \textbf{-:}\textit{varAfter}\textbf{ \textit{B})}\textit{A}}

				The advantage of infiltrating the BNF sequence \textit{B} is that the intermediate variables
				are populated, and that the cursor doesn't point after the matching of \textit{A} yet,
				but at the beginning of the sub sentence matched by \textit{A}.

			\textbf{Procedural way:} This BNF token is equivalent to the function:\\
				\texttt{function validateFindToken() \{\\
						\makebox[0.8cm][r]{}local bSuccess;\\
						\makebox[0.8cm][r]{}do \{\\
						\makebox[1.6cm][r]{}	set bSuccess = // \textit{expression} is expanded here;\\
						\makebox[1.6cm][r]{}\} while !bSuccess \&\& readChar();\\
						\makebox[0.8cm][r]{}return bSuccess;\\
					\}
				}

			\textbf{Example:} \samp{\textbf{->}"C"} matches the stream \textit{"ABCD"} and the
				cursor in the input stream points to \textit{'D'}.
	\item \pdflabel{BNF restricting the sentence} \index{BNF token!restricting the sentence} \index{\pipesup} restricting the scan to a \textit{sub sentence}.

		The sequence \samp{\textit{A} \textbf{|>} \textit{B}} is understood as considering
		the \textit{sub sentence} scanned by \samp{\textit{A}}, which delimits the portion of text left
		visible to \samp{\textit{B}}. \samp{\textit{B}} starts scanning at the beginning of
		the \textit{sub sentence} covered by \samp{\textit{A}} and cannot go beyond.
		
		Once the operator has achieved with success, the cursor points to the end of the
		\textit{sub sentence} covered by \samp{\textit{A}}.
		
		You'll find below the different steps processed by the operator:
		\begin{itemize}
			\item the BNF literal \samp{\textit{A}} is executed,
			\item if success, the cursor comes back to the beginning of the sub sentence covered by \samp{\textit{A}}
			\item then, \samp{\textit{B}} is executed, knowing that the operator forces the
				end of the \textit{sub sentence} where \samp{\textit{A}} had finished,
			\item if success, the cursor points to the end of \samp{\textit{A}}, even if
				\samp{\textit{B}} hadn't scan up to the end of the sentence.
		\end{itemize}
		
		\textbf{Example:}

		We want to recognize all colons present on a line. The \textit{sub sentence} we would like
		to scan is a line: \samp{\textbf{->}'$\backslash$n'}. Recognizing colons is like: \samp{\textbf{[->}':'\textbf{]*}},
		which asks for jumping from a colon to another, without considering the end of line.\\
		\samp{\textbf{->}'$\backslash$n'\textbf{ |> [->}':'\textbf{]*}} restricts the colon recognition
		to the line.
	\item \pdflabel{BNF calling a clause} \index{BNF token!calling a clause} calling a clause to match its rules:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{The name of the clause to match and, if any, the expected
				parameters between parenthesis separated by commas:\\
				\samp{\textit{clause-name}} or
				\samp{\textit{clause-name}\textbf{(}\textit{P1}\textbf{,} ...\textit{Pn}\textbf{)}}\\}
			\lineii{\textbf{Matching}}{The token is valid if the clause matches at the current
				position of the input stream.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to the function:\\
				\texttt{function validateClause() \{\\
						\makebox[0.8cm][r]{}return /*matching of rules of the clause*/;\\
					\}}\\}
			\lineii{\textbf{Example}}{\samp{\textit{INTEGER} \textbf{'.'} INTEGER} with
				\samp{\textit{INTEGER} ::= ['0'..'9']+} means that the clause must match at least
				one digit into the input stream, and be followed by a dot and then by another
				positive integer.}
		\end{tableii}
	\item \pdflabel{BNF the OR operator} \index{BNF token!the OR operator} offering a choice between 2 sequences of BNF tokens:
		\begin{tableii}{l|l}{.8}{Heading}{Description}
			\lineii{\textbf{Syntax}}{The 2 expressions are separated by the symbol \textbf{'|'}:\\
				\samp{\textit{sequence1} \textbf{|} \textit{sequence2}}\\}
			\lineii{\textbf{Matching}}{The token is valid if the clause matches one of the two
				sequences at the current position of the input stream.\\}
			\lineii{\textbf{Procedural way}}{This BNF token is equivalent to:\\
				\texttt{/*evaluate \textit{sequence1}*/ || /*evaluate \textit{sequence2}*/}\\}
			\lineii{\textbf{Example}}{\samp{\textbf{"class"} \textit{IDENT} \textbf{'\{'} | \textbf{"interface"} \textit{IDENT} \textbf{';'}} with
				\samp{\textit{IDENT} ::= ['a'..'z' | 'A'..'Z']+} means that the clause must match at least
				one digit into the input stream, and be followed by a dot and then by another
				positive integer.}
		\end{tableii}
\end{itemize}

\pdflabel{preprocessing of a clause}
\index{BNF!preprocessing of a clause}
\pdfsubsection{Preprocessing of a clause}

If no processing has been specified to a clause, characters will be ignored into the input stream, following the
instruction of the \textit{ignore} mode (determined by the predefined clause \samp{\#ignore}),
just before running the clause.

Sometimes, it arrives that the \textit{ignore} mode should change before calling the clause.
Let's imagine that C++ comments and blanks are ignored, except at some places where a line-comment
is expected, holding a description. If the clause that matches the line-comment is called
\samp{description}, each time a description has to be read, the following sequence must be written:\\
\texttt{\#ignore(blanks) \textit{description}:sDescription \#ignore(C++)}

Thanks to the preprocessing of clause, it is possible to require a specific \textit{ignore} mode
while calling a clause. For example:\\
\texttt{\textit{description} \textbf{\#ignore(}blanks\textbf{)} ::= "//" \#!ignore [\~{}['$\backslash$r' | '$\backslash$n']]*:description;}

On our example, each time a description has to be read, calling the clause \textit{description}
is naturally reduced to:\\
\texttt{\textit{description}:sDescription}

\pdflabel{operator '=>'}
\index{BNF!operator =>}
\pdfsubsection{Inserting instructions of the scripting language}

Instruction of the scripting language may be inserted into a sequence of tokens, and are considered
as valid, except when the controlling sequence is interrupted by the \samp{break} statement.
These instructions doesn't apply a matching on the input stream, but they serve generally to
check the consistence of data and to populate the parse tree. They are announced by the
symbol \textbf{'=>'}:\\
\samp{\textbf{"=>"} \textit{instruction} \textbf{';'}} or\\
\samp{\textbf{"=>"} \textit{compound-statement}} where a \textit{compound-statement} is a block
of instructions between braces.

\textbf{Example:}

\texttt{class_declaration(myClass : node) ::=\\
\makebox[0.8cm][r]{}"class" IDENT:myClass.name\\
\makebox[0.8cm][r]{}	\textit{=> traceLine("name = '" + myClass.name + "'")\textbf{;}}\\
\makebox[0.8cm][r]{}	[\\
\makebox[1.2cm][r]{}		':' IDENT:sParent\\
\makebox[1.2cm][r]{}		\textit{=> \{\\
\makebox[1.6cm][r]{}			if !findElement(sParent, listOfClasses)\\
\makebox[2.0cm][r]{}				error("class '" + sParent + "' hasn't been declared yet!");\\
\makebox[1.6cm][r]{}			ref myClass.parent = listOfClasses[sParent];\\
\makebox[1.2cm][r]{}		\}}\\
\makebox[0.8cm][r]{}	]?\\
\makebox[0.8cm][r]{}	'\{' ...}

The first swapping to the scripting language is just an instruction to trace, which must end
with a semi-colon and that isn't the end of the clause! The second swapping to the script
language implements a little more work that is put between braces.

Be careful about declaration of local variables. If you declare a variable into a compound
statement, it disappears once the controlling sequence leaves the scope. To declare a variable
local to the clause, you can do:\\
\samp{...\\
	  => local myVariable;\\
	  ...}

\pdfsubsection{Common properties of BNF tokens}

\pdflabel{BNF assigning a variable} \index{BNF token!assigning a variable} The sequence of characters that a BNF token has matched may be assigned to a variable. Then
the variable may follow the token, separated by a colon:\\
\samp{\textit{token} \textbf{':'} \textit{variable\_name}}

\textbf{Example:}

\texttt{IDENT : sName} (where \samp{\textit{IDENT} ::= ['a'..'z' | 'A'..'Z']+}) means that
if the clause \textit{IDENT} is valid, the identifier matching the BNF token is assigned to
\textit{sName}. Be careful that if the variable doesn't exist, it is pushed into the stack,
on the contrary of a classic \CodeWorker\ script that asks for declaring explicitly a local
variable.

You can also specify to concatenate the text covered by the BNF token, to the ancient value of the variable:\\
\samp{\textit{B}\textbf{:+}\textit{v}}.

\textbf{Example:}\\
If \textit{v} is worth \samp{\"nebula:\"} and if the sentence starts with \textit{\"Orion.\"},
then \textit{v} becomes \samp{\"nebula:Orion\"} after the resolution of:\\
\samp{\#readIdentifier\textbf{:+}\textit{v}}

\pdflabel{BNF checking a matched expression} \index{BNF token!checking a matched expression} The sequence of characters that a BNF token has matched may be worth a constant or may belong
to a set of values. Then, the constant or the set of values is following the token, separated
by a colon, as for variables:\\
\samp{\textit{token} \textbf{':'} \textit{constant\_value} [\textbf{':'} \textit{variable\_name}]} or\\
\samp{\textit{token} \textbf{':' '\{'} \textit{values\_of\_the\_set} \textbf{'\}'}\textbf{':'} \textit{variable\_name}} where\\
\samp{\textit{values\_of\_the\_set} ::= \textit{constant\_value} [\textbf{','} \textit{constant\_value}]*}

\textbf{Examples:}
\begin{itemize}
	\item \texttt{IDENT : {"class", "interface"}} (where \samp{\textit{IDENT} ::= ['a'..'z' | 'A'..'Z']+})
		means that the identifier must be worth \samp{"class"} or \samp{"interface"}. It isn't
		equivalent to \samp{["class" | "interface"]}, because this new clause matches the
		beginning of \samp{"class\textit{ify}"} or \samp{"interface\textit{s}"} and that's not
		what is expected.
	\item \texttt{\#readString : {"tea spoon", "fork"} : \textit{sSilverware}}
		means that the string must be worth \samp{"tea spoon"} or \samp{"fork"} and that the
		parsed value will be assigned to the variable called \textit{sSilverware}.
\end{itemize}

\index{BNF directives}
\pdflabel{BNF directives}
\pdfsubsection{BNF directives}

Some directives are available:
\begin{itemize}
	\item \index{BNF directives!\#appendedFile} \index{\#appendedFile} \samp{\textbf{\#}appendedFile(\textit{classical-expression})}: this directive is valid
		only for \textit{pattern} and \textit{translation} scripts. The directive is put into a sequence of tokens and will
		be applied on the rest of the sequence: the \textit{classical-expression} is evaluated
		and gives the name of an output file, which becomes the new output stream where code
		generation will be processed, such as text is appended to the output file.
	\item \pdflabel{BNF break} \index{BNF directives!\#break} \index{\#break} \samp{\textbf{\#}break}:
		this directive is put in a repeat token, ending a sequence of tokens.
		It leaves successfully the closer \textit{repeat token} into which the directive was put.

		\textbf{Example:}\\
		\texttt{\textbf{[}"---" \textbf{\#break} | attribute\textbf{]2,*}}

		Here, the engine reads at least one attribute, and leaves with success when it
		encounters the string \samp{"---"}. To succeed, the \samp{\#break} interruption cannot occur
		before the second iteration of this BNF sequence. Otherwise, the minus boundary isn't reached.

		Note that brackets with a multiplicity of \textbf{1} (brackets used as parenthesis for changing the
		priority of \textit{BNF sequence}\textbf{/}\textit{alternation} resolutions) propagate the
		\textbf{\samp{\#break}} interruption to the closer \textit{repeat token} it is inlayed in.
	\item \pdflabel{BNF continue} \index{BNF directives!\#continue} \index{\#continue} \samp{\textbf{\#}continue}:
		this directive is put into a sequence of tokens, and means that the rest of the token's
		sequence must match with the input stream. If not, an error is raised, giving the call
		stack and the position of the input stream where the mistake has occurred.

		\textbf{Example:}\\
		The following sentence is passed to the interpreter for scanning:\\
		\texttt{a -> b // we have forgotten the semi-comma!\\
				b -> c\textbf{;}}\\
		something that looks like state transitions for an automaton.

		Now, we write the corresponding BNF-parsing script:\\
		\texttt{\textit{TRANSITIONS}	::= [\textit{TRANSITION}]* \#empty => {traceLine("OK!");};\\
				\textit{TRANSITION}	::= \textit{STATE} \textbf{"->"} \textit{STATE} \textbf{';'};\\
				\textit{STATE}	::= \#readIdentifier;}\\
		You notice that the syntax reclaims a semi-comma to close a transition. So, the
		sentence shows a syntax error at the first line. The BNF script will fail applying
		the non-terminal \textit{TRANSITION}, so the scanning will stop before running
		the \samp{traceLine()} procedure. It fails silently: the head of the grammar doesn't
		match the sentence and that's all. The interpreter cannot guess that the failure is
		due to a semi-comma: the non-terminal \textit{TRANSITION} doesn't match, that's right,
		but perhaps that the caller (the non-terminal \textit{TRANSITIONS} here) proposes
		an alternative?

		To constraint the interpreter to raise a syntax error automatically, you have to employ the \samp{\#continue} keyword:\\
		\texttt{\textit{TRANSITION}	::= \textit{STATE} \textbf{"->"} \#continue \textit{STATE} \textbf{';'};}\\
		means that once the antecedent of a state transistion is detected, the rest of the
		production rule must be valid in any case. If the sequence following \samp{\#continue}
		(\samp{\textit{STATE} \textbf{';'}} here) fails, a detailed syntax error is thrown.
		Considering our sentence, the BNF script will raise a syntax error about the lacking
		semi-comma at the first line.

		Not using the directive \samp{\#continue} obliges you to write something like:\\
		\texttt{\textit{TRANSITION}	::= \textit{STATE} \textbf{"->"} /*syntax checking made by hand from here*/\\
			\makebox[2cm][l]{}[\textit{STATE} | \textbf{=> error(}"syntax error: STATE token expected"\textbf{)};]\\
			\makebox[2cm][l]{}[\textbf{';'} | \textbf{=> error(}"syntax error: ';' expected"\textbf{)};];}
	\item \pdflabel{BNF explicitCopy} \index{BNF directives!\#explicitCopy} \index{\#explicitCopy} \samp{\textbf{\#}explicitCopy}:
		this directive is available in a \textit{source-to-source translation} script and may be put:
			\begin{itemize}
				\item inside a sequence of tokens, meaning that the text scanned by the rest
					of the sequence won't be copied into the output stream automatically,
				\item outside the clauses, at the same level as their declaration, meaning
					that the entire input stream will be parsed without copying the scanned text
					into the output stream ; this is the default behavior,
			\end{itemize}
		If source code has to be put into the output stream, the developer must specify it explicitly
		between \textbf{'\arobas'} symbols in a compound statement announced by \textbf{=>}.
		See \samp{\#implicitCopy} to put the scanned text to the output stream automatically.
	\item \index{BNF directives!\#generatedFile} \index{\#generatedFile} \samp{\textbf{\#}generatedFile(\textit{classical-expression})}: this directive is valid
		only for \textit{pattern} and \textit{translation} scripts. The directive is put into a sequence of tokens and will
		be applied on the rest of the sequence: the \textit{classical-expression} is evaluated
		and gives the name of an output file, which becomes the new output stream where code
		generation will be processed. It allows changing the output file during the translation,
		to split it into a few files for example.
	\item \index{BNF directives!\#generatedString} \index{\#generatedString} \samp{\textbf{\#}generatedString(\textit{variable})}: this directive is valid
		only for \textit{template-based} and \textit{translation} scripts. The directive is put into a sequence of tokens and will
		be applied on the rest of the sequence: the output file is redirected into the string variable
		passed to the argument \textit{variable}, which becomes the new output stream where code
		generation will be processed.
		If you don't care about the result, you can pass \samp{null} instead of a string variable.
	\item \pdflabel{BNF ignore} \index{BNF directives!\#ignore} \index{\#ignore} \samp{\textbf{\#}ignore}:
		this directive is put into a sequence of tokens, and means that the rest of the token's
		sequence must ignore blanks and comments before evaluating tokens. It exists some
		different formats available:
		\begin{itemize}
			\item \samp{\textbf{\#}ignore}: it calls a clause implemented by the user, which
				is also named \samp{\textbf{\#}ignore} (see section \ref{BNF special clauses}),
			\item \samp{\textbf{\#}ignore(\textit{"constant-string"})}: it also calls a clause implemented
				by the user, but known as attached to a specific identifier. This custom ignore clause
				is named \samp{\textbf{\#}ignore[\textit{"constant-string"}]} (see section \ref{BNF special clauses}),
			\item \samp{\textbf{\#}ignore(blanks)}: it ignores blank characters (spaces, new lines,
				tabulations, carriage returns, ...), considered as having an ASCII code smaller
				than 32 but not null,
			\item \samp{\textbf{\#}ignore(C++)}: it ignores blank characters and C comments
				(\textbf{'/* ... */'}) and line comments (\textbf{'// ...'} up to the end of the line),
			\item \samp{\textbf{\#}ignore(HTML)}: it ignores blank characters and SGML comments
			(\textbf{'<!- - ... - ->'}),
			\item \samp{\textbf{\#}ignore(JAVA)}: it ignores blank characters and C comments
				(\textbf{'/* ... */'}) and line comments (\textbf{'// ...'} up to the end of the line),
			\item \samp{\textbf{\#}ignore(LaTeX)}: it ignores line comments that are start with
			the \textbf{'\%'} character, but not spaces or empty lines that have a signification,
		\end{itemize}
	\item \samp{\textbf{\#}!ignore}: this directive is put into a sequence of tokens, and
		means that the rest of the token's sequence will not ignore blanks or comments between
		tokens. It works recursively when evaluating a clause call. It is useful for reading
		a number literal for instance, where digits must be glued together.
	\item \pdflabel{BNF implicitCopy} \index{BNF directives!\#implicitCopy} \index{\#implicitCopy} \samp{\textbf{\#}implicitCopy}:
		this directive is available in a \textit{source-to-source translation} script and may be put:
			\begin{itemize}
				\item inside a sequence of tokens, meaning that the text scanned by the rest
					of the sequence is copied into the output stream automatically,
				\item outside the clauses, at the same level as their declaration, meaning
					that the entire input stream will be parsed and the scanned text will be
					copied into the output stream,
			\end{itemize}
		\samp{\#implicitCopy} means that the scanned text is copied to the output stream as
		long as the pattern matching succeeds. If a rule fails, the scanned text is removed
		from the output stream, up to the last valid token. This isn't the default behavior
		of a \textit{translation} mode. See \samp{\#explicitCopy} to switch this mode off.
	\item \index{BNF directives!\#insert} \index{\#insert} \samp{\textbf{\#}insert(\textit{variable}) \textit{sequence-of-BNF-instructions}}:
		the directive creates a new node \textit{variable} (if it doesn't exist yet) and executes
		the sequence of BNF instructions that follow. If the sequence fails and if the node was created
		by the directive, the \textit{variable} is removed.\\
		This directive is very useful while populating the parse tree, when some choices are
		proposed: either populate this node or another, or a branch...\\
		To write:
		\begin{verbatim}
			#insert(myNode) tryNewNode(myNode)
		\end{verbatim}
		is equivalent to:\\
		\begin{verbatim}
				=> local bCreated = !existVariable(myNode);
				=> if bCreated insert myNode;
				[
				        tryNewItem(myNode)
				    |
				        => if bCreated removeVariable(myNode);
				        #check(false)
				]
		\end{verbatim}
	\item \pdflabel{BNF matching} \index{BNF directives!\#matching} \index{\#matching} \samp{\textbf{\#}matching(\textit{variable})}:
		this directive is put outside the production rules. It informs the BNF engine to record the coverage of
		the input text by the production rules. Concretely, the BNF engine stores into a variable the list of all
		production rules of the grammar and all areas they match in the input text, once the execution has finished.
		The BNF engine populates the variable specified by the directive.
		
		%##markup##"file:Documentation/MatchingStructure.txt"
%##begin##"file:Documentation/MatchingStructure.txt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/MatchingStructure.txt":\\
	\makebox[1cm][r]{\textrm{\tiny     }} Tree structure of the variable populated by the BNF engine\\
	\makebox[1cm][r]{\textrm{\tiny     }} for \#matching(variable):\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} * variable\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.4cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.4cm][l]{}+- rules[]: list of production rules (signatures only),\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.4cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.4cm][l]{}+- areas[]: table of positions in the input text, the\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}|         key is worth the position P; no item value\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}+- begin[]: (optional) table for every rule starting\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}|  |       at the position P, the key being worth the\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}|  |       ending position Pf (decreasing order)\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}|  +- []: list of all rules matching [P, Pf] exactly,\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}|\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}+- end[]: (facultative) table for every rule ending at\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.2cm][l]{}|       the position P, the key being worth the\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.2cm][l]{}|       starting position Pi (increasing order)\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1.2cm][l]{}+- []: list of all rules matching [Pi, P] exactly,}

%##end##"file:Documentation/MatchingStructure.txt"

	\item \pdflabel{BNF moveAhead} \index{BNF directives!\#moveAhead} \index{\#moveAhead} \samp{\textbf{\#}moveAhead}:
		Located into a BNF sequence, it means that after a valid matching of the rest
		of the sequence, at least one character must have been consumed.

		Example:\\
		\texttt{\#moveAhead [A]? [B]?}

		If \samp{A} doesn't match the input file, then \samp{B} must match so that the scan has read at least one character.
	\item \pdflabel{BNF nextStep} \index{BNF directives!\#nextStep} \index{\#nextStep} \samp{\textbf{\#}nextStep}:
		this directive is put into BNF sequences inlayed in a BNF jump operator (\samp{\textbf{->}}) or in a
		BNF complementary operator (\textbf{$\hat{}$} or \textbf{\~{}}). Normally, these operators move the cursor of
		the input stream one position further, in case of failure while applying the BNF sequence.

		Using \samp{\textbf{\#nextStep}} allows changing the shift of the cursor to more than one character.
		It is very useful when you encounter to quoted strings or identifiers. For instance, if you are looking
		for constant strings and then number or identifiers, the following code is incorrect:\\
		\texttt{\textbf{->[}\#readCString \#readInteger \textbf{|} \#readIdentifier\textbf{]}}

		Why is it incorrect? If the constant string matches but not the integer, the next iteration will put the
		cursor just after the quote and will perhaps point to an identifier, embedded into the constant string.
		Then, the operator will match during the second iteration.

		In fact, if the constant string matches but not the rest of the BNF sequence, we want to
		force the next jump just after the constant string:\\
		\texttt{\textbf{->[}\#readCString \textbf{\#nextStep} \#readInteger \textbf{|} \#readIdentifier\textbf{]}}
	\item \pdflabel{BNF noCase} \index{BNF directives!\#noCase} \index{\#noCase} \samp{\textbf{\#}noCase}:
		this directive is put:
			\begin{itemize}
				\item inside a sequence of tokens, meaning that the rest of the sequence must
					match without taking into account the case of the letters,
				\item outside the clauses, at the same level of their declaration, meaning
					that the entire input stream will be parsed without taking into account
					the case of letters,
			\end{itemize}
	\item \index{BNF directives!\#parsedFile} \index{\#parsedFile} \samp{\textbf{\#}parsedFile(\textit{filename})}: this directive is valid
		only for \textit{parsing} and \textit{translation} scripts. The directive is put into
		a sequence of tokens and will be applied on the rest of the sequence: the input file
		is redirected into the file	passed to the argument \textit{filename}, which becomes
		the new input stream where scanning and parsing will be processed.
	\item \index{BNF directives!\#parsedString} \index{\#parsedString} \samp{\textbf{\#}parsedString(\textit{expression})}: this directive is valid
		only for \textit{parsing} and \textit{translation} scripts. The directive is put into
		a sequence of tokens and will be applied on the rest of the sequence: the input stream
		is redirected to the text resulting of the evaluation of the argument \textit{expression}, which becomes
		the new input stream where scanning and parsing will be processed.
	\item \index{BNF directives!\#pushItem} \index{\#pushItem} \samp{\textbf{\#}pushItem(\textit{variable}) \textit{sequence-of-BNF-instructions}}:
		the directive pushes a new item into the array of the node \textit{variable} and executes
		the sequence of BNF instructions that follow. If the sequence fails, the last element
		of the array \textit{variable} is removed.\\
		This directive is very useful while populating the parse tree, when some choices are
		proposed: either populate this array or another, or a branch...\\
		To write:\\
		\begin{verbatim}
			[#pushItem(list) tryNewItem(list#last)]+
		\end{verbatim}
		is equivalent to:\\
		\begin{verbatim}
				=> local bCreated = !existVariable(list);
				[
				        [
				            => pushItem(list);
				            tryNewItem(list#last)
				        ]+
				    |
				        => {
				            if bCreated removeVariable(list);
				            else removeLastElement(list);
				        }
				]
		\end{verbatim}
	\item \index{BNF directives!\#ratchet} \index{\#ratchet} \samp{\textbf{\#}ratchet}:
		When encountered in a production rule, the BNF engine memorizes what is the current position
		in the input stream, and then controls that the scan will never come back before this position.
	\item \index{BNF directives!\#super} \index{\#super} \samp{\textbf{\#}super \textbf{"::"} \textit{clause\_name}}:
		this directive applies to a non-terminal call, which was overloaded via the \samp{\#overload} keyword.
		The directive means that the underlying non-terminal must be called
		in place of the overloadee clause. If the non-terminal wasn't overloaded, an error
		is thrown.
	\item \pdflabel{BNF trace} \index{BNF directives!\#trace} \index{\#trace} \samp{\textbf{\#}trace}:
		this directive traces the resolution steps of the grammar. Hit a key to interrupt the display
		of trace information and to pause the controlling sequence.
	\item \index{BNF directives!\#try/\#catch} \index{\#try} \index{\#catch} \samp{\textbf{\#}try \textit{sequence-of-BNF-instructions} \textbf{\#}catch\textbf{(}\textit{variable}\textbf{)}}  \textit{sequence-of-BNF-instructions}:
		The \textit{try/catch} statement catches all error messages thrown from the
		embedded sequence.
		The error message is available in the variable passed to the \textit{catch} statement.
		If no error occurs, the flow of control continues on the sequence following the \textit{catch}.
		In case of error raising, the sequence breaks at the \textit{catch statement} in failure after
		populating the variable with the error message.\\
		\textbf{Example:}
		\begin{verbatim}
			#try
			non_terminal_call
			#catch(sError)
			=> traceLine("No trouble! There was no error thrown.");
			|
			=> traceLine("Error! Message = '" + sError + "'");
		\end{verbatim}
\end{itemize}

\pdflabel{BNF declaring a clause}
\index{BNF!declaring a clause}
\index{\#parameters}
\index{BNF!extending parameters}
\pdfsubsection{Declaring a clause}

We have seen that a clause may expect some arguments. Such a kind of clause conforms to the
syntax:\\
\samp{	\textit{clause\_specifier} ::= \textit{clause\_name} [\textit{parameters}]? [\textbf{':'} \textit{return\_type}]? \textbf{'::='} \textit{clause\_body}\\
		\textit{clause\_name} ::= \textit{identifier} [\textit{template\_resolution}]?;
		\textit{template\_resolution} ::= \textbf{'<'} [\textit{identifier} | \textit{constant_string}] \textbf{'>'};
		\textit{parameters} ::= \textbf{'('} \textit{parameter} [\textbf{','} \textit{parameter}]* \textbf{')'}\\
		\textit{parameter} ::= \textit{argument\_name} \textbf{':'} \textit{argument\_mode}\\
		\textit{argument\_mode} ::= \textbf{"value"} | [\textbf{"node"} | \textbf{"variable"}] | \textbf{"reference"}\\
		\textit{return\_type} ::= \textbf{"list"} | \textbf{"node"} | \textbf{"value"}\\
		\textit{clause\_body} ::= \textit{rule\_expression} \textbf{';'}}

\pdflabel{BNF argument mode} \index{BNF token!argument mode}
where the \textit{argument mode} means:
\begin{tableii}{l|l}{0.8}{Mode}{Description}
	\lineii{\samp{value}}{the parameter is passed by value to the clause, as for user-defined functions}
	\lineii{\samp{node} or \samp{variable}}{the parameter expects a tree node, as for user-defined functions}
	\lineii{\samp{reference}}{the parameter expects a reference to a variable, which allows
		changing the node pointed to by the variable, as for user-defined functions}
\end{tableii}

\textbf{Example:}

\texttt{attribute\_declaration(myAttribute : node, sClassName : value) ::= type\_specifier(myAttribute.type) IDENT:myAttribute.name;}

While reusing production rules from a scanner to build a parser, for example, the non-terminal
symbols of the parser need to pass a node intended to be fulfilled with parsing information,
or to contain some data about the context.

\pdflabel{BNF special clauses}
\index{BNF!special clauses}
It exists a special clause the user may have to define, named \samp{\textbf{\#}ignore}. It allows
the implementation of its own production rule for processing empty characters between tokens.

This clause doesn't expect any parameter:\\
\samp{\textbf{\#ignore} ::= ... /*the production rule of how to skip characters*/;}

To activate it in a production rule, type \samp{\textbf{\#ignore}} with no parameter.

In some cases, you might have to define more than one customized \textit{\#ignore} clause.
It is possible too, assigning a key to each new special clause while their implementation:\\
\samp{\textbf{\#ignore[}\textit{"the key"}\textbf{]} ::= ... /*the production rule of how to skip characters*/;}

To activate it in a production rule, type \samp{\textbf{\#ignore(}\textit{"the key"}\textbf{)}} with no parameter,
as you could have written \samp{\#ignore(C++)} for activating a predefined \textit{ignore mode}.

Note that these special clauses must figure at the beginning of the \textit{extended-BNF} script, before the
first appearance for activation in a production rule.

%--------------------------------------------------------------------------
\index{parsing!reading of tokens}
\index{scripts!reading of tokens}
\pdflabel{Reading tokens for parsing}
\pdfsection{Reading tokens for parsing}

The functions and procedures described below are available in a kind of parsing scripts: those
which read tokens in a procedural way, proposing a set of appropriate functions and
procedures. All examples that illustrate how to exploit them are applied on the floowing text to
parse:
%##markup##"file:Documentation/ParsingSample.txt"
%##begin##"file:Documentation/ParsingSample.txt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/ParsingSample.txt":\\
	\makebox[1cm][r]{\textrm{\tiny     }} identifier: \_potatoes41\$\\
	\makebox[1cm][r]{\textrm{\tiny     }} numbers: 42 23.45e6\\
	\makebox[1cm][r]{\textrm{\tiny     }} string: "a C-like string that accepts backslash-escape sequences"\\
	\makebox[1cm][r]{\textrm{\tiny     }} word: 1$\backslash$'ecurie\_1stable\\
	\makebox[1cm][r]{\textrm{\tiny     }} blanks: \\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1cm][l]{}"blanks are ignored"\\
	\makebox[1cm][r]{\textrm{\tiny     }} C++: /*comment*/\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1cm][l]{}// other comment\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1cm][l]{}"blanks and C++ comments are ignored"\\
	\makebox[1cm][r]{\textrm{\tiny     }} HTML: <!--comment-->\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1cm][l]{}"blanks and HTML comments are ignored"\\
	\makebox[1cm][r]{\textrm{\tiny     }} LaTeX: \% comment\\
	\makebox[1cm][r]{\textrm{\tiny     }} "blanks must be skipped explicitly"\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[1cm][l]{}"only comments were ignored"}

%##end##"file:Documentation/ParsingSample.txt"

There is no syntax extension provided for this mode of parsing, so it is really considered as
\textit{procedure-driven}, in the opposite of the \textit{BNF-driven} mode that has been seen
in the precedent section.

%##markup##"parsing script functions"
%##begin##"parsing script functions"
\pdflabel{attachInputToSocket()}
\index{attachInputToSocket()}
\pdfsubsection{attachInputToSocket}
\begin{itemize}
	\item procedure \textbf{attachInputToSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
\end{tableiii}
Joins the input stream of a parsing script to a socket stream: each time that
the input stream pointer reaches the end, the interpreter waits for bytes
coming from the socket.

Waiting for bytes is a blocking process, so once you don't expect for other bytes
anymore, don't forget to detach the socket via the procedure \samp{detachInputFromSocket()}
before reaching the end of the stream.


\textbf{See also:}

\samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{countInputCols()}
\index{countInputCols()}
\pdfsubsection{countInputCols}
\begin{itemize}
	\item function \textbf{countInputCols(}\textbf{) :} \textit{int}

Determines the column number in the line where the parse cursor points to.


\textbf{See also:}

\samp{countInputLines} \ref{countInputLines()}
\end{itemize}
\pdflabel{countInputLines()}
\index{countInputLines()}
\pdfsubsection{countInputLines}
\begin{itemize}
	\item function \textbf{countInputLines(}\textbf{) :} \textit{int}

Determines the current line number where the parse cursor points to.


\textbf{See also:}

\samp{countInputCols} \ref{countInputCols()}
\end{itemize}
\pdflabel{detachInputFromSocket()}
\index{detachInputFromSocket()}
\pdfsubsection{detachInputFromSocket}
\begin{itemize}
	\item procedure \textbf{detachInputFromSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
\end{tableiii}
Disconnects the input stream of a parsing script from a socket stream. You
should have join the socket to the input stream before, via the procedure \samp{attachInputToSocket()}.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{getInputFilename()}
\index{getInputFilename()}
\pdfsubsection{getInputFilename}
\begin{itemize}
	\item function \textbf{getInputFilename(}\textbf{) :} \textit{string}

Returns the path of the input file being parsed.
\end{itemize}
\pdflabel{getInputLocation()}
\index{getInputLocation()}
\pdfsubsection{getInputLocation}
\begin{itemize}
	\item function \textbf{getInputLocation(}\textbf{) :} \textit{int}

Returns the current file position for reading the input stream.

\textbf{Example:}

\texttt{// we move further into the input file, just after the '\$' character\\
readNextText("\$");\\
traceLine("The character following '\$' is put at position " + getInputLocation() + ", starting at 0");}

\textbf{Output:}

\texttt{The character following '\$' is put at position 24, starting at 0}


\pdflabel{getLocation()}
\index{deprecated!getLocation()}
\textbf{Deprecated form:} \samp{getLocation} has disappeared since version \textit{3.7.1}


\textbf{See also:}

\samp{setInputLocation} \ref{setInputLocation()}, \samp{goBack} \ref{goBack()}
\end{itemize}
\pdflabel{getLastReadChars()}
\index{getLastReadChars()}
\pdfsubsection{getLastReadChars}
\begin{itemize}
	\item function \textbf{getLastReadChars(}\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{length}}{\textit{int}}{number of characters to read}
\end{tableiii}
Returns the last \samp{length} characters that have been read: it takes up to
the number of characters passed to the argument \samp{length}, characters that
are preceding the current position of the input file.

\textbf{Example:}

\texttt{// we move further into the input file\\
readNextText("\$");\\
traceLine("getLastReadChars(12) = '" + getLastReadChars(12) + "'");}

\textbf{Output:}

\texttt{getLastReadChars(12) = '\_potatoes41\$'}


\pdflabel{readLastChars()}
\index{deprecated!readLastChars()}
\textbf{Deprecated form:} \samp{readLastChars} has disappeared since version \textit{1.30}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{goBack()}
\index{goBack()}
\pdfsubsection{goBack}
\begin{itemize}
	\item procedure \textbf{goBack(}\textbf{)}

Moves back the position of the input stream, pointing to the character just
before. If the current position was pointing to the beginning of the input
stream, the function has no effect.

\textbf{Example:}

\texttt{traceLine("we move further into the input file, just after '\$'");\\
readNextText("\$");\\
traceLine("and now, we go back to it");\\
goBack();\\
if !readIfEqualTo("\$") error("'\$' expected");}

\textbf{Output:}

\texttt{we move further into the input file, just after '\$'\\
and now, we go back to it}


\textbf{See also:}

\samp{setInputLocation} \ref{setInputLocation()}, \samp{getInputLocation} \ref{getInputLocation()}
\end{itemize}
\pdflabel{lookAhead()}
\index{lookAhead()}
\pdfsubsection{lookAhead}
\begin{itemize}
	\item function \textbf{lookAhead(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to match}
\end{tableiii}
Checks whether the next characters of the input stream match with the string
passed to argument \samp{text}. If so, the function returns \samp{true} and
the position of the input stream hasn't moved.

\textbf{Example:}

\texttt{// we move further into the input file,\\
// just after 'C++: '\\
readNextText("C++: ");\\
local iPosition = getInputLocation();\\
traceLine("lookAhead('/*') = '" + lookAhead("/*") + "'");\\
if iPosition != getInputLocation() error("What did I say? The file position shouldn't have moved!");}

\textbf{Output:}

\texttt{lookAhead('/*') = 'true'}


\textbf{See also:}

\samp{readIfEqualTo} \ref{readIfEqualTo()}, \samp{readIfEqualToIgnoreCase} \ref{readIfEqualToIgnoreCase()}, \samp{readIfEqualToIdentifier} \ref{readIfEqualToIdentifier()}
\end{itemize}
\pdflabel{peekChar()}
\index{peekChar()}
\pdfsubsection{peekChar}
\begin{itemize}
	\item function \textbf{peekChar(}\textbf{) :} \textit{string}

Returns the character found at the current input stream position, or an empty
string if the end of file has been reached. If succeeded, the position of the
input file \textbf{doesn't move} to the next character.

\textbf{Example:}

\texttt{setInputLocation(10);\\
traceLine("at position 10, peekChar() = '" + peekChar() + "'");\\
if !equal(getInputLocation(), 10) error("the position of the input stream shouldn't have moved!");\\
traceLine("the position didn't change, peekChar() = '" + peekChar() + "' again");}

\textbf{Output:}

\texttt{at position 10, peekChar() = ':'\\
the position didn't change, peekChar() = ':' again}


\textbf{See also:}

\samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readAdaString()}
\index{readAdaString()}
\pdfsubsection{readAdaString}
\begin{itemize}
	\item function \textbf{readAdaString(}\samp{text} \textbf{:} \textit{stringref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{stringref}}{a variable that will contain the string literal extracted from the input stream}
\end{tableiii}
Reads a string literal surrounded by double quotes, and where the double-quote character has to be repeated.

If succeeded, the position moves just after the trailing double quote and the
function returns \samp{true}.


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readByte()}
\index{readByte()}
\pdfsubsection{readByte}
\begin{itemize}
	\item function \textbf{readByte(}\textbf{) :} \textit{string}

Returns the byte read at the current file position, or an empty
string if the end of file has been reached. If succeeded, the position of the
input file moves to the next character.

The byte is returned as a 2-hexadecimal digit.

\textbf{Example:}

\texttt{while !lookAhead(":") traceText("0x" + readByte() + " ");}

\textbf{Output:}

\texttt{0x69 0x64 0x65 0x6E 0x74 0x69 0x66 0x69 0x65 0x72 }


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readBytes()}
\index{readBytes()}
\pdfsubsection{readBytes}
\begin{itemize}
	\item function \textbf{readBytes(}\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{length}}{\textit{int}}{number of bytes to read}
\end{tableiii}
Returns the sequence of \samp{length} bytes read at the current file position, or an empty
string if the end of file has been reached. If succeeded, the position of the
input file moves just after.

The sequence of bytes is returned as a concatenation of 2-hexadecimal digits.

\textbf{Example:}

\texttt{traceLine("6 first bytes = 0x" + readBytes(6));}

\textbf{Output:}

\texttt{6 first bytes = 0x6964656E7469}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readCChar()}
\index{readCChar()}
\pdfsubsection{readCChar}
\begin{itemize}
	\item function \textbf{readCChar(}\textbf{) :} \textit{string}

Returns the \textbf{C-like} constant character read at the current file position.
A C-like character stands between single quotes and admits the escape character \textbf{$\backslash$r}.
If succeeded, the position of the input file moves to the trailing single quote.
\end{itemize}
\pdflabel{readChar()}
\index{readChar()}
\pdfsubsection{readChar}
\begin{itemize}
	\item function \textbf{readChar(}\textbf{) :} \textit{string}

Returns the character read at the current file position, or an empty
string if the end of file has been reached. If succeeded, the position of the
input file moves to the next character.

\textbf{Example:}

\texttt{while !lookAhead(":") traceText(readChar());}

\textbf{Output:}

\texttt{identifier}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readCharAsInt()}
\index{readCharAsInt()}
\pdfsubsection{readCharAsInt}
\begin{itemize}
	\item function \textbf{readCharAsInt(}\textbf{) :} \textit{int}

Returns the ASCII value of character read at the current file position, or
a negative number \samp{-1} if the end of file has been reached. If succeeded,
the position of the input file moves to the next character.

\textbf{Example:}

\texttt{traceLine("we move to the end of a line,");\\
readNextText("\$");\\
traceLine("so carriage return or newline is " + readCharAsInt());}

\textbf{Output:}

\texttt{we move to the end of a line,\\
so carriage return or newline is 13}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readChars()}
\index{readChars()}
\pdfsubsection{readChars}
\begin{itemize}
	\item function \textbf{readChars(}\samp{length} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{length}}{\textit{int}}{number of characters to read}
\end{tableiii}
Returns the sequence of \samp{length} characters read at the current file position, or an empty
string if the end of file has been reached. If succeeded, the position of the
input file moves just after.

\textbf{Example:}

\texttt{traceLine("6 first characters = '" + readChars(6) + "'");}

\textbf{Output:}

\texttt{6 first characters = 'identi'}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readIdentifier()}
\index{readIdentifier()}
\pdfsubsection{readIdentifier}
\begin{itemize}
	\item function \textbf{readIdentifier(}\textbf{) :} \textit{string}

Returns the \textit{identifier} token read at the position of the input file,
or an empty string if it doesn't match.

An \textit{identifier} begins with an alphabetical character (letter without
accent) or an underscore and
may be followed by any of them or by digits.

\textbf{Example:}

\texttt{traceLine("we jump just before the identifier:");\\
readNextText("identifier: ");\\
traceLine("identifier = '" + readIdentifier() + "'");}

\textbf{Output:}

\texttt{we jump just before the identifier:\\
identifier = '\_potatoes41'}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readIfEqualTo()}
\index{readIfEqualTo()}
\pdfsubsection{readIfEqualTo}
\begin{itemize}
	\item function \textbf{readIfEqualTo(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to match}
\end{tableiii}
Checks whether the next characters of the input stream match with the string
passed to argument \samp{text}. If so, the function returns \samp{true} and
the position of the input stream moves just after.

\textbf{Example:}

\texttt{// we move further into the input file,\\
// just after 'C++: '\\
readNextText("C++: ");\\
local iPosition = getInputLocation();\\
traceLine("readIfEqualTo('/*') = '" + readIfEqualTo("/*") + "'");\\
if iPosition == getInputLocation() error("The file position should have moved after '/*'!");}

\textbf{Output:}

\texttt{readIfEqualTo('/*') = 'true'}


\textbf{See also:}

\samp{lookAhead} \ref{lookAhead()}, \samp{readIfEqualToIgnoreCase} \ref{readIfEqualToIgnoreCase()}, \samp{readIfEqualToIdentifier} \ref{readIfEqualToIdentifier()}
\end{itemize}
\pdflabel{readIfEqualToIdentifier()}
\index{readIfEqualToIdentifier()}
\pdfsubsection{readIfEqualToIdentifier}
\begin{itemize}
	\item function \textbf{readIfEqualToIdentifier(}\samp{identifier} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{identifier}}{\textit{string}}{an \textit{identifier} is a string composed of letters and underscores ; digits are admitted too, except at the first place}
\end{tableiii}
Checks whether the next characters of the input stream match with the
\textit{identifier} passed to argument. If so, the function returns
\samp{true} and the position of the input stream moves just after.

This function warrants that the character just before the beginning of the
\textit{identifier} into the input stream is neither a letter nor a digit nor
an underscore, to assure that the identifier really starts at the current
position of the input stream.

\textbf{Example:}

\texttt{traceLine("readIfEqualTo('ident') = '" + readIfEqualTo("ident") + "'");\\
traceLine("readIfEqualTo('identifier') = '" + readIfEqualTo("identifier") + "'");}

\textbf{Output:}

\texttt{readIfEqualTo('ident') = 'true'\\
readIfEqualTo('identifier') = ''}


\textbf{See also:}

\samp{lookAhead} \ref{lookAhead()}, \samp{readIfEqualTo} \ref{readIfEqualTo()}, \samp{readIfEqualToIgnoreCase} \ref{readIfEqualToIgnoreCase()}
\end{itemize}
\pdflabel{readIfEqualToIgnoreCase()}
\index{readIfEqualToIgnoreCase()}
\pdfsubsection{readIfEqualToIgnoreCase}
\begin{itemize}
	\item function \textbf{readIfEqualToIgnoreCase(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to match}
\end{tableiii}
Checks whether the next characters of the input stream match with the string
passed to argument \samp{text}, ignoring the case. If so, the function returns
\samp{true} and the position of the input stream moves just after.

\textbf{Example:}

\texttt{traceLine("readIfEqualToIgnoreCase('IDENTIFIER') = '" + readIfEqualToIgnoreCase("IDENTIFIER") + "'");\\
if !readIfEqualTo(":") error("':' expected after matching with 'IDENTIFIER'!");}

\textbf{Output:}

\texttt{readIfEqualToIgnoreCase('IDENTIFIER') = 'true'}


\textbf{See also:}

\samp{lookAhead} \ref{lookAhead()}, \samp{readIfEqualTo} \ref{readIfEqualTo()}, \samp{readIfEqualToIdentifier} \ref{readIfEqualToIdentifier()}
\end{itemize}
\pdflabel{readLine()}
\index{readLine()}
\pdfsubsection{readLine}
\begin{itemize}
	\item function \textbf{readLine(}\samp{text} \textbf{:} \textit{stringref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{stringref}}{a variable that will contain the line}
\end{tableiii}
Reads the next line, starting at the current position of the input file, and
puts it into parameter \samp{text}. Characters \textbf{'$\backslash$r'} or
\textbf{'$\backslash$n} are ignored, and the position points to the beginning
of the next line or at the end of file if reached.

If succeeded, the function returns \samp{true}.

\textbf{Example:}

\texttt{traceLine("Reads the 2 first lines:");\\
local sLine;\\
if !readLine(sLine) error("line 1 expected, instead of end of file");\\
traceLine("$\backslash$t" + sLine);\\
if !readLine(sLine) error("line 2 expected, instead of end of file");\\
traceLine("$\backslash$t" + sLine);}

\textbf{Output:}

\texttt{Reads the 2 first lines:\\
\makebox[0.8cm][l]{}identifier: \_potatoes41\$\\
\makebox[0.8cm][l]{}numbers: 42 23.45e6}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readNextText()}
\index{readNextText()}
\pdfsubsection{readNextText}
\begin{itemize}
	\item function \textbf{readNextText(}\samp{text} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{a sequence of characters to find}
\end{tableiii}
Looks for the next occurrence of the expression given by argument \samp{text},
starting at the current position of the input file.

If succeeded, the position moves just after the expression given by \samp{text}
and the function returns \samp{true}.

\textbf{Example:}

\texttt{traceLine("position of the input stream = " + getInputLocation());\\
if !readNextText("word:") error("where is 'word:'?");\\
traceLine("we jump to 'word:', and the new position is " + getInputLocation());}

\textbf{Output:}

\texttt{position of the input stream = 0\\
we jump to 'word:', and the new position is 119}


\textbf{See also:}

\samp{readUptoJustOneChar} \ref{readUptoJustOneChar()}
\end{itemize}
\pdflabel{readNumber()}
\index{readNumber()}
\pdfsubsection{readNumber}
\begin{itemize}
	\item function \textbf{readNumber(}\samp{number} \textbf{:} \textit{doubleref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{number}}{\textit{doubleref}}{a variable that will contain the number read into the input stream}
\end{tableiii}
Reads a number at the current position of the input stream, and puts it into
the variable \samp{number}. A number is either an integer or a floating-point
representation as encountered ordinary.

If succeded, the position moves just after the token and the function returns
\samp{true}.

\textbf{Example:}

\texttt{traceLine("we jump just before the numbers:");\\
readNextText("numbers: ");\\
local dNumber;\\
if !readNumber(dNumber) error("integer expected!");\\
traceLine("integer = " + dNumber);\\
skipBlanks();\\
if !readNumber(dNumber) error("double expected!");\\
traceLine("double = " + dNumber);}

\textbf{Output:}

\texttt{we jump just before the numbers:\\
integer = 42\\
double = 23450000}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readPythonString()}
\index{readPythonString()}
\pdfsubsection{readPythonString}
\begin{itemize}
	\item function \textbf{readPythonString(}\samp{text} \textbf{:} \textit{stringref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{stringref}}{a variable that will contain the string literal extracted from the input stream}
\end{tableiii}
Reads a string literal as defined in \textit{Python}, a scripting language. Notably,
it accepts triple-quoted strings.

If succeeded, the position moves just after the trailing double quote and the
function returns \samp{true}.


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readString} \ref{readString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readString()}
\index{readString()}
\pdfsubsection{readString}
\begin{itemize}
	\item function \textbf{readString(}\samp{text} \textbf{:} \textit{stringref}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{stringref}}{a variable that will contain the string literal extracted from the input stream}
\end{tableiii}
Reads a string literal surrounded by double quotes, and where escape sequences
are written as presented in function \samp{composeCLikeString()}
(\ref{composeCLikeString()}). The token is then put into the variable passed to
argument \samp{text}, without double quotes and after converting the escape
sequences into their ASCII representation.

If succeeded, the position moves just after the trailing double quote and the
function returns \samp{true}.

\textbf{Example:}

\texttt{traceLine("we jump just before the string:");\\
readNextText("string: ");\\
local sText;\\
if !readString(sText) error("constant string expected!");\\
traceLine("string = '" + sText + "'");}

\textbf{Output:}

\texttt{we jump just before the string:\\
string = 'a C-like string that accepts backslash-escape sequences'}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readWord} \ref{readWord()}
\end{itemize}
\pdflabel{readUptoJustOneChar()}
\index{readUptoJustOneChar()}
\pdfsubsection{readUptoJustOneChar}
\begin{itemize}
	\item function \textbf{readUptoJustOneChar(}\samp{oneAmongChars} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{oneAmongChars}}{\textit{string}}{a set of characters}
\end{tableiii}
Reads the input stream up to encountering a character that belongs to the
parameter \samp{oneAmongChars}, and returns the sequence of characters read.

The position of the input stream points to the first character that belongs to
the parameter \samp{oneAmongChars}. Calling \samp{readChar()} or \samp{readIfEqualTo()}
just after allows determining what character, amongst those put into \samp{oneAmongChars},
was encountered first.

\textbf{Example:}

\texttt{traceLine("readUptoJustOneChar('\$\_:') = '" + readUptoJustOneChar("\$\_:") + "'");}

\textbf{Output:}

\texttt{readUptoJustOneChar('\$\_:') = 'identifier'}


\textbf{See also:}

\samp{readNextText} \ref{readNextText()}
\end{itemize}
\pdflabel{readWord()}
\index{readWord()}
\pdfsubsection{readWord}
\begin{itemize}
	\item function \textbf{readWord(}\textbf{) :} \textit{string}

Returns the \textit{word} token read at the position of the input file,
or an empty string if it doesn't match.

\CodeWorker\ understands a \textit{word} token as a sequence of alphabetical
characters, including letters with an accent as existing in French or Germany, or
underscores or digits.

\textbf{Example:}

\texttt{traceLine("we jump just before the word:");\\
readNextText("word: ");\\
traceLine("readWord() = '" + readWord() + "'");}

\textbf{Output:}

\texttt{we jump just before the word:\\
readWord() = '1'}


\textbf{See also:}

\samp{peekChar} \ref{peekChar()}, \samp{getLastReadChars} \ref{getLastReadChars()}, \samp{readByte} \ref{readByte()}, \samp{readBytes} \ref{readBytes()}, \samp{readChar} \ref{readChar()}, \samp{readChars} \ref{readChars()}, \samp{readCharAsInt} \ref{readCharAsInt()}, \samp{readIdentifier} \ref{readIdentifier()}, \samp{readLine} \ref{readLine()}, \samp{readAdaString} \ref{readAdaString()}, \samp{readNumber} \ref{readNumber()}, \samp{readPythonString} \ref{readPythonString()}, \samp{readString} \ref{readString()}
\end{itemize}
\pdflabel{setInputLocation()}
\index{setInputLocation()}
\pdfsubsection{setInputLocation}
\begin{itemize}
	\item procedure \textbf{setInputLocation(}\samp{location} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{int}}{points to a position of the input stream}
\end{tableiii}
This procedure moves the position of the input stream elsewhere. The position
starts at 0.

\textbf{Example:}

\texttt{traceLine("we jump to identifier 'potatoes' at position 12");\\
setInputLocation(12);\\
if !readIfEqualToIdentifier("\_potatoes41") error("identifier '\_potatoes41' expected");}

\textbf{Output:}

\texttt{we jump to identifier 'potatoes' at position 12}


\pdflabel{setLocation()}
\index{deprecated!setLocation()}
\textbf{Deprecated form:} \samp{setLocation} has disappeared since version \textit{3.7.1}


\textbf{See also:}

\samp{goBack} \ref{goBack()}, \samp{getInputLocation} \ref{getInputLocation()}
\end{itemize}
\pdflabel{skipBlanks()}
\index{skipBlanks()}
\pdfsubsection{skipBlanks}
\begin{itemize}
	\item function \textbf{skipBlanks(}\textbf{) :} \textit{bool}

Ignores all blank characters. The current file position moves to the first
character that isn't a blank. A blank character is a space, a newline, a
carriage return, a tabulation and, more generally, any ASCII character smaller
that 32.

\textbf{Example:}

\texttt{readNextText("blanks: ");\\
traceLine("we skip blank characters");\\
skipBlanks();\\
traceText("now, we read the string token: ");\\
local sText;\\
if !readString(sText) error("constant string expected");\\
traceLine("'" + sText + "'");}

\textbf{Output:}

\texttt{we skip blank characters\\
now, we read the string token: 'blanks are ignored'}


\textbf{See also:}

\samp{skipEmptyCpp} \ref{skipEmptyCpp()}, \samp{skipEmptyCppExceptDoxygen} \ref{skipEmptyCppExceptDoxygen()}, \samp{skipEmptyHTML} \ref{skipEmptyHTML()}, \samp{skipEmptyLaTeX} \ref{skipEmptyLaTeX()}
\end{itemize}
\pdflabel{skipEmptyCpp()}
\index{skipEmptyCpp()}
\pdfsubsection{skipEmptyCpp}
\begin{itemize}
	\item function \textbf{skipEmptyCpp(}\textbf{) :} \textit{bool}

Ignores all blank characters and all C++/JAVA-like comments. The current file
position moves to the first character that must be kept.

\textbf{Example:}

\texttt{readNextText("C++: ");\\
traceLine("we skip C++ empty tokens");\\
skipEmptyCpp();\\
traceText("now, we read the string token: ");\\
local sText;\\
if !readString(sText) error("constant string expected");\\
traceLine("'" + sText + "'");}

\textbf{Output:}

\texttt{we skip C++ empty tokens\\
now, we read the string token: 'blanks and C++ comments are ignored'}


\textbf{See also:}

\samp{skipBlanks} \ref{skipBlanks()}, \samp{skipEmptyCppExceptDoxygen} \ref{skipEmptyCppExceptDoxygen()}, \samp{skipEmptyHTML} \ref{skipEmptyHTML()}, \samp{skipEmptyLaTeX} \ref{skipEmptyLaTeX()}
\end{itemize}
\pdflabel{skipEmptyCppExceptDoxygen()}
\index{skipEmptyCppExceptDoxygen()}
\pdfsubsection{skipEmptyCppExceptDoxygen}
\begin{itemize}
	\item function \textbf{skipEmptyCppExceptDoxygen(}\textbf{) :} \textit{bool}

Ignores all blank characters and all C++/JAVA-like comments, except when the comment conforms to the \textit{Doxygen} format. The current file
position moves to the first character that must be kept.

\textbf{Example:}

\texttt{readNextText("C++: ");\\
traceLine("we skip C++ empty tokens, except Doxygen comments");\\
skipEmptyCppExceptDoxygen();\\
traceText("now, we read the string token: ");\\
local sText;\\
if !readString(sText) error("constant string expected");\\
traceLine("'" + sText + "'");}

\textbf{Output:}

\texttt{we skip C++ empty tokens, except Doxygen comments\\
now, we read the string token: 'blanks and C++ comments are ignored'}


\textbf{See also:}

\samp{skipBlanks} \ref{skipBlanks()}, \samp{skipEmptyCpp} \ref{skipEmptyCpp()}, \samp{skipEmptyHTML} \ref{skipEmptyHTML()}, \samp{skipEmptyLaTeX} \ref{skipEmptyLaTeX()}
\end{itemize}
\pdflabel{skipEmptyHTML()}
\index{skipEmptyHTML()}
\pdfsubsection{skipEmptyHTML}
\begin{itemize}
	\item function \textbf{skipEmptyHTML(}\textbf{) :} \textit{bool}

Ignores all blank characters and all HTML/XML-like comments. The current file
position moves to the first character that must be kept.

\textbf{Example:}

\texttt{readNextText("HTML: ");\\
traceLine("we skip HTML empty tokens");\\
skipEmptyHTML();\\
traceText("now, we read the string token: ");\\
local sText;\\
if !readString(sText) error("constant string expected");\\
traceLine("'" + sText + "'");}

\textbf{Output:}

\texttt{we skip HTML empty tokens\\
now, we read the string token: 'blanks and HTML comments are ignored'}


\textbf{See also:}

\samp{skipBlanks} \ref{skipBlanks()}, \samp{skipEmptyCpp} \ref{skipEmptyCpp()}, \samp{skipEmptyCppExceptDoxygen} \ref{skipEmptyCppExceptDoxygen()}, \samp{skipEmptyLaTeX} \ref{skipEmptyLaTeX()}
\end{itemize}
\pdflabel{skipEmptyLaTeX()}
\index{skipEmptyLaTeX()}
\pdfsubsection{skipEmptyLaTeX}
\begin{itemize}
	\item function \textbf{skipEmptyLaTeX(}\textbf{) :} \textit{bool}

Ignores all LaTeX comments. A LaTeX comment is announced by the character
\samp{percent} and finishes at the end of the line. The current file
position moves to the first character that must be kept.

\textbf{Example:}

\texttt{readNextText("LaTeX: ");\\
traceLine("we skip LaTeX comments");\\
skipEmptyLaTeX();\\
traceText("now, we read the string token: ");\\
local sText;\\
if !readString(sText) error("constant string expected");\\
traceLine("'" + sText + "'");}

\textbf{Output:}

\texttt{we skip LaTeX comments\\
now, we read the string token: 'blanks must be skipped explicitly'}


\textbf{See also:}

\samp{skipBlanks} \ref{skipBlanks()}, \samp{skipEmptyCpp} \ref{skipEmptyCpp()}, \samp{skipEmptyCppExceptDoxygen} \ref{skipEmptyCppExceptDoxygen()}, \samp{skipEmptyHTML} \ref{skipEmptyHTML()}
\end{itemize}
%##end##"parsing script functions"

%--------------------------------------------------------------------------
\pdflabel{source code generation}
\pdfsection{Syntax and instructions for generating source code}
\index{\arobas}
\index{<\%}
\index{\%>}
\index{source code generation}
\index{expanding text}
\index{generating text}
\index{translating text}
\index{scripts!generation mode}
\index{scripts!expansion mode}
\index{scripts!translation mode}

A script that must be processed for source code generation is called a \textit{pattern script} in the
\CodeWorker\ vocabulary. It exists three ways to generate a file:
\begin{itemize}
	\item the classical \textbf{generation mode} is used to let the script produce the
		most part of the output. The output file is rewritten completely. Only some areas
		called \textit{protected areas} in the vocabulary of \CodeWorker\ are preserved in
		the file. This philosophy has been adopted by some modeling tools that generate
		a skinny skeleton copiously interspersed with areas intended to the developer.
	\item \textbf{expansion mode} is used when the file is mainly written by
		hand, but small portions need to be generated. The points where to
		insert the code are known as \textit{markups} in the vocabulary of
		\CodeWorker\ . Visual C++ changes source code like it via the \textit{Class Wizard}.
	\item \textbf{translation mode} is used when both parsing and source code generation are
		required to process a file. It arrives when a file must be rewritten in a different
		syntax, or when the positions the code must be inserted depend on a strategy that
		is determined by the parsing. For example, a script should add a trace at the beginning
		of each function body of a JAVA or C++ source code. To do that, parsing will allow
		discovering function bodies, and source code generation will write the C++ or JAVA code that
		implements the trace.
\end{itemize}

A \textit{pattern script}, except in \textit{translation mode}, begins with a sequence of
characters exactly like they must be written into the output file, up to it encounters special
character \textbf{'@'} or JSP-like tag \textbf{'<\%'}. Then it swaps into script mode, and
everything is interpreted as script instructions, up to the special character \textbf{'@'} or
the JSP-like tag \textbf{'\%>'} are encountered. The content of the script file is again
understood as a sequence of characters to write into the output file, up to the next special
character. And it continues swapping from a mode to another...

For convenience, the script mode might just be restrained to an expression (often a variable
expression) whose value is written into the output file.

Expanding a file consists of generating code to some determined points of the file. These
points are called \samp{markups} and are noted \textbf{\#\#markup\#\#"}\textit{name-of-the-markup}\textbf{"},
surrounded by comment delimiters.

For example, a valid markup inlayed in a C++ file could be:\\
\samp{//\#\#markup\#\#"factory"}\\
and a valid markup inlayed in an HTML file could be:\\
\samp{<!- -\#\#markup\#\#"classes"- ->}

A \textit{pattern} script intended to expand code is launched thanks to the procedure
\samp{expand} that expects three parameters:
\begin{itemize}
	\item the first one is the file name of the script,
	\item the second one is the current context of execution that will be accessed via the
		\samp{this} keyword into the script,
	\item the last one is the name of the file to expand,
\end{itemize}

Each time \CodeWorker\ will encounter a markup, it will call the \textit{pattern} script that
will decide how to populate it. The code generated by the \textit{pattern} script for this
markup is surrounded by tags \textbf{\#\#begin\#\#"}\textit{name-of-the-markup}\textbf{"} and
\textbf{\#\#end\#\#"}\textit{name-of-the-markup}\textbf{"}, automatically added by the
interpreter. If some protected areas were put into the generated code, they are preserved the
next time the expansion is required.

Note that \CodeWorker\ doesn't change what is written outside the markups and their begin/end
delimiters.

A \textit{script} that is intended to work on \textit{translation mode} expects first a
BNF-like description as presented at section \ref{BNF syntax}. As for any kind of
\textit{BNF-driven} script, \textit{procedural-driven} script may be inlayed in braces
after symbol \textbf{'=>'}. This compound statement may contain a subset of \textit{pattern
script}, as described in the precedent paragraph, which will take in charge of generating code
into the output file. Note that the flow of execution enters into the compound statement in
\textit{script mode}.

Such as for parsing, it exists some functions to handle a position into the output stream.
However, the principle is quite different, insofar as the current position of the output
stream cannot be changed and always points to the end.

A position is called a \textit{floating location} and has an ID. A \textit{floating location}
is used for overwriting or for inserting text to a point of the stream that has already been
generated. While generating a C++ body for example, it may be interesting to insert the
\samp{'\#include'} preprocessor directive as references to other headers are discovered during
the iteration of the parse tree.

The procedure \samp{newFloatingLocation} allows attaching a position to an ID, which
represents the name of the location. The function \samp{getFloatingLocation} returns the
position attached to a given \textit{floating location} ID.

Inserting text at a position leads to shift all \textit{floating locations} that are pointing
to, or after, the insertion point. The offset corresponds to the size of the text. So, it is
called a \textit{floating location} because the position assigned initially to the ID might
change in the future.

You'll find below a list of all built-in functions or procedures that may be used into a
\textit{pattern script}, as well as typical preprocessor directives.

\pdflabel{coverage recording}
\index{template-based directives!\#coverage}
\index{\#coverage}
\pdfsubsection{Preprocessor directive: coverage recording}

A functionality has been added to code generation, to know where the output comes from.
In CodeWorker, an output file is generated by a template-based script. The directive \samp{\#coverage}
asks for the recording of every script position giving rise to a piece of the output file.

This directive is located anywhere in the script to study, and requires a variable the code
generation engine will populate with coverage data.
The variable will be a list of sorted segments, entirely determined by their starting position
in the output and by the position of the corresponding script \textit{instruction}.
These positions are respectively stored in attributes \textbf{output} and \textbf{script}.

An adding information is assigned to the node representing the segment. It specifies the type of
script \textit{instruction}, belonging to one of the following values:
\begin{itemize}
	\item \textbf{"R"}: rough text,
	\item \textbf{"W"}: expression, variable or call to a \samp{writeText()}-family procedure,
	\item \textbf{"I"}: call to a \samp{insertText()}-family procedure,
	\item \textbf{"O"}: call to \samp{overwritePortion()} procedure,
\end{itemize}

\textbf{Example:}\\
\texttt{\textbf{rough text @}this.name\textbf{@ EOL\\
@}\\
\#coverage(project.coverage)}

Let say that \textit{this.name} is worth "VARIABLE_CONTENT".
The script generates the following output file:\\
\texttt{rough text VARIABLE_CONTENT EOL}

The variable \samp{project.coverage} is then worth the following list:\\
\texttt{\makebox[0.4cm][r]{\textrm{\tiny     }} ["0"] = "R"\\
\makebox[0.8cm][r]{\textrm{\tiny     }} |--+\\
\makebox[1.2cm][r]{\textrm{\tiny     }} script = 12\\
\makebox[1.2cm][r]{\textrm{\tiny     }} output = 0\\
\makebox[0.4cm][r]{\textrm{\tiny     }} ["1"] = "W"\\
\makebox[0.8cm][r]{\textrm{\tiny     }} |--+\\
\makebox[1.2cm][r]{\textrm{\tiny     }} script = 21\\
\makebox[1.2cm][r]{\textrm{\tiny     }} output = 11\\
\makebox[0.4cm][r]{\textrm{\tiny     }} ["2"] = "R"\\
\makebox[0.8cm][r]{\textrm{\tiny     }} |--+\\
\makebox[1.2cm][r]{\textrm{\tiny     }} script = 29\\
\makebox[1.2cm][r]{\textrm{\tiny     }} output = 27}

\pdflabel{Aspect-Oriented Programming}
\index{Aspect-Oriented Programming}
\index{advice}
\index{jointpoint}
\index{\#jointpoint}
\pdfsubsection{Aspect-Oriented Programming and template-based scripts}

This section will be extended later. First, we'll just focus on features turning
around AOP in CodeWorker.

A template-based script can indicate some joint points during the generation process.
A joint point represents a remarkable place in the output stream, like the declaration
of attributes or the body of a method. The developer is free to create as many joint point
as needed. He gives to them the meaning that he wishes.

The syntax of a joint point looks like:\\
\samp{\textbf{jointpoint} [\textbf{iterate}]? \textit{name} [\textbf{(} \textit{context} \textbf{)}]? \textbf{;}}\\
or\\
\samp{\textbf{jointpoint} [\textbf{iterate}]? \textit{name} [\textbf{(} \textit{context} \textbf{)}]? \textit{instruction}}

\textit{context} is a variable expression. If \textit{context} is not specified, it is
worth to \textbf{this}.

When the interpreter encounters a joint point, it checks the existence of the variable
\textit{context}. If the variable exists, the interpreter looks for actions to execute
before, around and after the joint point.

These actions are referred to as \textit{advices}. They normally intend for generating
text at the place of some particular joint points. To determine what are joint points
on which an advice must apply, the developer has to define point cuts. A point cut
takes the form of a boolean expression attached to the advice.

The syntax of an advice looks like:
\samp{\textbf{advice} \textbf{advice-type} : \textit{pointcut} \textit{instruction}}\\
with:
\samp{\textbf{advice-type} ::= \textbf{before} | \textbf{around} | \textbf{after} | \textbf{before_iteration} | \textbf{around_iteration} | \textbf{after_iteration}}\\

Note that \textit{pointcut} is a boolean expression whose variable scope contains two
local variables:
\begin{itemize}
	\item \textbf{jointpoint}: the name of the joint point currently processed,
	\item \textbf{context}: a reference to the \textit{context} variable passed to the joint point,
\end{itemize}

When the interpreter considers a joint point, it first looks for each advice of
type \textbf{before} where the point cut matches. Then it executes them in the order
they were implemented. Next, it looks for each advice working around the joint point (of type \textbf{around})
and executes them. When the interpreter leaves a joint point, it executes each advice
of type \textbf{after} where the point cut matches.

An advice can execute the body of a joint point at any time, eventually changing
the current context, using the directive \textbf{\#jointpoint}:\\
\samp{\textbf{\#jointpoint} [\textbf{(} \textit{context} \textbf{)}]?}

If the option \textbf{iterate} is requested, the joint point works on an array. If the
array is empty, the interpreter bypasses the joint point. If not, the interpreter
iterates each element of the array, looking for advices before, around and after each
iteration. The corresponding advice types are referred to as \textbf{before_iteration},
\textbf{around_iteration} and \textbf{after_iteration}.

\textbf{Example of a jointpoint working on an array:}
%##markup##"file:Documentation/AOP-example1.cwt"
%##begin##"file:Documentation/AOP-example1.cwt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/AOP-example1.cwt":\\
	\makebox[1cm][r]{\textrm{\tiny     }} Separation of concerns in CodeWorker:\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} // a list of method declarations (names only)\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert this.methods["display"].name = "display";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert this.methods["delete"].name = "delete";\\
	\makebox[1cm][r]{\textrm{\tiny     }} insert this.methods["visit"].name = "visit";\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // a joint point announcing the implementation\\
	\makebox[1cm][r]{\textrm{\tiny     }} // of methods\\
	\makebox[1cm][r]{\textrm{\tiny     }} jointpoint iterate methods(this.methods) \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// generates the skeleton of a method\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}@    void @this.name@() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} @... This is the end of the test\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // Implementation of an aspect to apply on methods:\\
	\makebox[1cm][r]{\textrm{\tiny     }} // several advices\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // first advice: called while entering the joint point\\
	\makebox[1cm][r]{\textrm{\tiny     }} advice before : jointpoint == "methods" \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}@// beginning of methods\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // advice to apply around each method iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} advice around\_iteration : jointpoint == "methods" \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}@    // BEGIN around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}\#jointpoint\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}@    // OUT around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // last advice: called while leaving the joint point\\
	\makebox[1cm][r]{\textrm{\tiny     }} advice after : jointpoint == "methods" \{\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}@// end of methods\\
	\makebox[1cm][r]{\textrm{\tiny     }} @\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}traceObject(this, 10);\\
	\makebox[1cm][r]{\textrm{\tiny     }} \}}

%##end##"file:Documentation/AOP-example1.cwt"

It generates the following output:\\
%##markup##"file:Documentation/AOP-example1.txt"
%##begin##"file:Documentation/AOP-example1.txt"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "Documentation/AOP-example1.txt":\\
	\makebox[1cm][r]{\textrm{\tiny     }} testing separation of concerns in CodeWorker:\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} // beginning of methods\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// BEGIN around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}void display() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// OUT around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// BEGIN around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}void delete() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// OUT around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// BEGIN around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}void visit() \{\}\\
	\makebox[1cm][r]{\textrm{\tiny     }} \makebox[0.8cm][l]{}// OUT around iteration\\
	\makebox[1cm][r]{\textrm{\tiny     }} // end of methods\\
	\makebox[1cm][r]{\textrm{\tiny     }} \\
	\makebox[1cm][r]{\textrm{\tiny     }} This is the end of the test}

%##end##"file:Documentation/AOP-example1.txt"

%##markup##"generation script functions"
%##begin##"generation script functions"
\pdflabel{allFloatingLocations()}
\index{allFloatingLocations()}
\pdfsubsection{allFloatingLocations}
\begin{itemize}
	\item procedure \textbf{allFloatingLocations(}\samp{list} \textbf{:} \textit{tree}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{list}}{\textit{tree}}{floating location names and their position}
\end{tableiii}
Populates the argument \samp{list} with all floating location registered
to the current output stream, such as the entry key is the floating location name and
the entry value is the position in the stream.


\textbf{See also:}

\samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{attachOutputToSocket()}
\index{attachOutputToSocket()}
\pdfsubsection{attachOutputToSocket}
\begin{itemize}
	\item procedure \textbf{attachOutputToSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
\end{tableiii}
Joins the output stream of a \textit{template-based} or \textit{translation} script
so that to send the generated text to the socket.

The generated text is sent at the end of the complete script execution.


\textbf{See also:}

\samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}, \samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}
\end{itemize}
\pdflabel{countOutputCols()}
\index{countOutputCols()}
\pdfsubsection{countOutputCols}
\begin{itemize}
	\item function \textbf{countOutputCols(}\textbf{) :} \textit{int}

Determines the column number in the line where the output stream cursor points to.


\textbf{See also:}

\samp{countOutputLines} \ref{countOutputLines()}
\end{itemize}
\pdflabel{countOutputLines()}
\index{countOutputLines()}
\pdfsubsection{countOutputLines}
\begin{itemize}
	\item function \textbf{countOutputLines(}\textbf{) :} \textit{int}

Determines the line number where the output stream cursor points to.


\textbf{See also:}

\samp{countOutputCols} \ref{countOutputCols()}
\end{itemize}
\pdflabel{decrementIndentLevel()}
\index{decrementIndentLevel()}
\pdfsubsection{decrementIndentLevel}
\begin{itemize}
	\item function \textbf{decrementIndentLevel(}\samp{level} \textbf{:} \textit{int}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{level}}{\textit{int}}{\textbf{default value:} \textit{1}\\
depth of indentation to remove}
\end{tableiii}
Decrements the indentation level, used to indenting output files automatically while writing.

The function returns \samp{false} if the \textit{level} parameter is greater than
the current indentation depth.
If the function returns \samp{false}, the indentation level is worth zero and it disables
the indent-mode.
Otherwise, each time a text will have to be written at the beginning of a line,
the line will be indented, depending on the indentation level.

Call the function \samp{incrementIndentLevel()} to increase the indentation.


\textbf{See also:}

\samp{incrementIndentLevel} \ref{incrementIndentLevel()}
\end{itemize}
\pdflabel{detachOutputFromSocket()}
\index{detachOutputFromSocket()}
\pdfsubsection{detachOutputFromSocket}
\begin{itemize}
	\item procedure \textbf{detachOutputFromSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
\end{tableiii}
Disconnects the output stream of a parsing script from a socket stream. You
should have join the socket to the output stream before, via the procedure \samp{attachOutputToSocket()}.

To call only if you have changed your mind and don't want the generated text
to be sent to the socket at the end of the \textit{template-based} script
execution anymore.


\textbf{See also:}

\samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}, \samp{flushOutputToSocket} \ref{flushOutputToSocket()}
\end{itemize}
\pdflabel{existFloatingLocation()}
\index{existFloatingLocation()}
\pdfsubsection{existFloatingLocation}
\begin{itemize}
	\item function \textbf{existFloatingLocation(}\samp{key} \textbf{:} \textit{string}\textbf{, }\samp{parent} \textbf{:} \textit{bool}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{name of a floating position into the output stream}
	\lineiii{\samp{parent}}{\textit{bool}}{while expanding a file, search into precedent markup area if this floating location exists or not}
\end{tableiii}
Returns \samp{true} if the \textit{floating location}, whose name is passed to argument \samp{key}, already exists.

If required (parameter \samp{parent} set to \samp{true}) and if the current output
file is being expanded, the function searches the floating location in precedent
visited markup areas.

\textbf{Example:}

\texttt{Roger Rabbit@\\
newFloatingLocation("Roger Rabbit");\\
@ doesn't like spinash@\\
traceLine("Does the floating location 'Roger Rabbit' exists? '" + existFloatingLocation("Roger Rabbit", false) + "'");}

\textbf{Output:}

\texttt{Does the floating location 'Roger Rabbit' exists? 'true'}

\textbf{Generated text:}

\texttt{Roger Rabbit doesn't like spinash}


\textbf{See also:}

\samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{flushOutputToSocket()}
\index{flushOutputToSocket()}
\pdfsubsection{flushOutputToSocket}
\begin{itemize}
	\item function \textbf{flushOutputToSocket(}\samp{socket} \textbf{:} \textit{int}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{socket}}{\textit{int}}{a client socket descriptor}
\end{tableiii}
Sends to a socket the complete text or binary data already generated by the
\textit{template-based} or \textit{translation} script. The function
then purges the output stream.

This function has no link with \samp{attachOutputToSocket()}. It only requires
that the socket descriptor exists and is opened correctly.


\textbf{See also:}

\samp{attachOutputToSocket} \ref{attachOutputToSocket()}, \samp{detachOutputFromSocket} \ref{detachOutputFromSocket()}, \samp{createINETClientSocket} \ref{createINETClientSocket()}, \samp{createINETServerSocket} \ref{createINETServerSocket()}, \samp{acceptSocket} \ref{acceptSocket()}, \samp{attachInputToSocket} \ref{attachInputToSocket()}, \samp{detachInputFromSocket} \ref{detachInputFromSocket()}, \samp{receiveBinaryFromSocket} \ref{receiveBinaryFromSocket()}, \samp{receiveFromSocket} \ref{receiveFromSocket()}, \samp{receiveTextFromSocket} \ref{receiveTextFromSocket()}, \samp{sendTextToSocket} \ref{sendTextToSocket()}, \samp{sendBinaryToSocket} \ref{sendBinaryToSocket()}, \samp{closeSocket} \ref{closeSocket()}
\end{itemize}
\pdflabel{getFloatingLocation()}
\index{getFloatingLocation()}
\pdfsubsection{getFloatingLocation}
\begin{itemize}
	\item function \textbf{getFloatingLocation(}\samp{key} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{name of an existing floating position into the output stream}
\end{tableiii}
Returns the position into the output stream attached to a \textit{floating location}
whose name is passed to argument \samp{key}.

The function raises an error if the floating location doesn't exist or is present
in a precedent markup area of a being-expanded file, but not in the current markup
area.

\textbf{Example:}

\texttt{Roger Rabbit@\\
newFloatingLocation("Roger Rabbit");\\
@ doesn't like spinash@\\
traceLine("Position just after 'Roger Rabbit' is " + getFloatingLocation("Roger Rabbit"));}

\textbf{Output:}

\texttt{Position just after 'Roger Rabbit' is 12}

\textbf{Generated text:}

\texttt{Roger Rabbit doesn't like spinash}


\textbf{See also:}

\samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{getLastWrittenChars()}
\index{getLastWrittenChars()}
\pdfsubsection{getLastWrittenChars}
\begin{itemize}
	\item function \textbf{getLastWrittenChars(}\samp{NbChars} \textbf{:} \textit{int}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{NbChars}}{\textit{int}}{how many characters to ask for}
\end{tableiii}
Returns the last characters written in the output file, up to \samp{NbChars}
or less if the beginning of the file is encountered too early.

\textbf{Example:}

\texttt{let's write some characters@\\
traceLine("getLastWrittenChars(10) = '" + getLastWrittenChars(10) + "'");}

\textbf{Output:}

\texttt{getLastWrittenChars(10) = 'characters'}

\textbf{Generated text:}

\texttt{let's write some characters}
\end{itemize}
\pdflabel{getMarkupKey()}
\index{getMarkupKey()}
\pdfsubsection{getMarkupKey}
\begin{itemize}
	\item function \textbf{getMarkupKey(}\textbf{) :} \textit{string}

This function must be called into a pattern script that runs in \textit{expansion mode}.
It returns the current markup key where code has to be expanded now.

\textbf{Example:}

\texttt{@\\
if getMarkupKey() == "examples" \{\\
\makebox[0.8cm][l]{}@A little example?@\\
\} else \{\\
\makebox[0.8cm][l]{}@We are doing the LaTeX documentation in expansion mode!@\\
\makebox[0.8cm][l]{}traceLine("current markup of the LaTeX documentation = '" + getMarkupKey() + "'");\\
\}}

\textbf{Output:}

\texttt{current markup of the LaTeX documentation = 'generation script functions'}

\textbf{Generated text:}

\texttt{We are doing the LaTeX documentation in expansion mode!}


\pdflabel{getMarkerKey()}
\index{deprecated!getMarkerKey()}
\textbf{Deprecated form:} \samp{getMarkerKey} has disappeared since version \textit{2.14}


\textbf{See also:}

\samp{getMarkupValue} \ref{getMarkupValue()}
\end{itemize}
\pdflabel{getMarkupValue()}
\index{getMarkupValue()}
\pdfsubsection{getMarkupValue}
\begin{itemize}
	\item function \textbf{getMarkupValue(}\textbf{) :} \textit{string}

This function must be called into a pattern script that runs in \textit{expansion mode}.
It returns the current markup value, if any, put between tags '\#\#data\#\#' after declaring the markup key.

\textbf{Example - hand-typed code to expand:}

\texttt{... extension of C++/Java: implements a 'switch' on strings\\
//\#\#markup\#\#"switch(sText)"\\
//\#\#data\#\#\\
//Product\\
//RentalItem\\
//Customer\\
//RentalOrder\\
//Figurine\\
//Movie\\
//DVD\\
//VideoStore\\
//\#\#data\#\#\\
... next code
}

\textbf{Example - the script:}

\texttt{\{\\
\makebox[0.8cm][l]{}int iHashCode = 0;\\
\makebox[0.8cm][l]{}std::string sKey = @coreString(getMarkupKey(), 7, 1)@;\\
\makebox[0.8cm][l]{}for (int i = 0; i < sKey.length(); i++) \{\\
\makebox[1.6cm][l]{}unsigned char c = sKey[i];\\
\makebox[1.6cm][l]{}iHashCode = (31*iHashCode + (c\%31)) \% 64000000;\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}switch(iHashCode) \{\\
@\\
local sData = getMarkupValue();\\
while sData \{\\
\makebox[0.8cm][l]{}local iIndex = sData.findString('$\backslash$n');\\
\makebox[0.8cm][l]{}if \$iIndex < 0\$ || !sData.startString("//") error("syntax error");\\
\makebox[0.8cm][l]{}local sKey = sData.midString(2, \$iIndex - 2\$);\\
\makebox[0.8cm][l]{}if sKey.endString('$\backslash$r') set sKey = sKey.rsubString(1);\\
\makebox[0.8cm][l]{}local iHashCode = 0;\\
\makebox[0.8cm][l]{}local i = 0;\\
\makebox[0.8cm][l]{}while \$i < sKey.length()\$ \{\\
\makebox[1.6cm][l]{}local c = sKey.charAt(i);\\
\makebox[1.6cm][l]{}iHashCode = \$(31*iHashCode + (c.charToInt()\%31)) \% 64000000\$;\\
\makebox[1.6cm][l]{}increment(i);\\
\makebox[0.8cm][l]{}\}\\
\makebox[0.8cm][l]{}@        case @iHashCode@: // "@sKey@"\\
@\\
\makebox[0.8cm][l]{}setProtectedArea("case $\backslash$"" + sKey + "$\backslash$":");\\
\makebox[0.8cm][l]{}set sData = sData.subString(\$iIndex + 1\$);\\
\}\\
@        default:\\
@\\
setProtectedArea("default:");\\
@    \}\\
\}\\
@}

\textbf{Generated text:}

\texttt{... extension of C++/Java: implements a 'switch' on strings\\
//\#\#markup\#\#"switch(sText)"\\
//\#\#data\#\#\\
//Product\\
//RentalItem\\
//Customer\\
//RentalOrder\\
//Figurine\\
//Movie\\
//DVD\\
//VideoStore\\
//\#\#data\#\#\\
//\#\#begin\#\#"switch(sText)"\\
\{\\
\makebox[3.2cm][l]{}int iHashCode = 0;\\
\makebox[3.2cm][l]{}std::string sKey = sText;\\
\makebox[3.2cm][l]{}for (int i = 0; i < sKey.length(); i++) \{\\
\makebox[4cm][l]{}unsigned char c = sKey[i];\\
\makebox[4cm][l]{}iHashCode = (31*iHashCode + (c\%31)) \% 64000000;\\
\makebox[3.2cm][l]{}\}\\
\makebox[3.2cm][l]{}switch(iHashCode) \{\\
\makebox[4cm][l]{}case 17133617: // "Product"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"Product$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"Product$\backslash$":"\\
\makebox[1.6cm][l]{}case 19256985: // "RentalItem"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"RentalItem$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"RentalItem$\backslash$":"\\
\makebox[1.6cm][l]{}case 26793087: // "Customer"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"Customer$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"Customer$\backslash$":"\\
\makebox[1.6cm][l]{}case 26446891: // "RentalOrder"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"RentalOrder$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"RentalOrder$\backslash$":"\\
\makebox[1.6cm][l]{}case 20050752: // "Figurine"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"Figurine$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"Figurine$\backslash$":"\\
\makebox[1.6cm][l]{}case 14413458: // "Movie"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"Movie$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"Movie$\backslash$":"\\
\makebox[1.6cm][l]{}case 6516: // "DVD"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"DVD$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"DVD$\backslash$":"\\
\makebox[1.6cm][l]{}case 56055430: // "VideoStore"\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"case $\backslash$"VideoStore$\backslash$":"\\
//\#\#protect\#\#"case $\backslash$"VideoStore$\backslash$":"\\
\makebox[1.6cm][l]{}default:\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"default:"\\
//\#\#protect\#\#"default:"\\
\makebox[0.8cm][l]{}\}\\
\makebox[2.4cm][l]{}\}\\
\makebox[2.4cm][l]{}//\#\#end\#\#"switch(sText)"\\
... next code}


\textbf{See also:}

\samp{getMarkupKey} \ref{getMarkupKey()}
\end{itemize}
\pdflabel{getOutputFilename()}
\index{getOutputFilename()}
\pdfsubsection{getOutputFilename}
\begin{itemize}
	\item function \textbf{getOutputFilename(}\textbf{) :} \textit{string}

Returns the path of the output file being generated.
\end{itemize}
\pdflabel{getOutputLocation()}
\index{getOutputLocation()}
\pdfsubsection{getOutputLocation}
\begin{itemize}
	\item function \textbf{getOutputLocation(}\textbf{) :} \textit{int}

Returns the current file position for writing to the output stream.

\textbf{Example:}

\texttt{I write 22 characters.@\\
traceLine("Current position to the output stream = " + getOutputLocation());}

\textbf{Output:}

\texttt{Current position to the output stream = 22}

\textbf{Generated text:}

\texttt{I write 22 characters.}


\textbf{See also:}

\samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{getProtectedArea()}
\index{getProtectedArea()}
\pdfsubsection{getProtectedArea}
\begin{itemize}
	\item function \textbf{getProtectedArea(}\samp{protection} \textbf{:} \textit{string}\textbf{) :} \textit{string}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{protection}}{\textit{string}}{unique ID of a protected area}
\end{tableiii}
Returns the content of the protected area whose name is given by parameter
\samp{protection}. If the protected area wasn't found into the ancient version
of the output stream, and if it hasn't been put yet via \samp{setProtectedArea}
into the output stream, it returns an empty string.

\textbf{Example:}

\texttt{@\\
setProtectedArea("keep this code for me, please!");\\
if !getProtectedArea("keep this code for me, please!") \{\\
\makebox[0.8cm][l]{}traceLine("you have never populated the protected area!");\\
\}}

\textbf{Output:}

\texttt{you have never populated the protected area!}

\textbf{Generated text:}

\texttt{//\#\#protect\#\#"keep this code for me, please!"\\
//\#\#protect\#\#"keep this code for me, please!"}


\textbf{See also:}

\samp{populateProtectedArea} \ref{populateProtectedArea()}, \samp{getProtectedAreaKeys} \ref{getProtectedAreaKeys()}, \samp{remainingProtectedAreas} \ref{remainingProtectedAreas()}, \samp{removeProtectedArea} \ref{removeProtectedArea()}, \samp{setProtectedArea} \ref{setProtectedArea()}
\end{itemize}
\pdflabel{getProtectedAreaKeys()}
\index{getProtectedAreaKeys()}
\pdfsubsection{getProtectedAreaKeys}
\begin{itemize}
	\item function \textbf{getProtectedAreaKeys(}\samp{keys} \textbf{:} \textit{tree}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{keys}}{\textit{tree}}{it will contain keys of all protected areas that were found into the output stream before the generation}
\end{tableiii}
Looks for all protected areas that were found into the output stream before processing
the source code generation and puts their keys into the well-named argument \samp{keys}.

Note: \samp{keys} stores the ID of protected areas in the lexicographical order.

The function returns how many protected areas were found into the output stream.
Both key and value of items are worth the protected area key. If the list wasn't
declared as \textit{local} or \textit{global} or as belonging to \samp{this},
a negative value is returned.

\textbf{Example - precedent output generated:}

\texttt{My first protected area:\\
//\#\#protect\#\#"hand-typed code"\\
I don't want to loose this portion of text\\
after another generation!\\
//\#\#protect\#\#"hand-typed code"\\
My second protected area:\\
//\#\#protect\#\#"don't forget me, please!"\\
This portion of text is also very important.\\
//\#\#protect\#\#"don't forget me, please!"\\
Now, you can erase text, I don't care.
}

\textbf{Example - the script:}

\texttt{My first protected area:\\
@\\
local listOfKeys;\\
local iNbKeys = getProtectedAreaKeys(listOfKeys);\\
traceLine("Number of preserved area at the beginning = " + iNbKeys + ":");\\
foreach i in listOfKeys traceLine(" '" + i + "'");\\
setProtectedArea("hand-typed code");\\
traceLine("after removing and setting protected areas,");\\
traceLine("the function behaves the same");\\
removeProtectedArea("don't forget me, please!");\\
if \$getProtectedAreaKeys(listOfKeys) != 2\$ error("bad behavior");\\
@Now, you can erase text, I don't care.\\
@}

\textbf{Output:}

\texttt{Number of preserved area at the beginning = 2:\\
\makebox[0.8cm][l]{}'don't forget me, please!'\\
\makebox[0.8cm][l]{}'hand-typed code'\\
after removing and setting protected areas,\\
the function behaves the same}

\textbf{Generated text:}

\texttt{My first protected area:\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"hand-typed code"\\
I don't want to loose this portion of text\\
after another generation!\\
//\#\#protect\#\#"hand-typed code"\\
Now, you can erase text, I don't care.\\
\makebox[2.4cm][l]{}}


\textbf{See also:}

\samp{populateProtectedArea} \ref{populateProtectedArea()}, \samp{getProtectedArea} \ref{getProtectedArea()}, \samp{remainingProtectedAreas} \ref{remainingProtectedAreas()}, \samp{removeProtectedArea} \ref{removeProtectedArea()}, \samp{setProtectedArea} \ref{setProtectedArea()}
\end{itemize}
\pdflabel{incrementIndentLevel()}
\index{incrementIndentLevel()}
\pdfsubsection{incrementIndentLevel}
\begin{itemize}
	\item procedure \textbf{incrementIndentLevel(}\samp{level} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{level}}{\textit{int}}{\textbf{default value:} \textit{1}\\
depth of indentation to add}
\end{tableiii}
Increments the indentation level, used to indenting output files automatically while writing.

If first call, it enables the indent-mode: each time a text will have to be written at the
beginning of a line, the line will be indented, depending on the indentation level.

Call the function \samp{decrementIndentLevel()} to decrease the indentation.


\textbf{See also:}

\samp{decrementIndentLevel} \ref{decrementIndentLevel()}
\end{itemize}
\pdflabel{indentText()}
\index{indentText()}
\pdfsubsection{indentText}
\begin{itemize}
	\item function \textbf{indentText(}\samp{mode} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{mode}}{\textit{string}}{type of text to indent}
\end{tableiii}
Indents the output stream, conforming to a given type of file, to choose amongst:
\begin{itemize}
	\item \textbf{C++}
	\item \textbf{JAVA}
\end{itemize}
More format will be recognized in the future.

The function returns \samp{true} if the output stream needed to be indented,
meaning that it has changed after processing the indentation.

Be careful that if you are expanding a file, only the expanded area will be
indented. In that case, it is better to use \samp{indentFile} once the generation
has completed.

\textbf{Example:}

\texttt{int f(int i) \{\\
switch (i) \{\\
case 1:\\
g(i + 1);\\
break;\\
case 2:\\
case 3:\\
if (i == 2) \{\\
h();\\
\}\\
g(i - 1);\\
break;\\
\makebox[2.4cm][l]{}\}\\
\}@\\
if indentText("C++") traceLine("the output stream wasn't indented correctly");}

\textbf{Output:}

\texttt{the output stream wasn't indented correctly}

\textbf{Generated text:}

\texttt{int f(int i) \{\\
\makebox[0.8cm][l]{}switch (i) \{\\
\makebox[1.6cm][l]{}case 1:\\
\makebox[2.4cm][l]{}g(i + 1);\\
\makebox[2.4cm][l]{}break;\\
\makebox[1.6cm][l]{}case 2:\\
\makebox[1.6cm][l]{}case 3:\\
\makebox[2.4cm][l]{}if (i == 2) \{\\
\makebox[3.2cm][l]{}h();\\
\makebox[2.4cm][l]{}\}\\
\makebox[2.4cm][l]{}g(i - 1);\\
\makebox[2.4cm][l]{}break;\\
\makebox[0.8cm][l]{}\}\\
\}}


\textbf{See also:}

\samp{indentFile} \ref{indentFile()}
\end{itemize}
\pdflabel{insertText()}
\index{insertText()}
\pdfsubsection{insertText}
\begin{itemize}
	\item procedure \textbf{insertText(}\samp{location} \textbf{:} \textit{int}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{int}}{points to a position of the output stream}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to insert}
\end{tableiii}
Inserts a sequence of characters passed to argument \samp{text}, at the position
of the output stream given by argument \samp{location}. The position starts
counting at 0. All \textit{floating locations} that point to \samp{location},
or after, are impacted by the insertion, and shift for an offset that is worth
the size of the text to insert.

If the position isn't valid, negative or bigger than the end of the output
stream, an error is raised.

In \textit{expansion mode}, the position 0 points to the first character written
for expansion and cannot exceed the last character written for expansion.

Generally, the position is given by the function \samp{getFloatingLocation()}.

\textbf{Example:}

\texttt{I'll drink a bottle of 'Margaux' year 1994@\\
newFloatingLocation("You'll be drunk!");\\
@ before smoking a cigar.@\\
traceLine("My glass is empty, let's try another bottle, year 1996");\\
insertText(getFloatingLocation("You'll be drunk!"), " and year 1996");\\
traceLine("My glass is empty once again, let's try another bottle, year 2000");\\
insertText(getFloatingLocation("You'll be drunk!"), " and year 2000");}

\textbf{Output:}

\texttt{My glass is empty, let's try another bottle, year 1996\\
My glass is empty once again, let's try another bottle, year 2000}

\textbf{Generated text:}

\texttt{I'll drink a bottle of 'Margaux' year 1994 and year 1996 and year 2000 before smoking a cigar.}


\textbf{See also:}

\samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeText} \ref{writeText()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{insertTextOnce()}
\index{insertTextOnce()}
\pdfsubsection{insertTextOnce}
\begin{itemize}
	\item procedure \textbf{insertTextOnce(}\samp{location} \textbf{:} \textit{int}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{int}}{points to a position of the output stream}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to insert}
\end{tableiii}
Inserts a sequence of characters passed to argument \samp{text}, at the position
of the output stream given by argument \samp{location}, only if the text has
never been encountered previously by a \samp{insertTextOnce()} or a \samp{writeTextOnce()}
procedure. The position starts counting at 0. All \textit{floating locations}
that point to \samp{location}, or after, are impacted by the insertion, and
shift for an offset that is worth the size of the text to insert.

If the position isn't valid, negative or bigger than the end of the output
stream, an error is raised.

In \textit{expansion mode}, the position 0 points to the first character written
for expansion and cannot exceed the last character written for expansion.

Generally, the position is given by the function \samp{getFloatingLocation()}.

\textbf{Example:}

\texttt{@\\
newFloatingLocation("include files");\\
@\\
void f(const std::string\& s) \{\\
...\\
\}\\
@\\
traceLine("I need an include: <string>!");\\
insertTextOnce(getFloatingLocation("include files"), "\#include <string>" + endl());\\
@std::vector<std::string> g() \{\\
...\\
\}\\
@\\
traceLine("I need two includes: <string> and <vector>!");\\
insertTextOnce(getFloatingLocation("include files"), "\#include <string>" + endl());\\
insertTextOnce(getFloatingLocation("include files"), "\#include <vector>" + endl());}

\textbf{Output:}

\texttt{I need an include: <string>!\\
I need two includes: <string> and <vector>!}

\textbf{Generated text:}

\texttt{\#include <string>\\
\#include <vector>\\
\\
void f(const std::string\& s) \{\\
...\\
\}\\
std::vector<std::string> g() \{\\
...\\
\}}


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeText} \ref{writeText()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{insertTextOnceToFloatingLocation()}
\index{insertTextOnceToFloatingLocation()}
\pdfsubsection{insertTextOnceToFloatingLocation}
\begin{itemize}
	\item procedure \textbf{insertTextOnceToFloatingLocation(}\samp{location} \textbf{:} \textit{string}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{string}}{the name of a floating location}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to insert}
\end{tableiii}
Inserts a sequence of characters passed to argument \samp{text}, at the position
of the floating location, whose name is given by the argument \samp{location}, but
only if the text has never been encountered previously by a \samp{insertTextOnce()}
 or a \samp{writeTextOnce()}procedure.

If the floating location doesn't exist, the function raises an error.

In \textit{expansion mode}, the floating location might point into a markup area
previously generated. So, on the contrary of \samp{insertTextOnce()}, the function
permits to insert text out of the current markup area.


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeText} \ref{writeText()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{insertTextToFloatingLocation()}
\index{insertTextToFloatingLocation()}
\pdfsubsection{insertTextToFloatingLocation}
\begin{itemize}
	\item procedure \textbf{insertTextToFloatingLocation(}\samp{location} \textbf{:} \textit{string}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{string}}{the name of a floating location}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to insert}
\end{tableiii}
Inserts a sequence of characters passed to argument \samp{text}, at the position
of the floating location, whose name is given by the argument \samp{location}.

If the floating location doesn't exist, the function raises an error.

In \textit{expansion mode}, the floating location might point into a markup area
previously generated. So, on the contrary of \samp{insertText()}, the function
permits to insert text out of the current markup area.


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeText} \ref{writeText()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{newFloatingLocation()}
\index{newFloatingLocation()}
\pdfsubsection{newFloatingLocation}
\begin{itemize}
	\item function \textbf{newFloatingLocation(}\samp{key} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{name of a floating position into the output stream}
\end{tableiii}
Assigns the current position into the output stream to a \textit{floating location}
whose name is passed to argument \samp{key}. If the \textit{floating location}
already exists, its position is updated.

\textbf{Example:}

\texttt{Roger Rabbit@\\
newFloatingLocation("Roger Rabbit");\\
@ doesn't like spinash@\\
traceLine("Position just after 'Roger Rabbit' is " + getFloatingLocation("Roger Rabbit"));}

\textbf{Output:}

\texttt{Position just after 'Roger Rabbit' is 12}

\textbf{Generated text:}

\texttt{Roger Rabbit doesn't like spinash}


\textbf{See also:}

\samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{overwritePortion()}
\index{overwritePortion()}
\pdfsubsection{overwritePortion}
\begin{itemize}
	\item procedure \textbf{overwritePortion(}\samp{location} \textbf{:} \textit{int}\textbf{, }\samp{text} \textbf{:} \textit{string}\textbf{, }\samp{size} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{int}}{points to a position of the output stream}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to write}
	\lineiii{\samp{size}}{\textit{int}}{size of the portion to overwrite}
\end{tableiii}
Writes a sequence of characters passed to argument \samp{text}, at the position
of the output stream given by argument \samp{location}. The text overwrites up to
\samp{size} characters and inserts the rest if any. The position starts
counting at 0.\\
About the behaviour of the overwriting:
\begin{itemize}
	\item If there are more than \samp{size} characters in \samp{text},
all \textit{floating locations} that point to \samp{location + size},
or after, are impacted by the insertion of the remaining characters of \samp{text},
and shift for an offset that is worth the size of the text minus the size of the
portion to overwrite.
	\item \samp{overwritePortion(\textit{pos}, \textit{text}, 0)} is worth \samp{insertText(\textit{pos}, \textit{text})}.
	\item If the portion to overwrite is bigger than the length of \samp{text},
all not overwritten characters of the portion are removed.
	\item \samp{overwritePortion(\textit{pos}, "", \textit{size})} removes \samp{\textit{size}} characters from the output stream at position \samp{\textit{pos}}.
\end{itemize}

If the position isn't valid, negative or bigger than the end of the output
stream, an error is raised.

In \textit{expansion mode}, the position 0 points to the first character written
for expansion and cannot exceed the last character written for expansion.

Generally, the position is given by the function \samp{getFloatingLocation()}.

\textbf{Example:}

\texttt{I'll drink a bottle of '@\\
newFloatingLocation("You'll be drunk!");\\
@Margaux' year 1994 before smoking a cigar.@\\
traceLine("Finally, I prefer to drink a bottle of Saint-Estephe,");\\
traceLine("I correct the output:");\\
local iPosition = getFloatingLocation("You'll be drunk!");\\
overwritePortion(iPosition, "Saint-Estephe", 7 /*size of 'Margaux'*/);}

\textbf{Output:}

\texttt{Finally, I prefer to drink a bottle of Saint-Estephe,\\
I correct the output:}

\textbf{Generated text:}

\texttt{I'll drink a bottle of 'Saint-Estephe' year 1994 before smoking a cigar.}


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeText} \ref{writeText()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{populateProtectedArea()}
\index{populateProtectedArea()}
\pdfsubsection{populateProtectedArea}
\begin{itemize}
	\item procedure \textbf{populateProtectedArea(}\samp{protectedAreaName} \textbf{:} \textit{string}\textbf{, }\samp{content} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{protectedAreaName}}{\textit{string}}{name of the protected area ; must be unique into the output stream}
	\lineiii{\samp{content}}{\textit{string}}{the content to copy into the protected area}
\end{tableiii}
This procedure assigns a content to the protected area whose name is passed to
argument \samp{protectedAreaName} and puts the protected area at the current
position of the output stream.

An error is raised if the protected area had already been put into the output stream.

\textbf{Example:}

\texttt{code to generate\\
@\\
if !getProtectedArea("reserved for the user")\\
\makebox[0.8cm][l]{}populateProtectedArea("reserved for the user", "I can't stand an empty protected area" + endl());\\
@I continue the code to generate@}

\textbf{Generated text:}

\texttt{code to generate\\
//\#\#protect\#\#"reserved for the user"\\
I can't stand an empty protected area\\
//\#\#protect\#\#"reserved for the user"\\
I continue the code to generate}


\textbf{See also:}

\samp{getProtectedArea} \ref{getProtectedArea()}, \samp{getProtectedAreaKeys} \ref{getProtectedAreaKeys()}, \samp{remainingProtectedAreas} \ref{remainingProtectedAreas()}, \samp{removeProtectedArea} \ref{removeProtectedArea()}, \samp{setProtectedArea} \ref{setProtectedArea()}
\end{itemize}
\pdflabel{remainingProtectedAreas()}
\index{remainingProtectedAreas()}
\pdfsubsection{remainingProtectedAreas}
\begin{itemize}
	\item function \textbf{remainingProtectedAreas(}\samp{keys} \textbf{:} \textit{tree}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{keys}}{\textit{tree}}{it will contain keys of all protected areas that haven't been placed into the output stream yet}
\end{tableiii}
Looks for all protected areas that haven't been placed into the output stream yet
and puts their keys into the well-named argument \samp{keys}. Both key and value
of items are worth the protected area key.

The list is sorted in the lexicographical order rather than the order of entrance.

The function returns how many protected areas are waiting for being put into the
output stream. If the variable \samp{keys} wasn't declared (\textit{local} or
\textit{global} or as an attribute of \samp{this}), samp{-1} is returned.

\textbf{Example - precedent output generated:}

\texttt{My first protected area:\\
//\#\#protect\#\#"hand-typed code"\\
I don't want to loose this portion of text\\
after another generation!\\
//\#\#protect\#\#"hand-typed code"\\
My second protected area:\\
//\#\#protect\#\#"don't forget me, please!"\\
This portion of text is also very important.\\
//\#\#protect\#\#"don't forget me, please!"\\
Now, you can erase text, I don't care.
}

\textbf{Example - the script:}

\texttt{My first protected area:\\
@\\
local listOfKeys;\\
local iHowMany = remainingProtectedAreas(listOfKeys);\\
traceLine("It remains " + iHowMany + " keys to set into the output file:");\\
foreach i in listOfKeys traceLine(" '" + i + "'");\\
traceLine("writing of protected area 'hand-typed code'");\\
setProtectedArea("hand-typed code");\\
@My second protected area:\\
@\\
set iHowMany = remainingProtectedAreas(listOfKeys);\\
traceLine("It remains " + iHowMany + " keys to set into the output file:");\\
foreach i in listOfKeys traceLine(" '" + i + "'");\\
traceLine("writing of protected area '" + listOfKeys\#front + "'");\\
setProtectedArea(listOfKeys\#front);\\
@Now, you can erase text, I don't care.\\
@\\
set iHowMany = remainingProtectedAreas(listOfKeys);\\
if \$iHowMany != 0\$ error("shouldn't remain any protected area!");\\
traceLine("It doesn't remain any area to set into the output file");}

\textbf{Output:}

\texttt{It remains 2 keys to set into the output file:\\
\makebox[0.8cm][l]{}'don't forget me, please!'\\
\makebox[0.8cm][l]{}'hand-typed code'\\
writing of protected area 'hand-typed code'\\
It remains 1 keys to set into the output file:\\
\makebox[0.8cm][l]{}'don't forget me, please!'\\
writing of protected area 'don't forget me, please!'\\
It doesn't remain any area to set into the output file}

\textbf{Generated text:}

\texttt{My first protected area:\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"hand-typed code"\\
I don't want to loose this portion of text\\
after another generation!\\
//\#\#protect\#\#"hand-typed code"\\
My second protected area:\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"don't forget me, please!"\\
This portion of text is also very important.\\
//\#\#protect\#\#"don't forget me, please!"\\
Now, you can erase text, I don't care.\\
\makebox[2.4cm][l]{}}


\textbf{See also:}

\samp{populateProtectedArea} \ref{populateProtectedArea()}, \samp{getProtectedArea} \ref{getProtectedArea()}, \samp{getProtectedAreaKeys} \ref{getProtectedAreaKeys()}, \samp{removeProtectedArea} \ref{removeProtectedArea()}, \samp{setProtectedArea} \ref{setProtectedArea()}
\end{itemize}
\pdflabel{removeFloatingLocation()}
\index{removeFloatingLocation()}
\pdfsubsection{removeFloatingLocation}
\begin{itemize}
	\item function \textbf{removeFloatingLocation(}\samp{key} \textbf{:} \textit{string}\textbf{) :} \textit{int}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{name of an existing floating position into the output stream}
\end{tableiii}
Removes the \textit{floating location} attached to \samp{key} and returns its position.
If the floating location belongs to a parent output stream, it is removed from the parent.

The function returns a negative integer if the floating location doesn't exist.


\textbf{See also:}

\samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{removeProtectedArea()}
\index{removeProtectedArea()}
\pdfsubsection{removeProtectedArea}
\begin{itemize}
	\item function \textbf{removeProtectedArea(}\samp{protectedAreaName} \textbf{:} \textit{string}\textbf{) :} \textit{bool}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{protectedAreaName}}{\textit{string}}{name of the protected area to remove}
\end{tableiii}
Removes the protected area whose name is passed to the argument \samp{protectedAreaName}
from the list of protected areas that were found into the output file before the
generation and that aren't been put into the output stream yet via the \samp{setProtectedArea()}
or \samp{populateProtectedArea()} functions.

\textbf{Example - precedent output generated:}

\texttt{My first protected area:\\
//\#\#protect\#\#"hand-typed code"\\
I don't want to loose this portion of text\\
after another generation!\\
//\#\#protect\#\#"hand-typed code"\\
My second protected area:\\
//\#\#protect\#\#"don't forget me, please!"\\
This portion of text is also very important.\\
//\#\#protect\#\#"don't forget me, please!"\\
Now, you can erase text, I don't care.
}

\textbf{Example - the script:}

\texttt{Finally, I have changed my mind and I keep only one protected area:\\
@\\
local listOfKeys;\\
local iHowMany = remainingProtectedAreas(listOfKeys);\\
traceLine("It remains " + iHowMany + " keys to set into the output file:");\\
foreach i in listOfKeys traceLine(" '" + i + "'");\\
traceLine("Protected area 'don't forget me, please!' is removed");\\
removeProtectedArea("don't forget me, please!");\\
set iHowMany = remainingProtectedAreas(listOfKeys);\\
traceLine("It remains " + iHowMany + " keys to set into the output file:");\\
foreach i in listOfKeys traceLine(" '" + i + "'");\\
traceLine("writing of protected area 'hand-typed code'");\\
setProtectedArea("hand-typed code");}

\textbf{Output:}

\texttt{It remains 2 keys to set into the output file:\\
\makebox[0.8cm][l]{}'don't forget me, please!'\\
\makebox[0.8cm][l]{}'hand-typed code'\\
Protected area 'don't forget me, please!' is removed\\
It remains 1 keys to set into the output file:\\
\makebox[0.8cm][l]{}'hand-typed code'\\
writing of protected area 'hand-typed code'}

\textbf{Generated text:}

\texttt{Finally, I have changed my mind and I keep only one protected area:\\
\makebox[2.4cm][l]{}//\#\#protect\#\#"hand-typed code"\\
I don't want to loose this portion of text\\
after another generation!\\
//\#\#protect\#\#"hand-typed code"}


\textbf{See also:}

\samp{populateProtectedArea} \ref{populateProtectedArea()}, \samp{getProtectedArea} \ref{getProtectedArea()}, \samp{getProtectedAreaKeys} \ref{getProtectedAreaKeys()}, \samp{remainingProtectedAreas} \ref{remainingProtectedAreas()}, \samp{setProtectedArea} \ref{setProtectedArea()}
\end{itemize}
\pdflabel{resizeOutputStream()}
\index{resizeOutputStream()}
\pdfsubsection{resizeOutputStream}
\begin{itemize}
	\item procedure \textbf{resizeOutputStream(}\samp{newSize} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{newSize}}{\textit{int}}{new size of the output stream}
\end{tableiii}
This procedure changes the size of the output stream to \samp{newSize}. The
only allowed resizing is to reduce the stream (the request is ignored otherwise).
If the current position becomes out of the boundaries, it points to the new end
of the output stream.

\textbf{Example:}

\texttt{I write 22 characters.@\\
traceLine("Current position to the output stream = " + getOutputLocation());\\
setOutputLocation(8);\\
@15@\\
resizeOutputStream(15);}

\textbf{Output:}

\texttt{Current position to the output stream = 22}

\textbf{Generated text:}

\texttt{I write 15 char}
\end{itemize}
\pdflabel{setFloatingLocation()}
\index{setFloatingLocation()}
\pdfsubsection{setFloatingLocation}
\begin{itemize}
	\item procedure \textbf{setFloatingLocation(}\samp{key} \textbf{:} \textit{string}\textbf{, }\samp{location} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{key}}{\textit{string}}{name of a floating position to put into the output stream}
	\lineiii{\samp{location}}{\textit{int}}{the position into the output stream to assign to the key, starting at \samp{0}}
\end{tableiii}
Assigns a position to the \textit{floating location} whose name is passed to argument \samp{key}.

\textbf{Example:}

\texttt{Roger Rabbit doesn't like spinash@\\
setFloatingLocation("Roger Rabbit", 5);\\
traceLine("the floating location 'Roger Rabbit' points just after 'Roger' = " + getFloatingLocation("Roger Rabbit"));}

\textbf{Output:}

\texttt{the floating location 'Roger Rabbit' points just after 'Roger' = 5}

\textbf{Generated text:}

\texttt{Roger Rabbit doesn't like spinash}


\textbf{See also:}

\samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setOutputLocation} \ref{setOutputLocation()}
\end{itemize}
\pdflabel{setOutputLocation()}
\index{setOutputLocation()}
\pdfsubsection{setOutputLocation}
\begin{itemize}
	\item procedure \textbf{setOutputLocation(}\samp{location} \textbf{:} \textit{int}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{location}}{\textit{int}}{points to a position of the output stream}
\end{tableiii}
This procedure moves the position of the output stream elsewhere. The position
passed to the argument \samp{location} starts at 0.

If \samp{location} is worth \textbf{\samp{-1}}, the cursor moves to the end of the output stream.

\textbf{Example:}

\texttt{I write 22 characters.@\\
traceLine("Current position to the output stream = " + getOutputLocation());\\
setOutputLocation(8);\\
@one sentence, finally!@}

\textbf{Output:}

\texttt{Current position to the output stream = 22}

\textbf{Generated text:}

\texttt{I write one sentence, finally!}


\textbf{See also:}

\samp{getFloatingLocation} \ref{getFloatingLocation()}, \samp{allFloatingLocations} \ref{allFloatingLocations()}, \samp{existFloatingLocation} \ref{existFloatingLocation()}, \samp{getOutputLocation} \ref{getOutputLocation()}, \samp{newFloatingLocation} \ref{newFloatingLocation()}, \samp{removeFloatingLocation} \ref{removeFloatingLocation()}, \samp{setFloatingLocation} \ref{setFloatingLocation()}
\end{itemize}
\pdflabel{setProtectedArea()}
\index{setProtectedArea()}
\pdfsubsection{setProtectedArea}
\begin{itemize}
	\item procedure \textbf{setProtectedArea(}\samp{protectedAreaName} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{protectedAreaName}}{\textit{string}}{name of the protected area ; must be unique into the output stream}
\end{tableiii}
This procedure puts a protected area at the current position of the output stream,
and allows preserving the code of the user between two code generations.

A protected area is bounded by the sequence \samp{\#\#protect\#\#"..."}, put into a comment.
The syntax of the comment must conform to the type of the target language expected in the
file \samp{outputFileName}.
So, an HTML file expects \textbf{<!- -} and \textbf{- ->}, a JAVA file is waiting
for \textbf{//} and \textbf{"$\backslash$n"}, ... 
Don't forget to configure correctly the syntax of comment boundaries with procedures
\samp{setCommentBegin()} (see \ref{setCommentBegin()}) and \samp{setCommentEnd()} (see \ref{setCommentEnd()}).

An error is raised if the protected area had already been put into the output stream.

\textbf{Example:}

\texttt{code to generate\\
@\\
setProtectedArea("reserved for the user");\\
@I continue the code to generate@}

\textbf{Generated text:}

\texttt{code to generate\\
//\#\#protect\#\#"reserved for the user"\\
//\#\#protect\#\#"reserved for the user"\\
I continue the code to generate}


\textbf{See also:}

\samp{populateProtectedArea} \ref{populateProtectedArea()}, \samp{getProtectedArea} \ref{getProtectedArea()}, \samp{getProtectedAreaKeys} \ref{getProtectedAreaKeys()}, \samp{remainingProtectedAreas} \ref{remainingProtectedAreas()}, \samp{removeProtectedArea} \ref{removeProtectedArea()}
\end{itemize}
\pdflabel{writeBytes()}
\index{writeBytes()}
\pdfsubsection{writeBytes}
\begin{itemize}
	\item procedure \textbf{writeBytes(}\samp{bytes} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{bytes}}{\textit{string}}{sequence of bytes to write at the current position of the output stream}
\end{tableiii}
Writes a sequence of bytes passed to argument \samp{bytes}, at the current
position of the output stream.

A byte is a couple of hexadecimal digits.

\textbf{Example:}

\texttt{codeworker@\\
writeBytes("4066726565");\\
@.fr@}

\textbf{Generated text:}

\texttt{codeworker@free.fr}


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeText} \ref{writeText()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{writeText()}
\index{writeText()}
\pdfsubsection{writeText}
\begin{itemize}
	\item procedure \textbf{writeText(}\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to write at the current position of the output stream}
\end{tableiii}
Writes a sequence of characters passed to argument \samp{text}, at the current
position of the output stream. It does the same work as the \textbf{@} tag, but
it puts a string into the output stream.

This is the common way to write the symbol \textbf{'@'} into the output stream.

\textbf{Example:}

\texttt{codeworker@\\
writeText("@");\\
@free.fr@}

\textbf{Generated text:}

\texttt{codeworker@free.fr}


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeTextOnce} \ref{writeTextOnce()}
\end{itemize}
\pdflabel{writeTextOnce()}
\index{writeTextOnce()}
\pdfsubsection{writeTextOnce}
\begin{itemize}
	\item procedure \textbf{writeTextOnce(}\samp{text} \textbf{:} \textit{string}\textbf{)}

\begin{tableiii}{l|l|l}{.6}{Parameter}{Type}{Description}
	\lineiii{\samp{text}}{\textit{string}}{sequence of characters to write at the current position of the output stream}
\end{tableiii}
Writes a sequence of characters passed to argument \samp{text}, at the current
position of the output stream, only if the text has never been encountered
previously by a \samp{insertTextOnce()} or a \samp{writeTextOnce()} procedure.

\textbf{Example:}

\texttt{@\\
traceLine("Do you know that Roger Rabbit is tired?");\\
writeTextOnce("Roger Rabbit is tired");\\
traceLine("Once again, Roger Rabbit is tired!");\\
writeTextOnce("Roger Rabbit is tired");\\
traceLine("Once more, Roger Rabbit is tired!");\\
writeTextOnce("Roger Rabbit is tired");\\
traceLine("The message hasn't been repeated into the generated text.");}

\textbf{Output:}

\texttt{Do you know that Roger Rabbit is tired?\\
Once again, Roger Rabbit is tired!\\
Once more, Roger Rabbit is tired!\\
The message hasn't been repeated into the generated text.}

\textbf{Generated text:}

\texttt{Roger Rabbit is tired}


\textbf{See also:}

\samp{insertText} \ref{insertText()}, \samp{insertTextOnce} \ref{insertTextOnce()}, \samp{insertTextOnceToFloatingLocation} \ref{insertTextOnceToFloatingLocation()}, \samp{insertTextToFloatingLocation} \ref{insertTextToFloatingLocation()}, \samp{overwritePortion} \ref{overwritePortion()}, \samp{writeBytes} \ref{writeBytes()}, \samp{writeText} \ref{writeText()}
\end{itemize}
%##end##"generation script functions"

%==========================================================================

\pdflabel{external bindings}
\index{extension!binding to languages}
\pdfchapter{External bindings}

\CodeWorker\ is written is C++ and works as a standalone console application or as a library.
However, it exists some ways to extend \CodeWorker\ that proposes:
\begin{itemize}
	\item to link to a JAVA application,
	\item to declare external functions, developed freely into another library,
\end{itemize}

\pdflabel{JAVA binding}
\index{JNI}
\index{extension!JAVA binding}
\pdfsection{The JAVA binding}
A semi-JNI (Java Native Interface) allows catching all messages of \CodeWorker\ intended to
the console. The developer has to develop its own JNI module in C++ to call the object
\samp{JNIExternalHandling}.
%##markup##"file:JNIExternalHandling.h"
%##begin##"file:JNIExternalHandling.h"

\texttt{
	\makebox[1cm][r]{\textrm{\tiny     }}  // file "JNIExternalHandling.h":\\
	\makebox[1cm][r]{\textrm{\tiny    1}} /* "CodeWorker":    a scripting language for parsing and generating text.\\
	\makebox[1cm][r]{\textrm{\tiny    2}} \\
	\makebox[1cm][r]{\textrm{\tiny    3}} Copyright (C) 1996-1997, 1999-2002 C\'edric Lemaire\\
	\makebox[1cm][r]{\textrm{\tiny    4}} \\
	\makebox[1cm][r]{\textrm{\tiny    5}} This library is free software; you can redistribute it and/or\\
	\makebox[1cm][r]{\textrm{\tiny    6}} modify it under the terms of the GNU Lesser General Public\\
	\makebox[1cm][r]{\textrm{\tiny    7}} License as published by the Free Software Foundation; either\\
	\makebox[1cm][r]{\textrm{\tiny    8}} version 2.1 of the License, or (at your option) any later version.\\
	\makebox[1cm][r]{\textrm{\tiny    9}} \\
	\makebox[1cm][r]{\textrm{\tiny   10}} This library is distributed in the hope that it will be useful,\\
	\makebox[1cm][r]{\textrm{\tiny   11}} but WITHOUT ANY WARRANTY; without even the implied warranty of\\
	\makebox[1cm][r]{\textrm{\tiny   12}} MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU\\
	\makebox[1cm][r]{\textrm{\tiny   13}} Lesser General Public License for more details.\\
	\makebox[1cm][r]{\textrm{\tiny   14}} \\
	\makebox[1cm][r]{\textrm{\tiny   15}} You should have received a copy of the GNU Lesser General Public\\
	\makebox[1cm][r]{\textrm{\tiny   16}} License along with this library; if not, write to the Free Software\\
	\makebox[1cm][r]{\textrm{\tiny   17}} Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA\\
	\makebox[1cm][r]{\textrm{\tiny   18}} \\
	\makebox[1cm][r]{\textrm{\tiny   19}} To contact the author: codeworker@free.fr\\
	\makebox[1cm][r]{\textrm{\tiny   20}} */\\
	\makebox[1cm][r]{\textrm{\tiny   21}} \\
	\makebox[1cm][r]{\textrm{\tiny   22}} \#ifndef \_JNIExternalHandling\_h\_\\
	\makebox[1cm][r]{\textrm{\tiny   23}} \#define \_JNIExternalHandling\_h\_\\
	\makebox[1cm][r]{\textrm{\tiny   24}} \\
	\makebox[1cm][r]{\textrm{\tiny   25}} \#include <string>\\
	\makebox[1cm][r]{\textrm{\tiny   26}} \\
	\makebox[1cm][r]{\textrm{\tiny   27}} \#ifdef CODEWORKER\_JNI\\
	\makebox[1cm][r]{\textrm{\tiny   28}} \#    include "jni.h"\\
	\makebox[1cm][r]{\textrm{\tiny   29}} \#else\\
	\makebox[1cm][r]{\textrm{\tiny   30}} \makebox[0.8cm][l]{}typedef void* JNIEnv;\\
	\makebox[1cm][r]{\textrm{\tiny   31}} \makebox[0.8cm][l]{}typedef void* jobject;\\
	\makebox[1cm][r]{\textrm{\tiny   32}} \makebox[0.8cm][l]{}typedef void* jclass;\\
	\makebox[1cm][r]{\textrm{\tiny   33}} \makebox[0.8cm][l]{}typedef void* jmethodID;\\
	\makebox[1cm][r]{\textrm{\tiny   34}} \makebox[0.8cm][l]{}typedef void* jobjectArray;\\
	\makebox[1cm][r]{\textrm{\tiny   35}} \makebox[0.8cm][l]{}typedef void* jstring;\\
	\makebox[1cm][r]{\textrm{\tiny   36}} \#endif\\
	\makebox[1cm][r]{\textrm{\tiny   37}} \\
	\makebox[1cm][r]{\textrm{\tiny   38}} \#include "CGExternalHandling.h"\\
	\makebox[1cm][r]{\textrm{\tiny   39}} \\
	\makebox[1cm][r]{\textrm{\tiny   40}} \\
	\makebox[1cm][r]{\textrm{\tiny   41}} namespace CodeWorker \{\\
	\makebox[1cm][r]{\textrm{\tiny   42}} \makebox[0.8cm][l]{}class JNIExternalHandling : public CGExternalHandling \{\\
	\makebox[1cm][r]{\textrm{\tiny   43}} \makebox[0.8cm][l]{}private:\\
	\makebox[1cm][r]{\textrm{\tiny   44}} \makebox[1.6cm][l]{}JNIEnv\& \_theEnv;\\
	\makebox[1cm][r]{\textrm{\tiny   45}} \makebox[1.6cm][l]{}jobject \_pJNIObject;\\
	\makebox[1cm][r]{\textrm{\tiny   46}} \\
	\makebox[1cm][r]{\textrm{\tiny   47}} \makebox[1.6cm][l]{}jclass \_pClass;\\
	\makebox[1cm][r]{\textrm{\tiny   48}} \makebox[1.6cm][l]{}jmethodID \_pInputLineMethod;\\
	\makebox[1cm][r]{\textrm{\tiny   49}} \makebox[1.6cm][l]{}jmethodID \_pTraceLineMethod;\\
	\makebox[1cm][r]{\textrm{\tiny   50}} \makebox[1.6cm][l]{}jmethodID \_pTraceTextMethod;\\
	\makebox[1cm][r]{\textrm{\tiny   51}} \\
	\makebox[1cm][r]{\textrm{\tiny   52}} \makebox[0.8cm][l]{}public:\\
	\makebox[1cm][r]{\textrm{\tiny   53}} \makebox[1.6cm][l]{}JNIExternalHandling(JNIEnv\& theEnv, jobject pJNIObject);\\
	\makebox[1cm][r]{\textrm{\tiny   54}} \makebox[1.6cm][l]{}virtual \~{}JNIExternalHandling();\\
	\makebox[1cm][r]{\textrm{\tiny   55}} \\
	\makebox[1cm][r]{\textrm{\tiny   56}} \makebox[1.6cm][l]{}jstring executeScript(jobjectArray listOfCommands);\\
	\makebox[1cm][r]{\textrm{\tiny   57}} \\
	\makebox[1cm][r]{\textrm{\tiny   58}} \makebox[1.6cm][l]{}virtual std::string inputKey(bool bEcho);\\
	\makebox[1cm][r]{\textrm{\tiny   59}} \makebox[1.6cm][l]{}virtual std::string inputLine(bool bEcho);\\
	\makebox[1cm][r]{\textrm{\tiny   60}} \makebox[1.6cm][l]{}virtual void traceLine(const std::string\& sLine);\\
	\makebox[1cm][r]{\textrm{\tiny   61}} \makebox[1.6cm][l]{}virtual void traceText(const std::string\& sText);\\
	\makebox[1cm][r]{\textrm{\tiny   62}} \makebox[0.8cm][l]{}\};\\
	\makebox[1cm][r]{\textrm{\tiny   63}} \}\\
	\makebox[1cm][r]{\textrm{\tiny   64}} \\
	\makebox[1cm][r]{\textrm{\tiny   65}} \#endif}


\textsc{line 53:}  the constructor of the C++ class \samp{JNIExternalHandling} that diverts the messages
 sent to the console by \CodeWorker\ . It must be called into the function of a C++
 JNI module. The two parameters are always passed by JAVA when calling a native
 interface.
 \begin{tableiii}{l|l|l}{0.6}{Parameter}{Type}{Description}
		\lineiii{theEnv}{JNIEnv\&}{the environment variable for JNI}
		\lineiii{pJNIObject}{jobject}{a reference to the JAVA instance whose class name
 		is chosen by the developer freely, and called \textit{mypackage\_MyClass} below}
 \end{tableiii}
 The constructor only serves to launch properly \samp{executeScript()} on the instance,
 and to call functions that catch messages intended to the display.\\
\textsc{line 56:}  the method \samp{executeScript()} expects a command line to execute by \CodeWorker\ 
 and it returns an error message if something failed, or and empty string if success.
 The method must be called into a C++ JNI module that first calls the constructor seen
 before:\\ 
 \texttt{/*\\ 
 * Class:     \textit{mypackage\_MyClass}\\ 
 * Method:    \textit{myMethod}\\ 
 * Signature: ([Ljava/lang/String;)Ljava/lang/String;\\ 
 * \begin{tableiii}{l|l|l}{0.6}{Parameter}{Type}{Description} \lineiii{theEnv}{JNIEnv\&}{the environment variable for JNI} \lineiii{pJNIObject}{jobject}{a reference to the JAVA instance} \lineiii{listOfCommands}{String[]}{the command line that \CodeWorker\ must execute} \end{tableiii}
 */\\ 
 JNIEXPORT jstring JNICALL Java\_\textit{mypackage\_MyClass\_myMethod}\\ 
 (JNIEnv *pEnv, jobject pJNIObject, jobjectArray listOfCommands)\\ 
 \{\\ 
 	JNIExternalHandling theExecution(*pEnv, pJNIObject);\\ 
 	return theExecution.executeScript(listOfCommands);\\ 
 \}}\\
\textsc{line 59:}  the callback method \samp{inputLine()} is waiting for a line that the user will put
 into the standard input, the keyboard generally.
 The method must be implemented into the JAVA class \textit{mypackage\_MyClass}
 under the prototype: \samp{public String inputLine(boolean bEcho)}, as seen further.\\
\textsc{line 60:}  the callback method \samp{traceLine()} passes the message intended to the console to the argument
 \samp{sLine}. The method must be implemented into the JAVA class \textit{mypackage\_MyClass}
 under the prototype: \samp{public void traceLine(String sLine)}, as seen further.\\
\textsc{line 61:}  the callback method \samp{traceText()} passes the message intended to the console to the argument
 \samp{sText}. The method must be implemented into JAVA class \textit{mypackage\_MyClass}
 under the prototype: \samp{public void traceText(String sText)}. An example of source
 code that illustrates the JAVA part of the JNI may be:\\ 
 \texttt{package \textit{mypackage};\\ 
 ...\\ 
 public class \textit{MyClass} \{\\ 
 \makebox[0.8cm][r]{}...\\ 
 \makebox[0.8cm][r]{}public native String \textit{myMethod}(String[] listOfCommands);\\ 
 \\ 
 \makebox[0.8cm][r]{}public String inputLine(boolean bEcho) \{\\ 
 \makebox[1.6cm][r]{}byte[] tbLine = new byte[512];\\ 
 \makebox[1.6cm][r]{}System.in.read(tbLine);\\ 
 \makebox[1.6cm][r]{}return new String(tbLine);\\ 
 \makebox[0.8cm][r]{}\}\\ 
 \\ 
 \makebox[0.8cm][r]{}public void traceLine(String sLine) \{\\ 
 \makebox[1.6cm][r]{}System.out.println(sLine);\\ 
 \makebox[0.8cm][r]{}\}\\ 
 \\ 
 \makebox[0.8cm][r]{}public void traceText(String sText) \{\\ 
 \makebox[1.6cm][r]{}System.out.print(sText);\\ 
 \makebox[0.8cm][r]{}\}\\ 
 \}}

 Before calling the native method for the first time, don't forget to load your library:\\ 
 \texttt{try \{\\
 \makebox[0.8cm][r]{}System.loadLibrary("\textit{MyLibrary}");\\ 
 \} catch(Exception exception) \{\\ 
 \makebox[0.8cm][r]{}System.out.println("Unable to load the library: '" + exception.toString() + "'");\\ 
 \}}

 The following source code is an example of implementation for calling the native method,
 to put into a method of \textit{MyClass}:\\
 \texttt{String sErrorMessage = null;\\ 
 try \{\\ 
 \makebox[0.8cm][r]{}sErrorMessage = \textit{myMethod}(_tsCommands);\\ 
 \} catch(UnsatisfiedLinkError exception) \{\\ 
 \makebox[0.8cm][r]{}System.out.println("Unable to link to function '\textit{myMethod}(String[])' into the library: '" + exception.toString() + "'");\\ 
 \} catch(Exception exception) \{\\ 
 \makebox[0.8cm][r]{}System.out.println("Unexpected exception while calling function '\textit{myMethod}(String[])' into the library: '" + exception.toString() + "'");\\ 
 \}}\\
%##end##"file:JNIExternalHandling.h"

\pdflabel{C++ binding}
\index{extension!C++ binding}
\pdfsection{Developing external functions}
We have seen that functions, if not predefined, are implemented by the developer via the script
language. But how to populate \CodeWorker\ with applicative data, or to interact with another
libraries?

Let imagine that you have developed a lot of powerful functionalities for your Business and
that you want to take advantage of parsing and source code generation processes into your application.

It may be a devoted Server Page, for example: you want to apply templates on your applicative
data to display them properly in HTML or anything else and you have integrated a tiny HTTP server.
You might implement some external functions that will be called by the template \CodeWorker\ 
scripts and that will populate the parse tree with your applicative data, coming from a
database or the memory of the application or anywhere.

The prototype of an external function is preceded by the \samp{external} keyword and its body
isn't implemented:\\
\samp{
	\textit{external-declaration} ::= \textbf{"external"} \textit{function-prototype} \textbf{';'}
}

An external function conforms to the following C++ \samp{typedef}s:\\
\samp{namespace CodeWorker \{\\
	\makebox[0.8cm][r]{}typedef std::string (*\textbf{EXTERNAL\_FUNCTION})(CppParsingTree\_var**);\\
	\makebox[0.8cm][r]{}typedef std::string (*\textbf{EXTERNAL\_TEMPLATE\_DISPATCHER\_FUNCTION})(const std::string\&, CppParsingTree\_var**);\\
\}}\\
where \samp{EXTERNAL_FUNCTION} represents the general C++ prototype of a classical function or an
instantiated template function and \samp{EXTERNAL_TEMPLATE_DISPATCHER_FUNCTION} represents
the C++ prototype of a template function dispatcher and that must be present as soon as at
least one instantiated template function exists.

\textbf{Example:}

\texttt{external function f<"x">(i, j:reference, k:variable);\\
external function f<"y">(i, j:reference, k:variable);\\
external function g(i, j:reference, k:variable);}

\pdfsubsection{Doing the C++ binding by hand (good luck!)}

The C++ prototype of function \samp{f<"x">(i, j:reference, k:variable)} conforms to the
\samp{EXTERNAL_FUNCTION} \samp{typedef} and may be
\samp{std::string f_x(CppParsingTree_var** tParameters)} for example.

As it is an instantiated template function, we need to declare a function whose role is to
dispatch dynamically the template functions instantiated on
\samp{f<...>(i, j:reference, k:variable)}. Its C++ prototype must conform to the
\samp{EXTERNAL_TEMPLATE_DISPATCHER_FUNCTION} \samp{typedef} and may be
\samp{std::string f(const std::string\& sTemplateKey, CppParsingTree_var** tParameters)}
for example. This function must implement the dispatching to the instantiated function
corresponding to the \textit{template key}. If the template key is empty, it means that
the function must evaluate its own code (\samp{f<"">(...)} is equivalent to \samp{f(...)} that
is a classical call to a standard function, see \ref{template function}).

The C++ prototype of function \samp{g(i, j:reference, k:variable)} conforms to the
\samp{EXTERNAL_FUNCTION} \samp{typedef} and may be
\samp{std::string g(CppParsingTree_var** tParameters)} for example.

\CodeWorker\ exists as a library and provides some C++ headers:
\begin{itemize}
	\item \textit{"CGRuntime.h"}: allows accessing to all functions and procedures of the
		interpreter and to the \samp{typedef}s seen before,
	\item \textit{"UtlException.h"}: declares the unique type of exception raised by the
		functions of \textit{"CGRuntime.h"} and called \samp{CodeWorker::UtlException},
	\item \textit{"CppParsingTree.h"}: declares the parse tree, such as:
		\begin{itemize}
			\item \samp{CodeWorker::CppParsingTree_var}: declares a variable that points to
				a parse tree,
			\item \samp{CodeWorker::CppParsingTree_value}: declares a parse tree intended
				to be pushed to the stack as a local variable; for convenience, a parse tree
				inherits from \samp{CodeWorker::CppParsingTree_var},
		\end{itemize}
\end{itemize}

External functions must be registered into the library. A unique key represents a function,
instantiated or classical, which is the prototype of the function expressed close to the
syntax of the scripting language. For example:\\
\begin{itemize}
	\item the function \samp{f<"x">(i, j:reference, k:node)} has the following unique key:
		\textit{"f<x>(i : value, j : reference, k : node)"},
	\item the dispatching function \samp{f(i, j:reference, k:variable)} has the following unique key:
		\textit{"f(i : value, j : reference, k : node)"},
	\item the function \samp{g(i, j:reference, k:variable)} has the following unique key:
		\textit{"g(i : value, j : reference, k : node)"},
\end{itemize}
Notice that the template key of the instantiated functions is written without double quotes
and that the argument mode is always specified. A space is inserted around the colon that
separates the name and the mode of an argument. A space is inserted after the comma that
separates two arguments.

To register a classical or an instantiated function, the C++ function
\samp{CodeWorker::CGRuntime::registerExternalFunction(...)} must be called:\\
\texttt{
	CodeWorker::CGRuntime::registerExternalFunction("f<x>(i : value, j : reference, k : node)", f_x);\\
	CodeWorker::CGRuntime::registerExternalFunction("g(i : value, j : reference, k : node)", g);
}

To register a dispatcher of template functions, the C++ function
\samp{CodeWorker::CGRuntime::registerExternalTemplateDispatcherFunction(...)} must be called,
but don't forget that this dispatcher function is also a classical function with an empty
\textit{template key} (declared as \samp{f\_} for example):\\
\texttt{
	CodeWorker::CGRuntime::registerExternalTemplateDispatcherFunction("f(i : value, j : reference, k : node)", f);\\
	CodeWorker::CGRuntime::registerExternalFunction("f(i : value, j : reference, k : node)", f\_);
}

Now, the body of the function \samp{f}, which takes the role of the template dispatcher, must
be implemented.

\pdfsubsection{Generating the C++ binding automatically}

It is very tedious to do the C++ binding by hand. Fortunately, \CodeWorker\ can generate all
the C++ binding of external functions automatically. And then, you'll just have to populate
the body of the C++ external functions.

The option \samp{-c++external} of the command line asks \CodeWorker\ for generating the C++
binding. A file name or the radical of a file (without extension) follows the option.
\CodeWorker\ will put together all external functions it has encountered into the
\textit{leader script} and all its dependencies (use options \samp{-script} or \samp{-compile}
to specify the script to explore recursively). It no error was raised during the execution
(option \samp{-script}) or the compilation (option \samp{-compile}), two files are generated:
\begin{itemize}
	\item The first one, built by taking the radical of the file passed to the command line
		and adding the extension \textit{".h"}, will describe the declaration of all external
		functions,
	\item The second one, built by taking the radical of the file passed to the command line
		and adding the extension \textit{".cpp"}, will describe the skeleton of all
		external functions and the implementation of all template dispatchers; you just have
		to type the user code into the protected areas,
\end{itemize}
A \samp{init()} function is generated that registers all functions correctly and that must
be called explicitly by the user before calling an external function into a \CodeWorker\ script.


%==========================================================================
\label{the integrated debugger}
\index{debug}
\index{statement modifier!debug}
\index{debugger}
\pdfchapter{The integrated debugger}

The integrated debugger assists in debugging your scripts running. There is no GUI to require
and display debug information, just a console.

\index{debugger!opening}
\pdfsection{Opening the debugger}
If you pass option \samp{-debug} on the command line, the debugger will automatically open
with the interpreter suspended, and the first line to execute will be displayed. If you
want to delimit the debugging session to a part of the project only, type keyword \samp{debug}
just before the statement to debug. Generally, the statement is a procedure that interprets
a parsing script or a pattern script, such as \samp{generate} or \samp{parseAsBNF}.

\pdfsection{General functionalities}
During the execution, the debugger may take the control when:
\begin{itemize}
	\item a breakpoint in the source code is encountered,
	\item a step-by-step has been required,
	\item the developer goes to the next instruction,
	\item an error is thrown, 
\end{itemize}

Once the debugger is open and the interpreter is suspended, you can work with the program in the following ways:
\begin{itemize}
	\item inspect the call stack,
	\item inspect local variables,
	\item step through functions,
	\item set and clear breakpoints,
	\item evaluate some expressions,
\end{itemize}

The debugger is very convenient during the writing of a parsing script, for example. At any
time, it is possible to inspect the parse tree and to understand why it isn't populated as
expected.

\index{debugger!commands}
\pdfsection{Commands of the debugger}
All available commands are reported below:
\begin{tableii}{l|l}{.6}{Option}{Description}
\lineii{\samp{b} \textit{filename}\\
		\samp{at} \textit{line}\\
		or \samp{breakpoint}}{To set a breakpoint in file \textit{filename} at line
								\textit{line}\\}
\lineii{\samp{c} or \samp{clear}}{To clear all breakpoints}
\lineii{\samp{c} \textit{filename}}{To clear all breakpoints into file \textit{filename}}
\lineii{\samp{c} \textit{filename} at \textit{line}}
			{To clear breakpoint located at \textit{line} into file \textit{filename}.\\}
\lineii{\samp{d} [\textit{height}]?\\
		or \samp{display}}
			{To display the current line the execution has suspended. If the argument
			\textit{height} was specified, it displays \textit{height} lines before and after
			the current line.\\}
\lineii{\samp{d} \textit{size}}
			{To display the current line the execution has suspended with \textit{size} lines
				before and \textit{size} lines after.\\}
\lineii{\samp{h} or \samp{help} or \samp{?}}{To display help about commands.}
\lineii{\samp{l} or \samp{local}}{To display local variables present on the stack.}
\lineii{\samp{n} or \samp{next}}{To go to the next statement.}
\lineii{\samp{o} or \samp{object}}{To inspect a variable.}
\lineii{\samp{q} or \samp{quit}}{To quit the debug session.}
\lineii{\samp{r} or \samp{run}}{To continue up to the next suspending cause, breakpoint or
								error thrown.}
\lineii{\samp{s} or \samp{step}}{To go into function calls or to the next statement.}
\lineii{\samp{stack}}{To inspect the call stack.}
\lineii{\samp{t} or \samp{trace}}{To evaluate an expression.}
\end{tableii}

Notice that the debugger never stops on a brace or on a text between \textbf{'@'}. So,
breakpoints will have no impact on them, and \samp{step} or \samp{next} commands will ignore
them.

\label{quantifying scripts}
\index{profiling}
\index{quantify}
\index{statement modifier!quantify}
\index{scripts!profiling}
\pdfchapter{Quantifying scripts}

\pdfsection{Presentation}

\CodeWorker\ integrates a profiling tool that measures the coverage of scripts you are
interpreting and the global time every functions and procedures have run.
It helps you quickly and easily find the untested parts of your code and the frequency of
passing through code lines. It pinpoints performance bottlenecks quickly. No development time 
will be wasted tuning code that runs too slow, helping you to develop scripts faster.

Interpreting scripts in quantify mode is about 5\% slower than in standard mode.

\pdfsection{Running the profiling tool}

The profiling tool may be launched in two ways:
\begin{itemize}
	\item on the command line with option \samp{-quantify [\textit{HTML-filename}]?} to
		instrument all scripts,
	\item on a statement into a script. The part of the script that belongs to the statement
		 and all visited scripts (via \samp{generate} or \samp{parseAsBNF} or ...) will be
		examinated. The statement to profile is then prefixed by the statement's modifier
		\textit{\samp{quantify}}. For instance:\\
		\texttt{quantify generate("JAVAObject.gen", myClass, myClass.name + ".java")}
		
		The BNF syntax is:\\
		\samp{quantify [\textbf{'('} \textit{HTML-filename} \textbf{')'}]? \textit{statement}}
\end{itemize}

\pdfsection{The profiling results}

When the \samp{-quantify} option (or the statement's modifier \samp{quantify}) isn't followed
by an HTML file name, the synthetic profiling results are reported to the console:
\begin{itemize}
	\item each user function appears, recalling the script file where it was defined, and
		giving how many times it was executed followed by the total execution time in
		milliseconds,
	\item each predefined function or procedure appears, giving how many times it was executed,
	\item the proportion of source code that was executed, considering visited scripts only,
\end{itemize}

If a file name was specified, the HTML output file highlights all visited script, so as to
show parts of the code that are executed a lot and those that are less executed. Each visited
line is prefixed by the number of times the controlling sequence has run on it.

Some points to notice:
\begin{itemize}
	\item the function called \samp{not} represents the unary boolean operator \textbf{!},
	\item the instruction called \samp{__RAW_TEXT_TO_WRITE} represents the text of a
		\textit{pattern script} to put into the output stream directly, which is inlayed in
		\textbf{@...@} or in \textbf{\%>...<\%} tags,
	\item the instruction called \samp{writeText} represents an expression of a
		\textit{pattern script} that was inlayed in \textbf{@...@} or in \textbf{<\%...\%>}
		tags,
\end{itemize}

%==========================================================================

\pdfchapter{Integrating source code generation into a project}

\pdfsection{Reusability}

IT people is convinced about the importance of reusability, which is applied to designs,
source codes, technical and functional components:
\begin{itemize}
	\item designs offer to reuse some modeling processes called \textit{design patterns},
	\item an object language answers to the concept of reusability with:
		\begin{itemize}
			\item the polymorphism,
			\item the inheritance,
			\item the encapsulation,
		\end{itemize}
		Some of them provide the reflectivity, which opens a large field of possibilities,
		thanks to a kind of generalization of the source code. Some others bring template
		functions and classes that is another step towards the factorization of the source
		code.
	\item components may be seen as a black box intented to provide services, and the way to
		reuse a component is to embed it into a module (object, library, executable, server)
		and to offer an interface for accessing its services.
\end{itemize}

Some points are relative to the concept of reusability, considering the capitalization of
skills, the IT knowledge, independently of the Business, but have no satisfying answers
today:
\begin{itemize}
	\item \textbf{How to integrate any kind of formal representation as a part of the project's
		modeling design?}\\
		A design is built under a modeling tool generally, but the modeling tool cannot
		accept to enrich the design with a very exotic format that conforms to an unknown
		syntax and that requires to change the internal representation of the \textit{world}
		and the way to implement it.
	\item \textbf{How to automatize the implementation of a \textit{design pattern}?}\\
		Perhaps that, starting from the design, your modeling tool offers the generation
		of some classical \textit{design patterns}. Perhaps that it is possible, under some
		constraints, to implement its own \textit{design patterns} via the modeling tool.
		But what about the flexibility and the readability and the convenience for use and
		the coverage of wishes?
	\item \textbf{How to automatize the bridge between the design and the implementation?}\\
		Modeling tools offer to generate the source code corresponding to the design in
		some classical languages. The implementation is often restricted to write the skeleton
		of classes and to implement some \textit{design patterns}. If you want to choose
		another language:\\
		\begin{itemize}
			\item you may have to pay fees for a new package,
			\item you may have to adapt some properties that depend on the target language,
		\end{itemize}
		The generated code is quite poor, and you feel that it should be possible to generate
		more from the design.
	\item \textbf{How to customize the style of the implementation, the features to include?}\\
		It depends on the flexibility of your modeling tool. The style for implementing some
		parts (attributes, methods) can be customized often. But changing completely the way
		an implementation is done may become very tedious and unreadable (if possible!). For
		example:
		\begin{itemize}
			\item to move a behaviour out of the class and to put it into a \textit{visitor-like}
				design pattern where all must be implemented,
			\item to implement a wrapper that inserts and updates and extracts objects into/from
				a database, where all convenient stored procedures are generated too,
		\end{itemize}
		The simplest and the most flexible it appears to change the generation, the furthest
		you might progress in the complexity and the proposal of new features. For instance,
		if the chosen syntax for writing JAVA or C++ programs was XML, which is very fashionable
		for the easiness it is lending itself to a computer processing, the human being wouldn't
		have been able to write as complex and powerful programs as today, because the syntax
		isn't adapted and too verbose: too much symbols should be required to express simple
		concepts.\\
		If you are convinced of this argument, you will be perhaps convinced that the code
		generation should be processed thanks to a language as much adapted as possible to
		simplify its description. It eliminates XML, but also Visual Basic and all
		\textit{large domain} programming languages (C, C++, JAVA, Fortran, ...).
	\item \textbf{How to preserve a project of the constraining and often definitive choice of
		a target language}?\\
		The only way to keep a project independent from the language's choice is to report
		the details of implementation as much as possible into the design. The most convenient
		way to express the details of implementation is often to use a programming language,
		but not systematically. If so, this programming language should be devoted to the
		phase of modeling of the design and might be translated to a classical programming
		language.\\
		Writing to a such language makes rather tricky the validation if no adapted environment
		is available, so it slows down the development process: changing the design and next,
		generating code and next, testing and next, taking back corrections to the design and
		let's continue the loop. If not a lot of protected areas (implementation present in
		the source code of the target language only, nothing coming from the design) have been
		populated, a good deal might be to support a set of scripts for each targeted language.
		The difficulty lies in keeping all sets of scripts at the same level.
		The inconvenient of supporting multi languages is how to refer to standard libraries:
		some functionalities exist on a language, some other not, or are exploited
		differently. However, it is possible to minimize the impact of choosing a language and
		to isolate rigorously what depends on a programming language exclusively.
	\item \textbf{How to propagate a new feature into a lot of source files?}\\
		The new feature may consist of serializing all business objects in a XML stream, for
		instance. It is impossible to implement it with the reflectivity as in JAVA, because
		one cannot distinguish between an aggregation and a common association, which don't
		lead to the same serialization (the description of the aggregated object is embedded
		into the description of the parent). The most convenient way is to dispose of the
		modeling design and to modify the process of generation as simply as possible.
	\item \textbf{How to limit strongly on the implementation, the impact of modifying the
		modeling design?}\\
		The most information exploitable by the computer you put into the design, the less
		source code or documentation you will have to modify or to add by hand each time the
		design will change. The design must be able to express as much concepts as possible,
		which will have to be implemented automatically.
	\item \textbf{How to automatize the implementation of an architecture?}
		Another underlying question: how to keep independent of the choice of the architecture
		while building the core of applications or modules? If you don't dispose of tools for
		generating automatically the layer of communication with the framework you have chosen:
		\begin{itemize}
			\item you will do it by hand and waste a lot of time for that,
			\item you will exploit some facilities provided by the framework to integrate your
				implementation, but you will write a framework-dependent source code to help
				accessing the functional part (see \samp{J2EE} for example).
		\end{itemize}
		In both cases, the required investment for implementing the layer will discourage you
		to rewrite it later for another framework.
	\item \textbf{How to get back the IT knowledge to another project?}
		You hope that some developers that own the technical skills will not leave you before
		the end and that will agree to work on the same technologies.
\end{itemize}
\CodeWorker\ proposes an answer for each of these points.

\pdfsection{The interest of controlling the format of the design}
The first interest of controlling the format of the design is to be able to acquire data into
the source code generator obviously.

The second one is to allow adapting a modeling language to specific needs. It may be to
enrich a \textit{UML}\footnote{Unified Modeling Language} design with some features that are
necessary to a better mapping to implementation, if you consider that \textit{UML} isn't
expressive enough to allow a source code generation as fine as expected and not depending on the
target language. Today, thanks to \textit{Rational ROSE}, some more detailed information can
be added to an \textit{UML} design, but they are depending on the target language. For
instance, if a method's parameter has to be given by reference, the designer has to know that
he wants to generate \textit{C++} and then, he writes \samp{std::string\&} explicitly as the
correct translation. Then, the design cannot be taken out for a \textit{JAVA} code
generation after. Finally, there is a strong dependency between the design and the language
which will be used for generation.\\
So, some extensions might be brought on \textit{UML} for remaining free from the choice of
the target language:
\begin{itemize}
	\item containers, such as \samp{list<\textit{value-type}>} or \samp{hashtable<\textit{key-type}, \textit{value-type}>}
		or \samp{set<\textit{value-type}>},
	\item \samp{PK<\textit{basic-type}>} for an attribute that holds the role of a kind of
		\textit{primary key},
	\item conditions of existence of an attribute that determine whether an optional
		attribute must be populated or not,
	\item checking rules that must be valid if the attribute exists,
	\item definition of constructors,
	\item a little \textit{design pattern} called \textit{build}, which is applied to
		aggregations and that generates a \samp{build<\textit{aggregation-name}>} method for
		each constructor of the aggregated object,
	\item a little \textit{design pattern} called \textit{add}, which is applied to lists
		of aggregations for building new instances and adding them automatically into the lists,
	\item \samp{const} and \samp{static} and \samp{virtual} (or \samp{final} keyword, it depends
		on what is admitted between C++/JAVA philosophy for polymorphism) as specifiers
		for methods,
	\item the parameter modes:
		\begin{itemize}
			\item \samp{in}: parameter is given by reference and can't be changed,
			\item \samp{out}: parameter will be created and assigned into the method,
			\item \samp{inout}: parameter is given by reference and allows changing,
			\item nothing: parameter is given by value (copied into the stack in C++),
		\end{itemize}
	\item the \samp{throw<\textit{exception-type}>} to specify what kind of exceptions might
		be raised by a method,
	\item some \textit{design patterns}:
		\begin{itemize}
			\item the \samp{visitor},
			\item the redirection of methods and accessors to an encapsulated object,
			\item the multi-dispatching like in ADA,
		\end{itemize}
	\item some free annotations (perhaps not reusable properly), such as \samp{sql}, to specify
		how to map the design to a SQL schema (attributes to make persistent, objects to map
		to a table or to merge to another, ...) and to generate the stored procedures for
		inserting and deleting and selecting objects,
\end{itemize}
The advantage of enriching \textit{UML} is that one can draw the design into a modeler, under
\textit{RATIONAL Rose} for instance, and to put extensions into. It becomes less readable and
the project cannot be generated with the modeler anymore, but classes and relationships are
built and displayed in a very convenient way. Of course, the design's file must be readable
by \CodeWorker\ and that's the case for \textit{"*.mdl"} files, which are produced by
\textit{RATIONAL Rose}\footnote{This isn't advertising!}. See the \textbf{script repository}
on \WebSite\ for taking the adapted parsing script back.

If the readability has suffered too much of adding all these features in a graphical modeler or
if the data you want to handle are far from a \textit{UML} representation, you can develop your
own modeling language or to adapt one of those proposed into the \textit{script repository}.

Just a point to notice: we don't care about the syntax of the designs to parse, but
the structure of the parse tree is very important to warrant the reusability. So, if you
want to improve a modeling language provided into the \textit{script repository}, be careful
about changes you'll made on the parse tree. Adding new attributes on nodes have no impact
on the existing \textit{generation} scripts, but removing or renaming some attributes of the
parse tree will change the generated text (some expected attributes will not be found).

So, an effort must be made to document as much as possible the structure of the parse tree,
to avoid diverging, so as to allow the reusability of your work or to reuse the work of
somebody else.

\pdfsection{Driving the implementation with CodeWorker}
\CodeWorker\ provides a scripting language where the syntax is adapted for parsing and code
generation tasks. It proposes an easy way to navigate along parse trees too. These three main
aspects allow both acquiring data and generating any kind of free text in a very convenient way
(adapted syntax and data structures).

\CodeWorker\ offers some basic functionalities for handling files and directories, which avoid
using shell or \textit{Perl} scripts, while building development/test environments within
a team for generating/compiling/debugging/sharing source code. The data structure of tree and
the \samp{foreach...cascading} statement (see \ref{foreach}) provide a very convenient way to
visualize/navigate along directories.

\TODO\ ...

%==========================================================================

\pdfchapter{Tutorials}

\begin{tableii}{l|l}{0.8}{Project}{Description}
	\lineii{JAVA connector}{A use-case that demonstrates how to use the JNI interface of
		\CodeWorker\ for running it via a JAVA application.\\}
	\lineii{TO DO}{A use-case that demonstrates how to exploit the \CodeWorker\ library inside
		a C++ application that requires parsing and source code generation.\\}
	\lineii{Server Page}{A use-case that demonstrates how to implement external functions for
		interacting between \CodeWorker\ and a C++ module (library or application).}
\end{tableii}

%==========================================================================

\printindex
\end{document}
