Commit 988de5df authored by Raphal Poss's avatar Raphal Poss
Browse files

2005-01-16 Raphael Poss <raph@lrde.epita.fr>

        Update documentation.

        * doc/README.txt: Fix some mistakes. Add a "See Also" section.

        * src/demos/fsm/README: Rewrite to...
        * src/demos/fsm/README.txt: ...this.

        * src/demos/vaucanswig/doc,
        * src/demos/vaucanswig/doc/Makefile.am: New directory.
        * src/demos/vaucanswig/Makefile.am: Update accordingly.

        * src/demos/vaucanswig/README: Rewrite to...
        * src/demos/vaucanswig/doc/README.txt: ...this. Fix some
        mistakes. Add more information. Change the layout for easier
        reading.

        * src/demos/vaucanswig/build-process.txt,
        * src/demos/vaucanswig/meta-build-process.txt: Rename to...
        * src/demos/vaucanswig/doc/build-process.txt,
        * src/demos/vaucanswig/doc/meta-build-process.txt: ...these.

        * src/demos/vaucanswig/doc/Makefile.am: Build documentation.

        * src/demos/vaucanswig/Makefile.am: Distribute expand.sh, since it
        is mentioned in the documentation.

parent adb3e9cc
2005-01-16 Raphael Poss <raph@lrde.epita.fr>
Update documentation.
* doc/README.txt: Fix some mistakes. Add a "See Also" section.
* src/demos/fsm/README: Rewrite to...
* src/demos/fsm/README.txt: ...this.
* src/demos/vaucanswig/doc,
* src/demos/vaucanswig/doc/Makefile.am: New directory.
* src/demos/vaucanswig/Makefile.am: Update accordingly.
* src/demos/vaucanswig/README: Rewrite to...
* src/demos/vaucanswig/doc/README.txt: ...this. Fix some
mistakes. Add more information. Change the layout for easier
reading.
* src/demos/vaucanswig/build-process.txt,
* src/demos/vaucanswig/meta-build-process.txt: Rename to...
* src/demos/vaucanswig/doc/build-process.txt,
* src/demos/vaucanswig/doc/meta-build-process.txt: ...these.
* src/demos/vaucanswig/doc/Makefile.am: Build documentation.
* src/demos/vaucanswig/Makefile.am: Distribute expand.sh, since it
is mentioned in the documentation.
2005-01-15 Raphael Poss <raph@lrde.epita.fr>
Cleanup documentation subsystem. Use reStructuredText more.
......
......@@ -59,7 +59,8 @@ if test "x$ac_cv_recent_swig" != "xyes"; then
AC_MSG_ERROR([You need swig >= 1.3 to compile vaucanswig.])
else
AC_CONFIG_FILES([src/demos/vaucanswig/Makefile
src/demos/vaucanswig/meta/Makefile
src/demos/vaucanswig/doc/Makefile
src/demos/vaucanswig/meta/Makefile
src/demos/vaucanswig/src/Makefile
src/demos/vaucanswig/python/Makefile])
VCSN_VAUCANSWIG_SUBDIR="vaucanswig"
......
......@@ -31,11 +31,13 @@ words from any free monoids. And on the other hand, a particular
algorithm can be specialized for a particular data structure
implementing only a pseudo behaviour.
Yet, Vaucanson is still in a fundamental development phase and
algorithms, data structures and global architecture are not totally
stable and well tested. In the ``doc/help`` directory, you can find a
short howto to start programming with Vaucanson. The ``src`` directory
contains several demonstrations, but you can also look at the
Yet, Vaucanson is an ongoing development project. Therefore
algorithms, data structures and the general architecture are not
totally stable and well tested.
In the ``doc/help`` directory, you can find a short howto to start
programming with Vaucanson. The ``src`` directory contains several
demonstrations, but you can also look at the
``include/vaucanson/algorithms`` to be introduced to the basics of
Vaucanson.
......@@ -48,11 +50,46 @@ Installation
See the documentation file ``INSTALL.txt`` for installation
instructions.
See Also
========
There are other sources of interest in the distribution.
- Headline news about the project can be found in the file ``NEWS`` at
the root of the source tree.
- Documentation about the XML I/O subsystem can be found in the
``doc/xml`` subdirectory.
- The library reference manual, generated by Doxygen_, is located in
``doc/ref``. It comes distributed as an archive of HTML files called
``ref.tar.gz``.
- Information about the test suite generation mechanism can be found
in the file ``src/tests/test-suites/README``.
- There are some demonstration programs distributed with the
project. See the ``src/demos`` subdirectory. Some of these are
noteworthy:
- Usage examples in subdirectories ``src/demos/samples`` and
``src/demos/xml/samples``.
- Vaucanson-FSM (``src/demos/fsm/README.txt``) is aimed at providing
an emulation of the FSM toolbox [3].
- Vaucanswig (``src/demos/vaucanswig/doc/README.txt``) is aimed at
providing a dynamic language interpreter to the Vaucanson library.
.. _Doxygen: http://www.doxygen.org
.. [3] http://www.research.att.com/~mohri/fsm/
Licence
=======
Vaucanson is released under the GNU Lesser General Public Licence.
See the file ``COPYING`` for details.
See the file ``COPYING`` (at the root of the source tree) for details.
Contacts
......
# demos/fsm/README
#
# $Id$
This demo is meant to generate tool-boxes "à la" FSM [1] from
a configuration file toolbox.hh that defines what kind of
automaton the user wants to manipulate.
The generated files can be used to benchmark Vaucanson in
comparison with fsm when it is instantiated with different
implementation.
USAGE
-----
1. create a directory (say "automaton_t") ;
2. create toolbox.hh and toolbox.cc into it. These files must
define a type "automaton_t" which is the type of automaton and
a function "series" which returns the series that are
used in the toolbox. (for example, look at the distributed
"usual_automaton_t/toolbox.[hh,cc]")
3. use the "./generate_toolbox.sh" script to generate the
toolbox files, like this:
./generate_toolbox.sh the_directory_of_1
4. in the directory, use the classical:
autoreconf
CPPFLAGS="-I your_vaucanson_include_dir" ./configure
make
NOTICE
------
Please send any remarks or wanted features at
vaucanson@lrde.epita.fr
[1] http://www.research.att.com/~mohri/fsm/
\ No newline at end of file
===================================
FSM_ -like toolbox for Vaucanson_
===================================
:Author: Yann Regis-Gianas
:Date: March 2004
:Version: $Id$
.. contents::
Introduction
============
This demo is meant to generate toolboxes "à la" FSM_ [1] from a
configuration file ``toolbox.hh`` that defines what kind of automaton
the user wants to manipulate.
The generated files can be used to benchmark Vaucanson_ in comparison
with FSM when it is instantiated with different implementations.
.. _Vaucanson: http://www.lrde.epita.fr/vaucanson
.. _FSM:
.. [1] http://www.research.att.com/~mohri/fsm/
Usage
=====
1. create a directory (e.g. ``automaton_t``),
2. in this directory, create the files ``toolbox.hh`` and
``toolbox.cc``. They should define a type ``automaton_t`` (the type
of automaton) and a function ``series`` which returns the series
that are used in the toolbox. For example, look at the distributed
files ``usual_automaton_t/toolbox.{hh,cc}``.
3. use the script ``./generate_toolbox.sh`` to generate the toolbox
sources, like this::
./generate_toolbox.sh [dirname]
4. in the directory, do::
autoreconf
./configure CPPFLAGS="-I your_vaucanson_include_dir"
make
Contact
=======
Please send any comments or wanted features to
``vaucanson@lrde.epita.fr``.
SUBDIRS = meta src python
EXTRA_DIST = build-process.txt meta-build-process.txt
SUBDIRS = doc meta src python
EXTRA_DIRST = expand.sh
Glossary
========
In this document, the name "category" designates the set of features
related to a particular algebraic configuration.
The following categories are predefined:
* usual: bool semiring, string words, polynom as serie_t, exp as exp_t
* numerical: int semiring, string words, polynom as serie_t, exp as exp_t
* tropical_min: int semiring / tmin, string words, polynom as serie_t, exp as exp_t
* tropical_max: int weights / tmin, string words, polynom as serie_t, exp as exp_t
They are those defined in usual.hh. Adding more categories is done by
adding more typedefs to usual.hh and the corresponding loop items in
expand.sh.
What is in a category ?
=======================
For a given category D, vaucanswig defines the following modules:
* vaucanswig_D_context: algebra and algebraic context
* vaucanswig_D_automaton: automata types (standard and generalized)
* vaucanswig_D_alg_...: the algorithm wrappers
* vaucanswig_D_algorithms: a wrapper around all available algorithms
Algebra
-------
The module vaucanswig_D_context contains:
* D_alphabet_t:
D_alphabet_t(const char*);
* D_monoid_t:
standard vaucanson constructors and operators
make(const std::string&);
D_monoid_elt_t identity();
* D_semiring_t:
standard vaucanson constructors and operators
make(int);
D_semiring_elt_t identity();
D_semiring_elt_t zero();
* D_series_set_t:
standard vaucanson constructors and operators
D_serie_t make(int);
D_serie_t make(const std::string&);
D_serie_t identity();
D_serie_t zero();
D_exp_t exp_identity();
D_exp_t exp_zero();
* D_automata_set_t:
standard vaucanson constructors and operators
* D_context:
D_context(const automata_set_t&);
D_context(const D_context&);
accessors:
automata_set(), series(),
monoid(), alphabet(), semiring()
shortcut constructors:
D_semiring_elt_t(int);
D_monoid_elt_t(const std::string&);
D_serie_t serie(int);
D_serie_t serie(const std::string&);
D_exp_t exp(const D_serie_t&);
// expression from polynom
D_exp_t exp(cosnt std::string&);
// expression parser
* D_context make_context(const D_alphabet_t&);
// shortcut context from alphabet
* D_monoid_elt_t:
* D_semiring_elt_t:
* D_serie_t:
* D_exp_t:
standard vaucanson constructors and operators
In addition, all classes are equipped with a `describe' method for
textual representation of values.
Example use (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'
Automata
--------
The module vaucanswig_D_automaton contains:
* D_auto_t: the standard automaton type
* gen_D_auto_t: the generalized automaton type
These classes construct by copy or from a D_context.
For convenience purposes, a gen_D_auto_t can be constructed from a
D_auto_t (generalization). The opposite is not possible, of course.
In addition to the standard vaucanson methods, these classes have been
enriched with the following operators:
describe() // short description
load(fname) // output to file
save(fname) // input from file
dot_run(tmpf, cmd) // run "cmd tmpf" after dumping to "tmpf"
Example use:
>>> 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
Algorithms
----------
As a general rule of thumb, if some algorithm 'foo' is defined in
vaucanson/algorithms/bar.hh, then:
- module vaucanswig_D_alg_bar contains 'foo'
- module vaucanswig_D_algorithms contains 'D.foo'
Adding algorithms
=================
You can add an algorithm to vaucanswig simply by adding
// INTERFACE: ....
declarations in include/vaucanson/algorithms.
Example
-------
Let foo.hh a file in include/vaucanson/algorithms containing the
following code:
// 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);
Then, after running expand.sh for category D, the following module is
available:
module vaucanswig_D_alg_foo
D_exp_t foo1(const D_exp_t&);
D_exp_t foo2(const D_exp_t&, const D_exp_t);
And the special algorithm class 'D', defined in
vaucanswig_D_algorithms, now contains 'foo1' and 'foo2'.
Limitations
-----------
When writing "// INTERFACE:" comments, the following notes must be
taken into consideration:
- the comment must stand on a single line.
For the moment, expand.sh does not support multi-line interface
declarations.
- the following special macro names are available:
* Exp: the expression type for the category
* Serie: the polynom/serie type for the category
* Automaton: the automaton type
* GenAutomaton: the generalized automaton type
* HList: std::list<int>, used as a standard container
- when accessing automata, a special behavior stands. Instead of
writing:
// INTERFACE: void foo(Automaton& a) { return vcsn::foo(a); }
// INTERFACE: void foo(GenAutomaton& a) { return vcsn::foo(a); }
one should write instead:
// INTERFACE: void foo(Automaton& a) { return vcsn::foo(*a); }
// INTERFACE: void foo(GenAutomaton& a) { return vcsn::foo(*a); }
Indeed, "Automaton" and "GenAutomaton" do not expand to vaucanson
automata types, but to a wrapper type. The real automaton can be
reached by means of operator*().
include $(top_srcdir)/doc/Makefile.doc
dist_doc_DATA = README.tex README.pdf README.html
# FIXME: the two other text files are not yet converted to reStructuredText.
# build-process.tex build-process.pdf build-process.html \
# meta-build-process.tex meta-build-process.pdf meta-build-process.html
EXTRA_DIST = README.txt build-process.txt meta-build-process.txt
MAINTAINERCLEANFILES = $(dist_doc_DATA)
=================================================
Vaucanswig: a dynamic wrapper around Vaucanson_
=================================================
:Author: Raphael Poss
:Contact: raph@lrde.epita.fr
:Version: $Id$
:Date: January 2005
Vaucanswig is a set of SWIG_ definitions which allow to use Vaucanson_
in a high-level, dynamic, language such as Python, Perl, PHP or Ruby.
.. _Vaucanson: http://www.lrde.epita.fr/vaucanson
.. _SWIG: http://www.swig.org
.. contents::
Introduction
============
Vaucanson_ is a C++ library that uses static genericity.
SWIG_ is an interface generator for C and C++ libraries, that allow
their use from a variety of languages: CHICKEN, C#, Scheme, Java,
O'Caml, Perl, Pike, PHP, Python, Ruby, Lisp and TCL.
Unfortunately, running SWIG directly on the Vaucanson library does not
work: most of Vaucanson features are expressed using C++ meta-code,
which means that basically there is no real code in Vaucanson for SWIG
to work on.
Vaucanswig comes in between SWIG and Vaucanson: it describes to SWIG
some explicit Vaucanson types and algorithms implementations so that
SWIG can generate the inter-language interface.
Usage
=====
For any SWIG-supported language, using Vaucanswig requires the
following steps:
1. generation of the language interface from SWIG input sources
(``.i`` files) provided by Vaucanswig,
2. compilation of the interface into extensions to the language
library (e.g. dynamically loadable shared package module for
Python).
3. loading the extension into the target language.
Vaucanswig provides no material nor tools to achieve these 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.
What is provided?
=================
Glossary
--------
In the next sections, the name "category" will refer to the set of
features related to a particular algebraic configuration in Vaucanson.
The following categories are predefined in Vaucanswig:
================ =============== ============= ============== ============= =================
Category Semiring values Monoid values Series Series values Expression values
================ =============== ============= ============== ============= =================
``usual`` ``bool`` ``string`` B<<A*>> ``polynom`` ``exp``
``numerical`` ``int`` ``string`` Z<<A*>> ``polynom`` ``exp``
``tropical_min`` ``int`` ``string`` Z(min,+)<<A*>> ``polynom`` ``exp``
``tropical_max`` ``int`` ``string`` Z(max,+)<<A*>> ``polynom`` ``exp``
================ =============== ============= ============== ============= =================
These are the standard contexts defined in Vaucanson. They are defined
in Vaucanswig in the file ``expand.sh``.
What is in a category?
----------------------
For a given category *D*, Vaucanswig defines the following
**modules**:
``vaucanswig_D_context``:
Algebra and algebraic context.
``vaucanswig_D_automaton``:
Automata types (standard and generalized).
``vaucanswig_D_alg_...``:
Algorithm wrappers.
``vaucanswig_D_algorithms``:
General wrapper for all algorithms.
Each of these modules becomes an extension package/module/namespace in
the target language.
Algebra
-------
For a given category *D*, the module ``vaucanswig_D_context``
contains the following **classes**:
``D_alphabet_t``:
Alphabet element with constructor from a string of generator
letters::
(constructor): string -> D_alphabet_t
``D_monoid_t``:
Monoid structural element with the following members:
- standard Vaucanson constructors and operators,
- method to construct a word element from a simple string::
make: string -> D_monoid_elt_t
- method to generate the identity value::
identity: -> D_monoid_elt_t
``D_monoid_elt_t``:
Word (monoid element) with standard Vaucanson constructors and
operators.
``D_semiring_t``:
Semiring structural element with the following members:
- standard Vaucanson constructors and operators,
- method to construct a weight element from a number::
make: int -> D_semiring_elt_t
- methods to generate the identity and zero values::
identity: -> D_semiring_elt_t
zero: -> D_semiring_elt_t
``D_semiring_elt_t``:
Weight (semiring element) with standard Vaucanson constructors
and operators.
``D_series_set_t``:
Series structural element with the following members:
- standard Vaucanson constructors and operators,
- methods to construct a series element from a number or
string::
make: int -> D_series_set_elt_t
make: string -> D_series_set_elt_t
- methods to generate the identity and zero values as polynoms
or expressions::
identity: -> D_series_set_elt_t
zero: -> D_series_set_elt_t
exp_identity: -> D_exp_t
exp_zero: -> D_exp_t
``D_series_set_elt_t``, ``D_exp_t``:
Polynom and expressions (series elements with polynom and
expression implementations) with standard Vaucanson constructors
and operators.
``D_automata_set_t``:
Structural element for automata. Include standard Vaucanson
constructors.
``D_context``:
Convenience class with utility methods. It provides the
following members:
- constructors::
(constructor): D_automata_set_t -> D_context
(copy constructor): D_context -> D_context
- accessors for structural elements::
automata_set: -> D_automata_set_t
series: -> D_series_set_t
monoid: -> D_monoid_t
semiring: -> D_semiring_t
alphabet: -> D_alphabet_t
- shortcut constructors for elements::
semiring_elt: int -> D_semiring_elt_t
word: string -> D_monoid_elt_t
series: int -> D_series_set_elt_t
series: word -> D_series_set_elt_t
series: D_exp_t -> D_series_set_elt_t
exp: D_series_set_elt_t -> D_exp_t
exp: string -> D_expt_t
In addition to these classes, the module ``vaucanswig_D_context``
contains the following **function**::