\chapter{Vaucanswig}
\label{sec:swig}

\section{Introduction to Vaucanswig}

Vaucanswig is a set of SWIG definitions which allow to use \Vauc in a
high-level dynamic language such as Python, Perl, PHP or Ruby.

\subsection{Introduction}

\Vauc is a \Cxx library that uses static genericity.

SWIG is an interface generator for C and \Cxx libraries which enables
their use from a variety of languages, including CHICKEN, C\#, Scheme,
Java, O'Caml, Perl, Pike, PHP, Python, Ruby, Lua, Lisp, and TCL.

Unfortunately, running SWIG directly on the \Vauc library does not
work: most of \Vauc features are expressed using \Cxx meta-code,
which means that basically there is no real code in \Vauc for SWIG
to work on.

Vaucanswig comes between SWIG and \Vauc: it describes to SWIG
some explicit \Vauc types and algorithms implementations so that
SWIG can generate the inter-language interface.

\subsection{Usage}

For  any  SWIG-supported   language,  using  Vaucanswig  requires  the
following steps:

\begin{enumerate}
\item Generate the language interface from SWIG input sources
  (\code{.i} files) provided by Vaucanswig,

\item Compile the interface into extensions to the language library
  (e.g. dynamically-loadable shared package modules for Python).

\item Load the extensions into the target language environment.
\end{enumerate}

Vaucanswig does not help with the latter two steps, except for the
Python language target (see below). Refer to the SWIG documentation
for information about generating language extensions from SWIG input
files for other languages.

\subsection{What is provided?}

\subsubsection{Glossary}

In the following sections, the term ``category'' refers to the set of
features related to a particular algebraic configuration in \Vauc.

The following categories are predefined in Vaucanswig:

\begin{center}
\begin{tabular}{*{6}{|c}|}
\hline
Category             & Semiring values & Monoid values  & Series          &Series values  & Expression values\\
\hline
\code{usual}         & \code{bool}     &  \code{string} & \SerSAnMon{\B}{\Ae} & \code{polynom}&   \code{exp}\\
\code{numerical}     & \code{int}      &  \code{string} & \SerSAnMon{\Z}{\Ae} & \code{polynom}&   \code{exp}\\
\code{tropical\_min} & \code{int}      &  \code{string} & \SerSAnMon{\Z(\min,+)}{\Ae}& \code{polynom}&   \code{exp}\\
\code{tropical\_max} & \code{int}      &  \code{string} & \SerSAnMon{\Z(\max,+)}{\Ae}& \code{polynom}&   \code{exp}\\
\hline
\end{tabular}
\end{center}

These are the standard contexts defined in \Vauc. They are defined
in Vaucanswig in the file \code{expand.sh}.

\subsubsection{What is in a category?}

For   a  given   category  \emph{D},   Vaucanswig  defines   the  following
\textbf{modules}:

\begin{description}
\item[\code{vaucanswig\_D\_context}] Algebra and algebraic context.
\item[\code{vaucanswig\_D\_automaton}] Automata types (standard and
  generalized).
\item[\code{vaucanswig\_D\_alg\_...}]  Algorithm wrappers.
\item[\code{vaucanswig\_D\_algorithms}] General wrapper for all
  algorithms.
\end{description}

Each of these modules becomes an extension package/module/namespace in
the target language.

\subsubsection{Algebra}

For a given category \emph{D}, the module
\code{vaucanswig\_D\_context} contains the following \textbf{classes}:

\begin{description}
\item[\code{D\_alphabet\_t}] Alphabet element with constructor from a
  string of generator letters:
  \begin{description}
  \item[(constructor)] string $\to$ D\_alphabet\_t
  \end{description}
\item[\code{D\_monoid\_t}] Monoid structural element with the
  following members:
  \begin{itemize}
  \item standard \Vauc constructors and operators,
  \item method to construct a word element from a simple string:
    \begin{description}
    \item[make] string $\to$ D\_monoid\_elt\_t
    \end{description}
  \item method to generate the identity value:
    \begin{description}
    \item[identity] $\to$ D\_monoid\_elt\_t
    \end{description}
  \end{itemize}
\item[\code{D\_monoid\_elt\_t}] Word (monoid element) with standard
  \Vauc constructors and operators.
