Object.h

Go to the documentation of this file.

#ifndef OPAL_Object_HH
#define OPAL_Object_HH
 
// ------------------------------------------------------------------------
// $RCSfile: Object.h,v $
// ------------------------------------------------------------------------
// $Revision: 1.2 $
// ------------------------------------------------------------------------
// Copyright: see Copyright.readme
// ------------------------------------------------------------------------
//
// Class: Object
//
// ------------------------------------------------------------------------
//
// $Date: 2000/03/29 10:40:37 $
// $Author: opal $
//
// ------------------------------------------------------------------------
 
#include <iosfwd>
#include <set>
#include <string>
#include <vector>
#include "AbstractObjects/Attribute.h"
 
class Invalidator;
class Parser;
class Statement;
class TokenStream;
 
// Class Object
// ------------------------------------------------------------------------
//  Any OPAL command object which may be generated by parsing a command or
//  definition.
//  All known Objects use standard C++ memory management.
//
//  Objects are linked by name to the OPAL directory, which resides in
//  the global object [b]OpalData[/b].  Each Object has a pointer pointing
//  to its parent object.  This may be an exemplar object, or a previously
//  generated command or definition object.  This mechanism allows to find
//  easily whether an Object belongs to a given class (see isTreeMember()).
 
class Object {
public:
    virtual ~Object();
 
    //  By default redefinition of an existing Object is not allowed.
    virtual bool canReplaceBy(Object* object);
 
    //  Call the [b]clone[/b] constructor to generate a copy of [b]this[/b]
    //  with a new name [b]name[/b].
    virtual Object* clone(const std::string& name) = 0;
 
    void copyAttributes(const Object&);
 
    //  For definitions check validity, for actions execute the action.
    virtual void execute();
 
    //  Find the Object's attribute identified by [b]name[/b]
    //  (version for non-constant object).
    virtual Attribute* findAttribute(const std::string& name);
 
    //  Find the Object's attribute identified by [b]name[/b]
    //  (version for constant object).
    virtual const Attribute* findAttribute(const std::string& name) const;
 
    //  Is overridden by the (still abstract) sub-classes of Object.
    virtual const std::string getCategory() const = 0;
 
    //  If true, the object's execute() function should be traced.
    //  For all commands for which OPAL should give tracing output this
    //  method must return true.
    virtual bool shouldTrace() const = 0;
 
    //  If true, the data structure must be updated before calling execute().
    //  For all commands which require the OPAL data structure to be up to date
    //  for their execution this method must return true.
    virtual bool shouldUpdate() const = 0;
 
    //  Construct an ``archetype'' object for a MACRO commands.
    //  The default version throws OpalException.
    virtual Object* makeTemplate(const std::string&, TokenStream&, Statement&);
 
    //  Construct an instance object from an ``archetype'' object.
    //  The default version throws OpalException.
    virtual Object* makeInstance(const std::string& name, Statement&, const Parser*);
 
    //  Parse the statement and fill in the Object's attributes.
    virtual void parse(Statement&);
 
    //  This parser allows to use unnamed attributes for command which
    //  have only one attribute.
    //  If [b]eval[/b] is false, then the attribute is not evaluated immediately
    //  even if the delimiter is ``=''.
    virtual void parseShortcut(Statement&, bool eval = true);
 
    //  Print a OPAL-readable image of [b]this[/b] on the given output stream.
    virtual void print(std::ostream&) const;
 
    virtual void printValue(std::ostream&) const;
 
    //  Print help information for [b]this[/b] on the default output stream (argument not used).
    virtual void printHelp(std::ostream&) const;
 
    //  Called for all defined objects, when an object [b]oldObject[/b] is
    //  replaced by a new definition [b]newObject[/b].
    //  This default version does nothing.
    //  Some derived classes may react to the redefinition by invalidating
    //  themselves or by replacing reference inside their data.
    virtual void replace(Object* oldObject, Object* newObject);
 
    //  Called for all defined objects, before an action command is executed.
    //  This default version does nothing.
    //  Derived classes may use this call to update their internal state.
    //  The beam line elements can update their OPALX counterpart.
    virtual void update();
 
    bool isBuiltin() const;
 
    //  If true, this object cannot be cloned to create new elements.
    //  If it is an element or a line, all references are to the same object.
    virtual bool isShared() const;
 
    //  If true, this object cannot be cloned to create new elements.
    //  If it is an element or a line, all references are to the same object.
    virtual void setShared(bool);
 
    //  Set the flag when an object is created and modified,
    //  reset it when the object is saved in the DOOM data base.
    void setDirty(bool);
 
    bool isDirty() const;
 
    //  flagged objects only.
    void setFlag(bool);
 
    bool isFlagged() const;
 
    //  Return the top-most ancestor of this object, i. e. the built-in
    //  object from which [b]this[/b] is ultimately derived.
    const Object* getBaseObject() const;
 
    const std::string& getOpalName() const;
 
    Object* getParent() const;
 
    //  Return true, if [b]this[/b] has been directly or indirectly derived
    //  from [b]subTree[/b].
    bool isTreeMember(const Object* subTree) const;
 
    void setOpalName(const std::string& name);
 
    //  This method should normally be called only from Directory.
    void setParent(Object*);
 
    void clear();
 
    int increment();
 
    int occurrenceCount();
 
    //  Place [b]a[/b] in the list of references.  Whenever [b]this[/b]
    //  is erased or modified, [b]a[/b] will be notified of the change.
    void registerReference(Invalidator* a);
 
    //  Remove [b]a[/b] from the list of references.  The object [b]a[/b]
    //  will no longer be notified of any change to [b]this[/b].
    void unregisterReference(Invalidator* a);
 
    void registerOwnership(const AttributeHandler::OwnerType& itsClass) const;
 
    std::vector<Attribute> itsAttr;
 
protected:
    //  The exemplar object will have the name [b]name[/b], and the help
    //  text [b]help[/b]; it initially reserves [b]size[/b] attributes.
    Object(int size, const char* name, const char* help);
 
    //  The clone object will have the name [b]name[/b]; it inherits its
    //  attributes (shared) from the object [b]*parent[/b].
    Object(const std::string& name, Object* parent);
 
    //  True, if the object is built-in to OPAL-9, i. e. if it is an exemplar
    //  or a predefined definition.
    bool builtin;
 
    //  True when [b]this[/b] is new or modified and should be saved in the
    //  DOOM data base.
    bool modified;
 
    //  This flag can be freely set and reset during the execution of a command.
    bool flagged;
 
private:
    // Not implemented.
    Object();
    Object(const Object& object);
    void operator=(const Object&);
 
    // Pointer to the parent object.
    Object* itsParent;
 
    // The object name.
    std::string itsName;
 
    // The help text.
    std::string itsHelp;
 
    // The occurrence counter.
    int occurrence;
 
    // The DOOM data base time stamp.
    double timeStamp;
 
    // The set of all references to this object.
    // This allows to invalidate the references when [b]this[/b] is deleted.
    std::set<Invalidator*> references;
 
    // If true, the object is shared.
    bool sharedFlag;
};
 
// Implementation.
// ------------------------------------------------------------------------
extern std::ostream& operator<<(std::ostream& os, const Object& object);
 
inline void Object::printValue(std::ostream& os) const { print(os); }
 
#endif  // OPAL_Object_HH