statemap.h

Go to the documentation of this file.

//
// The contents of this file are subject to the Mozilla Public
// License Version 1.1 (the "License"); you may not use this file
// except in compliance with the License. You may obtain a copy
// of the License at http://www.mozilla.org/MPL/
//
// Software distributed under the License is distributed on an
// "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
// implied. See the License for the specific language governing
// rights and limitations under the License.
//
// The Original Code is State Machine Compiler (SMC).
//
// The Initial Developer of the Original Code is Charles W. Rapp.
// Portions created by Charles W. Rapp are
// Copyright (C) 2000 - 2007. Charles W. Rapp.
// All Rights Reserved.
//
// Contributor(s):
//
// Namespace
//  statemap
//
// Description
//  This namespace contains the finite state machine context
//  class. The user can derive FSM contexts from this class and
//  interface to them with the methods of this class.
//
// Notes
//  The finite state machine needs to be initialized to the
//  starting state of the FSM.  This must be done manually in
//  the constructor of the derived class.
//
// Author
//  C. W. Rapp
//
// RCS ID
// $Id: statemap.h,v 1.15 2009/11/24 20:42:39 cwrapp Exp $
//
// CHANGE LOG
// (See bottom of file)
//

#ifndef SMCLIB__STATEMAP_H_
#define SMCLIB__STATEMAP_H_

#if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1))
#include <iostream>
#if defined(SMC_NO_EXCEPTIONS)
#include <cassert>
#endif  // SMC_NO_EXCEPTIONS
#include <cstdio>
#elif defined(WIN32)
#include <iostream>
#if defined(SMC_NO_EXCEPTIONS)
#include <cassert>
#endif  // SMC_NO_EXCEPTIONS
#else
#include <iostream.h>
#if defined(SMC_NO_EXCEPTIONS)
#include <assert.h>
#endif  // SMC_NO_EXCEPTIONS
#include <stdio.h>
#endif
#if !defined(SMC_NO_EXCEPTIONS)
#include <stdexcept>
#include <cstring>
#endif

#include <string>

// Limit names to 100 ASCII characters.
// Why 100? Because it is a round number.
#define MAX_NAME_LEN 100

namespace statemap
{
//---------------------------------------------------------------
// Routines.
//

inline char* copyString(const char *s)
{
    char *retval = NULL;

    if (s != NULL)
    {
        retval = new char[MAX_NAME_LEN + 1];
        retval[MAX_NAME_LEN] = '\0';
        (void) std::strncpy(retval, s, MAX_NAME_LEN);
    }

    return (retval);
}

//---------------------------------------------------------------
// Exception Classes.
//

#ifndef SMC_NO_EXCEPTIONS
// Base class for all SMC exceptions.
class SmcException :
    public std::runtime_error
{
    //-----------------------------------------------------------
    // Member methods
    //
    public:
        // Destructor.
        virtual ~SmcException() throw()
        {};

    protected:
        // Constructor.
        SmcException(const std::string& reason)
        : std::runtime_error(reason)
        {};

    private:
        // Default construction not allowed.
        SmcException();

    //-----------------------------------------------------------
    // Member data.
    //
    public:
    protected:
    private:
};

// This class is thrown when a pop is issued on an empty
// state stack.
class PopOnEmptyStateStackException :
    public SmcException
{
    //-----------------------------------------------------------
    // Member methods.
    //
    public:
        // Default constructor.
        PopOnEmptyStateStackException()
        : SmcException("no state to pop from state stack")
        {};

        // Destructor.
        virtual ~PopOnEmptyStateStackException() throw()
        {};

    protected:
    private:
    //-----------------------------------------------------------
    // Member data.
    //
    public:
    protected:
    private:
};

// This class is thrown when a transition is issued
// but there is no current state. This happens when
// a transition is issued from within a transition
// action.
class StateUndefinedException :
    public SmcException
{
    //-----------------------------------------------------------
    // Member methods.
    //
    public:
        // Default constructor.
        StateUndefinedException()
        : SmcException("transition invoked while in transition")
        {};

        // Destructor.
        virtual ~StateUndefinedException() throw()
        {};

    protected:
    private:
    //-----------------------------------------------------------
    // Member data.
    //
    public:
    protected:
    private:
};

// This class is thrown when a transition is issued
// but there is no code to handle it.
class TransitionUndefinedException :
    public SmcException
{
    //-----------------------------------------------------------
    // Member methods.
    //
    public:
        // Default constructor.
        TransitionUndefinedException()
        : SmcException("no such transition in current state"),
          _state(NULL),
          _transition(NULL)
        {};

        // Construct an exception using the specified state
        // and transition.
        TransitionUndefinedException(const char *state,
                                     const char *transition)
        : SmcException("no such transition in current state"),
          _state(copyString(state)),
          _transition(copyString(transition))
        {};

        // Copy constructor.
        TransitionUndefinedException(
            const TransitionUndefinedException& ex)
        : SmcException("no such transition in current state"),
          _state(copyString(ex._state)),
          _transition(copyString(ex._transition))
        {};

        // Destructor.
        virtual ~TransitionUndefinedException() throw()
        {
            if (_state != NULL)
            {
                delete[] _state;
                _state = NULL;
            }

            if (_transition != NULL)
            {
                delete[] _transition;
                _transition = NULL;
            }
        };

        // Assignment operator.
        const TransitionUndefinedException&
            operator=(const TransitionUndefinedException& ex)
        {
            // Don't do self assignment.
            if (this != &ex)
            {
                if (_state != NULL)
                {
                    delete[] _state;
                    _state = NULL;
                }

                if (_transition != NULL)
                {
                    delete[] _transition;
                    _transition = NULL;
                }

                _state = copyString(ex._state);
                _transition = copyString(ex._transition);
            }

            return (*this);
        };

        // Returns the state. May be NULL.
        const char* getState() const
        {
            return(_state);
        };

        // Returns the transition. May be NULL.
        const char* getTransition() const
        {
            return (_transition);
        };

    protected:
    private:
    //-----------------------------------------------------------
    // Member data.
    //
    public:
    protected:
    private:
        char *_state;
        char *_transition;
};

// This class is thrown when a state ID is either less than
// the minimal value or greater than the maximal value.
class IndexOutOfBoundsException :
    public SmcException
{
    //-----------------------------------------------------------
    // Member methods.
    //
    public:
        // Default constructor.
        IndexOutOfBoundsException()
        : SmcException("index out of bounds"),
          _index(0),
          _minIndex(0),
          _maxIndex(0)
        {};

        // Constructs an exception using the specified index,
        // minimum index and maximum index.
        IndexOutOfBoundsException(const int index,
                                  const int minIndex,
                                  const int maxIndex)
        : SmcException("index out of bounds"),
          _index(index),
          _minIndex(minIndex),
          _maxIndex(maxIndex)
        {};

        // Copy constructor.
        IndexOutOfBoundsException(
            const IndexOutOfBoundsException& ex)
        : SmcException("index out of bounds"),
          _index(ex._index),
          _minIndex(ex._minIndex),
          _maxIndex(ex._maxIndex)
        {};

        // Destructor.
        virtual ~IndexOutOfBoundsException() throw()
        {};

        // Assignment operator.
        const IndexOutOfBoundsException&
            operator=(const IndexOutOfBoundsException& ex)
        {
            // Don't do self assignment.
            if (this != &ex)
            {
                _index = ex._index;
                _minIndex = ex._minIndex;
                _maxIndex = ex._maxIndex;
            }

            return (*this);
        };

        // Returns the out-of-bounds index.
        int getIndex() const
        {
            return(_index);
        };

        // Returns the minimum allowed index value.
        int getMinIndex() const
        {
            return (_minIndex);
        };

        // Returns the maximum allowed index value.
        int getMaxIndex() const
        {
            return (_maxIndex);
        };

    protected:
    private:
    //-----------------------------------------------------------
    // Member data.
    //
    public:
    protected:
    private:
        int _index;
        int _minIndex;
        int _maxIndex;
};
#endif  // !SMC_NO_EXCEPTIONS

//
// end of Exception Classes.
//---------------------------------------------------------------

class State
{
//-----------------------------------------------------------
// Member functions.
//
public:
    const char* getName() const
    {
        return (_name);
    };

    int getId() const
    {
        return (_stateId);
    }

protected:
    State(const char *name, int stateId)
    : _name(NULL),
      _stateId(stateId)
    {
        if (name != NULL)
        {
            _name = copyString(name);
        }
        else
        {
            _name = copyString("NAME NOT SET");
        }
    };

    virtual ~State()
    {
        if (_name != NULL)
        {
            delete[] _name;
            _name = NULL;
        }
    };

private:
    // Make the default and copy constructors private to
    // prevent their use.
    State() {}
    State(const State&) {}

//-----------------------------------------------------------
// Member data.
//
public:
protected:
    // This state's printable name.
    char *_name;

    // This state's unique identifier.
    int _stateId;

private:
};

class FSMContext
{
//-----------------------------------------------------------
// Nested classes.
//
public:
protected:
private:
    // Implements the state stack.
    class StateEntry
    {
    //-------------------------------------------------------
    // Member functions.
    //
    public:
        StateEntry(State *state, StateEntry *next)
        : _state(state),
          _next(next)
        {};

        ~StateEntry()
        {
            _state = NULL;
            _next = NULL;
        };

        State* getState()
        {
            return(_state);
        };

        StateEntry* getNext()
        {
            return(_next);
        };

    protected:
    private:
    //-------------------------------------------------------
    // Member data.
    //
    public:
    protected:
    private:
        State *_state;
        StateEntry *_next;

    //-------------------------------------------------------
    // Friends
    //
        friend class FSMContext;
    };  // end of class StateEntry

//-----------------------------------------------------------
// Member functions
//
public:
    // Destructor.
    virtual ~FSMContext()
    {
        StateEntry *state;

        if (_transition != NULL)
        {
            delete[] _transition;
            _transition = NULL;
        }

        // But we did allocate the state stack.
        while (_state_stack != NULL)
        {
            state = _state_stack;
            _state_stack = _state_stack->_next;
            delete state;
        }
    };

    // Comparison and assignment operators
    // Assignment operator
    FSMContext& operator=(const FSMContext& fsm)
    {
        // Don't do the assignment if the left and right
        // hand sides are the same object.
        if (this != &fsm)
        {
            _state = fsm._state;
        }

        return(*this);
    };

    // Starts the finite state machine running by executing
    // the initial state's entry actions.
    virtual void enterStartState() = 0;

    // Exact same object (is it me?)
    int same(const FSMContext& fsm) const
    {
        return(this == &fsm);
    };

    // Returns the debug flag's current setting.
    bool getDebugFlag()
    {
        return(_debug_flag);
    };

    // Sets the debug flag. A true value means debugging
    // is on and false means off.
    void setDebugFlag(bool flag)
    {
        _debug_flag = flag;
        return;
    };

#ifdef SMC_USES_IOSTREAMS
    // Returns the stream to which debug output is written.
    std::ostream& getDebugStream()
    {
        return (*_debug_stream);
    };

    // Sets the debug output stream.
    void setDebugStream(std::ostream& debug_stream)
    {
        _debug_stream = &debug_stream;
        return;
    }
#endif  // SMC_USES_IOSTREAMS

    // Is this state machine already inside a transition?
    // Yes if state is null.
    bool isInTransition() const
    {
        return(_state == NULL ? true : false);
    };

    // Returns the current transition's name.
    // Used only for debugging purposes.
    char* getTransition()
    {
        return (_transition);
    };

    // Saves away the transition name only if debugging
    // is turned on.
    void setTransition(const char *transition)
    {
        if (_transition != NULL)
        {
            delete[] _transition;
            _transition = NULL;
        }

        _transition = copyString(transition);

        return;
    };

    // Clears the current state.
    void clearState()
    {
        _previous_state = _state;
        _state = NULL;
    };

    // Returns the state which a transition left.
    // May be NULL.
    State* getPreviousState()
    {
        return (_previous_state);
    }

    // Sets the current state to the specified state.
    void setState(const State& state)
    {
        _state = const_cast<State *>(&state);

        if (_debug_flag == true)
        {
#ifdef SMC_USES_IOSTREAMS
            *_debug_stream << "ENTER STATE     : "
                           << _state->getName()
                           << std::endl;
#else
            TRACE("ENTER STATE     : %s\n\r",
                  _state->getName());
#endif  // SMC_USES_IOSTREAMS
        }
    };

    // Returns true if the state stack is empty and false
    // otherwise.
    bool isStateStackEmpty() const
    {
        return (_state_stack == NULL);
    }

    // Returns the state stack's depth.
    int getStateStackDepth() const
    {
        StateEntry *state_ptr;
        int retval;

        for (state_ptr = _state_stack, retval = 0;
             state_ptr != NULL;
             state_ptr = state_ptr->getNext(), ++retval)
            ;

        return (retval);
    }

    // Push the current state on top of the state stack
    // and make the specified state the current state.
    void pushState(const State& state)
    {
        StateEntry *new_entry;

        // Do the push only if there is a state to be pushed
        // on the stack.
        if (_state != NULL)
        {
            new_entry = new StateEntry(_state, _state_stack);
            _state_stack = new_entry;
        }

        _state = const_cast<State *>(&state);

        if (_debug_flag == true)
        {
#ifdef SMC_USES_IOSTREAMS
            *_debug_stream << "PUSH TO STATE   : "
                           << _state->getName()
                           << std::endl;
#else
            TRACE("PUSH TO STATE   : %s\n\r",
                  _state->getName());
#endif  // SMC_USES_IOSTREAMS
        }
    };

    // Make the state on top of the state stack the
    // current state.
    void popState()
    {
        StateEntry *entry;

        // Popping when there was no previous push is an error.
#ifdef SMC_NO_EXCEPTIONS
        assert(_state_stack != NULL);
#else
        if (_state_stack == NULL)
        {
            throw PopOnEmptyStateStackException();
        }
#endif  // SMC_NO_EXCEPTIONS

        _state = _state_stack->getState();
        entry = _state_stack;
        _state_stack = _state_stack->getNext();
        delete entry;

        if (_debug_flag == true)
        {
#ifdef SMC_USES_IOSTREAMS
            *_debug_stream << "POP TO STATE    : "
                           << _state->getName()
                           << std::endl;
#else
            TRACE("POP TO STATE    : %s\n\r",
                  _state->getName());
#endif  // SMC_USES_IOSTREAMS
        }
    };

    // Remove all states from the state stack.
    void emptyStateStack()
    {
        StateEntry *state_ptr,
                   *next_ptr;

        for (state_ptr = _state_stack;
             state_ptr != NULL;
             state_ptr = next_ptr)
        {
            next_ptr = state_ptr->getNext();
            delete state_ptr;
        }

        _state_stack = NULL;
    };

protected:
    // Default constructor.
    FSMContext(const State& state)
    : _state(const_cast<State *>(&state)),
      _previous_state(NULL),
      _state_stack(NULL),
      _transition(NULL),
#ifdef SMC_USES_IOSTREAMS
      _debug_flag(false),
      _debug_stream(&std::cerr)
#else
      _debug_flag(false)
#endif  // SMC_USES_IOSTREAMS
    {};

private:
    // I don't believe that it makes sense to copy a
    // context. It may make sense to copy the application
    // class but the new object is *not* in the same
    // state as the old - the new object must start in
    // the FSM's initial state. Therefore, the copy
    // constructor is private in order to prevent it
    // being used.
    FSMContext(const FSMContext&)
    {};

//-----------------------------------------------------------
// Member data
//
public:
protected:
    // The current state of the finite state machine.
    State *_state;

    // Remember which state a transition left.
    State *_previous_state;

    // The stack of pushed states.
    StateEntry *_state_stack;

    // The current transition *name*. Use for debugging
    // purposes.
    char *_transition;

private:
    // When this flag is set to true, this class will print
    // out debug messages.
    bool _debug_flag;

// Include the following only if C++ iostreams are being used.
#ifdef SMC_USES_IOSTREAMS
    // When FSM debugging is on, debug messages will be
    // written to this output stream. This stream is set to
    // standard error by default.
    std::ostream *_debug_stream;
#endif  // SMC_USES_IOSTREAMS
};  // end of class FSMContext
}  // namespace statemap

//
// CHANGE LOG
// $Log: statemap.h,v $
// Revision 1.15  2009/11/24 20:42:39  cwrapp
// v. 6.0.1 update
//
// Revision 1.14  2009/03/01 18:20:40  cwrapp
// Preliminary v. 6.0.0 commit.
//
// Revision 1.13  2008/05/20 18:31:12  cwrapp
// ----------------------------------------------------------------------
//
// Committing release 5.1.0.
//
// Modified Files:
//  Makefile README.txt smc.mk tar_list.txt bin/Smc.jar
//  examples/Ant/EX1/build.xml examples/Ant/EX2/build.xml
//  examples/Ant/EX3/build.xml examples/Ant/EX4/build.xml
//  examples/Ant/EX5/build.xml examples/Ant/EX6/build.xml
//  examples/Ant/EX7/build.xml examples/Ant/EX7/src/Telephone.java
//  examples/Java/EX1/Makefile examples/Java/EX4/Makefile
//  examples/Java/EX5/Makefile examples/Java/EX6/Makefile
//  examples/Java/EX7/Makefile examples/Ruby/EX1/Makefile
//  lib/statemap.jar lib/C++/statemap.h lib/Java/Makefile
//  lib/Php/statemap.php lib/Scala/Makefile
//  lib/Scala/statemap.scala net/sf/smc/CODE_README.txt
//  net/sf/smc/README.txt net/sf/smc/Smc.java
// ----------------------------------------------------------------------
//
// Revision 1.12  2007/12/28 12:34:40  cwrapp
// Version 5.0.1 check-in.
//
// Revision 1.11  2007/08/05 12:58:54  cwrapp
// Version 5.0.1 check-in. See net/sf/smc/CODE_README.txt for more information.
//
// Revision 1.10  2007/01/15 00:23:50  cwrapp
// Release 4.4.0 initial commit.
//
// Revision 1.9  2006/07/11 18:28:22  cwrapp
// Move SmcException::copyString() to a package-wide routine.
//
// Revision 1.8  2006/04/22 12:45:24  cwrapp
// Version 4.3.1
//
// Revision 1.7  2005/06/08 11:09:14  cwrapp
// + Updated Python code generator to place "pass" in methods with empty
//   bodies.
// + Corrected FSM errors in Python example 7.
// + Removed unnecessary includes from C++ examples.
// + Corrected errors in top-level makefile's distribution build.
//
// Revision 1.6  2005/05/28 18:44:13  cwrapp
// Updated C++, Java and Tcl libraries, added CSharp, Python and VB.
//
// Revision 1.2  2005/02/21 19:01:42  charlesr
// Changed State::_id to State::_stateId because of Object-C++
// reserved word conflict.
//
// Revision 1.1  2004/05/31 13:44:41  charlesr
// Added support for non-iostreams output.
//
// Revision 1.0  2003/12/14 20:37:49  charlesr
// Initial revision

#endif  // SMCLIB__STATEMAP_H_