\chapter{Developer Guide}

The chapter is a work in progress.  It is not meant for users of the
\Vauc library, but for developers and those who wish to contribute
code to \Vauc.

\section{Tools}

\subsection{Maintainer Tools}

We use a number of tools during development which we call
\Index{\dfn{maintainer tools}}, because they are not required by the
end user.
\begin{description}
\item[Autoconf] Generates \command{configure} which probes the user
  system to configure the compilation.
\item[Doxygen] Reference documentation generator.  Available as
  \code{doxygen} in most package systems.
\item[rst2latex, rst2html] These tools are used to convert
  reStructuredText into more common formats.  Available in the
  DarwinPorts as \code{py-docutils}.
\end{description}


\subsection{Developer Tools}

Some tools help to improve the code.  Use them liberally!

\subsubsection{Valgrind}

Valgrind help catching incorrect memory usage: double deletes, memory
leaks, uninitialized memory readings, and so forth.  Usually, to
optimize speed, implementations of the C++ library don't free all the
memory they allocated unless asked.  Read the
\href{http://gcc.gnu.org/onlinedocs/libstdc++/faq/}{GCC's C++
  Library FAQ}, especially the item
\href{http://gcc.gnu.org/onlinedocs/libstdc++/faq/#4_4_leak}{``memory
  leaks'' in containers}.

Use the following shell script to track memory leaks:

\begin{lstlisting}[language=sh]
#! /bin/sh

exec 3>&1

# Ask the GNU libstdc++ to free allocated structures.
export GLIBCXX_FORCE_NEW=1

exec valgrind --num-callers=20 \
              --leak-check=yes \
              --leak-resolution=high \
              --show-reachable=yes \
              "$@" 2>&1 1>&3 3>&- |
  sed 's/^==[0-9]*==/==/' >&2 1>&2 3>&-
\end{lstlisting}%$

\subsubsection{Debugging STL}

STLPort is known to be a nice implementation of STL with lots of added
assertions that allow to catch common errors (mixing iterators of
different containers, unstable sorting order and so forth).

I, Akim Demaille, have not succeeded to use it though.  This is mainly
because Debian does not provide STLPort compiled with debugging
support.  Nevertheless the GNU standard \Cxx library comes with some
useful debugging features.  Just add \samp{-D\_GLIBCXX\_DEBUG} to your
\code{CPPFLAGS} when compiling Vaucanson.

You are likely to encounter issues with
\index{iterator!singular}\dfn{singular} iterators.  It refers to
default-constructed iterators, which is not the same thing as being
the \code{end()} of a given container.  They are write-only according
to the STL, and copying them is not allowed.

As a result, the following code is incorrect:

\begin{lstlisting}[language=C++]
std::vector<std::list<int>::iterator> is(10);
\end{lstlisting}