\item[\code{D\_semiring\_t}] Semiring structural element with the
  following members:
  \begin{itemize}
  \item standard \Vauc constructors and operators,
  \item method to construct a weight element from a number:
    \begin{description}
    \item[make] int $\to$ D\_semiring\_elt\_t
    \end{description}
  \item methods to generate the identity and zero values:
    \begin{description}
    \item[identity] $\to$ D\_semiring\_elt\_t
    \item[zero] $\to$ D\_semiring\_elt\_t
    \end{description}
  \end{itemize}
\item[\code{D\_semiring\_elt\_t}] Weight (semiring element) with
  standard \Vauc constructors and operators.
\item[\code{D\_series\_set\_t}] Series structural element with the
  following members:
  \begin{itemize}
  \item standard \Vauc constructors and operators,
  \item methods to construct a series element from a number or string:
    \begin{description}
    \item[make] int $\to$ D\_series\_set\_elt\_t
    \item[make] string $\to$ D\_series\_set\_elt\_t
    \end{description}
  \item methods to generate the identity and zero values as polynoms
    or expressions:
    \begin{description}
    \item[identity] $\to$ D\_series\_set\_elt\_t
    \item[zero] $\to$ D\_series\_set\_elt\_t
    \item[exp\_identity] $\to$ D\_exp\_t
    \item[exp\_zero] $\to$ D\_exp\_t
    \end{description}
  \end{itemize}
\item[\code{D\_series\_set\_elt\_t}, \code{D\_exp\_t}] Polynom and
  expressions (series elements with polynom and expression
  implementations) with standard \Vauc constructors and operators.
\item[\code{D\_automata\_set\_t}] Structural element for automata.
  Include standard \Vauc constructors.
\item[\code{D\_context}] Convenience class with utility methods. It
  provides the following members:
  \begin{itemize}
  \item constructors
    \begin{description}
    \item[(constructor)] D\_automata\_set\_t $\to$ D\_context
    \item[(copy constructor)] D\_context $\to$ D\_context
    \end{description}
  \item accessors for structural elements:
    \begin{description}
    \item[automata\_set] $\to$ D\_automata\_set\_t
    \item[series] $\to$ D\_series\_set\_t
    \item[monoid] $\to$ D\_monoid\_t
    \item[semiring] $\to$ D\_semiring\_t
    \item[alphabet] $\to$ D\_alphabet\_t
    \end{description}
  \item shortcut constructors for elements:
    \begin{description}
    \item[semiring\_elt] int $\to$ D\_semiring\_elt\_t
    \item[word] string $\to$ D\_monoid\_elt\_t
    \item[series] int $\to$ D\_series\_set\_elt\_t
    \item[series] word $\to$ D\_series\_set\_elt\_t
    \item[series] D\_exp\_t $\to$ D\_series\_set\_elt\_t
    \item[exp] D\_series\_set\_elt\_t $\to$ D\_exp\_t
    \item[exp] string $\to$ D\_expt\_t
    \end{description}
  \end{itemize}  
\end{description}
       
In  addition  to these  classes,  the module  \code{vaucanswig\_D\_context}
contains the following \textbf{function}:

\begin{description}
\item[make\_context] D\_alphabet\_t $\to$ D\_context
\end{description}
  
\subsubsection{Algebra usage}

All classes are equipped with a \code{describe} method for
textual representation of values. Example use (Python):

\begin{lstlisting}[language=Python]
>>> from vaucanswig_usual_context import *
>>> c = make_context(usual_alphabet_t("abc"))

>>> c.exp("a+b+c").describe()
'usual_exp_t@0x81a2e60 = ((a+b)+c)'

>>> (c.exp("a")*c.exp("a+b+c")).star().describe()
'usual_exp_t@0x81a20f8 = (a.((a+b)+c))*'

>>> from vaucanswig_tropical_min_context import *
>>> c = make_context(tropical_min_alphabet_t("abc"))

>>> c.series().identity().describe()
'tropical_min_serie_t@0x81ad8b8 = 0'
>>> c.series().zero().describe()
'tropical_min_serie_t@0x81a6de8 = +oo'
\end{lstlisting}

\subsubsection{Automata}

