#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 "AbstractObjects/Attribute.h"
#include "MemoryManagement/RCObject.h"
#include <iosfwd>
#include <set>
#include <string>
#include <vector>

class Invalidator;
class Parser;
class Statement;
class TokenStream;

// Class Object
// ------------------------------------------------------------------------
/// The base class for all OPAL objects.
//  Any OPAL command object which may be generated by parsing a command or
//  definition.
//  All known Objects are referred to via [b]Pointer<Object>[/b] to
//  make memory management easy.  For this purpose, the class Object is
//  derived from the abstract class RCObject.
//
//  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 RCObject {

public:

    virtual ~Object();

    /// Test if replacement is allowed.
    //  By default redefinition of an existing Object is not allowed.
    virtual bool canReplaceBy(Object *object);

    /// Return a clone.
    //  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;

    /// Copy attributes from another object.
    void copyAttributes(const Object &);

    /// Execute the command.
    //  For definitions check validity, for actions execute the action.
    virtual void execute();

    /// Find an attribute by name.
    //  Find the Object's attribute identified by [b]name[/b]
    //  (version for non-constant object).
    virtual Attribute *findAttribute(const std::string &name);

    /// Find an attribute by name.
    //  Find the Object's attribute identified by [b]name[/b]
    //  (version for constant object).
    virtual const Attribute *findAttribute(const std::string &name) const;

    /// Return the object category as a string.
    //  Is overridden by the (still abstract) sub-classes of Object.
    virtual const std::string getCategory() const = 0;

    /// Trace flag.
    //  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;

    /// Update flag.
    //  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;

    /// Macro handler function.
    //  Construct an ``archetype'' object for a MACRO commands.
    //  The default version throws OpalException.
    virtual Object *makeTemplate(const std::string &, TokenStream &, Statement &);

    /// Macro handler function.
    //  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 object.
    //  Parse the statement and fill in the Object's attributes.
    virtual void parse(Statement &);

    /// Parser for single-attribute commands.
    //  This parser allows to use unnamed attributes for command which
    //  have only one attribute.
    virtual void parseShortcut(Statement &);

    /// Print the object.
    //  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.
    //  Print help information for [b]this[/b] on the default output stream (argument not used).
    virtual void printHelp(std::ostream &) const;

    /// Replace references.
    //  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);

    /// Update this object.
    //  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 CLASSIC counterpart.
    virtual void update();

    /// True, if [b]this[/b] is a built-in object.
    bool isBuiltin() const;

    /// Shared flag.
    //  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;

    /// Set/reset shared flag.
    //  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/reset the [b]modified[/b] flag.
    //  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);

    /// True, if the [b]modified[/b] flag is set.
    bool isDirty() const;

    /// Flag/unflag this object, e. g. to control output of objects for
    //  flagged objects only.
    void setFlag(bool);

    /// True, if [b]this[/b] is flagged by setFlag(true).
    bool isFlagged() const;

    /// Return the object's base type object.
    //  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;

    /// Return object name.
    const std::string &getOpalName() const;

    /// Return parent pointer.
    Object *getParent() const;

    /// Test for tree membership.
    //  Return true, if [b]this[/b] has been directly or indirectly derived
    //  from [b]subTree[/b].
    bool isTreeMember(const Object *subTree) const;

    /// Set object name.
    void setOpalName(const std::string &name);

    /// Set parent object.
    //  This method should normally be called only from Directory.
    void setParent(Object *);

    /// Clear the occurrence counter.
    void clear();

    /// Increment and return the occurrence counter.
    int increment();

    /// Return the occurrence counter.
    int occurrenceCount();

    /// Register a reference to this object.
    //  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);

    /// Unegister a reference to this object.
    //  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;

    /// The object attributes (see Attribute.hh).
    std::vector<Attribute> itsAttr;

protected:

    /// Constructor for exemplars.
    //  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);

    /// Constructor for clones.
    //  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);

    /// Built-in flag.
    //  True, if the object is built-in to OPAL-9, i. e. if it is an exemplar
    //  or a predefined definition.
    bool builtin;

    /// Dirty flag.
    //  True when [b]this[/b] is new or modified and should be saved in the
    //  DOOM data base.
    bool modified;

    /// Object flag.
    //  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