\noindent
because this vector constructor builds a single default object (here a
default \code{std::list<int>::iterator}, then \emph{copies} it ten
times, which (ten times) forbidden.  It there is no clear means to
rewrite the code to avoid this violation, you might want to use
\code{end()} iterators, which can be used in comparisons, can be
copied, but cannot be dereferenced.

\begin{lstlisting}[language=C++]
std::vector<std::list<int>::iterator> is(10,
                                         std::list<int>().end());
\end{lstlisting}


\section{Contributing Code}
\label{sec:contributing-code}


\subsection{Directory usage}

\index{directories}
The \Vauc package is organized as follows:

\newcommand{\dir}[2]{\path{#1} & #2\\}
\noindent
\begin{tabularx}{\textwidth}{|l|X|}
  \hline
  Directory & Usage\\
  \hline
  \dir{doc}{Documentation.}
  \dir{doc/css}{CSS style for Doxygen.}
  \dir{doc/makefiles}{Sample Makefile to reduce compilation time in
    \Vauc.}
  \dir{doc/manual}{Manual.}
  \dir{doc/xml}{XML proposal.}
  \dir{include/vaucanson}{Library start point: defines classical entry
    points such as ``boolean\_automaton.hh''.}
  \dir{include/vaucanson/algebra/concept}{Algebra concepts, ``Structure''
    part of an Element.}
  \dir{include/vaucanson/algebra/implementation}{Implementations of
    algebraic Structures.  Some specialized structures too.}
  \dir{include/vaucanson/algorithms}{Algorithms.}
  \dir{include/vaucanson/algorithms/internal}{Internal functions of
    algorithms.}
  \dir{include/vaucanson/automata/concept}{Structure of an
    automaton.}
  \dir{include/vaucanson/automata/implementation}{Its
    implementation.}
  \dir{include/vaucanson/config}{Package configuration and system
    files.}
  \dir{include/vaucanson/contexts}{Context headers.}
  \dir{include/vaucanson/design_pattern}{Element design pattern
    implementation.}
  \dir{include/vaucanson/misc}{Internal headers of the whole
    library. }
  \dir{include/vaucanson/tools}{Tools such as dumper, bencher.}
  \dir{include/vaucanson/xml}{XML implementation.}
  \hline
\end{tabularx}
\begin{tabularx}{\textwidth}{|l|X|}
  \hline
  Directory & Usage\\
  \hline
  \dir{argp}{Argp library for TAF-Kit.}
  \dir{build-aux}{Where Autotools things go.}
  \dir{data}{Misc data, like Vaucanson's XSD, Emacs files.}
  \dir{data/b}{Generated Boolean automata.}
  \dir{data/z}{Generated Automata over Z.}
  \dir{debian}{Debian packaging.}
  \dir{src/bench}{Benchmarks.}
  \dir{src/demos}{Demos.}
  \dir{src/tests}{Test suite.}
  \dir{taf-kit}{Typed Automata Function Kit, binaries to use \Vauc.}
  \dir{taf-kit/tests}{Test suite using the TAF-Kit.}
  \dir{vaucanswig}{Vaucanswig, a SWIG interface for \Vauc.}
  \dir{vcs}{Version Control System configuration
    (\href{http://rubyforge.org/projects/vcs}{VCS Home Page}).}
  \hline
\end{tabularx}

\subsection{Writing Makefiles}

\begin{description}
\item[Produce the output atomically] Generating an output bits by
  bits, say with a series of \samp{>> \$@}, or even with some common
  programs, can result in invalid files if the process failed at some
  point, or was interrupted.  Note that in that case the (invalid)
  output file is newer than its dependencies, therefore it will
  remain.  Instead, create an temporary output, say \samp{\$@.tmp},
  and as last step, rename it a \samp{\$@}.  Sometimes, using
  \command{move-if-change} makes more sense.

\item[Look for the economy] Do what you can to save useless
  recompilations.  Using move-if-change, especially for generated
  files, does save cycles.  But then, beware that time stamps are not
  updated, which can be troublesome if the Makefile includes
  dependency tracking, as they will not be satisfied.

\item[Always include dependencies] included for the bootstrapping
  process.  In their regular development process, the contributors
  should not have to bootstrap again, that should be only for the
  initial check-out, and some other situation where the layout of the
  project has deeply changed.  Therefore, always hook the generated to
  the changes in the generators.

\item[Hunt Makefile duplication] Prefer an included Makefile to
  copy-and-paste of bits.  That's also true for generated Makefiles:
  put the constant parts in a Makefile to be included in the generated
  Makefiles, rather than copying these bits several times.

  This makes it easier to maintain, and also improves locality: you
  can edit the included Makefile and try it in just one directory,
  instead of having to relaunch the generation of all the Makefiles.
\end{description}


\subsection{Coding Style}

Until this is written, please refer to
\href{http://www.lrde.epita.fr/~akim/compil/assignments.split/Coding-Style.html#Coding-Style}{Tiger's
  Coding Style}.

Emacs users should use the indentation style of \file{data/vaucanson.el}.

\paragraph{Document in the \file{*.hh}}
Do not document in the implementation files, but in the declaration
files.  Unless, of course, the function is private and not
``exported''.

\paragraph{Use the same signature in the declaration and in the
  implementation}
It's a bad idea not to follow the same name on both sides, and it
confuses the reader.  Even worse is not giving names to the argument
in the declarations, giving the impression that the argument is
ignored, while using it for real in the implementation.

Keep also the same template parameter names.

Inconsistency confuses users, peer developers, and... Doxygen too.


\subsubsection{Includes}
\index{\#include}

\paragraph{Be extremely conservative with header inclusions}
Do not include something that is not needed \strong{by the file
  itself}.  Do not include in a \file{*.hh} something that is required
by the \file{*.hxx} file itself.

\paragraph{Sort the inclusions}
Always include standard headers first, then foreign headers we might
depend upon, and then Vaucanson headers.  Inside these groups, sort
the includes.

\paragraph{Qualify header names}
Please, never use backward relative paths anywhere.  There are very
difficult to follow (because several such strings can designate the
same spot), they make renaming and moving virtually impossible etc.

Relative paths to sub-directories are welcome, although in many
situations they are not the best bet.

In \strong{Makefiles}, please using absolute paths starting from
\samp{\$(top\_srcdir)}.  Unfortunately, because Automake cannot grok
includes with Make macros (except... \samp{\$(top\_srcdir)}), we can't
shorten these.

For \strong{header inclusion}, stacking zillions of \samp{-I} is not
the best solution because
\begin{itemize}
\item you have to work to find what file is really included
\item you are likely to find unexpected name collisions if two
  separate directories happens to have (legitimately) two different
  files share the same name
\item etc.
\end{itemize}

So rather, stick to \emph{hierarchies} of include files, and use
qualified \samp{\#include}s.  For instance, use \samp{-I
  \$(top\_srcdir)/include -I \$(top\_srcdir)/src/tests/include} and
\samp{\#include <vaucanson/...>} falls into the first one
(\file{\$(top\_srcdir)/include} has all its content in
\file{vaucanson}), and \samp{\#include <tests/...>} falls into the
latter since \file{\$(top\_srcdir)/src/tests/include} has all its
content in \file{vaucanson}).

\subsection{Use of macros}
\index{\command{cpp}}

\ac{cpp} is evil, but code duplication is even worse.  Macros can be
useful, as in the following example:

\begin{lstlisting}[language=Vaucanson]
# define PARSER_SET_PROPERTY(prop)			\
      if (parser->canSetFeature(XMLUni::prop, true))	\
	parser->setFeature(XMLUni::prop, true);

PARSER_SET_PROPERTY(fgDOMValidation);
PARSER_SET_PROPERTY(fgDOMNamespaces);
PARSER_SET_PROPERTY(fgDOMDatatypeNormalization);
PARSER_SET_PROPERTY(fgXercesSchema);
PARSER_SET_PROPERTY(fgXercesUseCachedGrammarInParse);
PARSER_SET_PROPERTY(fgXercesCacheGrammarFromParse);

# undef PARSER_SET_PROPERTY
\end{lstlisting}

\noindent
but please, respect the following conventions.
\begin{itemize}
\item Use upper case names, unless they are part of the interface such
  as \code{for\_all\_transitions} and so forth.
\item Make them live short lives, as above: undefine them as soon as
  they are no longer needed.
\item Respect the nesting structure: if \file{foo.hh} defines a macro,
  undefine it there too, not in the included \file{foo.hxx}.
\item Indent \ac{cpp} directives.  The initial dash should always be
  in the first column, but indent the spaces (one per indentation)
  between it and the directive.  The above code snippet was included
  in an outer \code{\#if}.
\item Each header file (\file{.hh}, \file{.hxx}, \ldots) should start
  with a classic \ac{cpp} guard of the form
  \begin{lstlisting}
#ifndef FILE_HH
# define FILE_HH
  ...
#endif // !FILE_HH
  \end{lstlisting}
  GCC has some optimizations on file parsing when this scheme is seen.
\item We often rely on \texttt{grep} and tags to search things. Please
  don't clutter names with \ac{cpp} evilness.
\end{itemize}

For instance, this is bad style:

\begin{lstlisting}[language=Vaucanson]
#define VCSN_choose_semiring(Canarg, Nonarg, Typeret...)                  \
    template <class Self>                                                 \
    template <class T>                                                    \
    Typeret                                                               \
    SemiringBase<Self>::Canarg ## choose_ ## Nonarg ## starable(          \
    SELECTOR(T)) const                                                    \
    {                                                                     \
      return op_ ## Canarg ## choose_ ## Nonarg ## starable(this->self(), \
							   SELECT(T));    \
    };
    VCSN_choose_semiring(can_,non_,bool)
    VCSN_choose_semiring(,,Element<Self, T>)
    VCSN_choose_semiring(,non_,Element<Self, T>)
\end{lstlisting}

\subsection{File Names}

In \Vauc the separator is \samp{\_}, not \samp{-}.  We use the
following file extensions:
\begin{description}
\item[cc] Implementation (compilation unit)
\item[hh] Declarations and documentation
\item[hxx] Inline Implementation
\end{description}

File names should match the class they declare, with the conversion of
name conventions (i.e., from \code{MyClass} to \file{my\_class.*}).

\subsection{Type Names}

Although some coding standards recommend against this practice, types
in \Vauc should end with \samp{\_t}.  One exception is traits, where
\code{ret} is commonly used.

\code{self\_t}, when defined, always refers to the current class.

\code{super\_t}, when defined, always refers to \emph{the} super
class.  When there are several, \code{super\_t} is not used.  The
macros \code{INHERIT\_TYPEDEF} and \code{INHERIT\_TYPEDEF\_} rely on
this convention.

\subsection{Variable Names}
\newcommand{\textstar}{\texttt{\ensuremath{*}}}
Using long variable names clutters the code, so please, don't name
your variables and arguments like \code{automaton1} or
\code{alphabet}.  Structure members and functions should be
descriptive though.

In order to keep the variable names reasonable in size, and
understandable, there are variable name conventions: some families of
identifiers are reserved for some types of entities.  The conventions
are listed below; developers must follow it, and users are encouraged
to do it too.  In the following list, \samp{\textstar} stands for ``nothing,
or a number''.
\begin{description}
\item[al\textstar, alpha\textstar, A\textstar] alphabets
\item[a\textstar, aut\textstar] automata (\code{automaton\_t}, etc.)
\item[t\textstar, tr\textstar] transitions
\item[p\textstar, q\textstar, r\textstar, s\textstar] states (\code{hstate\_t})
\end{description}

Some variables should be consistently used to refer to some ``fixed''
values.
\begin{description}
\item[monoid\_identity] The neutral for the monoid, the empty word.
\begin{lstlisting}[language=Vaucanson]
monoid_elt_t monoid_identity = a.series().monoid().empty_;
\end{lstlisting}

\item[null\_series] The null series, the 0, the identity for the sum.
\begin{lstlisting}[language=Vaucanson]
series_set_elt_t null_series = a.series().zero_;
\end{lstlisting}

\item[semiring\_elt\_zero] The zero for the weights.
\begin{lstlisting}[language=Vaucanson]
semiring_elt_t semiring_elt_zero = a.series().semiring().wzero_;
\end{lstlisting}
\end{description}

\subsection{Commenting Code}
\label{sec:commenting-code}

Use Doxygen.  Besides the usual interface description, the Doxygen
documentation must include:
\begin{itemize}
\item references to the definitions of the algorithm, e.g., a
  reference to the ``Éléments de la théorie des automates'', or even
  an URL to a mailing-list archive.
\item detailed description of the assumptions, or, if you wish, pre-
  and post-conditions.
\item the name of the developer
\item use the \texttt{@pre} and \texttt{@post} tags liberally.
\end{itemize}

Don't try to outsmart your tool, even though it does not use the words
``param'' and ``arg'' as we do, stick to \emph{its} semantics (let
alone to generate correct documentation without warnings).  This is
correct:
\begin{lstlisting}[language=C++]
  /**
   * Delete memory associated with a stream upon its destruction.
   *
   * @arg \c T	Type of the pointed element.
   *
   * @param ev	IO event.
   * @param io	Related stream.
   * @param idx	Index in the internal extensible array of a pointer to delete.
   *
   * @see iomanip
   * @author Thomas Claveirole <thomas.claveirole@lrde.epita.fr>
   */
  template <class T>
  void
  pword_delete(std::ios_base::event ev, std::ios_base &io, int idx);
\end{lstlisting}
while this is not:
\begin{lstlisting}[language=C++]
  /** ...
   * @param T	Type of the pointed element.
   *
   * @arg ev	IO event.
   * @arg io	Related stream.
   * @arg idx	Index in the internal extensible array of a pointer to delete.
   * ... */
\end{lstlisting}

\subsection{Writing Algorithms}

There is a number of requirement to be met before including an
algorithms into the library:
\begin{description}
\item[Document the algorithm] See \autoref{sec:commenting-code}.
\item[Comment the code] Especially if the code is a bit tricky, or
  smart, or avoids nasty pitfalls, it \emph{must} be commented.

\item[Bind the algorithm to \tafkit]

\item[Include tests] See \autoref{sec:writing-tests} for more
  details.  Tests based on \tafkit are appreciated.  Note that tests
  require test cases: to exercise an algorithm, not any automaton will
  do, try to find relevant samples.  Again, ETA is a nice source of
  inspiration.

\item[Complete the documentation]  The pre- and post-conditions should
  also be described here.
\end{description}

When submitting a patch, make it complete (i.e., including the
aforementioned items), and provide a ChangeLog.  See
\href{http://www.lrde.epita.fr/dload/guidelines/guidelines.html}{Le
  Guide du \lrde}, section ``La maintenance de projets'' and
especially ``Écrire un ChangeLog'' for more details.

Because \Vauc uses Trac, ChangeLog entries should explicit refer to
tickets (e.g., ``Fixing issue \#38: implement is\_ambiguous''), and
possible previous revisions (e.g., ``Fix a bug introduced in
[1224]'').

\subsection{Writing Tests}
\label{sec:writing-tests}


\subsection{Mailing Lists}
\label{sec:mailing-lists}

Vauc comes with a set of mailing lists:
\begin{description}
\item[vaucanson@lrde.epita.fr] General discussions, feature requests etc.
\item[vaucanson-bugs@lrde.epita.fr] To report errors in code,
  documentation, web pages, etc.
\item[vaucanson-patches@lrde.epita.fr] To submitted patches on code,
  documentation, and so forth.
\item[vaucanson-private@lrde.epita.fr] To contact privately the
  \Vauc team.
\end{description}

Please, bear in mind that there are these lists have many readers,
therefore this is a WORM medium: Write Once, Read Many.  As a
consequence:
\begin{itemize}
\item Be complete.\\
  One should not strive to understand what you are referring to, so
  always include proper references: URLs, Ticket numbers \emph{and
    summary}, etc.
\item Be concise.\\
  Write short, spell checked, understandable sentences.  Reread
  yourself, remove useless words, be proud of what you wrote.  Show
  respect to the reader.  Spare us useless messages.
\item Be structured.\\
  Quick and dirty replies with accumulated layers of replies at the
  bottom of the message is not acceptable.  The right ordering is not
  the one that is the quickest to write, but the easiest to read.
\item Be attentive.\\
  Lists are not write-only: consider the feedback that is given with
  respect.
\end{itemize}

As an example of what's not to be done, avoid answering to yourself to
point out you made a spell mistake: we can see that, and that's a
waste of time to read another message for that.  Also, there is no
hurry, it would probably be better to wait a bit to have a complete,
well thought out, message, rather than a thread of 4 messages
completing, contradicting, each other.  Finally, if you still need to
fix your message, supersede it, or even cancel it.

\section{Vaucanson I/O}
\label{sec:vaucanson-io}

January 2005

Here is some information about input and output of automata in
\href{http://www.lrde.epita.fr/vaucanson}{Vaucanson}.

\subsection{Introduction}

As usual, the structure of the data representing an automaton in a flat
file is called the file format.

There are several input and output formats for Vaucanson
automata. Obviously:
\begin{itemize}
\item {}
input formats are those that can be read from, i.e. from which an
automaton can be loaded.

\item {}
output formats are those that can be written to, i.e. to which an
automaton can be dumped.

\end{itemize}

Given these definitions, here is the meat:
\begin{itemize}
\item {}
Vaucanson supports Graphviz (dot) as an output format. Most kinds of
automata can be dumped as dot-files. Through the library this format
is simply called \texttt{dot}.

\item {}
Vaucanson supports XML as an input and output format. Most kinds of
automata can be read and written to and from XML streams, which
Vaucanson does by using the Xerces-C++ library. Through the library
this format is simply called \texttt{xml}.

\item {}
Vaucanson supports the FSM toolkit I/O format as an input and output
format. This allows for basic FSM interaction. Only certain kinds of
weighted automata can be meaningfully input and output with this
format. Through the library this format is simply called \texttt{fsm}.

\item {}
Vaucanson supports a simple informative textual format as an input
and output format. Most kinds of automata can be read and written to
and from this format. Through the library this format is simply called
\texttt{simple}.

\end{itemize}


%___________________________________________________________________________

\subsection{Dot format}

This format provides an easy way to produce a graphical representation
of an automaton.

Output using this format can be given as input to the Graphviz \texttt{dot}
command, which can in turn produce graphical representations in
Encapsulated PostScript, PNG, JPEG, and many others.

It uses Graphviz' ``directed graph'' subformat.

If you want to see what it looks like go to the \texttt{data/b}
subdirectory, build the examples and run them with the ``dot''
argument.

For Graphviz users:

Each graph generated by Vaucanson can be named with a string that also
prefixes each state name. If done so, several automata can be grouped
in a single graph by simply concatenating the Vaucanson outputs.


%___________________________________________________________________________

\subsection{XML format}

This format is intended to be an all-purpose strongly typed input and
output format for automata.

Using it requires:
\begin{itemize}
\item that the Xerces-C++ library is installed and ready to use by the
  C++ compiler that is used to compile Vaucanson.

\item configuring Vaucanson to use XML.

\item computer resources and time.
\end{itemize}

What you gain:
\begin{itemize}
\item support for the Greater and Better I/O format. See documentation
  in the \texttt{doc/xml} subdirectory for further information.
\end{itemize}

If you want to see what it looks like go to the \texttt{data/b}
subdirectory, build the examples and run them with the \texttt{xml}
argument.


%___________________________________________________________________________

\subsection{FSM format}

This format is intended to provide a basic level of compatibility with
the FSM tool kit. (FIXME: references needed)

Like FSM, support for this format in Vaucanson is limited to
deterministic automata. It probably does not work with transducers,
either.

It is not meant to be used that much apart from performance comparison
with FSM. Some code exists to simulate FSM, in
\texttt{src/demos/utilities/fsm}.

If you want to see what it looks like go to the \texttt{data/b}, build
the examples and run them with the \texttt{fsm} argument.


%___________________________________________________________________________

\subsection{Simple format}

Initially intended to be a quick and dirty debugging input and output
format, this format actually proves to be a useful, compact and
efficient textual representation of automata.

Advantages over XML:
\begin{itemize}
\item does not require additional 3rd party software,

\item simple and efficient (designed to be read and written to streams
  with very low memory footprint and minimum complexity),

\item more compact,

\item not strongly typed (can be dumped from one automaton type and
  loaded to another).
\end{itemize}

Drawbacks relative to XML:

\begin{itemize}
\item not strongly typed (one cannot know what automaton type to
  build by only looking at the raw data).

\item currently does not (probably) support transducers.
\end{itemize}

If you want to see what it looks like go to the \texttt{data/b}, build
the examples and run them with the \texttt{simple} argument.


%___________________________________________________________________________

\subsection{Using input and output}

The library provides an infrastructure for generic I/O, which
(hopefully) will help supporting more formats in the future.

The basis for this infrastructure is the way a developer C++ using the
library will use it:

\begin{lstlisting}[language=Vaucanson]
#include <vaucanson/tools/io.hh>

/* to save an automaton */
output_stream << automaton_saver(automaton, converter, format)

/* to load an automaton */
input_stream >> automaton_loader(automaton, converter, format, merge_states)
\end{lstlisting}

Where:
\begin{description}
\item[\texttt{automaton}] is the automaton undergoing input or output.
  Note that the object must already be constructed, even to be read
  into.

\item[\texttt{converter}] is a helper class that is able to convert
  automaton transitions to character strings and possibly vice-versa.

\item[\texttt{format}] is a helper class that is able to convert the
  automaton to (and possibly from) a character string, using the
  converter as an argument.

\item[\texttt{merge\_states}] is an optional argument that should be
  omitted in most cases. For advanced users, it allows loading a
  single automaton from several different streams that share the same
  state set.
\end{description}


%___________________________________________________________________________

\subsubsection{About converters}

The \texttt{converter} argument is mandatory. There are several converter
types already available in Vaucanson. See below.

An I/O converter is a function object with one or both of the following:
\begin{itemize}
\item an operation that takes an automaton, a transition label and
  converts the transition label to a character string (std::string).
  This is called the output conversion.

\item an operation that takes an automaton, a character string and
  converts the character string to a transition label. This is called
  the input conversion.
\end{itemize}

Vaucanson already provides these converters:
\begin{description}
\item[{\texttt{vcsn::io::string\_out}, bundled with \texttt{io.hh}.}]

  Provides the output conversion only. Uses the C++ operator
  {\textless}{\textless} to create a textual representation of
  transition labels. Should work with all label types.

\item[{\texttt{vcsn::io::usual\_converter\_exp}, defined in
    \texttt{tools/usual\_io.hh}.}]

  Provides both input and output conversions. Uses the C++ operator
  {\textless}{\textless} to create a textual representation of
  transition labels, but requires also that algebra::parse can read
  back that representation into a variable of the same type. It is
  mostly used for generalized automata where transitions are labeled
  by rational expressions, hence the name.

\item[{\texttt{vcsn::io::usual\_converter\_poly<ExpType>}, defined
    in \texttt{tools/usual\_io.hh}.}]  Provides both input and
  output conversions. Converts transition labels to and from ExpType
  before (after) doing I/O. The implementation is meant to be used
  when labels are polynoms, and using the generalized (expression)
  type as ExpType.
\end{description}


%___________________________________________________________________________

\paragraph{Notes about XML and converters}

When the XML I/O format was implemented, the initial converter system
was not used. Instead a specific converter system was re-designed
specifically for this format.

(FIXME: explain why!)

(FIXME: why hasn't the generic converter for XML been ported back to
fsm and simple formats?)

Because of this, when using XML I/O the ``converter'' argument is
completely ignored by the format processor. Usually you can see
\texttt{vcsn::io::string\_output} mentioned.

(FIXME: this is terrible! it must be patched to use an empty
vcsn::io::xml\_converter\_placeholder or something like it).


%___________________________________________________________________________

\subsubsection{About formats}

The \texttt{format} argument is mandatory. It specifies an instance of the
object in charge of the actual input or output.

A format object is a function object that provides one or both the
following operations:
\begin{itemize}
\item an operation that takes an output stream, the caller
  \texttt{automaton\_saver} object, and the \texttt{converter}
  object. This is called the output operation.

\item an operation that takes an input stream and the caller
  \texttt{automaton\_loader} object. This is called the input
  operation.  Note that this operation does not uses the
  \texttt{converter} object, because it should call back the
  \texttt{automaton\_loader} object to actually perform string to
  transition label conversions.
\end{itemize}

Format objects may require arguments to be constructed, such as the
title of the automaton in the output.

Format objects for a format should be defined in a
\texttt{tools/xxx\_format.hh} file.

Vaucanson provides the following format objects:
\begin{description}
\item[{\texttt{vscn::io::dot(const std::string{\&} digraph\_title)},
    in \texttt{tools/dot\_format.hh}.}]

  Provides an output operation for the Graphviz \texttt{dot}
  subformat. The title provided when buildint the \texttt{dot} object
  in Vaucanson becomes the title of the graph in the output data and a
  prefix for state names. Therefore the title must contain only
  alphanumeric characters or the underscore (\_), and no spaces.

\item[{\texttt{vcsn::io::simple()}, in
    \texttt{tools/simple\_format.hh}.}]

  Provides both input and output operations for a simple text format.

\item[{\texttt{vcsn::xml::XML(const std::string{\&} xml\_title)}, in
    \texttt{xml/XML.hh}.}]

  Provides both input and output operations for the Vaucanson XML I/O
  format.
\end{description}

(FIXME: why not tools/xml\_format.hh with proper includes of headers
in xml/?)

(FIXME: really the FSM format should have a format object too.)


%___________________________________________________________________________

\subsection{Examples}

Create a simple dot output for an automaton a1:
\begin{lstlisting}[language=vaucanson]
std::ofstream fout("output.dot");
fout << automaton_saver(a1, vcsn::io::string_output(), vcsn::io::dot("a1"));
fout.close()
\end{lstlisting}

Output automaton a1 to XML, read it back into another automaton a2
(possibly of another type):
\begin{lstlisting}[language=Vaucanson]
std::ofstream fout("file.xml");
fout << automaton_saver(a1, NULL, vcsn::xml::XML());
fout.close()

std::ifstream fin("file.xml");
fin >> automaton_loader(a2, NULL, vcsn::xml::XML());
fin.close()
\end{lstlisting}

Do the same, but this time using the simple format. The automata are
generalized, i.e. labeled by expressions:
\begin{lstlisting}[language=Vaucanson]
std::ofstream fout("file.txt");
fout << automaton_saver(a1, vcsn::io::usual_converter_exp(), vcsn::io::simple());
fout.close()

std::ifstream fin("file.txt");
fin >> automaton_loader(a2, vcsn::io::usual_converter_exp(), vcsn::io::simple());
fin.close()
\end{lstlisting}


%___________________________________________________________________________

\subsection{Internal scenario}

What happens in Vaucanson when you write:
\begin{lstlisting}[language=Vaucanson]
fin >> automaton_loader(a1, c1, f1)
\end{lstlisting}
?

\begin{enumerate}
\item function \texttt{automaton\_loader} creates an object AL1 of
  type \texttt{automaton\_loader\_} that memorizes its arguments.

\item \texttt{automaton\_loader()} returns AL1.

\item \texttt{operator>{}>(fin, AL1)} is called.

\item \texttt{operator>{}>} says to format object f1: ``hi, please use
  fin to load something with AL1''.

\item f1 scans input stream fin. Things may happen then:
  \begin{itemize}
  \item f1 finds a state numbered N. Then it says to AL1: ``hey, make
    a new state into the output automaton, keep its handler s1 for
    yourself and remember it is associated to N''.  (callback
    \texttt{AL1.add\_state})

  \item f1 finds a transition from state numbered N to state P,
    labeled with character string S. Then it says to AL1: ``hey,
    create a transition with N, P, and S.'' (callback
    \texttt{AL1.add\_transition}).  Then:
    \begin{itemize}
    \item AL1 remembers handler for state N (s1)

    \item AL1 remembers handler for state P (s2)

    \item AL1 says to converter c1: ``hey, make me a transition label
      from S''

    \item AL1 creates transition from s1 to s2 using converted label
      into output automaton.
\end{itemize}
\end{itemize}

\item When f1 is finished, it returns control to \texttt{operator>{}>}
  and then calling code.

  Of course since everything is statically compiled using templates
  there is no performance drawback due to the intensive use of
  callbacks.

\end{enumerate}

%___________________________________________________________________________

\subsection{Convenience utilities}

For most formats the (relatively) tedious following piece of code:
\begin{lstlisting}[language=Vaucanson]
output_stream << automaton_saver(a, CONVERTER(), FORMAT(...))
\end{lstlisting} %>>
is also available as:

\begin{lstlisting}[language=Vaucanson]
FORMAT_dump(output_stream, a, ...)
\end{lstlisting}

If available, this convenience utility is defined in
\texttt{tools/XXX\_dump.hh}.

Conversely, the following piece of code:

\begin{lstlisting}[language=Vaucanson]
input_stream >> automaton_loader(a, CONVERTER(), FORMAT(...))
\end{lstlisting}

is usually also available as:

\begin{lstlisting}[language=Vaucanson]
FORMAT_load(input_stream, a, ...)
\end{lstlisting}

If available, this convenience utility is defined in
\texttt{tools/XXX\_load.hh}.

As of today (2006-03-17) the FSM format is only available using the
fsm\_load() and fsm\_dump() interface.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "vaucanson-user-manual"
%%% End:
