config.h

Go to the documentation of this file.

/*************************************************************
 **
 ** @file base/config.h
 **
 ** Copyright (C) 2012  Xpace, LLC.  All rights reserved
 **
 ** www.xpace.net
 **
 **************************************************************/


#ifndef XPACE_CONFIG_H
#define XPACE_CONFIG_H

#include <functional>

#ifndef _WIN32
#include <stdint.h>
#endif

#include "base/types.h"
#include "base/exception.h"

namespace Xpace
{
  /// Each high-level Xpace object has a Configuration
  class XPACE_EXPORT Configuration
  {
  public:
    /// create a configuration from a fragment of XML
    /// @param str the XML fragment
    /// @param tag search the Configuration for a sub-configuration with this tag (cf. findTag)
    /// @throw XML_No_Value if tag is not found
    /// @throw XML_Error
    Configuration
      (const String& str = String(),
       const String& tag = String());   

    #if defined XPACE_FILE_H || defined DOCUMENTATION
    /// create a configuration from a configuration File
    /// @param file the configuration File
    /// @param tag search the Configuration for a sub-configuration with this tag (cf. findTag)
    /// @throw File_Cant_Read
    /// @throw XML_Error
    /// @throw XML_No_Value if tag is not found
    Configuration
      (File* file,
       const String& tag = String());   
    #endif

    /// @param tag search the Configuration for a sub-configuration with this tag (cf. findTag)
    Configuration
      (const Configuration&,
       const String& tag = String());
    Configuration& operator=
      (const Configuration&);

    ~Configuration();

    /// @return true if empty
    bool operator!
      ()
      const;

    /// @return the XML representation of the entire Configuration
    String toString
      ()
      const;

    #if defined QDOM_H || defined DOCUMENTATION
    /// Convert a QDomElement to a Configuration
    /// @param elt the QDomElement to be converted
    /// @param doc the QDomDocument the element's XML document (if none, create a document)
    /// @param deep if true, convert children as well
    Configuration
      (const QDomElement& elt,
       const QDomDocument& doc = QDomDocument(),
       bool deep = false);

    /// Convert a Configuration to a QDomElement
    /// @return the QDomElement
    operator const QDomElement&
      ()
      const;

    /// Get the QDomDocument containing this Config 
    /// @return the QDomDocument
    const QDomDocument& getDomDocument
      ()
      const;
    #endif

    /// @return this Configuration's XML tag
    String getTag
      ()
      const;

    /// Copy a sub-configuration
    /// @param tag search the Configuration for a sub-configuration with this tag
    /// @param name search for a sub-configuration with this attribute or child
    /// @param value search for a sub-configuration with an attribute/child called name with this value
    /// @param deep iff true, return all descendants
    /// @return a copy of the sub-configuration
    Configuration findTag
      (const String& tag,
       const String& name = String(),
       const String& value = String(),
       bool deep = true)
      const;

    /// get a node's value or an attribute
    /// search for attribute first, then child value

    /// @param tag the tag of the child/attribute whose value we want; separate >1 tags with '|'
    ///   if tag is empty, return this node's value
    /// @return the (String) value
    String getValue
      (const String& tag = String())
      const;

    /// @param tag the tag of the child/attribute whose value we want; separate >1 tags with '|'
    ///   if tag is empty, return this node's value
    /// @param def the default value if not found
    /// @param ok fillin true if found
    /// @return the integer value
    int64 getValueInt
      (const String& tag = String(),
       int64 def = 0,
       bool* ok = 0)
      const;

    /// @param tag the tag of the child/attribute whose value we want; separate >1 tags with '|'
    ///   if tag is empty, return this node's value
    /// @return the (boolean) value
    bool getValueBool
      (const String& tag = String())
      const;

    /// get named values, starting at root
    /// @param name depth-first search for this tag
    /// @return the values associated with this tag, delimited by '.'
    String getValuePath
      (const String& tag)
      const;

    // find children only, not attributes

