HowTo create a new predicate
============================

$Id: CreatePredicate.txt,v 1.4 2005/09/05 16:16:29 petan Exp $
Created 2000-09-16 by Fredrik Heintz
Last updated 2002-09-13 by Fredrik Heintz


The purpose of this HowTo is to describe how to
create a new predicate and add it to the RoboSoc distribution.
I will use the SawBall predicate as an example. All paths
are relative to the RoboSoc directory.


Hint: Copy this file and then search and replace SawBall with
      the name of the predicate you want to create. Then you can copy
      the commands from this file without very many changes.


-1. Make sure that the template directory is updated.

   &> cvs update -d Framework/template/


0. Go to the RoboSoc directory.


1. Copy the files PredicateStub.h PredicateStub.icc PredicateStub.cc from
   Framework/template to your preferred directory (myDir).

   %> cp Framework/template/PredicateStub.* myDir


2. Change the names of the files to the name of the predicate.

   %> cd myDir
   %> mv PredicateStub.h SawBall.h
   %> mv PredicateStub.icc SawBall.icc
   %> mv PredicateStub.cc SawBall.cc


3. Open the files and change the names inside.

   %> emacs SawBall.h SawBall.icc SawBall.cc &
      C-x b SawBall.cc		(change buffers to SawBall.cc)
      M-<			(goto the top of the file)
      M-% predicatestub SawBall	(search and replace)
      !				(replace all instances)
      C-x b SawBall.icc	(change buffers to SawBall.icc)
      replace the names as above
      C-x b SawBall.h		(change buffers to SawBall.h)
      replace the names as above


4. If the predicate should use arguments then it should inherit
   from PredicateWithArgument or one of its subclasses.

      C-x b SawBall.h		(change buffers to SawBall.h)
      C-s Predicate		(search for Predicate)
      change it to PredicateWithArgument (or another class)
      C-x b SawBall.cc		(change buffers to SawBall.cc)
      C-s Predicate		(search for Predicate)
      change it to PredicateWithArgument (or the other class)


5. Change the description of the files and the predicate.

      C-x b SawBall.h		(change buffers to SawBall.h)
      C-s Created by		(search Created by)
      change the name and date
      C-s $Log			(search for $Log)
      remove everything between $Log ...$ and */
      C-s @class	        (search for @class)
      change the description of the predicate,
      its preconditions and postconditions.
      C-x C-s			(save the changes)
      C-x b SawBall.icc		(change buffers to SawBall.icc)
      change name, date and remove old log information as above
      C-x b SawBall.cc		(change buffers to SawBall.cc)
      change name, date and remove old log information as above


6. Add the predicate dependecies to the implementation file.

      C-x b SawBall.cc		(change buffers to SawBall.cc)
      C-s #include		(search for #include)
      add #include "PredicateName.h" to make a dependency
      C-x C-s			(save the changes)


7. If you don't use an inline methods then the .icc file should be empty.
   If it is, delete it. Also remove the section as instructed at the
   end of the .h and .cc files.

   %> rm SawBall.icc
      C-x b SawBall.cc		(change buffers to SawBall.cc)
      C-s // Remove		(search for // Remove)
      remove the section
      C-x C-s			(save the changes)
      C-x b SawBall.h		(change buffers to SawBall.h)
      remove as above


8. Add the files to Makefile.am

     C-x C-f Makefile.am       (open myDir/Makefile.am)
     add SawBall.h and SawBall.icc to PREDICATE_HEADER
       only SawBall.h if no inline methods are used
     add SawBall.cc to PREDICATE_SOURCE
     If add the files on a new line don't forget the backslash
     at the end of the previous line!


9. Try to compile the predicate

    %> make	(in the myDir directory)