stamina-core 0.5.0

data/CHANGELOG.md

@@ -0,0 +1,78 @@
+# 0.5.0 / FIX ME
+
+* Breaking features.
+
+  * Support for ruby 1.8.7 has been definitely removed.
+
+* Major enhancements
+
+  * The project has been split in different sub gems (core, induction and gui). This
+    implies a lot of internal changes, but the public API has not been affected. A main
+    'stamina' gem automatically includes all sub gems so previous behavior is guaranteed.
+
+* Minor enhancements
+    * Fixed a bug with bundler usage in main stamina binary
+    * adl2dot command now support samples as input in addition to automata. In that case,
+      the dot result models a PTA (prefix tree acceptor)
+    * Added --png to 'stamina adl2dot'
+
+# 0.4.0 / 2011-05-01
+
+* Major Enhancements
+
+    * Added Automaton#to_adl as an shortcut for Stamina::ADL::print_automaton(...)
+    * Added Sample#to_pta taken from Induction::Commons
+    * Added Automaton completion (all strings parsable) under Automaton#complete[!?]
+    * Added Automaton stripping (removal of unreachable states) under Automaton#strip[!]
+    * Added Automaton minimization (Hopcroft + Pitchies) under Automaton#minimize
+    * Added Abbadingo generators under Abbadingo::RandomDFA and Abbadingo::RandomSample
+    * Added a main 'stamina' command relying on Quickl. classiy/adl2dot commands become
+      subcommands of stamina itself (see stamina --help for a list of available commands).
+      Induction command (rpni and redblue) are now handled by a 'stamina infer' with
+      options.
+    * Error states and now correctly handled in ADL::parse and ADL::flush
+    * RedBlue has been renamed as BlueFringe everywhere (red_?blue -> blue_fringe)
+
+* Minnor Enhancements
+    * Added a few optimizations here and there
+
+* Bug fixes
+
+    * Fixed a bug in Automaton#depth when some states are unreachable
+
+# 0.3.1 / 2011-03-24
+
+* Major Enhancements
+
+    * Implemented the decoration algorithm of Damas10, allowing to decorate states
+      with information propagated from states to states until a fixpoint is reached.
+    * Added Automaton::Metrics module, automatically included, with useful metrics
+      like automaton depth, accepting ratio and so on.
+    * Added Scoring module and Classifier#classification_scoring(sample) method
+      with common measures from information retrieval.
+
+* On the devel side
+
+    * Moved specific automaton tests under test/stamina/automaton/...
+
+# 0.3.0 / 2011-03-24
+
+* On the devel side
+
+  * The project structure is now handled by Noe
+  * Ensures that tests are correctly executed under ruby 1.9.2
+
+
+# 0.2.2 / 2010-10-22
+
+* Major Enhancements
+
+  * Sample#<< does not detect inconsistencies anymore, to ensure a linear method instead of a quadratic one.
+
+* On the devel side
+
+  * Fixes a bug in Rakefile that lead to test failures under ruby 1.8.7
+
+# 0.2.1 / 2010-05-01
+
+* Main public version for the official competition, extracted from private SVN.

data/LICENCE.md

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2008-2009 University of Louvain
+(Universite catholique de Louvain-la-Neuve, Belgium)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/stamina-core/stamina-core.rb

@@ -0,0 +1 @@
+require_relative 'stamina/core'

data/lib/stamina-core/stamina/adl.rb

