========
Examples
========

-------------------------
Creating a simple machine
-------------------------

.. testcode::

    from automaton import machines
    m = machines.FiniteMachine()
    m.add_state('up')
    m.add_state('down')
    m.add_transition('down', 'up', 'jump')
    m.add_transition('up', 'down', 'fall')
    m.default_start_state = 'down'
    print(m.pformat())

**Expected output:**

.. testoutput::

    +---------+-------+------+----------+---------+
    |  Start  | Event | End  | On Enter | On Exit |
    +---------+-------+------+----------+---------+
    | down[^] |  jump |  up  |    .     |    .    |
    |    up   |  fall | down |    .     |    .    |
    +---------+-------+------+----------+---------+

------------------------------
Transitioning a simple machine
------------------------------

.. testcode::

    m.initialize()
    m.process_event('jump')
    print(m.pformat())
    print(m.current_state)
    print(m.terminated)
    m.process_event('fall')
    print(m.pformat())
    print(m.current_state)
    print(m.terminated)

**Expected output:**

.. testoutput::

    +---------+-------+------+----------+---------+
    |  Start  | Event | End  | On Enter | On Exit |
    +---------+-------+------+----------+---------+
    | down[^] |  jump |  up  |    .     |    .    |
    |   @up   |  fall | down |    .     |    .    |
    +---------+-------+------+----------+---------+
    up
    False
    +----------+-------+------+----------+---------+
    |  Start   | Event | End  | On Enter | On Exit |
    +----------+-------+------+----------+---------+
    | @down[^] |  jump |  up  |    .     |    .    |
    |    up    |  fall | down |    .     |    .    |
    +----------+-------+------+----------+---------+
    down
    False


-------------------------------------
Running a complex dog-barking machine
-------------------------------------

.. testcode::

    from automaton import machines
    from automaton import runners


    # These reaction functions will get triggered when the registered state
    # and event occur, it is expected to provide a new event that reacts to the
    # new stable state (so that the state-machine can transition to a new
    # stable state, and repeat, until the machine ends up in a terminal
    # state, whereby it will stop...)

    def react_to_squirrel(old_state, new_state, event_that_triggered):
        return "gets petted"


    def react_to_wagging(old_state, new_state, event_that_triggered):
        return "gets petted"


    m = machines.FiniteMachine()

    m.add_state("sits")
    m.add_state("lies down", terminal=True)
    m.add_state("barks")
    m.add_state("wags tail")

    m.default_start_state = 'sits'

    m.add_transition("sits", "barks", "squirrel!")
    m.add_transition("barks", "wags tail", "gets petted")
    m.add_transition("wags tail", "lies down", "gets petted")

    m.add_reaction("barks", "squirrel!", react_to_squirrel)
    m.add_reaction('wags tail', "gets petted", react_to_wagging)

    print(m.pformat())
    r = runners.FiniteRunner(m)
    for (old_state, new_state) in r.run_iter("squirrel!"):
        print("Leaving '%s'" % old_state)
        print("Entered '%s'" % new_state)

**Expected output:**

.. testoutput::

    +--------------+-------------+-----------+----------+---------+
    |    Start     |    Event    |    End    | On Enter | On Exit |
    +--------------+-------------+-----------+----------+---------+
    |    barks     | gets petted | wags tail |    .     |    .    |
    | lies down[$] |      .      |     .     |    .     |    .    |
    |   sits[^]    |  squirrel!  |   barks   |    .     |    .    |
    |  wags tail   | gets petted | lies down |    .     |    .    |
    +--------------+-------------+-----------+----------+---------+
    Leaving 'sits'
    Entered 'barks'
    Leaving 'barks'
    Entered 'wags tail'
    Leaving 'wags tail'
    Entered 'lies down'

------------------------------------
Creating a complex CD-player machine
------------------------------------

.. testcode::

    from automaton import machines


    def print_on_enter(new_state, triggered_event):
       print("Entered '%s' due to '%s'" % (new_state, triggered_event))


    def print_on_exit(old_state, triggered_event):
       print("Exiting '%s' due to '%s'" % (old_state, triggered_event))


    m = machines.FiniteMachine()

    m.add_state('stopped', on_enter=print_on_enter, on_exit=print_on_exit)
    m.add_state('opened',  on_enter=print_on_enter, on_exit=print_on_exit)
    m.add_state('closed',  on_enter=print_on_enter, on_exit=print_on_exit)
    m.add_state('playing',  on_enter=print_on_enter, on_exit=print_on_exit)
    m.add_state('paused',  on_enter=print_on_enter, on_exit=print_on_exit)

    m.add_transition('stopped', 'playing', 'play')
    m.add_transition('stopped', 'opened', 'open_close')
    m.add_transition('stopped', 'stopped', 'stop')

    m.add_transition('opened', 'closed', 'open_close')

    m.add_transition('closed', 'opened', 'open_close')
    m.add_transition('closed', 'stopped', 'cd_detected')

    m.add_transition('playing', 'stopped', 'stop')
    m.add_transition('playing', 'paused', 'pause')
    m.add_transition('playing', 'opened', 'open_close')

    m.add_transition('paused', 'playing', 'play')
    m.add_transition('paused', 'stopped', 'stop')
    m.add_transition('paused', 'opened', 'open_close')

    m.default_start_state = 'closed'

    m.initialize()
    print(m.pformat())

    for event in ['cd_detected', 'play', 'pause', 'play', 'stop',
                  'open_close', 'open_close']:
        m.process_event(event)
        print(m.pformat())
        print("=============")
        print("Current state => %s" % m.current_state)
        print("=============")



