readerWriter.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2013 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/


#pragma once

#include "readerWriter/readerWriterDefines.h"
#include "stdio.h"
#include <mtl/mtl.h>
#include <vlutil/vlString.h>
#include "readerWriter/readerWriterRegistry.h"
#include "readerWriter/putSelfCallbackInfo.h"
#include "readerWriter/getSelfCallbackInfo.h"
#include <vlutil/vlMachineTypes.h>
#include "readerWriter/symbolString.h"
#include <mtl/environment.h>
#include <vlutil/vlFilename.h>
#include <list>
#include <vlutil/vlSmartPointers.h>
#include <vlutil/vlTime.h>

#include <ostream>

class DtRwVariableBindings;
class DtReaderWriterFactory;
class DtPropertyInterface;

typedef DT_DLL_readerWriter DtBoost::shared_ptr<DtEnvironment> DtEnvironmentSP;

// \brief The base class for all objects that are part of the ReaderWriter system
// in VR-Forces.
// ReaderWriter classes and the ReaderWriter system provide a mechanism for 
// serializing objects to a text file that us human readable and editable, 
// and reading that data back into a C++ structure.
// The data is written to the file in an "mtl" format, which is a list-like
// format, using key-value pairs.
// \par
// ReaderWriter objects can be nested within other ReaderWriter objects to
// create a hierarchy.  Each ReaderWriter object reads and writes its immediate
// children, and relies on those children to read and write their own contents.
// The ordering of the values within a single block of reader writer data is not
// relevant, since it is treated as a key-value pair set.  
// \par
// Each DtReaderWriter subclass that contains ReaderWriter children creates
// those children in its constructor, and gives them both types and names (keys)
// at that time.  When a class is read from file, each key encountered in the file
// is looked up in the reading class, and the stream is passed to that child for
// reading.  Writing work in a similar way in reverse.
// \par
// Not all children items of a DtReaderWriter need to exist in the file that is
// being read.  If a particular key is not present in the file being read, then
// the default value (assigned in the constructor) for that value is used, and
// that member has it valueSpecified() flag set to false.
// \par Aliases
// It is possible to create aliases for a particular key so that multiple keys
// will cause data to be read into the same data member.  This is useful when 
// newer versions of code are reading older files, and some members have changed
// names, but need to be able to read the old files.  See the addAlias() and
// hasAlias() methods.
// \par Variable Bindings
// The ReaderWriter system also supports a concept called variable bindings.
// This allows substitutions to be made as a file is read by a reader writer class.
// The class DtRwVariableBindings holds a set of bindings between string variable names and
// DtReaderWriter instances which will be used in place of those variables when
// encountered in the reading of a file.  The \a $ character is used as a special
// variable designation character for this purpose.  The types of the DtReaderWriter
// objects are explicitly indicated in the DtRwVariableBindings, and must match
// the type of DtReaderWriter object being read when the variable is encountered
// for the substitution to be successful.
// \par
// The DtRwVariableBindings class itself is also a DtReaderWriter subclass, and
// as such can also be placed in the file structures.  Each DtReaderWriter block
// in a file may contain a special "variable-bindings" section at the start, which
// specifies any variables that will be substituted, and what they will be substituted
// with for all of its members, as well as all its child members.
// \par
// As a special case, variables appearing within DtRwString members will be
// substituted if there is a string type variable defined with the specified name.
// \par Examples
//   - \link convertparamdb convertParamDb \endlink
class DT_DLL_readerWriter DtReaderWriter
{
public:

   typedef std::vector<DtSymbolString> aliasContainer;
   typedef std::vector<DtSymbolString>::iterator aliasIter;
   typedef std::vector<DtSymbolString>::const_iterator aliasConstIter;
   typedef std::vector<DtFilename> SearchPaths;

   DtReaderWriter();

   DtReaderWriter(const DtString& name, DtReaderWriterRegistry*
      parentRegistry = NULL, bool readonly = false);
   DtReaderWriter(const DtSymbolString& name, DtReaderWriterRegistry*
      parentRegistry = NULL, bool readonly = false);

   DtReaderWriter(const DtString& name, const DtReaderWriter& orig,
      DtReaderWriterRegistry* parentRegistry = NULL);
   DtReaderWriter(const DtSymbolString& name, const DtReaderWriter& orig,
      DtReaderWriterRegistry* parentRegistry = NULL);

   explicit DtReaderWriter(const DtReaderWriter&,
      DtReaderWriterRegistry* parentRegistry = NULL);

   const DtReaderWriter& operator=(const DtReaderWriter& orig);

   bool operator==(const DtReaderWriter&) const;

   bool operator!=(const DtReaderWriter& rhs) { return !(*this == rhs); };

   virtual ~DtReaderWriter();

   virtual void putSelf(std::string& fp, int indentLevel = 0,
      bool writeUnspecified = false, const DtFilename& path =
      DtFilename::nullFilename());

   virtual void postPutSelf();

   virtual void prePutSelf();

   virtual void getSelf(DtlObjPtr args,
      const DtReaderWriter::SearchPaths& searchPaths = SearchPaths(),
      const DtVariableBindingsList& variableBindings = nullVariableReference());

   virtual void postGetSelf();

   virtual void preGetSelf();

   virtual void writeSelf(std::string& fp, int indentLevel = 0,
      bool writeUnspecified = false,
      const DtFilename& path = DtFilename::nullFilename());


   virtual void putData(std::string& fp, int indentLevel = 0);
   virtual DtlObjPtr getData(DtlObjPtr args, const SearchPaths& searchPaths,
      const DtVariableBindingsList& variableBindings);

   virtual DtSymbolString name() const;

   static void putIndent(std::string& fp, int indentLevel);

   // \return An empty DtVariableBindingList, which can be passed
   // to getSelf() methods if there are no variables to bind.
   static const DtVariableBindingsList& nullVariableReference();


   virtual void setValueSpecified(bool specified, bool recurse = false);
   virtual bool valueSpecified() const;

   virtual void addAlias(const DtSymbolString& alias);
   virtual void addAlias(const DtString& alias);

   virtual bool hasAlias(const DtSymbolString& alias);

   virtual const aliasContainer& aliases() const;

   virtual void setReadonly(bool flag);

   inline bool isReadonly() const
   {
      return myReadOnlyFlag;
   }

   virtual void reset();


   virtual bool isVariableReference() const;
   virtual void setIsVariableReference(bool value);

   virtual void clearAllVariableReferenceFlags();


   virtual int alignment() const;


   virtual DtSymbolString variableName() const;
   virtual void setVariableName(const DtSymbolString variableName);

   virtual const DtReaderWriter* defaultRWValue() const;
   virtual DtReaderWriter* defaultRWValue();

   virtual void setDefaultRWValue(DtReaderWriter*);

   virtual bool checkAndSetDefaultRWValue(DtlObjPtr args, 
      const DtReaderWriter::SearchPaths& searchPaths = SearchPaths(), 
      const DtVariableBindingsList& variableBindings = nullVariableReference());

   virtual DtString toXml() const;

   virtual DtRwVariableBindings* generateVariableBindings() const;

   static DtReaderWriter* createFromXmlFile(const DtFilename&, bool createAsProperty = false);

   static DtReaderWriter* createFromXml(const DtString&, bool createAsProperty = false);

   static DtReaderWriter* createFromEnvironment(DtEnvironmentSP, bool createAsProperty = false);

   virtual bool toXml(const DtFilename&) const;

   virtual bool fromXml(const DtString&);

   virtual bool fromXmlFile(const DtFilename&);
   virtual void putSelf(DtEnvironmentSP, DtEnvValueSP parent) const;

   static DtString getAttribute(DtEnvironmentSP env, const DtString& name, DtEnvValueSP root);

   virtual void putData(DtEnvironmentSP, DtEnvValueSP value) const;

   virtual void putVariableReference(DtEnvironmentSP, DtEnvValueSP value) const;

   virtual void getSelf(const DtEnvironmentSP, const DtEnvValueSP root,
      const SearchPaths& searchPaths = SearchPaths(), 
      const DtVariableBindingsList& bindings = DtVariableBindingsList());

   virtual void getData(const DtEnvironmentSP, const DtEnvValueSP,
      const SearchPaths& searchPaths = SearchPaths(), 
      const DtVariableBindingsList& bindings = DtVariableBindingsList());

   virtual void unrecognizedItem(const DtEnvironmentSP env, const DtEnvValueSP root,
      const SearchPaths& searchPaths, const DtVariableBindingsList& varBindings);

   virtual void getVariableReference(DtEnvironmentSP, DtEnvValueSP value);


   virtual bool variableIsBound() const;
   virtual void unbindVariable();

   static void setPostGetSelfCallback(DtGetSelfCallbackFcn fcn, void* usrData);
   static void setPrePutSelfCallback(DtPutSelfCallbackFcn fcn, void* usrData);

   static void setPutIndent(bool);
   static bool putIndent();


   const DtReaderWriterRegistry& registry() const;
   DtReaderWriterRegistry& registry();

   virtual void setName(const DtString&);

   virtual const char* readerWriterType() const;

   static const char* theXmlType();

   virtual const char* xmlType() const
   {
      return theXmlType();
   }

   virtual DtString prettyPrint() const;

   std::string debugText() const;

   virtual void bindVariables(DtVariableBindingsList variableBindings);

   typedef std::pair<DtSymbolString, DtString> DtVariableNameType;
   virtual std::list<DtVariableNameType> unboundVariables() const;
   
   static const DtFilename& appPath();

   bool invalid() const;

   virtual bool hasChild(const DtReaderWriter* p) const;

   typedef DtReaderWriterFactory* (*DtReaderWriterFactoryCreatorFcn)();

   static void setFactoryCreatorFunction(DtReaderWriterFactoryCreatorFcn fcn);

   static void createReaderWriterFactory();
   static void cleanupFactory();

   // \return A pointer to the static DtReaderWriterFactory.  This factory
   // can create instances of DtReaderWriter subclasses that have been 
   // registered with it.
   static DtReaderWriterFactory* factory();

   virtual bool hasVariableReference() const;

   virtual void bindLocalVariables(const DtVariableBindingsList& variableBindings);
   
   virtual DtPropertyInterface* property();
   virtual const DtPropertyInterface* property() const;

   virtual void recordUpdateTime() const;

   virtual bool wasUpdatedSince(DtTime t) const;

   virtual bool changedSinceLastChecked();
   
   virtual bool peekChangedSinceLastChecked() const;

   static void setOutputStream(DtOutputStream* stream);
   static DtOutputStream& outputStream();

protected:
   virtual void bindToRwAsVariable(const DtReaderWriter* rw);

protected:

   const DtSymbolString myName;
   DtReaderWriterRegistry myRegistry;
   DtReaderWriterRegistry* myParentRegistry;
   bool myValueSpecified;
   bool myReadOnlyFlag;
   bool myIsVariableReference;
   DtSymbolString myVariableName;
   bool myVariableIsBound;

   DtReaderWriter*   myDefaultValue;

   aliasContainer myAliases;

   static DtString theUnspecifiedValue;

   static DtGetSelfCallbackInfo thePostGetSelfCallback;
   static DtPutSelfCallbackInfo thePrePutSelfCallback;
   static const DtVariableBindingsList theEmptyVariableBindingsList;

   static bool theCreatorFcnSet;
   static DtReaderWriterFactory* theFactory;
   static DtReaderWriterFactoryCreatorFcn theFactoryCreatorFcn;
   static bool thePutIndent;

   bool  myInvalid;

   bool myChangedFlag;

   static DtOutputStream* theOutputStream;
};

inline const DtReaderWriterRegistry& DtReaderWriter::registry() const
{
   return myRegistry;
}

inline DtReaderWriterRegistry& DtReaderWriter::registry()
{
   return myRegistry;
}

inline bool DtReaderWriter::invalid() const
{
   return myInvalid;
}

inline std::string& operator<<(std::string& a, const std::string& b) { a += b; return a; }
inline std::string& operator<<(std::string& a, const char* b) { a += b; return a; }
inline std::string& operator<<(std::string& a, char b) { a += b; return a; }
DT_DLL_readerWriter std::string& operator<<(std::string&, int);
DT_DLL_readerWriter std::string& operator<<(std::string&, unsigned int);
DT_DLL_readerWriter std::string& operator<<(std::string&, double);
DT_DLL_readerWriter std::string& operator<<(std::string&, float);