%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%% 
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%% 
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced
%% professionals having in-depth computer knowledge. Users are therefore
%% encouraged to load and test the software's suitability as regards
%% their requirements in conditions enabling the security of their
%% systems and/or data to be ensured and, more generally, to use and
%% operate it in the same conditions as regards security.
%% 
%% The fact that you are presently reading this means that you have had
%% knowledge of the CeCILL-A license and that you accept its terms.
%%
%%
%% ViTE developers are:
%%
%%        - COULOMB Kevin
%%        - FAVERGE Mathieu
%%        - JAZEIX Johnny
%%        - LAGRASSE Olivier
%%        - MARCOUEILLE Jule
%%        - NOISETTE Pascal
%%        - REDONDY Arthur
%%        - VUCHENER Clément 
%%

\subsection{Representation of the file trace line by line}
\subsubsection{Introduction}
A line is a syntaxical unit in a file following the Paj\'e trace format. Tokens are supplied by a File (a class which encapsulates a std::ifstream). In Paj\'e file trace format, a line is the beginning of a definition, the end of a definition, a definition or an event.

For example :
\begin{itemize}
\item '\%EventDef	PajeDefineContainerType	1'
\item '\%	Name	string'
\item '111 1.03305 MT 31:11392 315706-13 112'
\end{itemize}

\subsubsection{Implementation}

Line object stands for a line. The method fill\_line() fill the object. It enables the item() method to access line's tokens : the item() method is an indexed access to line's token.

\paragraph{Construction of a line}
A line is built by fill\_line() that consists in append character while they do a token and as long as the current token read is different from \verb?'\n'?.

\paragraph{Storage}
A private std::vector$<$std::string$>$ stores line's tokens. Actually there is no use of an indexed access. The item() method could simply supply the next token of a line.

\subsection{Representation of the definitions described in the trace file}
\subsubsection{Introduction}

A Definition is the definition of events found while parsing the file. It is always composed by a field "name", with other caracteristics of the event such as type or values.
The set of definition is stored in a table. The definition and its identifiers are paired. For example, with this file trace~:

\begin{verbatim}
%EventDef PajeDestroyContainer 8
% Time date 
% Name string
% Type string 
%EndEventDef
%EventDef PajeDefineStateType 3
% Alias string
% ContainerType string
% Name string
%EndEventDef
\end{verbatim}
The table of definitions will be \{(8, d1),(3,d2)\}, the d1 definition \{"PajeDestroyContainer",\{f1,f2,f3\}\} and the f1 field \{"Alias", "string"\}.

\subsubsection{Implementation}
Extensible definition fields are stored in a std::vector. Couples of definition and id are available in a std::map$<$int,Definition$>$ hash table.

\subsection{Acknowledge of definitions' lines}
\subsubsection{Introduction}

ParserDefinitionDecoder performs a received Line which starts with percent.

\subsubsection{Definition}
A field Line is a Line with the two first tokens that are the name of a variable and a name.
A EventDef Line is a Line with the first token that is EventDef.
A EndEventDef Line is a Line with the first token that is EndEventDef.

A definition is a set of lines that begins by an EndEventDef Line, have an indefinite number of fields Line and ends with an EndEventDef Line.

\subsubsection{Automaton of definition}
Implementation faithfully uses the automaton described. 

Automaton reaches "in a definition" when an EventDef Line is read and instanciated a new definition which enables :
\begin{itemize}
\item reading a field Line : which is translated and read fields are added to the current definition.
\item reading an EndEventDef Line : which consists in storing the current definition in the table and fall in "out of a definition".
\end{itemize}

\subsubsection{Specification}

A ParserDefinitionDecoder can be instanciated by an empty constructor.

The store\_definition() method requires a filled Line Object which starts with percent tokens and returns when this line is read.

get\_definition() enables access to the table of definition.

\subsection{Event parser}

\subsubsection{Introduction}

The parser provides a Line which represents an event and the definition of this event. The purpose of the event parser is to give the values of this event to the data structure in order to store it.

\subsubsection{Implementation}

The event parser contains only one method which fills the data structure step by step with the lines (Line) provided. To do that, there are as many local variables as known field names in Paj\'e's events. The variables which fit the event defined by the definition (Definition) are filled ordered by the fields of the definition by converting the strings read in the line to the defined type. The values which do not fit some known field names are stored in a vector. Then, the event parser uses the data structure methods to fill it. The variables given as arguments for these methods depend on the Paj\'e event name.

\subsection{Handling of a trace}
\subsubsection{Introduction}

ParserPaje reads a file trace and sends messages to Trace accordingly. 

\subsubsection{Implementation}
ParserPaje opens a file (instanciate a Line), instanciates a ParserEventDecoder and a ParserDefinitionDecoder. 
It reads lines until the end of the file.
Each line is parsed by ParserEventDecoder or ParserDefinitionDecoder whether or not the line starts with \% token.

\begin{figure}[ht!]
\includegraphics[scale=0.5]{images/automateParserSyntaxique}
\caption{\label{ParserAutomaton} The Paj\'e parser automaton}
\end{figure}

\subsubsection{Specification}

A ParserPaje can be instanciated by an empty constructor.
The parse() method requires a filename to be opened and an instance of a trace object to proceed.

\subsubsection{Tests}

A test reads a trace file, uses the ParserDefinitionDecoder and ParserEventDecoder and prints the calls to the trace object. Each event produces a call as expected.
