TODO

ToySM TODO list:

## Legend:
x: done
~: partially done
*: need evolution in an external package
?: maybe worth doing, needs more thought put into it

## Stuff missing from UML State Machines
- add support for event deferral
- support for Choice Pseudo States (i.e. Dynamic eval as opposed to static
  eval currently in place for Junctions)
- fork/join pseudostates
- entry/exit pseudostates
- threaded state (UML do-activity)

## Features
- implement StateMachine pause function
? before starting a state machine, check that all states (aside
  from the root state) have a parent. This actually can be 
  broadened to implementing better/stricter checking of constraints
  layed out in the UML2 spec.

## Misc
- Revisit naming of SMState vs Instance to make things simpler to grasp.
  One ideas is to rename SMState something like SMDescriptor...

## DONE / Partially DONE ##
~ graph
~ debug
  1.one state instance
  2.one state class
  3.the entire fsm
  for 1 & 2, a decorator/function to be applied to class/instance much
  like the Trace used in the test classes.
  => for now only a Logger is defined (TBD if this is sufficient)
x python2 issues:
  - sched.run doesn't support the non-blocking variant
    => should be possible to work around the issue by defining
       a custom 'wait' function.
x history states
  => DeepHistory not done yet
x s1>'x'>s2 doesn't work because it translates to s1 > 'x' and 'x'>s2...
  whereas (s1 > 'x') > s2 works and so does s1 > ('x' > s2) !!!!
  => resolved by using r/lshift operators
x replace on_entry by _on_entry and have the latter callback into an
  optional user defined on_enty. Same for on_exit/_on_exit.
x Allow State constructor to receive substates, e.g.
  State('s1', sub=[State('s2'), ...])
  => Builder idea
x Transition metaclass to register subclasses and associated
  compatible ctor arguments
x on_entry and on_exit should /also/ be called for toplevel state in FSM
x 'else' type guard
   => this could be achieved by having State.transitions be a list rather than
      a set, the 'else' clause would then be an unguarded transition that
      comes last in the list.
x get_*_transitions methods could _yield_ their result
  => NO. All transitions in a compound transition need to be followed
     so using a yield doesn't improve anything
* graph should treat Transitions according to their type (INTERNAL, EXTERNAL,
etc)
* graph: edge labels aren't positionned properly when source/target is a
         cluster (this is an issue with Graphviz)
? graph (optional): use a metaclass to have each subclass of DotMixin
         merge local attributes with those from superclasses. This would
         allow inheritance of all attributes that aren't locally overriden
         instead of forcing a complete redefinition of the 'dot' dictionary.
* graph: specific representation for entry/exit states
x rework get_enabled_transitions in State, possible to transfer logic
  for compound transitions to StateMachine
  => logic simplified by recursively resolving entry transitions directly
     when a transition is followed that reaches a state.
~ create an Exception type and use it instead of asserts
  => one assert left
x remove code used when a transition's source/target  is redefined, should
  simply considered an error/exception.
x Add GPL file and GPL headers to .py files.
~ Scapy integration (PacketTransition StateMachineBox)
x use 'public' decorator snippet to manage exported/public symbols
x remove DotMixin => functionality isn't used, replace it with a function
  to generate the attribute string based on the dot attribute of a node.
x break fsm.py up into several files: sm.py transition.py state.py
  => core.py contains transition + state (dificult to avoid circular dependencies
  otherwise)
x join should return a boolean indicating whether or not the tread stopped
x add a sm.settle method to wait until the event queue is empty
x multi-instance FSM:
  x a function is used to determine a key based on Events posted
    to event queue, each unknown key yields a new FSM, and those
    that yield a known key are processed by their specific FSM.
  ? transient hooks on State entry/exit (e.g. Timeouts) need to 
    be tied to one of the SM instances => SMState should
    store this info.
    Note: For now States and StateMachine don't evolve while the SM
          is running everything happens within SMState. This covers
	  all current test cases/features.