Commit 25eeceeb authored by Alexandre Duret-Lutz's avatar Alexandre Duret-Lutz
Browse files

doc: more documentation

* doc/contexts.rst, doc/gensets.rst, kinds.rst: New files.
* doc/automata.rst, doc/index.rst, doc/kratexp.rst, doc/poly.rst,
doc/scalars.rst, doc/weightsets.rst: More cross reference, and
small corrections.
parent e755be4e
......@@ -73,6 +73,7 @@ Overview
Here is the interface of an automaton::
typedef ... context_t;
typedef ... genset_t;
typedef ... weightset_t;
typedef ... kind_t;
......@@ -85,7 +86,8 @@ Here is the interface of an automaton::
typedef ... weight_t;
typedef ... entry_t;
// Related sets
// Context and related sets
const context_t& context() const;
const genset_t& genset() const;
const weightset_t& weightset() const;
const entryset_t& entryset() const;
......@@ -179,17 +181,21 @@ Detailed interface
Types
~~~~~
.. type:: context_t
The :doc:`context<contexts>` of the automaton.
.. type:: genset_t
The type of the generator set of the automaton.
The type of the :doc:`generator set<gensets>` of the automaton, as specified by the :doc:`context<contexts>`.
.. type:: weightset_t
The type of the weight set of the automaton.
The type of the :doc:`weight set<weightsets>` of the automaton, as specified by the :doc:`context<contexts>`.
.. type:: kind_t
The kind of the automaton.
The kind of the automaton, as specified by the :doc:`context<contexts>`.
.. type:: entryset_t
......@@ -207,7 +213,7 @@ Types
.. type:: label_t
The type use to label the automaton. This usually depends on :type:`kind_t`. For
The type use to label the automaton. Depending on the :type:`kind_t` spe. For
``labels_are_letters``, the transitions are labeled by ``genset_t::letter_t``,
while for ``labels_are_words`` they are labeled by ``genset_t::word_t``.
......@@ -219,17 +225,22 @@ Types
The type used to represent entry in this automaton. Equal to ``entryset_t::weight_t``.
Related sets
~~~~~~~~~~~~
.. function:: const genset_t& genset() const
Context and related sets
~~~~~~~~~~~~~~~~~~~~~~~~
.. function:: const context_t& context() const
Return the generator set used by this automaton.
The :doc:`context<contexts>` of the automaton.
.. function:: const genset_t& genset() const
Return the :doc:`generator set<gensets>` of the automaton, as specified by the :doc:`context<contexts>`.
.. function:: const weightset_t& weightset() const
Return the weight set used by this automaton.
Return the :doc:`weight set<weightsets>` of the automaton, as specified by the :doc:`context<contexts>`.
.. function:: const entryset_t& entryset() const
.. function:: const entryset_t& entryset() const
Return the entry set used by this automaton.
......@@ -564,16 +575,28 @@ Iteration on entries
Available Automata
------------------
.. class:: mutable_automaton<GenSet, WeightSet, Kind>
.. class:: mutable_automaton<Context>
An automaton on the generator set *GenSet* with weights in
*WeightSet* and kind *Kind*, implementing all the above interface,
An automaton on the generator set ``Context::genset_t``, with
weights in ``Context::weightset_t`` and kind ``Context::kind_t``,
implementing all the above interface,
Defined in ``vcsn/core/mutable_automaton.hh``.
.. function:: mutable_automaton(const GenSet& gs, const WeightSet& ws)
mutable_automaton(const GenSet& gs)
.. function:: mutable_automaton(const Context& ctx)
The constructor for a mutable automaton takes an instance of a context.
.. function:: mutable_automaton<Context> make_mutable_automaton(const Context& ctx)
Helper function to build a ``mutable_automaton``, inferring the
``Context`` type. Compare::
vcsn::ctx::char_z_lal ctx{{'a', 'b', 'c'}};
auto a = vcsn::mutable_automaton<vcsn::ctx::char_z_lal>(ctx);
with::
vcsn::ctx::char_z_lal ctx{{'a', 'b', 'c'}};
auto a = vcsn::make_mutable_automaton(ctx);
The constructor for a mutable automaton takes an instance of a
generator set *a* and an instance of the weight set *ws*. The
latter can be omitted if ``WeightSet`` has a default constructor.
Contexts
========
A context is essentially a triplet that groups a :doc:`generator
set<gensets>` with a :doc:`weight set<weightsets>` and a
:doc:`kind<kinds>`.
Overview
--------
A context offers the following interface::
template <typename GenSet, typename WeightSet, typename Kind>
class context: public dyn::context
{
public:
using genset_t = GenSet;
using weightset_t = WeightSet;
using genset_ptr = std::shared_ptr<const genset_t>;
using weightset_ptr = std::shared_ptr<const weightset_t>;
using kind_t = Kind;
enum
{
is_lae = std::is_same<kind_t, labels_are_empty>::value,
is_lal = std::is_same<kind_t, labels_are_letters>::value,
is_law = std::is_same<kind_t, labels_are_words>::value,
};
/// Type of transition labels, and type of RatExp atoms.
using label_t = typename label_trait<kind_t, genset_t>::label_t;
using word_t = typename genset_t::word_t;
/// Type of weights.
using weight_t = typename weightset_t::value_t;
/// Type of RatExp kratexps objects.
using node_t = rat::node<label_t, weight_t>;
using kratexp_t = std::shared_ptr<const node_t>;
using kratexpset_t = typename vcsn::kratexpset<context>;
/// Type of RatExp visitor.
using const_visitor = vcsn::rat::const_visitor<label_t, weight_t>;
context(const context& that);
context(const genset_ptr& gs, const weightset_ptr& ws);
context(const genset_t& gs = {}, const weightset_t& ws = {});
static std::string sname();
virtual std::string vname() const override final;
virtual std::string genset_string() const override final;
const genset_ptr& genset() const;
const weightset_ptr& weightset() const;
kratexpset_t make_kratexpset() const;
std::string format(const kratexp_t& e) const;
kratexp_t downcast(const rat::exp_t& e) const;
};
.. todo:: Document the context interface and the available contexts.
.. default-domain:: cpp
Generators Sets
===============
Generators sets offers functions to build words over a set of
*generators* (called letters).
Overview
--------
Generators sets offer the following interface::
static std::string sname();
typedef ... letter_t;
typedef ... word_t;
typedef ::vcsn::empty_t empty_t;
typedef ... iterator_t;
bool has(typename letter_t l) const;
iterator_t begin() const;
iterator_t end() const;
word_t to_word(const empty_t) const;
word_t to_word(const letter_t l) const;
word_t to_word(const word_t& l) const;
word_t concat(const letter_t l, const letter_t r);
word_t concat(const word_t l, const letter_t r) const;
word_t concat(const letter_t l, const word_t r) const;
word_t concat(const word_t l, const word_t r) const;
word_t identity() const;
bool is_identity(const word_t& w) const;
word_t transpose(const word_t& w) const;
letter_t transpose(letter_t l) const;
empty_t transpose(empty_t) const;
bool equals(empty_t, empty_t) const;
bool equals(const letter_t& l1, const letter_t& l2) const;
bool equals(const word_t& w1, const word_t& w2) const;
bool is_letter(const empty_t&) const;
bool is_letter(const letter_t&) const;
bool is_letter(const word_t& w) const;
std::ostream& print(std::ostream& o, const empty_t&) const; // REMOVE?
std::ostream& print(std::ostream& o, const letter_t& l) const;
std::ostream& print(std::ostream& o, const word_t& w) const;
std::string format(const letter_t l) const;
std::string format(const word_t& w) const;
template<class T = letter_t>
T special() const;
Detailed interface
------------------
.. function:: static std::string sname()
The (static) name of the weight set (i.e., its class name).
.. type:: letter_t
The type used to represent letters.
.. type:: word_t
The type used to represent words built from ``letter_t`` elements.
.. type:: empty_t
The type use to represent an empty word (in LAE) context.
.. todo:: the use of ``empty_t`` in this whole interface is quite
unsatisfactory. Maybe we should implement
an *empty generator set* for LAR contexts.
.. type:: iterator_t
The type of an iterator over the generators.
.. function:: bool has(typename letter_t l) const
Whether ``l`` is a generator.
.. function:: iterator_t begin() const
iterator_t end() const
Iterators over the generators.
.. function:: word_t to_word(const empty_t) const
word_t to_word(const letter_t l) const
word_t to_word(const word_t& l) const
Conversion to words.
.. function:: word_t concat(const letter_t l, const letter_t r)
word_t concat(const word_t l, const letter_t r) const
word_t concat(const letter_t l, const word_t r) const
word_t concat(const word_t l, const word_t r) const
Concatenation of two letters or words to form a new word.
.. function:: word_t identity() const
Returns the empty word.
.. function:: bool is_identity(const word_t& w) const
Test whether a word is empty.
.. function:: word_t transpose(const word_t& w) const
letter_t transpose(letter_t l) const
empty_t transpose(empty_t) const
Transpose a word. Calling transpose on letters or ``empty_t`` has
no effect.
.. function:: bool equals(empty_t, empty_t) const
bool equals(const letter_t& l1, const letter_t& l2) const
bool equals(const word_t& w1, const word_t& w2) const
Test equality between two words or letters.
.. function:: bool is_letter(const empty_t&) const
bool is_letter(const letter_t&) const
bool is_letter(const word_t& w) const
Check whether a word is a letter (i.e., has size 1).
.. function:: std::ostream& print(std::ostream& o, const empty_t&) const
std::ostream& print(std::ostream& o, const letter_t& l) const
std::ostream& print(std::ostream& o, const word_t& w) const
Print a word ``w`` or letter ``l`` on a stream ``o``.
.. todo:: The current implementation for ``empty_t`` print
``"EMPTY"``. It would probably makes more sense to
print ``""`` or ``"\\e"``. The current situation seems
to indicate that the function is never used, yet
removing it breaks the build.
.. function:: std::string format(const letter_t l) const
std::string format(const word_t& w) const
Format a word ``w`` or letter ``l`` as a string. It is more
efficient to call ``print()`` if that string is to be printed
right away.
.. function:: T special() const
Return the special letter to be used to label transitions leaving
:func:`pre` or reaching :func:`post` in :doc:`automata`.
Implementations
---------------
There is currently only one implementation of the above interface, the
``set_alphabet<char_letter>`` class. Letters are stored as ``char``,
words as ``std::string``, and the ``set_alphabet<char_letter>``
instance keeps an alphabet (a list of allowed letters) as an
``std::set<char>``.
This alphabet can be populated either at construction time, or
using the function ``add_letter``.
.. function:: set_alphabet()
set_alphabet(const std::initializer_list<letter_t>& l)
Instantiate a ``set_alphabet``, either with an empty alphabet, or with an alphabet initialized from a list of letters.
.. function:: set_alphabet& add_letter(typename letter_t l)
Add ``l`` to the set of letters of the alphabet.
......@@ -7,7 +7,9 @@ Vaucanson Developer's Reference
===============================
.. toctree::
:maxdepth: 2
weightsets
gensets
kinds
contexts
automata
.. default-domain:: cpp
Kinds
-----
Vaucanson distinguishes different *kinds* of automata and rational expressions.
The following types are declared in ``vcsn/core/kind.hh`` and used as
parameters in :doc:`contexts` that are in turn passed to complex types
such as :doc:`automata` or :doc:`kratexp`.
.. class:: labels_are_empty
labels_are_letters
labels_are_words
For automata, these kinds are used to select what kind of labels
should be used by the transitions. For rational expressions,
``labels_are_empty`` is not used, and the other two types indicate
whether the atoms of an expression are words or letters.
These types all implement the following static methods.
.. function:: static std::string sname()
The (static) name of the kind as a three-letter acronym (i.e.,
``"lae"``, ``"lal"``, or ``"law"``).
.. class:: label_traits<Kind, GenSet>
This traits ease the selection of the type used to store the
labels, for a given :doc:`generator set<gensets>`.
.. type:: label_t
The type used to store the labels for the pair ``Kind`` and
``GenSet``. For instance if Kind is ``labels_are_letters``,
this returns ``GenSet::letter_t``.
......@@ -14,7 +14,7 @@ Weighted Rational Expressions
Overview
========
``kratexpset`` implements the :doc:`Weight-Set interface <weightsets>`
``kratexpset`` implements the :doc:`Weight Set interface <weightsets>`
and adds other methods specific to the handling of rational
expressions::
......@@ -42,7 +42,7 @@ expressions::
value_t weight(value_t e, const weight_t& w) const;
value_t weight(const weight_t& w, value_t e) const;
// Weight-Set interface
// Weight Set interface
static std::string sname();
bool is_zero(value_t v) const;
bool is_unit(value_t v) const;
......@@ -64,9 +64,9 @@ expressions::
New methods
-----------
We only describe methods that are not part of the
:doc:`Weight-Set interface <weightsets>`.
We only describe methods that are not part of the :doc:`Weight Set
interface <weightsets>`. The ``add()`` and ``mul()`` function
respectively correspond to choice and concatenation.
.. function:: kratexpset<context_t>(const context_t& ctx)
......@@ -74,9 +74,10 @@ We only describe methods that are not part of the
``value_t`` instances created by this class represent weighted
rational expression using a syntax tree whose internal nodes are
operators (disjunction, concatenation, Kleen star) and leaves
(a.k.a. atoms) are ``label_t``. The definition of ``label_t``
depends on the *kind* of ``ctx``.
operators (disjunction, concatenation, Kleen star) and leaves are
either atoms (of labeled by ``label_t``) or constants (zero or
one). The definition of ``label_t`` depends on the *kind* of
``ctx``.
Each internal node has one left weight and one right weight. (This
distinction is useful in cases where weight multiplication is not
......@@ -90,3 +91,34 @@ We only describe methods that are not part of the
.. function:: value_t atom(const label_t& v) const
Create an atom (a leave in the syntax tree) labeled by ``v``.
.. function:: value_t concat(value_t l, value_t r) const
Implicit concatenation of two expressions. Use ``mul(l, r)``
for the regular concatenation operator.
This function only differs from ``mul()`` only in
``label_are_letter`` and ``label_are_empty`` contexts, where
concatenating ``"(ab).a"`` to ``"b"`` will result in
``"(ab).(ab)"`` with implicit concatenation, and ``"(ab).a.b"``
with the regular concatenation. This function is probably only
useful to the parser of rational expressions.
.. todo:: ``concat()`` should probably be renamed to something like
``iconcat()`` or ``imul()``, with ``i`` standing for
*implicit*.
.. function:: value_t weight(value_t e, const weight_t& w) const
value_t weight(const weight_t& w, value_t e) const
Multiply the expression ``e`` by ``w``. The order of the arguments
determines whether we are using a left or right multiplication.
Each internal node has one left weight and one right weight. (This
distinction is useful in cases where weight multiplication is not
commutative.) Leaves have only one weight.
.. todo:: It could be clearer to have ``lweight()`` and
``rweight()``.
......@@ -9,7 +9,7 @@ words), and coefficients are weights. For instance::
{3}ab + {4}\e + a
is a polynomial over the alphabet :math:`\{a,b\}`, and the weight-set
is a polynomial over the alphabet :math:`\{a,b\}`, and the weight set
:cpp:class:`z` (for instance). It has three monomials: ``{3}ab``,
``{4}\e`` and ``a``.
......@@ -34,7 +34,7 @@ weights. The above example implement the following mapping::
Overview
--------
``polynomialset`` implements the :doc:`Weight-Set interface
``polynomialset`` implements the :doc:`Weight Set interface
<weightsets>` (they are more usually used as *entries* rather than
*weights*) and adds a few other methods specific to the handling of
polynomials::
......@@ -67,7 +67,7 @@ polynomials::
value_t& add_weight(value_t& v, const word_t& w, const weight_t k) const;
const value_t get_weight(value_t& v, const word_t& w) const;
// Weight-set interface
// weight set interface
std::string sname() const;
value_t add(const value_t& l, const value_t& r) const;
value_t mul(const value_t& l, const value_t& r) const;
......@@ -88,7 +88,7 @@ New methods
-----------
We only describe methods that are not part of the
:doc:`Weight-Set interface <weightsets>`.
:doc:`Weight Set interface <weightsets>`.
.. function:: polynomialset<context_t>(const context_t& ctx)
......
......@@ -3,7 +3,7 @@
Scalar Weights
==============
The following classes implement the :doc:`Weight-Set interface <weightsets>`.
The following classes implement the :doc:`Weight Set interface <weightsets>`.
.. class:: b
......
.. default-domain:: cpp
Weight-Sets
Weight Sets
===========
.. index:: storage type, weight-set
......@@ -18,14 +18,14 @@ interpreted as an element of the semiring
:math:`(\mathbb{Z},+,\times,0,1)` or as an element of the semiring
:math:`(\mathbb{Z}\cup\{\infty\},\min,+,\infty,0)`.
A :dfn:`weight-set` object stores the semantic information associated
to the weights. Ideally you should have one weight-set instantiated
A :dfn:`weight set` object stores the semantic information associated
to the weights. Ideally you should have one weight set instantiated
somewhere in order to manipulate weights.
Overview
--------
Here is the required interface of a *Weight-Set* object::
Here is the required interface of a *Weight Set* object::
static std::string sname();
......@@ -48,7 +48,7 @@ Here is the required interface of a *Weight-Set* object::
std::string format(const value_t v) const;
std::ostream& print(std::ostream& o, const value_t v) const;
Implementations of weight-sets with a complex storage type may decide
Implementations of weight sets with a complex storage type may decide
to receive them as `const value_t&` and emit them as `const value_t&`
instead of the above pass-by-copy specifications.
......@@ -57,11 +57,11 @@ Detailed interface
.. function:: static std::string sname()
The (static) name of the weight-set (i.e., it's class name).
The (static) name of the weight set (i.e., its class name).
.. type:: value_t
The storage type of the weight-set's elements.
The storage type of the weight set's elements.
.. function:: value_t add(const value_t l, const value_t r) const
......@@ -108,7 +108,7 @@ Detailed interface
.. index:: positive semiring
Whether this weight-set is a *positive semiring*.
Whether this weight set is a *positive semiring*.
:math:`(\mathbb{K},+,\times,0,1)` is a :dfn:`positive semiring` if
it is *zero-divisor-free* and *zero-sum-free*: :math:`\forall
......@@ -139,7 +139,7 @@ Detailed interface
instead of ``std::cout << format(v)``, because no intermediate
string is created.
Available Weight-Sets
Available Weight Sets
---------------------
.. toctree::
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment