


     Object Oriented Programming with States [Version 1.0a]



Since the first version has been  released one year ago (this version
was hardly working) number of significant improvements have been made
to the tools supporting the 'Object Oriented Programming with States'
paradigm.
The version 1.0a is the first version to implement almost all the concepts
of the programmation with states (as well as some 'extra goodies'), making
it the ideal support of quality programming for C++ developers.
More important, the version 1.0a is the first version robust enough to be
'whidely' used (for initiation purposes).
Any comments and remarks concerning the tools, the documentation or the
examples are welcomme.
You can contact me at the following addresses:
- "H.Lecoeuche@uk22p.bull.co.uk"
- "hutch@ifhpserv.insa-lyon.fr"


Table of content:

  1 - Presentation of "Object Oriented Programming with States" paradigm
  2 - The OOPS Toolset
  3 - Content of package & installation
                           ------------
  4 - The two demo examples
  5 - The speed test
  6 - Future of the OOPS Toolset

Copyright notice:

	Copyright (c) 1991-1995 Hugues Lecoeuche

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided
that the above copyright notice, author statement and this permission
notice appear in all copies of this software and related documentation.

 THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
 EXPRESS IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY
 OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
 INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
 RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF
 THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT
 OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


/1/ - Presentation of "Object Oriented Programming with States"
      ---------------------------------------------------------


Programming by states (or with states) makes it possible to directly
exploit, at the application source code level, the information present
in the dynamic models produced during the analisys and design stages.
Dynamic models, expressed in terms of state/transition diagrams are
translated into state declarations inserted in the class interfaces.
The declaration of the states makes use of a syntactical extention of
the underlying object oriented programming language. In the case of the
C++ language, this extention introduces 14 new key words (not all of them
being directly related with the states declarations).
A pre-processor transforms the state declarations into control code that
is inserted into the application initial code (i.e. the code written by
the developper).
The control consists in checking that:
- at the beginning of each method execution the object current state
  effectively allows to execute the method,
- at the end of each method execution, the object current state
  effectively coresponds to the expected one (state transition validation).
The interrest of this approach is that it does not require any extra effort
from the developper in order to introduce controls that automatically ensure
that, at run time, objects behave as expected (i.e. their effective behaviour
is compliant with the behavior described in the state/transition diagrams of
their classes).
The main advantage of the state notion used in this approach is to perfectly
fit into the inheritance hierarchy of the classes (i.e. to support
inheritance between classes). This hability makes it possible to exploit in
sub-classes the behavior described in the ancestor classes.



/2/ - The "Object Oriented Programming with States" supporting Toolset
      ----------------------------------------------------------------

The version 1.0a of the tools supporting the "programming with states"
paradigm only contains the translation tools (i.e. tools that translate
state declarations into control code). Graphical tools able to translate
state/transition diagrams into state declarations are still in development
stage.
Files containing enriched C++ code are distinguished from files containing
native C++ code on a name extension basis. The extensions used by the tools
to differentiate the files may be changed in the file 'CHECKER.CFG'.
By default, the following extension are used:
- ".EHP" for files containing the declaration of classes declaring states,
- ".ECP" for files containing the definition of classes declaring states,

The translation tools (CHECKER.EXE and EPURE.EXE) are called using the
command: "CHECKER.EXE <options> <file to translate>"
To obtain some help on the diferent options available just enter:
	 "CHECKER.EXE" (without any option or file name).

The translation tools of the version 1.0a support:
- state abandon,
- state redefinition,
- abstract states,
- incompatibility declaration between states,
- classes that do not declare states inheriting from classes
  declaring states,
- multiple inheritance between classes declaring states,
- parametrized translation to optimise execution time,
- debug mode translation,
- state entry debugging massages,                                       /new/
- a code generation adapted to the target compiler
  (for example the hability of the compiler to support exceptions), 
- a code generation adapted to the user constraints
  (increasing object size vs numerous compile time warnings),
- parametrized file name extensions for translated and generated files,
- pre/post conditions for methods
  (even though this is not directly related to the state notion pre/post
  conditions are known to improve code reliability),                    /new/
- the hability to 'freeze' methods (contrary of 'virtual'
  (even though this is not directly related to the state notion this
  feature eases the developpment of robust class libraries).            /new/
  


/3/ - Content of the package & installation
      -------------------------------------

The package contains:
- the source files of two complete example of 'state programmation',
- the version 1.0a of the translating tools,
- a presentation document of the OOPS Toolset (practical and theoretical),
- a guided tour and a demonstration program under windows,

Installation:

A) From the 'Net':
 If you have imported the file 'OOPSV10A.ZIP', unzip it in any directory you
 like (for example the 'TEMP' directory of your hard drive) and run the
 'SETUP.EXE' installation procedure from within Windows.
B) From a loppy:
 Run the 'SETUP.EXE' installation procedure from within Windows.

The installation procedure allows to choose the target directory as well
as 'a la carte' installation of the different provided elements.
In case of a complete installation, 7 sub-directories are created under
the main target directory:
- DEMODOC  that contains the source files of a very simple example,
- DEMOLIFT that contains the source files of a quite complicated example,
- DEMOWIN  that contains the source files and the windows demonstration program,
- OOPSTOOL that contains the binary files of the translation tools,
- OOPSTOUR that contains the documentation that comes with the demo disk.
	   (one 'WinWord6' document presenting the concepts and the details
	    of the examples ; one 'PowerPoint4' document ment to be an "OOPS
	    guided tour"),
- OOPSLIB  that contains the OOPS library required to compile the translated
	   source code,
- LIB      that contains libraries used by the compiler,
- INCLUDE  that contains include files used by the compiler,

Remarks:
- the complete installation of the OOPS Toolset requires 2,5 Mo.
- the installation does NOT modify any system file.
- the installation does copy the dumy program named 'OOPSICO.EXE' into
  the 'Windows\System' directory of the computer. This program is only
  intended to store the icons used in the 'OOPS' group. It can be deleted
  at any time without any problem (only the icons will not be accessible
  any more).



/4/ - The examples
      ------------

Two examples are provided with the OOPS Toolset in order to illustrate
the use of the 'Programming with State' paradigm:
- DEMODOC  : Simple example (stored in the DEMODOC directory),
- DEMOLIFT : More complicated example (stored in the DEMOLIFT directory).

For both examples, all the files required to translate/compile the example
are present in the related directory. This file are of 4 different nature:

<1> The source files of the application,
    - the files with extension ".EHP" and ".ECP"
    - may be some other files (depending on the example)
<2> The configuration file used for the translation:
    - 'STATE.CFG'
<3> The project files used by the compiler:
    - 'DEMODOC.PRJ' / 'DEMOLIFT.PRJ'
    - 'DEMODOC.DSK' / 'DEMOLIFT.DSK'
<4> The command files used to automatize some tasks:
    - 'CLEAN.BAT' to delete files generated by the translation process,
    - 'GETTOOLS.BAT' to copy the tools in the directory containing the
      source files to be translated,
    - 'GETLIB.BAT' to copy the "programming by state" compile library in the
      directory containing the source files to be translated,
    - 'TRADUIRE.BAT' to start the translation process.
WARNING:
 In order to compile the examples, you should have a C++ compiler able to generate
 DOS code. You will have to adapt the 'makefile' files provided with each example.
 You may also have to customize the files 'CHECKER.CFG' and 'STATE.CFG' in order
 to make them compliant with the requirements of you C++ compiler.

A) The 'STATE.CFG' file:

  /* *************************************************************** */
  /* configuration file for the controls based on state descriptions */
  /* *************************************************************** */
  /* --------------------------------------------------------------- */
  /* List of the supported operating systems.                        */
  /* --------------------------------------------------------------- */
  #define STATE_DOS     1
  #define STATE_WINDOWS 2
  /* --------------------------------------------------------------- */
  /* Definition of the current operating system.                     */
  /* --------------------------------------------------------------- */
  #define STATE_SYSTEME STATE_DOS       <<== MANDATORY FOR THE PROVIDED EXAMPLES

  /* --------------------------------------------------------------- */
  /* List of the supported family of compilers.                      */
  /* --------------------------------------------------------------- */
  #define STATE_BORLAND   1
  #define STATE_MICROSOFT 2
  /* --------------------------------------------------------------- */
  /* Definition of the current compiler.                             */
  /* --------------------------------------------------------------- */
  #define STATE_COMPILER STATE_XXXX     <<== TO BE ADAPTED TO YOUR NEEDS

  /* --------------------------------------------------------------- */
  /* STATE_DEBUG controls the introduction of 'debug' functions.     */
  /* --------------------------------------------------------------- */
  #define STATE_DEBUG                   <<== may be removed

  /* --------------------------------------------------------------- */
  /* STATE_TRACE controls the introduction of 'traces' in the code.  */
  /* --------------------------------------------------------------- */
  /* #define STATE_TRACE */             <<== only use in case of problems

  /* --------------------------------------------------------------- */
  /* The STATE_LIGHT option should be set to 1 only if the           */
  /* translation option used for ALL the files of the application is */
  /* "-tl" or "-TL".                                                 */
  /* --------------------------------------------------------------- */
  #define STATE_LIGHT 0                 <<== advanced option !!!

  /* --------------------------------------------------------------- */
  /* STATE_USE_EXCEPT controls the use of exceptions in the          */
  /*                  generated code.                                */
  /* --------------------------------------------------------------- */
  #define STATE_USE_EXCEPT 1            <<== 0 or 1 depending on your compiler
                                        <<== ability to support exceptions

  /* --------------------------------------------------------------- */
  /* STATE_OLD_COMPILER for very old compilers.                      */
  /* --------------------------------------------------------------- */
  #define STATE_OLD_COMPILER 0          <<== 0 or 1 depending of the age of
                                        <<== your compiler (try 0 first)

  /* --------------------------------------------------------------- */
  /* The STATE_STATIC_IN_INLINE is an advanced option !!             */
  /* When set to 0 it prevents the introduction of static variables  */
  /* into inline methods. The translation does then increase the     */
  /* size of the objects as the variables are introduced as a        */
  /* private object variables.                                       */
  /* When set to 1 it allows the introduction of static variables    */
  /* into inline methods. The translation does then induce lot of    */
  /* warning messages at compile time.                               */
  /* --------------------------------------------------------------- */
  #define STATE_STATIC_IN_INLINE 0      <<== 0 or 1 (tru 0 first)


B) the 'CHECKER.CFG' file:


  The tools CHECKER.EXE and EPURE.EXE read and generate files whith
  extension name that may be parametrized by the user. The file containing
  the extensions to be used by the tools is named 'CHECKER.CFG'. It is
  located in the 'OOPSTOOL' sub-directory.
  The information provided by the file 'CHECKER.CFG' is used by the tools
  in order to differenciate the input files (files containing enriched
  source code). It is also used by the tools to generate files whose names
  are compliants with the compiler used to compile the generated files.

   MAIN_ROOT_NAME="main"<<== root of the name of files containing free functions.
   STATE_DCL_EXT="ehp"  <<== declaration of classes with states (enriched code)
   STATE_DEF_EXT="ecp"  <<== definition of classes with states (enriched code)
   CPP_DCL_EXT="hpp"    <<== normal declaration of classes (native code)
   CPP_DEF_EXT="cpp"    <<== normal definition of classes (native code)
   NOT_FILE_EXT="not"   <<== extention of files that should NOT be read
   TMP_FILE_EXT="tmp"   <<== extention of temporary files
   COD_FILE_EXT="cod"   <<== extention of constant files
			      DANGER: DO NOT CHANGE THIS LAST EXTENSION!!!
   
/* ------------------------------------------------------------------- */
/* WARNING:                                                            */
/* If the 'CPP_DCL_EXT' and 'CPP_DEF_EXT' have to be changed to comply */ 
/* with your C++ compiler do not forget to:                            */
/* - rename properly the files of the 'OOPS library'                   */
/* - change the "#include" statements in the files of the 'OOPS library*/
/* ------------------------------------------------------------------- */

Remark:
  As the files 'CLEAN.BAT' and 'TRANSLATE.BAT' use the extensions of the
  generated files it is better update these files and the 'CHECKER.CFG'
  file at the same time.


The DEMODOC example
===================

** Presentation **

This example simulates the behavior of a book used in a library.
The user acts through a command menu proposing the 8 folowing options:
- 1 : Register      (used to give a reference to the book)
- 2 : Consulting    (used to consult the book when it is on shelves)
- 3 : Damage        (used to signal that the book is damaged and need
		     to be rebounded)
- 4 : Repared       (used to signalthe the book has been rebounded)
- 5 : Borrow        (used to signal the the book is borrowed by a
		     library member)
- 6 : Renew         (used to renew the borrowing)
- 7 : Restitute     (used to signal a borrowed book has been returned)
- 8 : Quit          (no comments)

The behavior of the book is such that it can not be used when it is to be
rebound. It neither can be consulted when it is borrowed.
The way the programm is translated is such that the 'Document' class (the
base classe of the example class hierarchy is translated in debug mode.
This is the reason why messages like <Method name state is ...> are some
time displayed. The 'damaged' state (defined in the 'RepearableDocument'
class is enriched with the debug option 'toSignal'. This is the reason
why a message is displayed each time the object current state is 'damaged'.
For more accurate information concerning the classes used in this example
please refer to the documentation provided with the 'Demo Disk'.


** The example source files **

The DEMODOC example source file are:
- the files with extension ".EHP" and ".ECP",


** Translation/compilation of the example **

The translation/compilation of the example is completely automated by the
file 'DEMODOC.BAT' you can find in the main installation target directory
(provided you have properly updated the 'makefile' file).
The translation can also be done manually by going through the following
stages:
- As the translation requiers the translating tools to be in the same
  directory than the files to be translated the tools may be copied in
  this directory by running the 'GetTools.BAT' file.
- The example translation only works on the files having ".EHP" and ".ECP"
  as extension. The translation may be started by running the file
  'TRANSLATE.BAT'.
- The compilation of the  example requires the "programming by state"
  library to be present in the same directory than the translated files.
  To copy the library files in the good directory run the 'GetLib.BAT' file.
- The example compilation requires the use of YOUR C++ COMPILER you should
  be able to use without my advices.



The DEMOLIFT example
====================

** Presentation **

This example simulates the behavior of a lift cabin.
At the beginning of its execution, the program let the user choose
some configuration details (number of floors, size of the memory used
to store the pending calls, gestion mode og this memory).
The user acts through a command menu proposing the 6 folowing options:
- 1 : Calling       (used to call the lift)
- 2 : Reparing      (used to repare the lift when it powering system
		     is out of order)
- 3 : signal floor  (used to simulate the action of the captors located
		     at the different floors)
- 4 : signal timer  (used to simlate the end of a timer that pilots the
		     closing of the door)
- 5 : audit         (allows to access to the internal state of the
		     system components)
- 6 : Quit          (no comments)

At creation time, the user can choose the type of behavior the memory storing
the lift call should have. The choice is between:
- a LIFO behavior (which is not the best choice for a lift),
- a FIFO behavior (wich is usually correct).
The way the two 'specialised' type of memories have been developped (by
redefining part of the behavior described in the 'AbstractMemory' class shows
the power of combining states and frozen methods).

WARNING:
 Some 'bugs' have deliberately been left into the program so that the
 efficiency of the object behavior control can be proved. Amongs these bugs are:
 - any attemp to call the lift when its door is open will trigger an execution
   error as this induces a transition to incompatible states (door open and lift
   moving).
 - any sequence of calls that contains two time the same floor (like 1-2-1) will
   triggers an execution error the second time the same floor is served. The
   reason being that the button associated with the floor has already be switched
   off the first time the lift has stopped at the floor.
 For more accurate information concerning the classes used in this example
 please refer to the documentation provided with the 'Demo Disk'.

** The example source files **

The DEMOLIFTT example source file are:
- the files with extension ".EHP" and ".ECP",
- the 'ITEM.H' and 'ITEM.C' files.


** Translation/compilation of the example **

Same process than for the DEMODOC example except that you should look
for 'DEMOLIFT' files and directories instead of 'DEMODOC'.


/6/ - The speed test
      --------------

If you select the proper option while installing, you will find a 'SPEEDTST'
sub-directory under the main installation directory. The SPEEDTST' directory 
contains almost the same files that the 'DEMOLIFT' directory.
The purpose of this directory is to enable the user to effectively assertain
the runtime over-head induced by the use of states and pre/post conditions
in order to monitor at run-time the object behaviors.
The 'MAINFILE.ECP' has been changed so that the program does not any more
allow the user to drive the lift but forces the lift to move repeatedly
between the ground floor and the first floor. The number of iterations is
given by the user.
Three '.BAT' files make it possible to generate three versions of the
program:
- the FULLTST version that implements all the behavior controls,
- the LIGHT version that only checks the preconditions (i.e. 'are the
  requested methods allowed in the object current state'),
- the PURE version that performs NO control.
Each of the '.BAT' file ('FULLTST.BAT', 'LIGHT.BAT' and 'PURE.BAT')
generates an '.EXE' file with the same root name ('FULLTST.EXE', 'LIGHT.EXE'
and 'PURE.EXE').
You must this time update three 'makefiles' ('makefile.pur', 'makefile.lgh'
and 'makefile.ful').

  
  7 - Future of the OOPS Toolset
      --------------------------

Two major changes should occur in the OOPS Toolset:
- The tools of the current version (i.e. the textual translators) are going
  to be redevopped using the 'PCCTS' compiler generator toolset.
  Doing this should allow to improve the reliability of the translaters and
  to use a more 'upto date' version of the C++ grammar (i.e. supporting the
  exceptions and the templates).
- A new set of tools should be added in order to support the graphical
  description of the object expected behavior and then to automatically
  generate the ".EHP" files.
