disti_metadata.h

Go to the documentation of this file.

///   \file
///   \brief  The disti metadata.
///
///   \par Copyright Information
///
///   Copyright (c) 2017 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 INCLUDED_DISTI_METADATA_H
#define INCLUDED_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 <stdlib.h>
#    include <typeinfo>
#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;

    // for easier debugging
#define GLS_DEBUG_ATTRIBUTE_NAMES 0
#if GLS_DEBUG_ATTRIBUTE_NAMES
    std::string _name;
#endif

    /** 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 unsigned int _currentFileVersionMajor;
    /** \sa _currentFileVersionMajor */
    static DISTI_EXPORT unsigned int _currentFileVersionMinor;
    /** \sa _currentFileVersionMajor */
    static DISTI_EXPORT unsigned int _currentFileVersionBuild;

    /** \deprecated Do not use. Will be removed in a later version. */
    static DISTI_EXPORT double _currentFileVersionPrimary;
    /** \deprecated Do not use. Will be removed in a later version. */
    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:
    typedef void ( containerClass::*SetMethodType )( setType );
    typedef getType ( containerClass::*GetMethodType )();

    DistiAttributeEnumDefList* _pairList;
    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