Initial commit of tutorial Abstract Data Type (ADT) with specs of interface only

1 files changed, 199 insertions, 0 deletions

diff --git a/tutorius/tutorial.py b/tutorius/tutorial.py
new file mode 100644
index 0000000..16a3c48
--- /dev/null
+++ b/tutorius/tutorial.py
@@ -0,0 +1,199 @@
+
+class Tutorial(object):
+    """ This class replaces the previous Tutorial class and 
+        allows manipulation of the abstract representation
+        of a tutorial as a state machine
+    """
+
+    def __init__(self):
+        pass
+
+    def add_state(self, state_name):
+        pass
+
+    def add_action(self, state_name, action):
+        pass
+
+    def add_transition(self, state_name, transition):
+        pass
+
+    def update_action(self, state_name, action_name, properties):
+        pass
+
+    def update_transition(self, state_name, transition_name, properties):
+        pass
+ 
+    def replace_state(self, state_name, state):
+        pass
+
+    def delete_action(self, state_name, action_name):
+        pass
+
+    def delete_transition(self, state_name, transition_name):
+        pass
+
+    def delete_state(self, state_name):
+        pass
+
+    def _validate_action(self, action):
+        """
+        Validate that an action conforms to what we expect,
+        throws an exception otherwise.
+        
+        @param action The action to validate
+        @throw InvalidAction if the action fails to conform to what we expect
+        """
+        pass
+
+    def _validate_transition(self, transition):
+        """
+        Validate that a transition conforms to what we expect,
+        throws an exception otherwise.
+        
+        @param transition The transition to validate
+        @throw InvalidTransition if the transition fails to conform to what we expect
+        """
+        pass
+
+class State(object):
+    """
+    This is a step in a tutorial. The state represents a collection of actions 
+    to undertake when entering the state, and a series of transitions to lead
+    to next states.
+
+    This class is not meant to be used explicitly as no validation is done on
+    inputs, the validation should be done by the containing class.
+    """
+    
+    def __init__(self, name="", action_list=[], transition_list=[]):
+        """
+        Initializes the content of the state, like loading the actions
+        that are required and building the correct tests.
+        
+        @param action_list The list of actions to execute when entering this
+        state
+        @param transition_list A list of tuples of the form 
+        (event, next_state_name), that explains the outgoing links for
+        this state
+        """
+        object.__init__(self)
+        
+        self.name = name
+        
+        self._actions = {} 
+        for action in action_list:
+            self._actions[self._generate_unique_action_name(action)] = action
+        
+        self._transitions = {}
+        for transition in transition_list:
+            self._transitions[self._generate_unique_transition_name(transition)] = transition
+        
+    # Action manipulations
+    def add_action(self, new_action):
+        """
+        Adds an action to the state (only if it wasn't added before)
+        
+        @param new_action The new action to execute when in this state
+        @return a unique name for this action
+        """
+        if new_action not in self._actions:
+            self._actions.append(new_action)
+            return True
+        return False
+
+    def delete_action(self, action_name):
+        """
+        Delete the action with the name action_name returned when the 
+        action was added or when they are listed
+ 
+        @param action_name The name of the action to delete
+        @return True if the action existed of False if no action had this name
+        """
+        pass
+
+    def update_action(self, action_name, action):
+        """ 
+        Update the action with the name action_name with the properties from
+        action
+
+        @param action_name The name of the action to update
+        @param action The action whose properties will be copied over
+        @return True if action_name existed and the properties were valid, False otherwise
+        """
+        pass
+        
+    def get_action_dict(self):
+        """
+        @return A dictionary of actions that the state will execute
+        """
+        return self._actions
+        
+    def delete_actions(self):
+        """
+        Removes all the action associated with this state. A cleared state will
+        not do anything when entered or exited.
+        """
+        self._actions = {}
+
+    # Transition manipulations    
+    def add_transition(self, transition):
+        """
+        Adds a transition from this state to another state.
+        
+        The same transition may not be added twice.
+        
+        @param transition The new transition.
+        @return A unique name for the transition could be added, False otherwise
+        """
+        return False
+
+    def update_transition(self, transition_name, transition):
+        """
+        Update the transition with the name transition_name with the properties from
+        transition
+        
+        @param transition_name The name of the transition to update
+        @param transition The transition whose properties will be copied over
+        @return True if transition_name existed and the properties were valid, False otherwise
+        """
+        pass
+
+    def delete_transition(self, transition_name):
+        """
+        Delete the transition with the name transition_name
+        
+        @param transition_name The name of the transition to delete
+        @return True if transition_name existed, False otherwise
+        """
+        pass
+    
+    def get_transition_dict(self):
+        """
+        @return The dictionary of transitions associated with this state.
+        """
+        return self._transitions 
+    
+    def delete_transitions(self):
+        """
+        Delete all the transitions associated with this state.
+        """
+        self._transitions = {}
+
+    def _generate_unique_action_name(self, action):
+        """
+        Returns a unique name for the action in this state
+        
+        @param action The action to generate a name for
+        @return A name garanteed to be unique within this state
+        """ 
+        return None
+
+    def _generate_unique_transition_name(self, transition):
+        """
+        Returns a unique name for the transition in this state
+
+        @param transition The transition to generate a name for
+        @return A name garanteed to be unique within this state
+        """
+        return None
+