For  a  given  category  \emph{D},  the  module  \code{vaucanswig\_D\_automaton}
contains the following \textbf{classes}:

\begin{description}
\item[\code{D\_auto\_t}] The standard automaton type for this
  category.
\item[\code{gen\_D\_auto\_t}] The generalized (with expression labels)
  automaton type for this category.
\end{description}

These class provides the following constructors:

\begin{description}
\item[(constructor)] D\_context $\to$ D\_auto\_t
\item[(constructor)] D\_context $\to$ gen\_D\_auto\_t
\item[(copy constructor)] D\_auto\_t $\to$ D\_auto\_t
\item[(copy constructor)] gen\_D\_auto\_t $\to$ gen\_D\_auto\_t
\item[(constructor)] D\_auto\_t $\to$ gen\_D\_auto\_t
\end{description}

For   convenience  purposes,  a   \code{gen\_D\_auto\_t}  instance   can  be
constructed from a \code{D\_auto\_t}  (generalization). The opposite is not
possible, of course.

In addition to the standard \Vauc methods, these classes have been
augmented with the following operators:

\begin{description}
\item[\code{describe()}] Give a short description for the object.
\item[\code{save(filename)}] Save data to a file.
\item[\code{load(filename)}] Load data from a file. The automaton must
  be already defined (empty) and its structural element must be
  compatible with the file data.