@@ -0,0 +1,298 @@
+module Stamina
+  #
+  # Automaton Description Language module. This module provides parsing and
+  # printing methods for automata and samples. Documentation of the file format
+  # used for an automaton is given in parse_automaton; file format for samples is
+  # documented in parse_sample.
+  #
+  # Methods of this module are not intended to be included by a class but invoked
+  # on the module instead:
+  #
+  #   begin
+  #     dfa = Stamina::ADL.parse_automaton_file("my_automaton.adl")
+  #   rescue ADL::ParseError => ex
+  #     puts "Oops, the ADL automaton file seems corrupted..."
+  #   end
+  #
+  # == Detailed API
+  module ADL
+
+    #################################################################################
+    # Automaton Section                                                             #
+    #################################################################################
+
+    #
+    # Parses a given automaton description and returns an Automaton instance.
+    #
+    # Raises:
+    # - ArgumentError unless _descr_ is an IO object or a String.
+    # - ADL::ParseError if the ADL automaton format is not respected.
+    #
+    # ADL provides a really simple grammar to describe automata. Here is a succint
+    # example (full documentation of the ADL automaton grammar can be found in
+    # the self-documenting example/adl/automaton.adl file).
+    #
+    #    # Some header comments: tool which has generated this automaton,
+    #    # maybe a date or other tool options ...
+    #    # here: 'this automaton accepts the a(ba)* regular language'
+    #    2 2
+    #    0 true false
+    #    1 false true
+    #    0 1 a
+    #    1 0 b
+    #
+    def self.parse_automaton(descr)
+      automaton = nil
+      ADL::to_io(descr) do |io|
+        state_count, edge_count = nil, nil
+        state_read, edge_read = 0, 0
+        states = {}
+        mode = :header
+
+        automaton = Automaton.new do |fa|
+          # parse each description line
+          line_number = 1
+          io.each_line do |l|
+            index = l.index('#')
+            l = l[0,index] if index
+            l = l.strip
+            next if l.empty? or l[0,1]=='#'
+
+            case mode
+            when :header
+              # looking for |state_count edge_count|
+              raise(ADL::ParseError,
+                    "Parse error line #{line_number}: 'state_count edge_count' expected, "\
+                    "'#{l}' found.") unless /^(\d+)\s+(\d+)$/ =~ l
+              state_count, edge_count = $1.to_i, $2.to_i
+              mode = :states
+
+            when :states
+              # looking for |number initial accepting|
+              raise(ADL::ParseError,
+                    "Parse error line #{line_number}: state definition expected, "\
+                    "'#{l}' found.") unless /^(\S+)\s+(true|false)\s+(true|false)(\s+(true|false))?$/ =~ l
+              id, initial, accepting, error = $1, $2, $3, $5
+              initial, accepting, error = ("true"==initial), ("true"==accepting), ("true"==error)
+
+              state = fa.add_state(:initial => initial, :accepting => accepting, :error => error)
+              state[:name]=id.to_s
+              states[id] = state
+
+              state_read += 1
+              mode = (edge_count==0 ? :end : :edges) if state_read==state_count
+
+            when :edges
+              # looking for |source target symbol|
+              raise(ADL::ParseError,
+                    "Parse error line #{line_number}: edge definition expected, "\
+                    "'#{l}' found.") unless /^(\S+)\s+(\S+)\s+(\S+)$/ =~ l
+              source, target, symbol = $1, $2, $3
+              raise(ADL::ParseError,
+                    "Parse error line #{line_number}: no such state #{source}") \
+                    unless states[source]
+              raise(ADL::ParseError,
+                    "Parse error line #{line_number}: no such state #{target}") \
+                    unless states[target]
+
+              fa.connect(states[source], states[target], {:symbol => symbol})
+
+              edge_read += 1
+              mode = :end if edge_read==edge_count
+
+            when :end
+              raise(ADL::ParseError,
+                    "Parse error line #{line_number}: trailing data found '#{l}")
+
+            end # case mode
+
+            line_number += 1
+          end
+
+          raise(ADL::ParseError, "Parse error: #{state_count} states annouced, "\
+                               "#{state_read} found.") if state_count != state_read
+          raise(ADL::ParseError, "Parse error: #{edge_count} edges annouced, "\
+                               "#{edge_read} found.") if edge_count != edge_read
+
+        end # Automaton.new
+      end
+      return automaton
+    end # def self.parse
+
+    #
+    # Parses an automaton file _f_.
+    #
+    # Shortcut for:
+    #   File.open(f, 'r') do |io|
+    #     Stamina::ADL.parse_automaton(io)
+    #   end
+    #
+    def self.parse_automaton_file(f)
+      automaton = nil
+      File.open(f) do |file|
+        automaton = ADL::parse_automaton(file)
+      end
+      automaton
+    end
+
+    #
+    # Prints an automaton to a buffer (responding to <code>:&lt;&lt;</code>) in ADL
+    # format. Returns the buffer itself.
+    #
+    def self.print_automaton(fa, buffer="")
+      buffer << "#{fa.state_count.to_s} #{fa.edge_count.to_s}" << "\n"
+      fa.states.each do |s|
+        buffer << "#{s.index.to_s} #{s.initial?} #{s.accepting?}" << (s.error? ? " true" : "") << "\n"
+      end
+      fa.edges.each do |e|
+        buffer << "#{e.source.index.to_s} #{e.target.index.to_s} #{e.symbol.to_s}" << "\n"
+      end
+      buffer
+    end
+
+    #
+    # Prints an automaton to a file whose path is provided.
+    #
+    # Shortcut for:
+    #   File.open(file, 'w') do |io|
+    #     print_automaton(fa, io)
+    #  end
+    #
+    def self.print_automaton_to_file(fa, file)
+      File.open(file, 'w') do |io|
+        print_automaton(fa, io)
+      end
+    end
+
+    #################################################################################
+    # String and Sample Section                                                     #
+    #################################################################################
+
+    #
+    # Parses an input string _str_ and returns a InputString instance. Format of
+    # input strings is documented in parse_sample. _str_ is required to be a ruby
+    # String.
+    #
+    # Raises:
+    # - ADL::ParseError if the ADL string format is not respected.
+    #
+    def self.parse_string(str)
+      symbols = str.split(' ')
+      case symbols[0]
+        when '+'
+          symbols.shift
+          InputString.new symbols, true, false
+        when '-'
+          symbols.shift
+          InputString.new symbols, false, false
+        when '?'
+          symbols.shift
+          InputString.new symbols, nil, false
+        else
+          raise ADL::ParseError, "Invalid string format #{str}", caller
+      end
+    end
+
+    #
+    # Parses the sample provided by _descr_. When a block is provided, yields it with
+    # InputString instances and ignores the sample argument. Otherwise, fills the sample
+    # (any object responding to <code><<</code>) with string, creating a fresh new
+    # one (as a Sample instance) if sample is nil.
+    #
+    # ADL provides a really simple grammar to describe samples (here is a succint
+    # example, the full documentation of the sample grammar can be found in the
+    # self-documenting example/adl/sample.adl file):
+    #
+    #    #
+    #    # Some header comments: tool which has generated this sample,
+    #    # maybe a date or other tool options ...
+    #    # here: 'this sample is caracteristic for the a(ba)* regular language'
+    #    #
+    #    # Positive, Negative, Unlabeled strings become with +, -, ?, respectively
+    #    # Empty lines and lines becoming with # are simply ignored.
+    #    #
+    #    -
+    #    + a
+    #    - a b
+    #    + a b a
+    #
+    # Raises:
+    # - ArgumentError unless _descr_ argument is an IO object or a String.
+    # - ADL::ParseError if the ADL sample format is not respected.
+    # - InconsistencyError if the sample is not consistent (see Sample)
+    #
+    def self.parse_sample(descr, sample=nil)
+      sample = Sample.new if (sample.nil? and not block_given?)
+      ADL::to_io(descr) do |io|
+        io.each_line do |l|
+          l = l.strip
+          next if l.empty? or l[0,1]=='#'
+          if sample.nil? and block_given?
+            yield parse_string(l)
+          else
+            sample << parse_string(l)
+          end
+        end
+      end
+      sample
+    end
+
+    #
+    # Parses an automaton file _f_.
+    #
+    # Shortuct for:
+    #   File.open(f) do |file|
+    #      sample = ADL::parse_sample(file, sample)
+    #   end
+    #
+    def self.parse_sample_file(f, sample=nil)
+      File.open(f) do |file|
+        sample = ADL::parse_sample(file, sample)
+      end
+      sample
+    end
+
+    #
+    # Prints a sample in ADL format on a buffer. Sample argument is expected to be
+    # an object responding to each, yielding InputString instances. Buffer is expected
+    # to be an object responding to <code><<</code>.
+    #
+    def self.print_sample(sample, buffer="")
+      sample.each do |str|
+        buffer << str.to_s << "\n"
+      end
+    end
+
+    #
+    # Prints a sample in a file.
+    #
+    # Shortcut for:
+    #   File.open(file, 'w') do |io|
+    #     print_sample(sample, f)
+    #   end
+    #
+    def self.print_sample_in_file(sample, file)
+      File.open(file, 'w') do |f|
+        print_sample(sample, f)
+      end
+    end
+
+    ### private section ##########################################################
+    private
+
+    #
+    # Converts a parsable argument to an IO object or raises an ArgumentError.
+    #
+    def self.to_io(descr)
+      case descr
+      when IO
+        yield descr
+      when String
+        yield StringIO.new(descr)
+      else
+        raise ArgumentError, "IO instance expected, #{descr.class} received", caller
+      end
+    end
+
+  end # module ADL
+end # module Stamina

data/lib/stamina-core/stamina/automaton.rb

@@ -0,0 +1,1300 @@
+module Stamina
+
+  #
+  # Automaton data-structure.
+  #
+  # == Examples
+  # The following example uses a lot of useful DRY shortcuts, so, if it does not
+  # fit you needs then, read on!):
+  #
+  #     # Building an automaton for the regular language a(ba)*
+  #     fa = Automaton.new do
+  #       add_state(:initial => true)
+  #       add_state(:accepting => true)
+  #       connect(0,1,'a')
+  #       connect(1,0,'b')
+  #     end
+  #
+  #     # It accepts 'a b a b a', rejects 'a b' as well as ''
+  #     puts fa.accepts?('? a b a b a')   # prints true
+  #     puts fa.accepts?('? a b')         # prints false
+  #     puts fa.rejects?('?')            # prints true
+  #
+  # == Four things you need to know
+  # 1. Automaton, State and Edge classes implement a Markable design pattern, that
+  #    is, you can read and write any key/value pair you want on them using the []
+  #    and []= operators. Note that the following keys are used by Stamina itself,
+  #    with the obvious semantics (for automata and transducers):
+  #    - <tt>:initial</tt>, <tt>:accepting</tt>, <tt>:error</tt> on State;
+  #      expected to be _true_ or _false_ (_nil_ and ommitted are considered as false).
+  #      Shortcuts for querying and setting these attributes are provided by State.
+  #    - <tt>:symbol</tt> on Edge, with shortcuts as well on Edge.
+  #      The convention is to use _nil_ for the epsilon symbol (aka non observable)
+  #      on non deterministic automata.
+  #    The following keys are reserved for future extensions:
+  #    - <tt>:output</tt> on State and Edge.
+  #    - <tt>:short_prefix</tt> on State.
+  #    See also the "About states and edges" subsection of the design choices.
+  # 2. Why using State methods State#step and State#delta ? The Automaton class includes
+  #    the Walking module by default, which is much more powerful !
+  # 3. The constructor of this class executes the argument block (between <tt>do</tt>
+  #    and <tt>end</tt>) with instance_eval by default. You won't be able to invoke
+  #    the methods defined in the scope of your block in such a case. See new
+  #    for details.
+  # 4. This class has not been designed with efficiency in mind. If you experiment
+  #    performance problems, read the "About Automaton modifications" sub section
+  #    of the design choices.
+  #
+  # == Design choices
+  # This section fully details the design choices that has been made for the
+  # implementation of the Automaton data structure used by Stamina. It is provided
+  # because Automaton is one of the core classes of Stamina, that probably all
+  # users (and contributors) will use. Automaton usage is really user-friendly,
+  # so <b>you are normally not required</b> to read this section in the first
+  # place ! Read it only if of interest for you, or if you experiment unexpected
+  # results.
+  #
+  # === One Automaton class only
+  # One class only implements all kinds of automata: deterministic, non-deterministic,
+  # transducers, prefix-tree-acceptors, etc. The Markable design pattern on states and
+  # edges should allow you to make anything you could find useful with this class.
+  #
+  # === Adjacency-list graph
+  # This class implements an automaton using a adjacent-list graph structure.
+  # The automaton has state and edge array lists and exposes them through the
+  # _states_ and _edges_ accessors. In order to let users enjoy the enumerability
+  # of Ruby's arrays while allowing automata to be modified, these arrays are
+  # externaly modifiable. However, <b>users are not expected to modify them!</b>
+  # and future versions of Stamina will certainly remove this ability.
+  #
+  # === Indices exposed
+  # State and Edge indices in these arrays are exposed by this class. Unless stated
+  # explicitely, all methods taking state or edge arguments support indices as well.
+  # Moreover, ith_state, ith_states, ith_edge and ith_edges methods provide powerful
+  # access to states and edges by indices. All these methods are robust to invalid
+  # indices (and raise an IndexError if incorrectly invoked) but do not allow
+  # negative indexing (unlike ruby arrays).
+  #
+  # States and edges know their index in the corresponding array and expose them
+  # through the (read-only) _index_ accessor. These indices are always valid;
+  # without deletion of states or edges in the automaton, they are guaranteed not
+  # to change. Indices saved in your own variables must be considered deprecated
+  # each time you perform a deletion ! That's the only rule to respect if you plan
+  # to use indices.
+  #
+  # Indices exposition may seem a strange choice and could be interpreted as
+  # breaking OOP's best practice. You are not required to use them but, as will
+  # quiclky appear, using them is really powerful and leads to beautiful code!
+  # If you don't remove any state or edge, this class guarantees that indices
+  # are assigned in the same order as invocations of add_state and add_edge (as
+  # well as their plural forms and aliases).
+  #
+  # === About states and edges
+  # Edges know their source and target states, which are exposed through the
+  # _source_ and _target_ (read-only) accessors (also aliased as _from_ and _to_).
+  # States keep their incoming and outgoing edges in arrays, which are accessible
+  # (in fact, a copy) using State#in_edges and State#out_edges. If you use them
+  # for walking the automaton in a somewhat standard way, consider using the Walking
+  # module instead!
+  #
+  # Common attributes of states and edges are installed using the Markable pattern
+  # itself:
+  # - <tt>:initial</tt>, <tt>:accepting</tt> and <tt>:error</tt> on states. These
+  #   attributes are expected to be _true_ or _false_ (_nil_ and ommitted are also
+  #   supported and both considered as false).
+  # - <tt>:symbol</tt> on edges. Any object you want as long as it responds to the
+  #   <tt><=></tt> operator. Also, the convention is to use _nil_ for the epsilon
+  #   symbol (aka non observable) on non deterministic automata.
+  #
+  # In addition, useful shortcuts are available:
+  # - <tt>s.initial?</tt> is a shortcut for <tt>s[:initial]</tt> if _s_ is a State
+  # - <tt>s.initial!</tt> is a shortcut for <tt>s[:initial]=true</tt> if _s_ is a State
+  # - Similar shortcuts are available for :accepting and :error
+  # - <tt>e.symbol</tt> is a shortcut for <tt>e[:symbol]</tt> if _e_ is an Edge
+  # - <tt>e.symbol='a'</tt> is a shortcut for <tt>e[:symbol]='a'</tt> if _e_ is an Edge
+  #
+  # Following keys should be considered reserved by Stamina for future extensions:
+  # - <tt>:output</tt> on State and Edge.
+  # - <tt>:short_prefix</tt> on State.
+  #
+  # === About Automaton modifications
+  # This class has not been implemented with efficiency in mind. In particular, we expect
+  # the vast majority of Stamina core algorithms considering automata as immutable values.
+  # For this reason, the Automaton class does not handle modifications really efficiently.
+  #
+  # So, if you experiment performance problems, consider what follows:
+  # 1. Why updating an automaton ? Building a fresh one is much more clean and efficient !
+  #    This is particularly true for removals.
+  # 2. If you can create multiples states or edges at once, consider the plural form
+  #    of the modification methods: add_n_states and drop_states. Those methods are
+  #    optimized for multiple updates.
+  #
+  # == Detailed API
+  class Automaton
+    include Stamina::Markable
+
+    #
+    # Automaton state.
+    #
+    class State
+      include Stamina::Markable
+      attr_reader :automaton, :index
+
+      #
+      # Creates a state.
+      #
+      # Arguments:
+      # - automaton: parent automaton of the state.
+      # - index: index of the state in the state list.
+      # - data: user data attached to this state.
+      #
+      def initialize(automaton, index, data)
+        @automaton = automaton
+        @index = index
+        @data = data.dup
+        @out_edges = []
+        @in_edges = []
+        @epsilon_closure = nil
+      end
+
+      ### public read-only section ###############################################
+      public
+
+      # Returns true if this state is an initial state, false otherwise.
+      def initial?
+        !!@data[:initial]
+      end
+
+      # Sets this state as an initial state.
+      def initial!
+        @data[:initial] = true
+      end
+
+      # Returns true if this state is an accepting state, false otherwise.
+      def accepting?
+        !!@data[:accepting]
+      end
+
+      # Sets this state as an accepting state.
+      def accepting!
+        @data[:accepting] = true
+      end
+
+      # Returns true if this state is an error state, false otherwise.
+      def error?
+        !!@data[:error]
+      end
+
+      # Sets this state as an error state.
+      def error!
+        @data[:error] = true
+      end
+
+      # Returns true if this state is deterministic, false otherwise.
+      def deterministic?
+        outs = out_symbols
+        (outs.size==@out_edges.size) and not(outs.include?(nil))
+      end
+
+      # Checks if this state is a sink state or not. Sink states are defined as
+      # non accepting states having no outgoing transition or only loop
+      # transitions.
+      def sink?
+        !accepting? && out_edges.all?{|e| e.target==self}
+      end
+
+      # Returns an array containing all incoming edges of the state. Edges are
+      # sorted if _sorted_ is set to true. If two incoming edges have same symbol
+      # no order is guaranteed between them.
+      #
+      # Returned array may be modified.
+      def in_edges(sorted=false)
+        sorted ? @in_edges.sort : @in_edges.dup
+      end
+
+      # Returns an array containing all outgoing edges of the state. Edges are
+      # sorted if _sorted_ is set to true. If two outgoing edges have same symbol
+      # no order is guaranteed between them.
+      #
+      # Returned array may be modified.
+      def out_edges(sorted=false)
+        sorted ? @out_edges.sort : @out_edges.dup
+      end
+
+      # Returns an array with the different symbols appearing on incoming edges.
+      # Returned array does not contain duplicates. Symbols are sorted in the
+      # array if _sorted_ is set to true.
+      #
+      # Returned array may be modified.
+      def in_symbols(sorted=false)
+        symbols = @in_edges.collect{|e| e.symbol}.uniq
+        return sorted ? (symbols.sort &automaton.symbols_comparator) : symbols
+      end
+
+      # Returns an array with the different symbols appearing on outgoing edges.
+      # Returned array does not contain duplicates. Symbols are sorted in the
+      # array if _sorted_ is set to true.
+      #
+      # Returned array may be modified.
+      def out_symbols(sorted=false)
+        symbols = @out_edges.collect{|e| e.symbol}.uniq
+        return sorted ? (symbols.sort &automaton.symbols_comparator) : symbols
+      end
+
+      # Returns an array with adjacent states (in or out edge).
+      #
+      # Returned array may be modified.
+      def adjacent_states()
+        (in_adjacent_states+out_adjacent_states).uniq
+      end
+
+      # Returns an array with adjacent states along an incoming edge (without
+      # duplicates).
+      #
+      # Returned array may be modified.
+      def in_adjacent_states()
+        (@in_edges.collect {|e| e.source}).uniq
+      end
+
+      # Returns an array with adjacent states along an outgoing edge (whithout
+      # duplicates).
+      #
+      # Returned array may be modified.
+      def out_adjacent_states()
+        (@out_edges.collect {|e| e.target}).uniq
+      end
+
+      # Returns reachable states from this one with an input _symbol_. Returned
+      # array does not contain duplicates and may be modified. This method if not
+      # epsilon symbol aware.
+      def step(symbol)
+        @out_edges.select{|e| e.symbol==symbol}.collect{|e| e.target}
+      end
+
+      # Returns the state reached from this one with an input _symbol_, or nil if
+      # no such state. This method is not epsilon symbol aware. Moreover it is
+      # expected to be used on deterministic states only. If the state is not
+      # deterministic, the method returns one reachable state if such a state
+      # exists; which one is returned must be considered non deterministic.
+      def dfa_step(symbol)
+        edge = @out_edges.find{|e| e.symbol==symbol}
+        edge ? edge.target : nil
+      end
+
+      # Computes the epsilon closure of this state. Epsilon closure is the set of
+      # all states reached from this one with a <tt>eps*</tt> input (sequence of
+      # zero or more epsilon symbols). The current state is always contained in
+      # the epsilon closure. Returns an unsorted array without duplicates; this
+      # array may not be modified.
+      def epsilon_closure()
+        @epsilon_closure ||= compute_epsilon_closure(Set.new).to_a.freeze
+      end
+
+      # Internal implementation of epsilon_closure. _result_ is expected to be
+      # a Set instance, is modified and is the returned value.
+      def compute_epsilon_closure(result)
+        result << self
+        step(nil).each do |t|
+          t.compute_epsilon_closure(result) unless result.include?(t)
+        end
+        raise if result.nil?
+        return result
+      end
+
+      # Computes an array representing the set of states that can be reached from
+      # this state with a given input _symbol_. Returned array does not contain
+      # duplicates and may be modified. No particular ordering of states in the
+      # array is guaranteed.
+      #
+      # This method is epsilon symbol aware (represented with nil) on non
+      # deterministic automata, meaning that it actually computes the set of
+      # reachable states through strings respecting the <tt>eps* symbol eps*</tt>
+      # regular expression, where eps is the epsilon symbol.
+      def delta(symbol)
+        if automaton.deterministic?
+          target = dfa_delta(symbol)
+          target.nil? ? [] : [target]
+        else
+          # 1) first compute epsilon closure of self
+          at_epsilon = epsilon_closure
+
+          # 2) now, look where we can go from there
+          at_espilon_then_symbol = at_epsilon.collect do |s|
+            s.step(symbol)
+          end.flatten.uniq
+
+          # 3) look where we can go from there using epsilon
+          result = at_espilon_then_symbol.collect do |s|
+            s.epsilon_closure
+          end.flatten.uniq
+
+          # return result as an array
+          result
+        end
+      end
+
+      # Returns the target state that can be reached from this state with _symbol_
+      # input. Returns nil if no such state exists.
+      #
+      # This method is expected to be used on deterministic automata. Unlike delta,
+      # it returns a State instance (or nil), not an array of states. When used on
+      # non deterministic automata, it returns a state immediately reachable from
+      # this state with _symbol_ input, or nil if no such state exists. This
+      # method is not epsilon aware.
+      def dfa_delta(symbol)
+        return nil if symbol.nil?
+        edge = @out_edges.find{|e| e.symbol==symbol}
+        edge.nil? ? nil : edge.target
+      end
+
+      # Provides comparator of states, based on the index in the automaton state
+      # list. This method returns nil unless  _o_ is a State from the same
+      # automaton than self.
+      def <=>(o)
+        return nil unless State===o
+        return nil unless automaton===o.automaton
+        return index <=> o.index
+      end
+
+      # Returns a string representation
+      def inspect
+        's' << @index.to_s
+      end
+
+      # Returns a string representation
+      def to_s
+        's' << @index.to_s
+      end
+
+      ### protected write section ################################################
+      protected
+
+      # Changes the index of this state in the state list. This method is only
+      # expected to be used by the automaton itself.
+      def index=(i) @index=i end
+
+      #
+      # Fired by Loaded when a user data is changed. The message is forwarded to
+      # the automaton.
+      #
+      def state_changed(what, description)
+        @epsilon_closure = nil
+        @automaton.send(:state_changed, what, description)
+      end
+
+      # Adds an incoming edge to the state.
+      def add_incoming_edge(edge)
+        @epsilon_closure = nil
+        @in_edges << edge
+      end
+
+      # Adds an outgoing edge to the state.
+      def add_outgoing_edge(edge)
+        @epsilon_closure = nil
+        @out_edges << edge
+      end
+
+      # Adds an incoming edge to the state.
+      def drop_incoming_edge(edge)
+        @epsilon_closure = nil
+        @in_edges.delete(edge)
+      end
+
+      # Adds an outgoing edge to the state.
+      def drop_outgoing_edge(edge)
+        @epsilon_closure = nil
+        @out_edges.delete(edge)
+      end
+
+      protected :compute_epsilon_closure
+    end
+
+    #
+    # Automaton edge.
+    #
+    class Edge
+      include Stamina::Markable
+      attr_reader :automaton, :index, :from, :to
+
+      #
+      # Creates an edge.
+      #
+      # Arguments:
+      # - automaton: parent automaton of the edge.
+      # - index: index of the edge in the edge list.
+      # - data: user data attached to this edge.
+      # - from: source state of the edge.
+      # - to: target state of the edge.
+      #
+      def initialize(automaton, index, data, from, to)
+        @automaton, @index = automaton, index
+        @data = data
+        @from, @to = from, to
+      end
+
+      # Returns edge symbol.
+      def symbol()
+        @data[:symbol]
+      end
+
+      # Sets edge symbol.
+      def symbol=(symbol)
+        @data[:symbol] = symbol
+      end
+
+      alias :source :from
+      alias :target :to
+
+      #
+      # Provides comparator of edges, based on the index in the automaton edge
+      # list. This method returns nil unless  _o_ is an Edge from the same
+      # automaton than self.
+      # Once again, this method has nothing to do with equality, it looks at an
+      # index and ID only.
+      #
+      def <=>(o)
+        return nil unless Edge===o
+        return nil unless automaton===o.automaton
+        return index <=> o.index
+      end
+
+      # Returns a string representation
+      def inspect
+        'e' << @index.to_s
+      end
+
+      # Returns a string representation
+      def to_s
+        'e' << @index.to_s
+      end
+
+      ### protected write section ################################################
+      protected
+
+      # Changes the index of this edge in the edge list. This method is only
+      # expected to be used by the automaton itself.
+      def index=(i) @index=i end
+
+      #
+      # Fired by Loaded when a user data is changed. The message if forwarded to
+      # the automaton.
+      #
+      def state_changed(what, infos)
+        @automaton.send(:state_changed, what, infos)
+      end
+
+    end
+
+    ### Automaton class ##########################################################
+    public
+
+    # State list and edge list of the automaton
+    attr_reader :states, :edges
+
+    #
+    # Creates an empty automaton and executes the block passed as argument. The _onself_
+    # argument dictates the way _block_ is executed:
+    # - when set to false, the block is executed traditionnally (i.e. using yield).
+    #   In this case, methods invocations must be performed on the automaton object
+    #   passed as block argument.
+    # - when set to _true_ (by default) the block is executed in the context of the
+    #   automaton itself (i.e. with instance_eval), allowing call of its methods
+    #   without prefixing them by the automaton variable. The automaton still
+    #   passes itself as first block argument. Note that in this case, you won't be
+    #   able to invoke a method defined in the scope of your block.
+    #
+    # Example:
+    #   # The DRY way to do:
+    #   Automaton.new do |automaton|     # automaton will not be used here, but it is passed
+    #     add_state(:initial => true)
+    #     add_state(:accepting => true)
+    #     connect(0, 1, 'a')
+    #     connect(1, 0, 'b')
+    #
+    #     # method_in_caller_scope()     # commented because not allowed here !!
+    #   end
+    #
+    #   # The other way:
+    #   Automaton.new(false) do |automaton|      # automaton MUST be used here
+    #     automaton.add_state(:initial => true)
+    #     automaton.add_state(:accepting => true)
+    #     automaton.connect(0, 1, 'a')
+    #     automaton.connect(1, 0, 'b')
+    #
+    #     method_in_caller_scope()               # allowed in this variant !!
+    #   end
+    #
+    def initialize(onself=true, &block) # :yields: automaton
+      @states = []
+      @edges = []
+      @initials = nil
+      @alphabet = nil
+      @deterministic = nil
+
+      # if there's a block, execute it now!
+      if block_given?
+        if onself
+          if RUBY_VERSION >= "1.9.0"
+            instance_exec(self, &block)
+          else
+            instance_eval(&block)
+          end
+        else
+          block.call(self)
+        end
+      end
+    end
+
+    # Coerces `arg` to an automaton
+    def self.coerce(arg)
+      if arg.respond_to?(:to_fa)
+        arg.to_fa
+      elsif arg.is_a?(String)
+        parse(arg)
+      else
+        raise ArgumentError, "Invalid argument #{arg} for `Automaton`"
+      end
+    end
+
+    # Parses an automaton using ADL
+    def self.parse(str)
+      ADL::parse_automaton(str)
+    end
+
+    ### public read-only section #################################################
+    public
+
+    # Returns a symbols comparator taking epsilon symbols into account. Comparator
+    # is provided as Proc instance which is a lambda function.
+    def symbols_comparator
+      @symbols_comparator ||= Kernel.lambda do |a,b|
+        if a==b then 0
+        elsif a.nil? then -1
+        elsif b.nil? then 1
+        else a <=> b
+        end
+      end
+    end
+
+    # Returns the number of states
+    def state_count() @states.size end
+
+    # Returns the number of edges
+    def edge_count() @edges.size end
+
+    #
+    # Returns the i-th state of the state list.
+    #
+    # Raises:
+    # - ArgumentError unless i is an Integer
+    # - IndexError if i is not in [0..state_count)
+    #
+    def ith_state(i)
+      raise(ArgumentError, "Integer expected, #{i} found.", caller)\
+        unless Integer === i
+      raise(ArgumentError, "Invalid state index #{i}", caller)\
+        unless i>=0 and i<state_count
+      @states[i]
+    end
+
+    #
+    # Returns state associated with the supplied state name, throws an exception if no such state can be found.
+    #
+    def get_state(name)
+      raise(ArgumentError, "String expected, #{name} found.", caller)\
+        unless String === name
+        result = states.find do |s|
+          name == s[:name]
+        end
+      raise(ArgumentError, "State #{name} was not found", caller)\
+        if result.nil?
+      result
+    end
+
+    #
+    # Returns the i-th states of the state list.
+    #
+    # Raises:
+    # - ArgumentError unless all _i_ are integers
+    # - IndexError unless all _i_ are in [0..state_count)
+    #
+    def ith_states(*i)
+      i.collect{|j| ith_state(j)}
+    end
+
+    #
+    # Returns the i-th edge of the edge list.
+    #
+    # Raises:
+    # - ArgumentError unless i is an Integer
+    # - IndexError if i is not in [0..state_count)
+    #
+    def ith_edge(i)
+      raise(ArgumentError, "Integer expected, #{i} found.", caller)\
+        unless Integer === i
+      raise(ArgumentError, "Invalid edge index #{i}", caller)\
+        unless i>=0 and i<edge_count
+      @edges[i]
+    end
+
+    #
+    # Returns the i-th edges of the edge list.
+    #
+    # Raises:
+    # - ArgumentError unless all _i_ are integers
+    # - IndexError unless all _i_ are in [0..edge_count)
+    #
+    def ith_edges(*i)
+      i.collect{|j| ith_edge(j)}
+    end
+
+    #
+    # Calls block for each state of the automaton state list. States are
+    # enumerated in index order.
+    #
+    def each_state() @states.each {|s| yield s if block_given?} end
+
+    #
+    # Calls block for each edge of the automaton edge list. Edges are
+    # enumerated in index order.
+    #
+    def each_edge() @edges.each {|e| yield e if block_given?} end
+
+    #
+    # Returns an array with incoming edges of _state_. Edges are sorted by symbols
+    # if _sorted_ is set to true. If two incoming edges have same symbol, no
+    # order is guaranteed between them. Returned array may be modified.
+    #
+    # If _state_ is an Integer, this method returns the incoming edges of the
+    # state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if _state_ is not a valid state for this automaton.
+    #
+    def in_edges(state, sorted=false) to_state(state).in_edges(sorted) end
+
+    #
+    # Returns an array with outgoing edges of _state_. Edges are sorted by symbols
+    # if _sorted_ is set to true. If two incoming edges have same symbol, no
+    # order is guaranteed between them. Returned array may be modified.
+    #
+    # If _state_ is an Integer, this method returns the outgoing edges of the
+    # state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if state is not a valid state (not a state or not from this
+    #   automaton)
+    #
+    def out_edges(state, sorted=false) to_state(state).out_edges(sorted) end
+
+    #
+    # Returns an array with the different symbols appearing on incoming edges of
+    # _state_. Returned array does not contain duplicates and may be modified;
+    # it is sorted if _sorted_ is set to true.
+    #
+    # If _state_ is an Integer, this method returns the incoming symbols of the
+    # state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if _state_ is not a valid state for this automaton.
+    #
+    def in_symbols(state, sorted=false) to_state(state).in_symbols(sorted) end
+
+    #
+    # Returns an array with the different symbols appearing on outgoing edges of
+    # _state_. Returned array does not contain duplicates and may be modified;
+    # it is sorted if _sorted_ is set to true.
+    #
+    # If _state_ is an Integer, this method returns the outgoing symbols of the
+    # state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if state is not a valid state (not a state or not from this
+    #   automaton)
+    #
+    def out_symbols(state, sorted=false) to_state(state).out_symbols(sorted) end
+
+    #
+    # Returns an array with adjacent states (along incoming and outgoing edges)
+    # of _state_. Returned array does not contain duplicates; it may be modified.
+    #
+    # If _state_ is an Integer, this method returns the adjacent states of the
+    # state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if state is not a valid state (not a state or not from this
+    #   automaton)
+    #
+    def adjacent_states(state) to_state(state).adjacent_states() end
+
+    #
+    # Returns an array with adjacent states (along incoming edges) of _state_.
+    # Returned array does not contain duplicates; it may be modified.
+    #
+    # If _state_ is an Integer, this method returns the incoming adjacent states
+    # of the state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if state is not a valid state (not a state or not from this
+    #   automaton)
+    #
+    def in_adjacent_states(state) to_state(state).in_adjacent_states() end
+
+    #
+    # Returns an array with adjacent states (along outgoing edges) of _state_.
+    # Returned array does not contain duplicates; it may be modified.
+    #
+    # If _state_ is an Integer, this method returns the outgoing adjacent states
+    # of the state'th state in the state list.
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if state is not a valid state (not a state or not from this
+    #   automaton)
+    #
+    def out_adjacent_states(state) to_state(state).out_adjacent_states() end
+
+    #
+    # Collects all initial states of this Automaton and returns it. Returned array
+    # does not contain duplicates and may be modified.
+    #
+    # This method is epsilon symbol aware (represented with nil) on
+    # non-deterministic automata, meaning that it actually computes the set of
+    # reachable states from an initial state through strings respecting the
+    # <tt>eps*</tt> regular expression, where eps is the epsilon symbol.
+    #
+    def initial_states
+      if @initials.nil? or @initials.empty?
+        @initials = compute_initial_states
+      end
+      @initials
+    end
+
+    #
+    # Returns the initial state of the automaton. This method is expected to used
+    # on deterministic automata only. Unlike initial_states, it returns one State
+    # instance instead of an Array.
+    #
+    # When used with a non deterministic automaton, it returns one of the states
+    # tagged as initial. Which one is returned must be considered a non
+    # deterministic choice. This method is not epsilon symbol aware.
+    #
+    def initial_state
+      initial_states[0]
+    end
+
+    # Internal implementation of initial_states.
+    def compute_initial_states()
+      initials = @states.select {|s| s.initial?}
+      initials.collect{|s| s.epsilon_closure}.flatten.uniq
+    end
+
+    ### public write section #####################################################
+    public
+
+    #
+    # Adds a new state.
+    #
+    # Arguments:
+    # - data: user-data to attach to the state (see Automaton documentation).
+    #
+    # Raises:
+    # - ArgumentError if _data_ is not a valid state data.
+    #
+    def add_state(data={})
+      data = to_valid_state_data(data)
+
+      # create new state, add it to state-list
+      state = State.new(self, state_count, data)
+      @states <<  state
+
+      # let the automaton know that something has changed
+      state_changed(:state_added, state)
+
+      # return created state
+      state
+    end
+    alias :create_state :add_state
+
+    #
+    # Adds _n_ new states in the automaton. Created states are returned as an
+    # ordered array (order of states according to their index in state list).
+    #
+    # _data_ is duplicated for each created state.
+    #
+    def add_n_states(n, data={})
+      created = []
+      n.times do |i|
+        created << add_state(block_given? ? data.merge(yield(i)) : data.dup)
+      end
+      created
+    end
+    alias :create_n_states :add_n_states
+
+    #
+    # Adds a new edge, connecting _from_ and _to_ states of the automaton.
+    #
+    # Arguments:
+    # - from: either a State or a valid state index (Integer).
+    # - to: either a State or a valid state index (Integer).
+    # - data: user data to attach to the created edge (see Automaton documentation).
+    #
+    # Raises:
+    # - IndexError if _from_ is an Integer but not in [0..state_count)
+    # - IndexError if _to_ is an Integer but not in [0..state_count)
+    # - ArgumentError if _from_ is not a valid state for this automaton.
+    # - ArgumentError if _to_ is not a valid state for this automaton.
+    # - ArgumentError if _data_ is not a valid edge data.
+    #
+    def add_edge(from, to, data)
+      from, to, data = to_state(from), to_state(to), to_valid_edge_data(data)
+
+      # create edge, install it, add it to edge-list
+      edge = Edge.new(self, edge_count, data, from, to)
+      @edges << edge
+      from.send(:add_outgoing_edge, edge)
+      to.send(:add_incoming_edge, edge)
+
+      # let automaton know that something has changed
+      state_changed(:edge_added, edge)
+
+      # return created edge
+      edge
+    end
+    alias :create_edge :add_edge
+    alias :connect :add_edge
+
+    #
+    # Adds all states and transitions (as copies) from a different automaton.
+    # None of the added states are made initial. Returns the (associated state
+    # of the) initial state of the added part.
+    #
+    # This method is deprecated and should not be used anymore. Use dup instead.
+    #
+    # In order to ensure that names of the new states do not clash with names of
+    # existing states, state names may have to be removed from added states;
+    # this is the case if _clear_names_ is set to true.
+    #
+    def add_automaton(fa, clear_names = true)
+      initial = nil
+      fa.dup(self){|source,target|
+        initial = target if target.initial?
+        target[:initial] = false
+        target[:name] = nil if clear_names
+      }
+      initial
+    end
+
+    #
+    # Constructs a replica of this automaton and returns a copy.
+    #
+    # This copy can be modified in whatever way without affecting the original
+    # automaton.
+    #
+    def dup(fa = Automaton.new)
+      added = states.collect do |source|
+        target = fa.add_state(source.data.dup)
+        yield(source, target) if block_given?
+        target
+      end
+      edges.each do |edge|
+        from, to = added[edge.from.index], added[edge.to.index]
+        fa.connect(from, to, edge.data.dup)
+      end
+      fa
+    end
+
+    #
+    # Drops a state of the automaton, as well as all connected edges to that state.
+    # If _state_ is an integer, the state-th state of the state list is removed.
+    # This method returns the automaton itself.
+    #
+    # Raises:
+    # - IndexError if _edge_ is an Integer but not in [0..edge_count)
+    # - ArgumentError if _edge_ is not a valid edge for this automaton.
+    #
+    def drop_state(state)
+      state = to_state(state)
+      # remove edges first: drop_edges ensures that edge list is coherent
+      drop_edges(*(state.in_edges + state.out_edges).uniq)
+
+      # remove state now and renumber
+      @states.delete_at(state.index)
+      state.index.upto(state_count-1) do |i|
+        @states[i].send(:index=, i)
+      end
+      state.send(:index=, -1)
+
+      state_changed(:state_dropped, state)
+      self
+    end
+    alias :delete_state :drop_state
+
+    #
+    # Drops all states passed as parameter as well as all their connected edges.
+    # Arguments may be state instances, as well as valid state indices. Duplicates
+    # are even supported. This method has no effect on the automaton and raises
+    # an error if some state argument is not valid.
+    #
+    # Raises:
+    # - ArgumentError if one state in _states_ is not a valid state of this
+    #   automaton.
+    #
+    def drop_states(*states)
+      # check states first
+      states = states.collect{|s| to_state(s)}.uniq.sort
+      edges  = states.collect{|s| (s.in_edges + s.out_edges).uniq}.flatten.uniq.sort
+
+      # Remove all edges, we do not use drop_edges to avoid spending too much
+      # time reindexing edges. Moreover, we can do it that way because we take
+      # edges in reverse indexing order (has been sorted previously)
+      until edges.empty?
+        edge = edges.pop
+        edge.source.send(:drop_outgoing_edge,edge)
+        edge.target.send(:drop_incoming_edge,edge)
+        @edges.delete_at(edge.index)
+        edge.send(:index=, -1)
+        state_changed(:edge_dropped, edge)
+      end
+
+      # Remove all states, same kind of hack is used
+      until states.empty?
+        state = states.pop
+        @states.delete_at(state.index)
+        state.send(:index=, -1)
+        state_changed(:state_dropped, state)
+      end
+
+      # sanitize state and edge lists
+      @states.each_with_index {|s,i| s.send(:index=,i)}
+      @edges.each_with_index {|e,i| e.send(:index=,i)}
+
+      self
+    end
+
+    #
+    # Drops an edge in the automaton. If _edge_ is an integer, the edge-th edge
+    # of the edge list is removed. This method returns the automaton itself.
+    #
+    # Raises:
+    # - IndexError if _edge_ is an Integer but not in [0..edge_count)
+    # - ArgumentError if _edge_ is not a valid edge for this automaton.
+    #
+    def drop_edge(edge)
+      edge = to_edge(edge)
+      @edges.delete_at(edge.index)
+      edge.from.send(:drop_outgoing_edge,edge)
+      edge.to.send(:drop_incoming_edge,edge)
+      edge.index.upto(edge_count-1) do |i|
+        @edges[i].send(:index=, i)
+      end
+      edge.send(:index=,-1)
+      state_changed(:edge_dropped, edge)
+      self
+    end
+    alias :delete_edge :drop_edge
+
+    #
+    # Drops all edges passed as parameters. Arguments may be edge objects,
+    # as well as valid edge indices. Duplicates are even supported. This method
+    # has no effect on the automaton and raises an error if some edge argument
+    # is not valid.
+    #
+    # Raises:
+    # - ArgumentError if one edge in _edges_ is not a valid edge of this automaton.
+    #
+    def drop_edges(*edges)
+      # check edges first
+      edges = edges.collect{|e| to_edge(e)}.uniq
+
+      # remove all edges
+      edges.each do |e|
+        @edges.delete(e)
+        e.from.send(:drop_outgoing_edge,e)
+        e.to.send(:drop_incoming_edge,e)
+        e.send(:index=, -1)
+        state_changed(:edge_dropped, e)
+      end
+      @edges.each_with_index do |e,i|
+        e.send(:index=,i)
+      end
+
+      self
+    end
+    alias :delete_edges :drop_edges
+
+    ### protected section ########################################################
+    protected
+
+    #
+    # Converts a _state_ argument to a valid State of this automaton.
+    # There are three ways to refer to a state, by position in the internal
+    # collection of states, using an instance of State and using a name of a
+    # state (represented with a String).
+    #
+    # Raises:
+    # - IndexError if state is an Integer and state<0 or state>=state_count.
+    # - ArgumentError if state is not a valid state (not a state or not from this
+    #   automaton)
+    #
+    def to_state(state)
+      case state
+      when State
+        return state if state.automaton==self and state==@states[state.index]
+        raise ArgumentError, "Not a state of this automaton", caller
+      when Integer
+        return ith_state(state)
+      when String
+        result = get_state(state)
+        return result unless result.nil?
+      end
+      raise ArgumentError, "Invalid state argument #{state}", caller
+    end
+
+    #
+    # Converts an _edge_ argument to a valid Edge of this automaton.
+    #
+    # Raises:
+    # - IndexError if _edge_ is an Integer but not in [0..edge_count)
+    # - ArgumentError if _edge_ is not a valid edge (not a edge or not from this
+    #   automaton)
+    #
+    def to_edge(edge)
+      case edge
+      when Edge
+        return edge if edge.automaton==self and edge==@edges[edge.index]
+        raise ArgumentError, "Not an edge of this automaton", caller
+      when Integer
+        return ith_edge(edge)
+      end
+      raise ArgumentError, "Invalid edge argument #{edge}", caller
+    end
+
+    #
+    # Checks if a given user-data contains enough information to be attached to
+    # a given state. Returns the data if ok.
+    #
+    # Raises:
+    # - ArgumentError if data is not considered a valid state data.
+    #
+    def to_valid_state_data(data)
+      raise(ArgumentError,
+            "User data should be an Hash", caller) unless Hash===data
+      data
+    end
+
+    #
+    # Checks if a given user-data contains enough information to be attached to
+    # a given edge. Returns the data if ok.
+    #
+    # Raises:
+    # - ArgumentError if data is not considered a valid edge data.
+    #
+    def to_valid_edge_data(data)
+      return {:symbol => data} if data.nil? or data.is_a?(String)
+      raise(ArgumentError,
+            "User data should be an Hash", caller) unless Hash===data
+      raise(ArgumentError,
+            "User data should contain a :symbol attribute.",
+            caller) unless data.has_key?(:symbol)
+      raise(ArgumentError,
+            "Edge :symbol attribute cannot be an array.",
+            caller) if Array===data[:symbol]
+      data
+    end
+
+    ### public sections with useful utilities ####################################
+    public
+
+    # Returns true if the automaton is deterministic, false otherwise
+    def deterministic?
+      if @deterministic.nil?
+        @deterministic = @states.all?{|s| s.deterministic?}
+      end
+      @deterministic
+    end
+
+    ### public & protected sections about alphabet ###############################
+    protected
+
+    # Deduces the alphabet from the automaton edges.
+    def deduce_alphabet
+      edges.collect{|e| e.symbol}.uniq.compact.sort
+    end
+
+    public
+
+    # Returns the alphabet of the automaton.
+    def alphabet
+      @alphabet || deduce_alphabet
+    end
+
+    # Sets the aphabet of the automaton. _alph_ is expected to be an array without
+    # nil nor duplicated. This method raises an ArgumentError otherwise. Such an
+    # error is also raised if a symbol used on the automaton edges is not included
+    # in _alph_.
+    def alphabet=(alph)
+      raise ArgumentError, "Invalid alphabet" unless alph.uniq.compact.size==alph.size
+      raise ArgumentError, "Invalid alphabet" unless deduce_alphabet.reject{|s| alph.include?(s)}.empty?
+      @alphabet = alph.sort
+    end
+
+    ### public section about coercions ###########################################
+    public
+
+    # Returns a finite automaton
+    def to_fa
+      self
+    end
+
+    # Returns a deterministic finite automaton
+    def to_dfa
+      self.deterministic? ? self : self.determinize
+    end
+
+    # Returns a canonical deterministic finite automaton
+    def to_cdfa
+      cdfa = self
+      cdfa = cdfa.determinize unless self.deterministic?
+      cdfa = cdfa.complete    unless self.complete?
+      cdfa = cdfa.minimize
+      cdfa
+    end
+
+    # Returns a regular language
+    def to_reglang
+      RegLang.new(self)
+    end
+
+    ### public section about dot utilities #######################################
+    protected
+
+    #
+    # Converts a hash of attributes (typically automaton, state or edge attributes)
+    # to a <code>[...]</code> dot string. Braces are part of the output.
+    #
+    def attributes2dot(attrs)
+      buffer = ""
+      attrs.keys.sort{|k1,k2| k1.to_s <=> k2.to_s}.each do |key|
+        buffer << " " unless buffer.empty?
+        value = attrs[key].to_s.gsub('"','\"')
+        buffer << "#{key}=\"#{value}\""
+      end
+      buffer
+    end
+
+    public
+
+    #
+    # Generates a dot output from an automaton. The rewriter block takes
+    # two arguments: the first one is a Markable instance (graph, state or
+    # edge), the second one indicates which kind of element is passed (through
+    # :automaton, :state or :edge symbol). The rewriter is expected to return a
+    # hash-like object providing dot attributes for the element.
+    #
+    # When no rewriter is provided, a default one is used by default, providing
+    # the following behavior:
+    # - on :automaton
+    #
+    #   {:rankdir => "LR"}
+    #
+    # - on :state
+    #
+    #   {:shape => "doublecircle/circle" (following accepting?),
+    #    :style => "filled",
+    #    :fillcolor => "green/red/white" (if initial?/error?/else, respectively)}
+    #
+    # - on edge
+    #
+    #   {:label => "#{edge.symbol}"}
+    #
+    def to_dot(&rewriter)
+      unless rewriter
+        to_dot do |elm, kind|
+          case kind
+            when :automaton
+              {:pack => true, :rankdir => "LR", :ranksep => 0, :margin => 0}
+            when :state
+              {:shape => (elm.accepting? ? "doublecircle" : "circle"),
+               :style => "filled",
+               :color => "black",
+               :fillcolor => (elm.initial? ? "green" : (elm.error? ? "red" : "white")),
+               :width => 0.6, :height => 0.6, :fixedsize => true
+              }
+            when :edge
+              {:label => elm.symbol.nil? ? '' : elm.symbol.to_s,
+               :arrowsize => 0.7}
+          end
+        end
+      else
+        buffer = "digraph G {\n"
+        attrs = attributes2dot(rewriter.call(self, :automaton))
+        buffer << "  graph [#{attrs}];\n"
+        self.depth
+        states.sort{|s1,s2| s1[:depth] <=> s2[:depth]}.each do |s|
+          s.remove_mark(:depth)
+          attrs = attributes2dot(rewriter.call(s, :state))
+          buffer << "  #{s.index} [#{attrs}];\n"
+        end
+        edges.each do |e|
+          attrs = attributes2dot(rewriter.call(e, :edge))
+          buffer << "  #{e.source.index} -> #{e.target.index} [#{attrs}];\n"
+        end
+        buffer << "}\n"
+      end
+    end
+
+    ### public section about adl utilities #######################################
+    public
+
+    # Prints this automaton in ADL format
+    def to_adl(buffer = "")
+      Stamina::ADL.print_automaton(self, buffer)
+    end
+
+    ### public section about reordering ##########################################
+    public
+
+    # Uses a comparator block to reorder the state list.
+    def order_states(&block)
+      raise ArgumentError, "A comparator block must be given" unless block_given?
+      raise ArgumentError, "A comparator block of arity 2 must be given" unless block.arity==2
+      @states.sort!(&block)
+      @states.each_with_index{|s,i| s.send(:index=, i)}
+      self
+    end
+
+    ### protected section about changes ##########################################
+    protected
+
+    #
+    # Fires by write method when an automaton change occurs.
+    #
+    def state_changed(what, infos)
+      @initials = nil
+      @deterministic = nil
+    end
+
+    protected :compute_initial_states
+
+    DUM = Automaton.new{ add_state(:initial => true, :accepting => false) }
+    DEE = Automaton.new{ add_state(:initial => true, :accepting => true)  }
+  end # class Automaton
+
+end # module Stamina
+require_relative 'automaton/walking'
+require_relative 'automaton/complete'
+require_relative 'automaton/complement'
+require_relative 'automaton/strip'
+require_relative 'automaton/equivalence'
+require_relative 'automaton/determinize'
+require_relative 'automaton/minimize'
+require_relative 'automaton/metrics'
+require_relative 'automaton/compose'
+require_relative 'automaton/hide'