**Expected output:**

.. testoutput::

    +------------+-------------+---------+----------------+---------------+
    |   Start    |    Event    |   End   |    On Enter    |    On Exit    |
    +------------+-------------+---------+----------------+---------------+
    | @closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | @closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened   |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused   |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused   |     play    | playing | print_on_enter | print_on_exit |
    |   paused   |     stop    | stopped | print_on_enter | print_on_exit |
    |  playing   |  open_close |  opened | print_on_enter | print_on_exit |
    |  playing   |    pause    |  paused | print_on_enter | print_on_exit |
    |  playing   |     stop    | stopped | print_on_enter | print_on_exit |
    |  stopped   |  open_close |  opened | print_on_enter | print_on_exit |
    |  stopped   |     play    | playing | print_on_enter | print_on_exit |
    |  stopped   |     stop    | stopped | print_on_enter | print_on_exit |
    +------------+-------------+---------+----------------+---------------+
    Exiting 'closed' due to 'cd_detected'
    Entered 'stopped' due to 'cd_detected'
    +-----------+-------------+---------+----------------+---------------+
    |   Start   |    Event    |   End   |    On Enter    |    On Exit    |
    +-----------+-------------+---------+----------------+---------------+
    | closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened  |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused  |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused  |     play    | playing | print_on_enter | print_on_exit |
    |   paused  |     stop    | stopped | print_on_enter | print_on_exit |
    |  playing  |  open_close |  opened | print_on_enter | print_on_exit |
    |  playing  |    pause    |  paused | print_on_enter | print_on_exit |
    |  playing  |     stop    | stopped | print_on_enter | print_on_exit |
    |  @stopped |  open_close |  opened | print_on_enter | print_on_exit |
    |  @stopped |     play    | playing | print_on_enter | print_on_exit |
    |  @stopped |     stop    | stopped | print_on_enter | print_on_exit |
    +-----------+-------------+---------+----------------+---------------+
    =============
    Current state => stopped
    =============
    Exiting 'stopped' due to 'play'
    Entered 'playing' due to 'play'
    +-----------+-------------+---------+----------------+---------------+
    |   Start   |    Event    |   End   |    On Enter    |    On Exit    |
    +-----------+-------------+---------+----------------+---------------+
    | closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened  |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused  |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused  |     play    | playing | print_on_enter | print_on_exit |
    |   paused  |     stop    | stopped | print_on_enter | print_on_exit |
    |  @playing |  open_close |  opened | print_on_enter | print_on_exit |
    |  @playing |    pause    |  paused | print_on_enter | print_on_exit |
    |  @playing |     stop    | stopped | print_on_enter | print_on_exit |
    |  stopped  |  open_close |  opened | print_on_enter | print_on_exit |
    |  stopped  |     play    | playing | print_on_enter | print_on_exit |
    |  stopped  |     stop    | stopped | print_on_enter | print_on_exit |
    +-----------+-------------+---------+----------------+---------------+
    =============
    Current state => playing
    =============
    Exiting 'playing' due to 'pause'
    Entered 'paused' due to 'pause'
    +-----------+-------------+---------+----------------+---------------+
    |   Start   |    Event    |   End   |    On Enter    |    On Exit    |
    +-----------+-------------+---------+----------------+---------------+
    | closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened  |  open_close |  closed | print_on_enter | print_on_exit |
    |  @paused  |  open_close |  opened | print_on_enter | print_on_exit |
    |  @paused  |     play    | playing | print_on_enter | print_on_exit |
    |  @paused  |     stop    | stopped | print_on_enter | print_on_exit |
    |  playing  |  open_close |  opened | print_on_enter | print_on_exit |
    |  playing  |    pause    |  paused | print_on_enter | print_on_exit |
    |  playing  |     stop    | stopped | print_on_enter | print_on_exit |
    |  stopped  |  open_close |  opened | print_on_enter | print_on_exit |
    |  stopped  |     play    | playing | print_on_enter | print_on_exit |
    |  stopped  |     stop    | stopped | print_on_enter | print_on_exit |
    +-----------+-------------+---------+----------------+---------------+
    =============
    Current state => paused
    =============
    Exiting 'paused' due to 'play'
    Entered 'playing' due to 'play'
    +-----------+-------------+---------+----------------+---------------+
    |   Start   |    Event    |   End   |    On Enter    |    On Exit    |
    +-----------+-------------+---------+----------------+---------------+
    | closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened  |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused  |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused  |     play    | playing | print_on_enter | print_on_exit |
    |   paused  |     stop    | stopped | print_on_enter | print_on_exit |
    |  @playing |  open_close |  opened | print_on_enter | print_on_exit |
    |  @playing |    pause    |  paused | print_on_enter | print_on_exit |
    |  @playing |     stop    | stopped | print_on_enter | print_on_exit |
    |  stopped  |  open_close |  opened | print_on_enter | print_on_exit |
    |  stopped  |     play    | playing | print_on_enter | print_on_exit |
    |  stopped  |     stop    | stopped | print_on_enter | print_on_exit |
    +-----------+-------------+---------+----------------+---------------+
    =============
    Current state => playing
    =============
    Exiting 'playing' due to 'stop'
    Entered 'stopped' due to 'stop'
    +-----------+-------------+---------+----------------+---------------+
    |   Start   |    Event    |   End   |    On Enter    |    On Exit    |
    +-----------+-------------+---------+----------------+---------------+
    | closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened  |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused  |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused  |     play    | playing | print_on_enter | print_on_exit |
    |   paused  |     stop    | stopped | print_on_enter | print_on_exit |
    |  playing  |  open_close |  opened | print_on_enter | print_on_exit |
    |  playing  |    pause    |  paused | print_on_enter | print_on_exit |
    |  playing  |     stop    | stopped | print_on_enter | print_on_exit |
    |  @stopped |  open_close |  opened | print_on_enter | print_on_exit |
    |  @stopped |     play    | playing | print_on_enter | print_on_exit |
    |  @stopped |     stop    | stopped | print_on_enter | print_on_exit |
    +-----------+-------------+---------+----------------+---------------+
    =============
    Current state => stopped
    =============
    Exiting 'stopped' due to 'open_close'
    Entered 'opened' due to 'open_close'
    +-----------+-------------+---------+----------------+---------------+
    |   Start   |    Event    |   End   |    On Enter    |    On Exit    |
    +-----------+-------------+---------+----------------+---------------+
    | closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |  @opened  |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused  |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused  |     play    | playing | print_on_enter | print_on_exit |
    |   paused  |     stop    | stopped | print_on_enter | print_on_exit |
    |  playing  |  open_close |  opened | print_on_enter | print_on_exit |
    |  playing  |    pause    |  paused | print_on_enter | print_on_exit |
    |  playing  |     stop    | stopped | print_on_enter | print_on_exit |
    |  stopped  |  open_close |  opened | print_on_enter | print_on_exit |
    |  stopped  |     play    | playing | print_on_enter | print_on_exit |
    |  stopped  |     stop    | stopped | print_on_enter | print_on_exit |
    +-----------+-------------+---------+----------------+---------------+
    =============
    Current state => opened
    =============
    Exiting 'opened' due to 'open_close'
    Entered 'closed' due to 'open_close'
    +------------+-------------+---------+----------------+---------------+
    |   Start    |    Event    |   End   |    On Enter    |    On Exit    |
    +------------+-------------+---------+----------------+---------------+
    | @closed[^] | cd_detected | stopped | print_on_enter | print_on_exit |
    | @closed[^] |  open_close |  opened | print_on_enter | print_on_exit |
    |   opened   |  open_close |  closed | print_on_enter | print_on_exit |
    |   paused   |  open_close |  opened | print_on_enter | print_on_exit |
    |   paused   |     play    | playing | print_on_enter | print_on_exit |
    |   paused   |     stop    | stopped | print_on_enter | print_on_exit |
    |  playing   |  open_close |  opened | print_on_enter | print_on_exit |
    |  playing   |    pause    |  paused | print_on_enter | print_on_exit |
    |  playing   |     stop    | stopped | print_on_enter | print_on_exit |
    |  stopped   |  open_close |  opened | print_on_enter | print_on_exit |
    |  stopped   |     play    | playing | print_on_enter | print_on_exit |
    |  stopped   |     stop    | stopped | print_on_enter | print_on_exit |
    +------------+-------------+---------+----------------+---------------+
    =============
    Current state => closed
    =============