\item[\code{dot\_run(tmpf, cmd)}] Dump the automaton to file named
  \code{tmpf}, then run command \code{cmd} on file \code{tmpf}. The
  file is in dot format compatible with
  Graphviz.\footnote{\url{http://www.research.att.com/sw/tools/graphviz/}}
\end{description}

Example use:

\begin{lstlisting}[language=Python]
>>> from vaucanswig_usual_automaton import *
>>> a = usual_auto_t(c)
>>> a.add_state()
0
>>> a.add_state()
1
>>> a.add_state()
2
>>> a.del_state(1)
>>> for i in a.states():
...   print i
...
0
2
>>> a.dot_run("tmp", "dot_view")

>>> a.save("foo")
>>> a2 = usual_auto_t(c)
>>> a2.load("foo");
>>> a2.states().size()
2
\end{lstlisting}


\subsubsection{Algorithms}

As a  general rule of thumb,  if some algorithm \code{foo}  is defined in
the source file \code{vaucanson/algorithms/bar.hh} then:

\begin{itemize}
\item the module \code{vaucanswig\_D\_alg\_bar} contains a function
  \code{foo},
\item the module \code{vaucanswig\_D\_algorithms} contains
  \code{D.foo}.
\end{itemize}


\subsection{Adding new algorithms}
The Vaucanswig  generator automatically build  Vaucanswig modules from
definitions found in the \Vauc source files.

You  can  add   a  new  algorithm  to  vaucanswig   simply  by  adding
declarations of the form:

\begin{lstlisting}[language=C++]
// INTERFACE: ....
\end{lstlisting}

to the \Vauc headers.


\subsubsection{Example}

Let's consider the \Vauc header \code{foo.hh} in
\code{include/vaucanson/algorithms}, which contains the following
code:

\begin{lstlisting}[language=C++]
// INTERFACE: Exp foo1(const Exp& other) { return vcsn::foo1(other); }
template<typename S, typename T>
Element<S, T> foo1(const Element<S, T>& exp);

// INTERFACE: Exp foo1(const Exp& other1, const Exp& other2) { return vcsn::foo2(other1, other2); }
template<typename S, typename T>
Element<S, T> foo1(const Element<S, T>& exp);
\end{lstlisting}

Then,  after  running  \code{expand.sh}  (the Vaucanswig  generator)  for
category \emph{D}, the module \code{vaucanswig\_D\_alg\_foo} becomes available:

\begin{lstlisting}[language=C++]
   foo1: D_exp_t $\to$ D_exp_t
   foo2: (D_exp_t, D_exp_t) $\to$ D_exp_t
\end{lstlisting}

In   addition,  the   special  algorithm   class  \code{D},   defined  in
\code{vaucanswig\_D\_algorithms}, also contains 'foo1' and 'foo2'.

\subsubsection{Limitations}

When writing  \code{// INTERFACE:} comments, the following  notes must be
taken into consideration:

\begin{itemize}
\item The comment must stand on a single line.  Indeed,
  \code{expand.sh} does not currently support multi-line interface
  declarations.

\item The following special macro names are available:

  \begin{description}
  \item[\code{Exp}] The expression type for the category.
  \item[\code{Serie}] The polynom/serie type for the category.
  \item[\code{Automaton}, \code{GenAutomaton}] The automaton types for
    the category.
  \item[\code{HList}] A list of state or transition handlers
    (integers). This type is \code{std::list<int>} in \Cxx and a
    standard sequence of numbers in the target language.
  \item[\code{Word}] The word type for the category.
  \end{description}

\item When accessing automata, a special behavior stands. Instead of
  writing:

  \begin{lstlisting}[language=C++]
    // INTERFACE: void foo(Automaton& a) { return vcsn::foo(a); }
    // INTERFACE: void foo(GenAutomaton& a) { return vcsn::foo(a); }
  \end{lstlisting}

  one should write instead:

  \begin{lstlisting}[language=C++]
    // INTERFACE: void foo(Automaton& a) { return vcsn::foo(*a); }
    // INTERFACE: void foo(GenAutomaton& a) { return vcsn::foo(*a); }
  \end{lstlisting}

  Indeed,  \code{Automaton}   and  \code{GenAutomaton}  do   not  expand  to
  \Vauc automata types, but to  a wrapper type. The real automaton
  can be reached by means of operator*().

\end{itemize}

\subsection{Python support}

For convenience purposes, Python interfaces for Vaucanswig are
included in the distribution.  They are automatically compiled and
installed with \Vauc if enabled.  To enable these modules, run the
\code{configure} script like this:

\begin{lstlisting}
configure --enable-vaucanswig
\end{lstlisting}

\section{Building language interfaces with Vaucanswig}
\label{sec:swig:build}

This section describes how to use Vaucanswig to produce interfaces
with other languages.

\subsection{Background}

Vaucanswig is a set of \href{http://www.swig.org}{SWIG} wrapper
definitions for the \Vauc library.

SWIG takes Vaucanswig as input, and generates code to link between any
supported scripting language and \Cxx. In that sense, Vaucanswig is
already "meta", because it ultimately supports several scripting
languages. But still, even Vaucanswig itself is automatically
generated, and this "meta-build" process is described in
\autoref{sec:swig:meta}.

The document you are reading explains how to \emph{use} Vaucanswig once it
has been generated.


\subsection{General idea}

Once Vaucanswig has been generated, it is composed of input files to
SWIG.

To use \Vauc in a target scripting language, two steps are necessary:

\begin{enumerate}
\item Produce \Cxx sources for the interface (running SWIG).\\
  This step only requires Vaucanswig sources and a decent version of
  SWIG.
\item Compile these sources.\\
  This step requires the \Vauc library and the extension libraries
  for the selected target language.
\end{enumerate}

\subsection{SWIG modules (\texttt{MODULES})}

Vaucanswig defines a number of SWIG modules.

The list of SWIG modules, hereinafter named \texttt{MODULES}, contains:

\begin{tabular}{|l|p{.6\linewidth}|}
  \hline
  Name of module      & Description
  \\
  \hline
  \code{core}	     & the core of vaucanswig.
  \\
   \code{K\_context}    & for each \var{K}, the definition of the
                         algebraic context \var{K} (\var{K} can be
                         \code{usual}, \code{numerical},
                         \code{tropical} and so on)
  \\
   \code{K\_automaton}  & definition of the Automaton and Expression
   		       types in context \var{K}
  \\
   \code{K\_alg\_A}	     & for each algorithm \emph{A}, the definition of the
                         specific instance of \emph{A} in context
                         \var{K}. (\emph{A} can be "complete", "standard",
                         "product" and so on)
  \\
   \code{K\_algorithms} & a convienient wrapper for context \var{K} with
                         "shortcuts" to all the algorithms instanciated
                         for \var{K}.
  \\
  \hline
\end{tabular}

Note that the name of SWIG modules are closely related to the namespace
where the corresponding features can be found in the target scripting language.

Then, for each module \emph{M}, two items are available:

\begin{tabular}{|l|p{.6\linewidth}|}
  \hline
  Item                     & Description\\
  \hline
   \file{src/vaucanswig\_M.i} &  the dedicated SWIG source file\\

   \file{src/M.deps} &		 (optional, may not exist) a file containing a list
   			 of modules that \emph{M} is dependent upon. If the file is
  			 empty, two cases apply:
                           \begin{itemize}
                           \item \emph{M} is "core" - no dependency
                           \item \emph{M} is not "core" - it depends on "core".
                           \end{itemize}
                           \\
  \hline
\end{tabular}

The first item is the most important. The second is only useful to create
automated build processes which require dependency rules.


\subsection{\CxxHR sources specific to the target scripting language (T.S.L.)}

Each TSL needs a different set of wrapper for the Vaucanswig modules.

For any given TSL, source files for the \code{MODULES} can be created by
SWIG by running the following pseudo-algorithm:

\begin{lstlisting}
  $ for M in ${MODULES}; do
      ${SWIG} -noruntime -c++ -${TSL} \
         -I${VAUCANSWIGDIR}/src \
	 -I${VAUCANSWIGDIR}/meta \
	 -I${VAUCANSON_INCLUDES}  \
 	 ${VAUCANSWIGDIR}/src/vaucanswig_${M}.i
    done
\end{lstlisting}%$

Where:

\begin{itemize}
\item \code{\$\{TSL\}} is the SWIG option pertaining to the language
  (python, java ...)
\item \code{\$\{VAUCANSWIGDIR\}} is the root directory of Vaucanswig.
\item \code{\$\{SWIG\}} is the path to the SWIG binary.
\item \code{\$\{VAUCANSON\_INCLUDES\}} is the base directory of the
  \Vauc library.
\end{itemize}

\subsection{Compilation of the binaries for the target scripting language}

The previous step creates a bunch of \Cxx source files of the form
\file{vaucanswig\_\$\{M\}\_wrap.cxx}. They should be compiled with the
\Cxx compiler supported by the TSL.

The \Cxx compilation should use the following flags:

\begin{itemize}
\item \samp{-DINTERNAL\_CHECKS -DSTRICT -DEXCEPTION\_TRAPS}\\
  Use for more secure code in \Vauc.

\item \samp{-I\$\{VAUCANSON\_INCLUDES\}}\\
  Specify the location of the \Vauc library headers.

\item \samp{-I\$\{VAUCANSWIGDIR\}/src -I\$\{VAUCANSWIGDIR\}/meta}\\
  Needed by Vaucanswig.
\end{itemize}

In addition, any "compatibility" flags required by \Vauc for this
particular \Cxx compiler should be used as well.


\subsection{Automake support for Python as a TSL}

According to the previous section, a \file{Makefile.am} file is
generated in the subdirectory \file{python/}.

It contains four main parts:
\begin{description}
\item[A header]~\\
\begin{lstlisting}[language=Make]
##
## Set INCLUDES for compilation of C++ code.
##

# FIXME: the python path is hardcoded, this is NOT good.
INCLUDES = -I/usr/include/python2.2 \
           -I$(srcdir)/../src -I$(srcdir)/../meta \
  	   -I$(top_srcdir)/include -I$(top_builddir)/include

##
## Set AM_... flags.
##

# According to spec.
AM_CPPFLAGS = -DINTERNAL_CHECKS -DSTRICT -DEXCEPTION_TRAPS
# We want lots of debugging information in the wrapper code.
AM_CXXFLAGS = $(CXXFLAGS_DEBUG)
# For Libtool, to generate dynamically loadable modules.
AM_LDFLAGS = -module -avoid-version
\end{lstlisting}%$

\item[The list of binary targets]
(the shared objects - DLL)

\begin{lstlisting}[language=Make]
# for each MODULE:
pyexec_LTLIBRARIES += libvs_$(MODULE).la
\end{lstlisting}%$

\item[The list of Python source files]~\\

\begin{lstlisting}[language=Make]
# for each MODULE:
python_PYTHON += vaucanswig_$(MODULE).py
\end{lstlisting}%$

\item[Build specifications for binary targets]~\\

\begin{lstlisting}[language=Make]
# for each MODULE:
libvs_$(MODULE)_la_SOURCES = vaucanswig_$(MODULE)_wrap.cxx

# If the module is "core":
#    # This should be the only dependency against static, non-template
#    # Vaucanswig code. And make it a dependency to the SWIG runtime.
#    libvs_core_la_LIBADD = ../meta/libvv.la -lswigpy

# Else:
#    If src/$(MODULE).deps is empty:
#	      libvs_$(MODULE)_la_LIBADD = libvs_core.la
#    Else:
#        for each DEPENDENCY in src/$(MODULE).deps do:
#	        libvs_$(MODULE)_la_LIBADD += libvs_$(DEPENDENCY).la
\end{lstlisting}%$
\end{description}

Additionnaly, the following (not important) parts are generated for
convenience purposes:

\begin{itemize}
\item Rules to rerun SWIG in case something changes in Vaucanswig:
\begin{lstlisting}[language=Make]
vaucanswig_*_wrap.cxx vaucanswig_*.py: ../src/vaucanswig_*.i
	$(SWIG) -noruntime -c++ -python -I... \
	               -o vaucanswig_*_wrap.cxx \
		       ../src/vaucanswig_*.i
\end{lstlisting}%$

\item Installation and uninstallation hooks.
\end{itemize}


\subsection{Automake support for the TSL-independent code}

In order to make things comply to the spirit of the Autotools, a
convenience \file{Makefile.am} is generated in the \file{src/}
directory.

It contains a definition of EXTRA\_DIST with all the SWIG module
source files, of the form: \file{vaucanswig\_\$(MODULE).i}.


\section{Generating and extending Vaucanswig sources}
\label{sec:swig:meta}

The \autoref{sec:swig:build} describes how to use Vaucanswig to create
a wrapper for \Vauc in a scripting language.  (read it first)

This document instead describes how Vaucanswig itself is generated,
currently using the infamous \file{expand.sh} script.

\subsection{The list of Vaucanswig modules}

Once generated, Vaucanswig is a set of SWIG modules. This list of
modules is algorithmically generated. The overall process to build the
list of module names is as follows:

\begin{enumerate}
\item put \code{core} in the \code{MODULES} list.

\item create an auxiliary list \code{ALGS} of algorithm families.

  (detailed below, gives \code{alg\_sum}, \code{alg\_complete}, ...)

\item create an auxiliary list \code{KINDS} of algebra contexts

  (contains \code{boolean}, \code{z}, \code{z\_max\_plus}, ...)

\item extend \code{ALGS} with "\code{context}", "\code{algorithms}"
  and "\code{automaton}".

\item make the cross product of \code{KINDS} and \code{ALGS} putting a
  "\_" between the two parts of each generated name.

\item add the results of this cross product to the \code{MODULES}
  list.
\end{enumerate}

\subsection{The list of algorithm families (\code{ALGS} in step 2 above)}


In Vaucanswig, an "algorithm family" is the set of algorithms declared
in a single \Vauc header file. Most families declare only one
algorithm, but usually with several forms (using overloading). In
Vaucanswig, each algorithm family is related to a SWIG source file:
\code{src/vaucanswig\_alg\_NAME.i} where \code{NAME} is the name of the
algorithm family.

Each family source file contains the following items:

\begin{itemize}
\item a link to its \Cxx header.

\item the definition of a bunch of SWIG macros which are able to
  instanciate the algorithm *declarations* for the type set given as
  parameters.

\item the definition of a bunch of SWIG macros which are able to
  instanciate algorithm \emph{wrappers} for the set of types given as
  parameters.
\end{itemize}

To create the list of algorithm families and associated SWIG sources,
the geneeration script proceeds as follows:

\begin{enumerate}
\item Find all files in the \Vauc includes that declare algorithms
  using the "\code{// INTERFACE:}" construct.

\item For each such include file, proceed as follows:

  \begin{enumerate}
  \item Prepend the base name of the file with "\code{alg\_}" to make a
    "family name".

  \item Create \code{src/vaucanswig\_(family\_name).i} containing the
    relevant SWIG code

  \item Put the generated family name (with prefix) in the \code{ALGS}
    list.
  \end{enumerate}
\end{enumerate}

\subsection{The cross-product of contexts and generic code (step 5 above)}

This is where you find all the magic. :)

This is the step where \emph{real} code (i.e. non-template) is produced.

The goal of this step is to build the list of SWIG modules names *and*
the source file for each SWIG module. The basic idea is simple. It
relies on the following two facts:

\begin{enumerate}
\item each algorithm family defined above defines macros that take
  types as parameters and produce non-template declarations and
  definitions.

\item each algebra context defines a set of types, that fit as
  parameters in the macros for algorithm families.
\end{enumerate}

Now the rest is quite simple. Since we have two lists \code{KINDS}
(contexts) and \code{ALGS} (algorithm families), proceed as follows:

\begin{lstlisting}
  for each K of KINDS, do:
    for each A of ALGS, do:

      # Step 5.1
      instanciate macros...
      ... from src/vaucanswig_alg_${A}.i
      ... using ${K}
      ... into src/vaucanswig_${K}_${A}.i

      # Step 5.2
      add "${K}_${A}" to the MODULES list.

    # the following step is not fundamental, but required for later
    # compilation:

    # Step 5.3 (still in the K loop)
    add "${K}_context" to src/${K}_automaton.deps

    for each algorithm family F, do:

       # Step 5.4
       add "${K}_automaton" to src/${K}_${F}.deps

       # Step 5.5
       add "${K}_${F}" to src/${K}_algorithms.deps
\end{lstlisting}

The result of steps 5.3, 5.4 and 5.5 above can later be used to create
dynamic link dependencies between object code for modules (see
\code{build-process.txt}). It creates the following dependency graph:

\begin{lstlisting}
  core $\to$ K1_context $\to$ K1_automaton $\to$ K1_F1 $\to$ K1_algorithms
                                     $\to$ K1_F2 $\to$
				     $\to$ K1_F3 $\to$

       $\to$ K2_context $\to$ K2_automaton $\to$ K2_F1 $\to$ K2_algorithms
                                     $\to$ K2_F2 $\to$
				     $\to$ K2_F3 $\to$
\end{lstlisting}

  (and so on)

\subsection{The transparency property}

At every level, a property can be recognized. If an algorithm
\code{foo()} is declared (\Cxx) in \file{bar.h}, then:
\begin{itemize}
\item \code{bar} is the "algorithm family" of \code{foo()}

\item for each selected context \var{K}, exactly one SWIG module exists
  and is called called \samp{K\_bar}.

\item the goal is that at the end of the compilation, in the target
  scripting language you can write:
  \begin{lstlisting}[language=sh]
K_bar.foo()
# (or equivalent)
  \end{lstlisting}
\end{itemize}


\subsection{What is \emph{not} automatic}

Some work is required from the part of the developer:
\begin{itemize}
\item keeping \samp{// INTERFACE:} tags in \Vauc headers.

\item deciding a list of contexts to instanciate in Vaucanswig.

\item running the generator for Vaucanswig generic code whenever
  the \Vauc library is updated.

\item distributing the generated generic sources and building rules
  afterwards.
\end{itemize}

\subsection{Things not easy to change \emph{yet}}

In this section, \var{K} stands for any algebra context.

The set of \var{K} -dependent types available in wrapper code in the
\samp{// INTERFACE:} tags is not yet easily configurable, because it
involves a huge piece of hand-written dedicated code.

For the moment, the following types are available for each
context \code{K}:

\begin{tabular}{|l|p{.6\linewidth}|}
  \hline
   Name of type   & Description\\
  \hline
     Automaton	& the automaton type labeled by series \\
     GenAutomaton& the corresponding type labeled by expressions \\
     Series	& the type of series in K \\
     Exp	& the type of expressions in K \\
     HList	& a type for lists of unsigned integer
                  (to be used as automaton handlers where required) \\
     Word	& the type of the monoid elements \\
  \hline
\end{tabular}

Adding more of these is not difficult, but very tedious. It involves
adding a new argument in various argument list in various SWIG macros
in the code. These will be documented later.

But still, it remains \strong{very difficult} to bind in Vaucanswig
any algorithm that operates on more than one algebra context at the
same time. "Very difficult" here means that some major work is
required to change Vaucanswig to support this case.



%%% Local Variables:
%%% mode: latex
%%% ispell-local-dictionary: "american"
%%% TeX-master: "vaucanson-user-manual"
%%% End:
