disti_metadata.h

Go to the documentation of this file.

/*! \file
  \brief  The disti metadata.

  \par Copyright Information

  Copyright (c) 2015 by The DiSTI Corporation.<br>
  11301 Corporate Blvd; Suite 100<br>
  Orlando, Florida 32817<br>
  USA<br>
  <br>
  All rights reserved.<br>

  This Software contains proprietary trade secrets of DiSTI and may not be
reproduced, in whole or part, in any form, or by any means of electronic,
mechanical, or otherwise, without the written permission of DiSTI.  Said
permission may be derived through the purchase of applicable DiSTI product
licenses which detail the distribution rights of this content and any
Derivative Works based on this or other copyrighted DiSTI Software.

  NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.

  LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
EXCEED FIVE DOLLARS (US$5.00).

  The aforementioned terms and restrictions are governed by the laws of the
State of Florida and the United States of America.

*/

#ifndef DISTI_METADATA_H
#define DISTI_METADATA_H

#if defined(WIN32)
#pragma warning( push )
#pragma warning (disable:4786)
#pragma warning (disable:4251) // This may hide non-exported code.
#endif

#include <iostream>
#include <list>
#include <map>
#include <sstream>
#include <vector>

#include <stdarg.h>

#include "disti_include.h"
#include "dynamic_array.h"
#include "scoped_ptr.h"
#include "tlist.h"
#include "unhide_globals.h"
#include "weak_reference.h"
#include "weak_referenceable_mixin.h"

#if defined(LINUX)
#include <typeinfo>
#include <stdlib.h>
#endif


namespace disti
{
class CallbackMethodCallerBase;
class Mutex;
const int MAX_ATTRIBUTE_NAME_LENGTH = 128;
/** AttributeName class can be treated like a std::string in some instances
  * It creates static storage for any referenced name.
  * This results in only one copy for each name which saves memory
  * Very fast comparison between references to names
  */
class AttributeName
{
private:
    /** Defines the Singleton static storage class */
    class StaticNameStorage
    {
    public:
        /** Returns or creates and returns the instance of the class */
        static DISTI_EXPORT StaticNameStorage* Instance();

        /** Returns the access mutex used for accessing the StaticNameStorage::Instance */
        static DISTI_EXPORT disti::Mutex* AccessMutex();

        /** Allows the index to be looked up from the name */
        std::map<std::string,int> _nameMap;

        /** Allows the name to be looked up directly from the index */
        std::vector<std::string> _nameVector;
    };
    long _stringIndex;

    /** Attempts to find the specified name.
      * If found _stringIndex is set to its index
      * otherwise a new one is created and its index is saved */
    DISTI_EXPORT void Initialize(const char *name);

public:

    /** Constructor 
      * Explicit because construction of an AttributeName is an
      * expensive operation.  If possible you should use a static
      * AttrbuteName object rather than constructing a new
      * one each time it is needed.
      * \param name the desired Name */
    explicit DISTI_EXPORT AttributeName(const std::string &name);

    /** Constructor 
      * See comments on AttributeName(const std::string &name)
      * \param name the desired Name */
    explicit DISTI_EXPORT AttributeName(const char *name);

    /** Constructor
      * \param stringIndex  The index into the string map.
      */
    explicit DISTI_EXPORT AttributeName(long stringIndex);

    /** Returns the index to the string associate with this instance */
    DISTI_EXPORT long StringIndex() const;

    /** Compares this string to the specified AttributeName.
      * This compare is very fast compared to doing string compares, and is
      * one of the primary reasons for creating this class */
    bool DISTI_EXPORT operator == (const AttributeName & other) const;
    
    /** Compares this string for inequality to the specified AttributeName.
      * This compare is very fast compared to doing string compares, and is
      * one of the primary reasons for creating this class */
    bool DISTI_EXPORT operator != (const AttributeName & other) const;

    /** Defines the cast operator to make this look like a std::string for reading */
    DISTI_EXPORT operator std::string() const;

    /** More pretending to be a std::string.
      * Returns a C string pointer to the actual name*/
//REMOVED because not thread safe    const DISTI_EXPORT char* c_str() const;

    /** Defines the stream out operator */
    friend DISTI_EXPORT std::ostream & operator<<(std::ostream & outstr, const AttributeName & name);

    /** Defines various == operators which makes the users syntax easier */
    friend DISTI_EXPORT bool operator==(const AttributeName & lName, const char* rName);
    friend DISTI_EXPORT bool operator==(const char* lName, const AttributeName & rName);
    friend DISTI_EXPORT bool operator==(const std::string& lName, const AttributeName & rName);
    friend DISTI_EXPORT bool operator==(const AttributeName & lName, const std::string& rName);
};

class DistiAttributeBase;

/** Class used to call a callback method that takes a DistiAttributeBase */
class AttributeObserver
{
public:
    /** call the callback with the provided display event */
    virtual void Call( DistiAttributeBase& attr ) = 0;

    /** When IsValid is false, then this AttributeObserver can be deleted. */
    virtual bool IsValid() const = 0;

    virtual ~AttributeObserver() {}
};

class DistiAttributeObserverList;

/** \class DistiAttributeBase
  *  This is the base class for all Disti Attributes.
  */
class DistiAttributeBase : public WeakReferenceableMixin
{
private:
    DistiAttributeBase( const DistiAttributeBase& other );
public:
    /** The name of this attribute */
    AttributeName _name;
    /** The callback which is called when the value of this object changes */
    CallbackMethodCallerBase* _callback;

    ScopedPtr< DistiAttributeObserverList > _observerList;

    /** _localStorage is true if this attributes data should be copied.
      * It would typically be set false if the data is stored externally,
      * and there is no need to copy the data through metadata. 
      * It is also used to determine if storage should be deleted.*/
    bool _localStorage;
public:

    /** Constructor
      * \param callback The method to call when the value changes.  A duplicate of the
               CallbackMethodCallerBase is created and stored internally. 
      * \param name The name of the attribute
      * \param localStorage True if this DistiAttribute contains actual storage,
               rather than just a pointer to somebody elses storage*/
    DISTI_EXPORT DistiAttributeBase(CallbackMethodCallerBase* callback, const AttributeName &name, bool localStorage);

    /** This will perform the copy using ReadValue() and WriteValue()
      * It can be overridden by any dervied classes to do a smarter more efficent copy.  */
    virtual DISTI_EXPORT DistiAttributeBase& operator = (const DistiAttributeBase & oldClass);

    virtual DISTI_EXPORT ~DistiAttributeBase();
  
    /** Returns the name of this object */
    DISTI_EXPORT const AttributeName& Name() const;

    /** Returns the name of this object */
    DISTI_EXPORT AttributeName& Name();

    /** Returns true if this object has local storage */
    DISTI_EXPORT bool LocalStorage() const;

    /** Its not a word, but it means able to be copied
      * This should return true if it makes sense for the data to be copied.
      * By default, will only copy if it contains local storage */
    virtual DISTI_EXPORT bool Copyable() const;

    /** Returns true if this object is ready to have its WriteValue() called 
      * This SHOULD be overriden by any derived objects that may not be ready
      * to write at any point.
      * The reason for this is the data is often written "NAME: VALUE".  If
      * Value is not available, we don't want to write "NAME: " first, so before
      * writting "NAME: ", OkToWrite() can be called to see if it will have a valid value */
    virtual DISTI_EXPORT bool OkToWrite() const;

    /** Returns true if the object's value has changed since 
      * calling ResetValueChanged()
      * However, it is not implmented in the base class and will
      * always return true if not overridden */
    virtual DISTI_EXPORT bool ValueChanged();
    
    /** Saves the current value for later comparison by ValueChanged()
      * This does nothing in the base class */
    virtual DISTI_EXPORT void ResetValueChanged();
    
    /** Returns the std::string version of the attribute data.
      * Here in the base class it uses WriteValue()
      * If this particular attribute's underlying type is a string, this returns the unencoded value, suitable for users.
      * If a file encoded value is required, call WriteValue instead.
      */
    virtual DISTI_EXPORT std::string ValueString();

    /** Sets the value from a std::string argument.
      * Here in the base class it uses ReadValue()
      * If this particular attribute's underlying type is a string, this should not be set to an encoded value.
      * If needing to set from an encoded value, call ReadValue instead.
      */
    virtual DISTI_EXPORT void ValueString(const std::string& s);

    /** Allows for faster access to integer types than the more generic 
      * stream operators.  However, it is only faster if it is overridden. */
    virtual DISTI_EXPORT long ValueInt();

    /** Allows for faster access to integer types than the more generic 
      * stream operator.  However, it is only faster if it is overridden. */
    virtual DISTI_EXPORT void ValueInt(long val);

    /** Allows for faster access to floating-point types than the more generic 
      * stream operators.  However, it is only faster if it is overridden. */
    virtual DISTI_EXPORT double ValueFloat();

    /** Allows for faster access to floating-point types than the more generic 
      * stream operator.  However, it is only faster if it is overridden. */
    virtual DISTI_EXPORT void ValueFloat(double val);

    /** Calls callback CallType3 if it has been set */
    virtual DISTI_EXPORT void CallCallback();

    /** Pure virtual because this is specific to the data type to be contained.
      * This should be overridden to write the data to the stream.
      * The value written could be encoded for writing to a file as a single string,
      * or have its own special encoding specific to its underlying type.
      * In the case of attribute strings, this will be the GLS file encoded value.
      * The user is responsible for decoding the value themselves, or using ReadValue
      * which should perform decoding to maintain symmetry. */
    virtual std::ostream & WriteValue(std::ostream &outstr) = 0;
    /** Pure virtual because this is specific to the data type to be contained.
      * This should be overridden to read the data from the stream.
      * The value read could be encoded for being read from a file as a single string,
      * or have its own special encoding specific to its underlying type.
      * In the case of attribute strings, this will be the GLS file encoded value.
      * The user is responsible for encoding the value themselves, or using WriteValue
      * which should perform encoding to maintain symmetry.
      */
    virtual std::istream & ReadValue(std::istream &instr) = 0;

    /** Compares name and value 
      * This can be overriden to improve speed. */
    virtual DISTI_EXPORT bool operator==(const DistiAttributeBase& r);

    /** Allow for generic access to some data types.
      * This will NOT work for types which:
      *   s << val does not work.
      * In general if the WriteValue is overridden, then it probably will not work.
      */
    template<class valType>
    DistiAttributeBase & operator<<( const valType& val )
    {
        std::stringstream s;
        s << val;
        ReadValue(s);
        return *this;
    }
    /** Allows for generic access to some data types.
      * This will NOT work for types which:
      *   s >> val does not work.
      * In general if the ReadValue is overridden, then it probably will not work.
      */
    template<class valType>
    DistiAttributeBase & operator>>( valType& val )
    {
        std::stringstream s;
        WriteValue(s);
        s >> val;
        return *this;
    }

    /** Allows this class to send to a stream.
      * Internally it uses WriteValue() */
    friend DISTI_EXPORT std::ostream & operator<<(std::ostream & outstr, const DistiAttributeBase & attribute);
    /** Allows this class to receive from a stream.
      * Internally it uses ReadValue() */
    friend DISTI_EXPORT std::istream & operator>>(std::istream & instr,  DistiAttributeBase & attribute);
    
    /// Type for unique identifiers
    typedef unsigned int CallbackID;

    /** Register a callback that is called when the value of the attribute changes.  If multiple oservers are registered, they will be notified in the order they registered.
      * DistiAttributeBase takes ownership of the observer and will delete it. 
      * \param observer the observer to notify.  It is automatically unregistered and destroyed when it becomes invalid.
      * \return an id that can be used to unregister the observer
      */
    virtual DISTI_EXPORT CallbackID RegisterObserver( AttributeObserver* observer );

    /** Unregister an observer
      * \param id the id returned when the observer was registered
      */
    virtual DISTI_EXPORT void UnregisterObserver( CallbackID id );

    /** Triggers all observers to have their callbacks called.  Typically called by the class that owns the DistiAttributeBase */
    virtual DISTI_EXPORT void NotifyObservers();
};

/** Template for an AttributeCallbackBase that will call a class method whenever the attribute changes. The class must implement WeakReferenceable. 
  * Don't use this directly, use CreateAttributeMethodCallback instead.
  */
template <class T>
class AttributeMethodCallback : public AttributeObserver
{
public:
    typedef void ( T::*Callback )( DistiAttributeBase& attr );

    AttributeMethodCallback( T* object, Callback method )
        : _method( method )
        , _object( object )
    {
        GLS_VERIFY( NULL != method );
        GLS_VERIFY( NULL != object );
    }

    void Call( DistiAttributeBase& ev )
    {
        if( IsValid() )
        {
            ( _object.Get()->*( _method ) )( ev );
        }
    }

    virtual bool IsValid() const
    {
        return !_object.IsNull();
    }

protected:
    Callback   _method;
    WeakRef<T> _object; 
};

/** Create an AttributeCallbackBase that will call a class method whenever the attribute changes.
    * \param obj the object to call the method on
    * \param method a class method pointer
    */
template <class Class>
AttributeObserver* CreateAttributeMethodCallback(
    Class* const                                            obj,
    const typename AttributeMethodCallback<Class>::Callback method )
{
    return new AttributeMethodCallback<Class>( obj, method );
}

/** Template for an AttributeCallbackBase that will set another object's attribute whenever the attribute changes. The class must implement WeakReferenceable. 
  * Don't use this directly, use CreateAttributeResourceCallback instead.
  */
template <class T>
class AttributeResourceCallback : public AttributeObserver
{
public:
    AttributeResourceCallback( T* object, const AttributeName& attributeName )
        : _attributeName( attributeName )
        , _object( object )
    {
        GLS_VERIFY( NULL != object );
    }

    void Call( DistiAttributeBase& attr )
    {
        if( IsValid() )
        {
            if( DistiAttributeBase* objAttr = _object.Get()->Attributes().Get( _attributeName ) )
            {
                ( *objAttr ) << attr.ValueString();
            }
        }
    }

    virtual bool IsValid() const
    {
        return !_object.IsNull();
    }

protected:
    AttributeName _attributeName;
    WeakRef<T>    _object;
};

/** Create an AttributeCallbackBase that will set another object's attribute whenever the attribute changes.
    * \param obj the object to set the resource on
    * \param attributeName the name of the property
    */
template <class Class>
AttributeObserver* CreateAttributeResourceCallback(
    Class* const obj,
    const char*  attributeName )
{
    return new AttributeResourceCallback<Class>( obj, AttributeName( attributeName ) );
}

/** Interface for notifying when attributes have changed */
class AttributeChangedNotifier
{
public:
    /** Notify the class that the attribute has changed.  Observers of the attribute will have their callbacks called 
      * \param name the name of the attribute
      */
    virtual DISTI_EXPORT void NotifyAttributeChanged( const AttributeName& name ) = 0;

    /** destructor */
    virtual ~AttributeChangedNotifier() {}
};

/** helper method to notify if an attribute has changed through a setter method
  * \param object the object to notify
  * \param property the storage for the data that is going to be set
  * \param newValue the new value to set
  * \param name the attribute name
  */
template< class T >
void SetAndNotifyIfChanged( AttributeChangedNotifier* object, T& property, const T& newValue, const AttributeName& name )
{
    if( newValue != property )
    {
        property = newValue;
        object->NotifyAttributeChanged( name );
    }
}


/** \class DistiAttribute 
  * A templated class for creating attributes.
  */
class DistiAttribDict;
template <class T>
class DistiAttribute : public DistiAttributeBase
{
protected:
    /** Points to the actual storage */
    T *_attribPtr;
    /** Allows for setting of precision for floating point numbers */
    int _precision;
public:
    /** Constructor
      * Keeps a pointer to the specified type
      * \param callback The method to call when the value changes.  A duplicate of the
      *        CallbackMethodCallerBase is created and stored internally. 
      * \param name The name of the attribute
      * \param attribPtr The address of the storage.
      */
    DistiAttribute(CallbackMethodCallerBase* callback, const AttributeName &name, T *attribPtr): 
      DistiAttributeBase(callback, name, false),
      _attribPtr(attribPtr),
      _precision(0)
    {
          // Automatically use some precision for floats
          if ( typeid( T ) == typeid( float ) ||
               typeid( T ) == typeid( double )||
               typeid( T ) == typeid( long double ))
          {
              _precision = 10;
          }
    }

    /** Constructor
      * Actually creates storage of the specified type
      * \param callback The method to call when the value changes.  A duplicate of the
      *        CallbackMethodCallerBase is created and stored internally. 
      * \param name The name of the attribute
      * \param initialValue The initial value of the intenally stored variable.
      */
    DistiAttribute(CallbackMethodCallerBase* callback, const AttributeName &name, const T& initialValue): 
      DistiAttributeBase(callback, name, true /*Because we actually have storage*/),
      _attribPtr(new T(initialValue)),
      _precision(0)
    {
          // Automatically use some precision for floats
          if ( typeid( T ) == typeid( float ) ||
               typeid( T ) == typeid( double )||
               typeid( T ) == typeid( long double ))
          {
              _precision = 10;
          }
    }
    /** Its not a word, but it means able to be copied
      * This should return true if it makes sense for the data to be copied.
      * By default, will return true for this template.
      * It is overridden here to allow for template specialization */
    virtual bool Copyable() const { return true; }

    /** Allows for faster access to integer types than the more generic 
      * GetValueSimple.  However, it is only faster if it is overridden. 
      * It is overridden here to allow for template specialization */
    virtual long ValueInt()
    { 
        return DistiAttributeBase::ValueInt();
    }
    /** Allows for faster access to integer types than the more generic 
      * SetValueSimple.  However, it is only faster if it is overridden.
      * It is overridden here to allow for template specialization */
    virtual void ValueInt(long val) 
    { 
        DistiAttributeBase::ValueInt(val);
    }

    /** Allows for faster access to integer types than the more generic 
      * GetValueSimple.  However, it is only faster if it is overridden. 
      * It is overridden here to allow for template specialization */
    virtual double ValueFloat()
    { 
        return DistiAttributeBase::ValueFloat();
    }
    /** Allows for faster access to integer types than the more generic 
      * SetValueSimple.  However, it is only faster if it is overridden.
      * It is overridden here to allow for template specialization */
    virtual void ValueFloat(double val)
    { 
        DistiAttributeBase::ValueFloat(val);
    }

    /** This will perform the copy using Value() and Value(val) */
    virtual DistiAttributeBase& operator = (const DistiAttributeBase & oldClass)
    {
        DistiAttribute* ptr;

        ptr = dynamic_cast<DistiAttribute*>(const_cast<DistiAttributeBase*>(&oldClass));
        if (ptr)
        {
            Value(ptr->Value());
        }
        else
        {
            return DistiAttributeBase::operator = (oldClass);
        }
        return *this;
    }

    /** Writes the data to the stream */
    virtual std::ostream & WriteValue(std::ostream &outstr) 
    {
        if (_precision > 0)
            outstr.precision(_precision);

        //operator<<(outstr, *_attribPtr);
        outstr << *_attribPtr;
        return outstr;
    };

    /** Reads the data from the stream 
      * The ReadValue call shall consume only what it needs.  It is the responsibility of
      * the calling function to read to the end of line, or to clean up from a bad read.
      * The calling function will also ensure that the data starts as the next byte in the stream. */
    virtual std::istream& ReadValue( std::istream& instr )
    {
        return ReadValueImpl( instr );
    };

    /** Allows for type specific access to the data */
    virtual T Value()
    {
        return *_attribPtr;
    }
    /** Allows for type specific access to the data */
    virtual void Value(const T &val)
    {
        *_attribPtr = val;
        CallCallback();
    }
    /** Performs type specific comparison.
      * This results in faster comparisons than the base class */
    virtual bool operator==(const DistiAttributeBase& rArg)
    {
        DistiAttribute< T >* r = dynamic_cast< DistiAttribute< T >* >( const_cast<DistiAttributeBase*>(&rArg) );
        if (!r)
            return false;

        if (!(_name == r->_name))
            return false;

        return Value() == r->Value();
    }

    /** Destructor 
      * deletes local storage if we created it */
    virtual ~DistiAttribute()
    {
        // Only delete it if we created it.
        if (_localStorage && _attribPtr)
            delete _attribPtr;
        _attribPtr = NULL;
    }

private:
    inline std::istream& ReadValueImpl( std::istream& instr )
    {
        instr >> *_attribPtr;
        CallCallback();

        return instr;
    }
};

/** Optimized ReadValueImpl for floating point types.
  * Visual Studio 2012 (vc110) runtime performs much slower when using
  * std::istream::operator>>( float& val )
  */
template<>
inline std::istream& DistiAttribute< float >::ReadValueImpl( std::istream& instr )
{
    char instrBuf[64];
    instr >> instrBuf;
    *_attribPtr = static_cast< float >( atof( instrBuf ) );
    CallCallback();

    return instr;
}

template<>
inline std::istream& DistiAttribute< double >::ReadValueImpl( std::istream& instr )
{
    char instrBuf[64];
    instr >> instrBuf;
    *_attribPtr = atof( instrBuf );
    CallCallback();

    return instr;
}


/** The Attribute Dictionary is a container for DistiAttributeBase derived objects */
class DistiAttribDict
{
public:
    /** Allows for easy access to the contained class type */
    typedef DistiAttributeBase* Attr_t;

    typedef std::list<Attr_t> List_t;
    typedef std::multimap<long, Attr_t> Map_t;

    typedef List_t::const_iterator const_iterator;
    typedef List_t::iterator iterator;

    /** Constructor */
    DISTI_EXPORT DistiAttribDict();

    /** Destructor */
    virtual DISTI_EXPORT ~DistiAttribDict();

    /** Used as needed for version specific parsing
      * Whenever a version is parsed, the results should be stored here.
      * This does add order dependency. 
      *
      * Note: These are not set or used by the DistiAttribDict class
      * they are here to be set and accessed by the derived Attributes.
      * Since they are shared by all instances of DistiAttribDict, they
      * are only valid while the dictionary is parsing a file.
      */
    static DISTI_EXPORT double _currentFileVersionPrimary;
    static DISTI_EXPORT long   _currentFileVersionSecondary;

    /** Assignment operator
      * Copies the values for all items which have matching names.
      * All others are ignored */
    DISTI_EXPORT DistiAttribDict& operator = (const DistiAttribDict &old_class);

    /** Equality operator
      * Compares length, names and values.
      * order does not matter */
    DISTI_EXPORT bool operator == (const DistiAttribDict &old_class);

    /** Adds the specified Attribute to the list.
      * The object passed in becomes the responsibility 
      * of this class, and should NOT be deleted by the
      * caller.  It will be deleted by this class as needed */
    virtual DISTI_EXPORT void Add(DistiAttributeBase* attr);

    const_iterator Begin() const { return _list.begin(); }
    const_iterator End() const { return _list.end(); }
    iterator Begin() { return _list.begin(); }
    iterator End() { return _list.end(); }

    /** Returns the current number of elements in the dictionary */
    int DISTI_EXPORT Count() const;

    /** Returns the number of elements with the same name in the dictionary */
    int DISTI_EXPORT Count(const AttributeName& name) const;

    /** Removes all elements in the list, deleting the data as it goes */
    void DISTI_EXPORT Clear();

    /** Removes the attribute specified by name from the dictionary and
      * deletes the data. This does actually delete the attribute.
      */
    virtual DISTI_EXPORT void Delete(const AttributeName& name);

    /** Reads a stream, expecting each line to be of the form
      *    NAME: SomeStringValue
      * For each line a new DistiAttribute<std::string> is created, 
      * and the remaining line is placed as it's value.
      * This is intended for special uses and is not considered
      * the 'normal' mode of operation */
    virtual DISTI_EXPORT void ReadStrings(std::istream &instr);

    /** Writes all items in the dictionary to the stream in the form:
      * "NAME: VALUE"
      * If changedDataOnly is true, only items which return ValueChanged() == true
      * will be written.
      */
    virtual DISTI_EXPORT void Write(std::ostream &outstr, bool changedDataOnly = false);

    /** Reads multiple attributes from the stream expecting the form:
      * "NAME: VALUE"
      * Returns true if something was found and set. */
    virtual DISTI_EXPORT bool Read(std::istream &instr);

    /** Reads multiple attributes from the stream expecting the form:
      * "NAME: VALUE"
      * missing stream is filled with attributes that were not in the dictionary
      * Returns true if something was found and set. */
    DISTI_EXPORT bool ReadAndCaptureMissing(std::istream &instr, std::stringstream* missingStream);

    /** Returns the std::string value of the attribute specified by name
      * Returns "" if not found 
      * Internally it uses ValueString() from the attribute */
    virtual DISTI_EXPORT std::string ValueString(const AttributeName& name) const;

    /** Sets the attribute of named 'name' to the value of 'val' 
      * If name is not found, there is no indication */
    virtual DISTI_EXPORT void ValueString(const AttributeName& name, const std::string& val);

    /** Gets the ValueInt() of the named attribute */
    DISTI_EXPORT long ValueInt(const AttributeName& name) const;

    /** Sets the ValueInt() of the named attribute */
    DISTI_EXPORT void ValueInt(const AttributeName& name, long val);

#if 0
    /** Allows for generic access to some data types.
      * This will NOT work for types which:
      *   s << val does not work.
      * In general if the attribute's WriteValue is overridden, then it probably will not work.
      * Returns false if not found. */
    template<class valType>
    bool SetValueSimple(const AttributeName& name, const valType& val) 
    {
        Map_t::iterator attr(_map.find(name.StringIndex())); 
        
        if (attr != _map.end())
        {
            attr->second->SetValueSimple(val);
        }

        return attr != _map.end();
    }
    /** Allows for generic access to some data types.
      * This will NOT work for types which:
      *   s >> val does not work.
      * In general if the attribute's ReadValue is overwridden, then it probably will not work.
      * Will both set the argument, and return the value.
      * The argument is required to determine the template type.
      * Returns false if not found. */
    template<class valType>
    bool GetValueSimple(const AttributeName& name, valType& val) 
    {
        Map_t::iterator attr(_map.find(name.StringIndex())); 
        
        if (attr != _map.end())
        {
            attr->second->GetValueSimple(val);
        }

        return attr != _map.end();
    }
#endif
 
    /** Calls WriteValue() for the attribute specified by name */
    virtual DISTI_EXPORT std::ostream & WriteValue(const AttributeName& name, std::ostream &outstr);

    /** Calls ReadValue() for the attribute specified by name */
    virtual DISTI_EXPORT std::istream & ReadValue(const AttributeName& name, std::istream &instr);

    /** Returns the DistiAttributeBase* for the specified name
      * If not found it returns NULL */
    virtual DISTI_EXPORT DistiAttributeBase* Get(const AttributeName& name) const;

    /** Retuns a comparison of val with ValueInt() of the attribute 
      * looked up by name 
      * Returns false if not found */
    virtual DISTI_EXPORT bool IsEqual(const AttributeName& name, const long val) const;

    /** Static, data for formating output */
    static DISTI_EXPORT int currentOutputSpacing; // Should be private

    /** Static, Increments the current spacing */
    static DISTI_EXPORT void SpacingInc();

    /** Static, Decrements the current spacing */
    static DISTI_EXPORT void SpacingDec();

    /** Static, Sets the spacing to zero */
    static DISTI_EXPORT void SpacingZero();

    /** Static, Returns a string containing the current spacing */
    static DISTI_EXPORT std::string SpacingString();

    /** Static method used for parsing a stream
      * Used internally and Exposed here so others can use it.
      */
    static DISTI_EXPORT bool ScanToken(std::istream &instr, std::string &result);

    /** Removes the attribute specified by name
      * This does NOT actually delete the attribute, just removes it from the
      * dictionary.
      */
    virtual DISTI_EXPORT void Remove(const AttributeName& name);

protected:
     
    List_t _list;
    Map_t  _map;

private:
    /** Copy constructor
      * Don't copy anything
      * Almost everything is a pointer, so it wouldn't make sense */
    DistiAttribDict(const DistiAttribDict &old_class);
};


////////////////////////////////////////////////////////////
// Some useful derivations
////////////////////////////////////////////////////////////

/** \class DistiAttributeEnumStringPair
    * A string to enumeration mapping
    */
typedef struct 
{
    char _string[64];
    int _enum;
} DistiAttributeEnumStringPair;


/** A list of enumeration definitions */
class DistiAttributeEnumDefList : public std::list<DistiAttributeEnumStringPair*>
{
public:
    DISTI_EXPORT DistiAttributeEnumDefList(char *stringVal, ...);
    virtual DISTI_EXPORT int EnumToInt(const std::string& string);
    virtual DISTI_EXPORT ~DistiAttributeEnumDefList();
};

/** \class DistiAttributeEnum
  * A Disti Attribute which reads and writes enumerations.
  */
template<class containerClass,class setType,class getType>
class DistiAttributeEnum : public DistiAttributeBase
{
public:

    DistiAttributeEnumDefList *_pairList; 

    typedef void (containerClass::*SetMethodType)(setType);
    typedef getType (containerClass::*GetMethodType)();

    containerClass*       _object;     /* Object that contains the attribute */
    SetMethodType        _setMethod;  /* Set method member pointer */
    GetMethodType        _getMethod;  /* Get method member pointer */

    DistiAttributeEnum(containerClass *object,SetMethodType setMethod, GetMethodType getMethod,const AttributeName &name) :
       DistiAttributeBase(NULL,name,false),
       _object(object),
       _setMethod(setMethod),
       _getMethod(getMethod)
    {
        DistiAssert(setMethod);
        DistiAssert(getMethod);

    }

    virtual ~DistiAttributeEnum()
    {
    }

    virtual long ValueInt() 
    { 
        return (long)(_object->*_getMethod)();
    }

    virtual void ValueInt(long val) 
    { 
        (_object->*_setMethod)((setType)val); 
    };

    virtual DistiAttributeBase& operator = (const DistiAttributeBase & oldClass)
    {
        DistiAttributeEnum<containerClass,getType,setType>* ptr=dynamic_cast<DistiAttributeEnum<containerClass,getType,setType>*>(const_cast<DistiAttributeBase*>(&oldClass));
        if (ptr)
        {
            ValueInt(ptr->ValueInt());
        }
        else
        {
            return DistiAttributeBase::operator = (oldClass);
        }
        return *this;
    }

    virtual std::ostream & WriteValue(std::ostream &outstr) 
    {
        bool foundIt = false;
        getType value = (_object->*_getMethod)();
        DistiAttributeEnumDefList::iterator item =  _pairList->begin();
        while (item != _pairList->end() && *item)
        {
            if ((*item)->_enum == value)
            {
                outstr << (*item)->_string;
                foundIt = true;
                break;
            }
            ++item;
        }
        if (!foundIt)
        {
            //Didn't find it so just write the number
            outstr << value;
        }
        return outstr;
    }

    int EnumToInt(std::string &string)
    {
        bool foundIt = false;
        int returnVal = 0;
        DistiAttributeEnumDefList::iterator item =  _pairList->begin();

        while (item != _pairList->end() && *item)
        {
            if (strcmp((*item)->_string, string.c_str()) == 0)
            {
                foundIt = true;
                returnVal = (*item)->_enum;
                break;
            }
            ++item;
        }
        return returnVal;
    }

    virtual std::istream & ReadValue(std::istream &instr) 
    {
        char value[64];
        instr >> value;

        bool foundIt = false;
        DistiAttributeEnumDefList::iterator item =  _pairList->begin();

        // First look by enumeration
        while (item != _pairList->end() && *item)
        {
            if (strcmp((*item)->_string, value) == 0)
            {             
                (_object->*_setMethod)((setType)(*item)->_enum); 

                foundIt = true;
                break;
            }
            ++item;
        }

        // If not found, assume that the numerical value is specified.
        if (!foundIt)
        {
            (_object->*_setMethod)((setType)atoi(value)); 
        }        
        return instr;
    }
};


} // namespace disti

#if defined(WIN32)
#pragma warning( pop )
#endif

#endif