    /// @param tag the Child's tag
    /// @return true iff the Child exists
    bool hasChild
      (const String& tag)
      const;

    /// @param add a this as a child
    void addChild
      (const Configuration& child);

    /// @param tag the child tag whose values we want
    /// @return the (String) values
    std::vector<String> getChild
      (const String& tag)
      const;

    /// @param tag the child tag whose values we want
    /// @param def the default value if not found
    /// @param ok fillin true if found
    /// @return the integer values
    std::vector<int64> getChildInt
      (const String& tag,
       int64 def,
       bool* ok)
      const;

    /// @param tag the child tags whose values we want
    /// @return the (boolean) values
    std::vector<bool> getChildBool
      (const String& tag)
      const;

    /// set attribute values

    /// set this Configuation's XML tag
    /// @param tag the new tag
    void setTag
      (const String& tag);

    /// @param name set this attribute
    /// @param value to this (String) value
    void setValue
      (const String& name,
       const String& value);

    /// @param name set this attribute
    /// @param value to this (integer) value
    void setValue
      (const String& name,
       int64 value);

    /// @param tag set this attribute
    /// @param value to this (boolean) value
    void setValue
      (const String& name,
       bool value);
    
    /// Callback for traversing Configuration nodes
    /// @oaram depth the node's depth
    /// @param pos the node's position (relative to parent)
    /// @param tag the node's XML tag 
    /// @param config the node's (sub-)Configuration
    /// @return true to continue, false to break
    typedef std::function<bool(uint depth, 
                               uint pos,
                               const String& tag,
                               const String& config)> nodeCallback;

    /// Traverse (pre-order) a Configuration
    /// @param callback the callback function
    /// @param deep iff true, put each node's children in config sent to callback
    /// @param tag if not empty, match this tag before calling back
    /// @param maxDepth how many levels to descend (relative to tag, if any)
    /// @return true iff the callback always returned true
    bool traverse
      (nodeCallback callback,
       bool deep = false,
       const String& tag = String(),
       uint maxDepth = ~0)
      const;  

    #if defined XPACE_FILE_H || defined DOCUMENTATION
    /// serialize the Configuration
    /// @param f to this file
    /// @return true if successfully serialized
    bool write
      (File* f)
      const;
    #endif

  //protected:
    typedef std::function<bool(uint depth,
                               const String& tag,
                               intptr_t elt)> elt_callback;
  protected:
    bool elt_traverse
      (elt_callback, 
       const String& tag);

  private:
    intptr_t config[2];
  };

  /// base class for a configurable object
  /// inherit from this to make your object configurable
  class XPACE_EXPORT Configurable
  {
  public :
    /// @return this object's read-only Configuration
    virtual const Configuration& getConfig
      ()
      const
    = 0;
  };

  /// Configuration errors

  /// XML parse error
  class XML_Error : public Exception
  {
  public :
    /// @param error an English description of the error
    /// @param source the source XML
    /// @line the line number on which the error occurred
    /// @col the column in which the error occurred
    XML_Error
      (const String error,    
       const String source,
       uint line,
       uint col);
  };

  /// Can't find a named value
  class XML_No_Value : public Exception
  {
  public :
    /// @param name the name of the value 
    /// @param source the source XML
    /// @param the exception cauing the failure, if any
    XML_No_Value
      (const String name,
       const String source,
       const Exception reason = Exception());
  };

  /// Found a value, but it's bad (e.g., out of range, meaningless)
  class XML_Bad_Value : public Exception
  {
  public :
    /// @param name the name of the value 
    /// @param value the bad value
    /// @param source the source XML
    XML_Bad_Value
      (const String name,
       const String value,
       const String source);
  };

  // A simple, standard implementation
  class ConfigImpl : public Configurable
  {
  public:
    ConfigImpl
      (const Configuration& c,
       const String& tag = String());

    const Configuration& getConfig
      ()
      const override;

  protected:
    void setConfig
      (const Configuration&);

  private:
    Configuration config;
  };
}

#endif