Element.hh

Go to the documentation of this file.

/*
 * Copyright 2015 Open Source Robotics Foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
#ifndef SDF_ELEMENT_HH_
#define SDF_ELEMENT_HH_
 
#include <any>
#include <map>
#include <memory>
#include <optional>
#include <set>
#include <string>
#include <unordered_set>
#include <utility>
#include <vector>
 
#include "sdf/Error.hh"
#include "sdf/Param.hh"
#include "sdf/PrintConfig.hh"
#include "sdf/config.hh"
#include "sdf/system_util.hh"
#include "sdf/Types.hh"
 
#ifdef _WIN32
// Disable warning C4251 which is triggered by
// std::enable_shared_from_this
#pragma warning(push)
#pragma warning(disable: 4251)
#endif

namespace sdf
{
  // Inline bracket to help doxygen filtering.
  inline namespace SDF_VERSION_NAMESPACE {
  //
 
  class ElementPrivate;
  class SDFORMAT_VISIBLE Element;

  typedef std::shared_ptr<Element> ElementPtr;

  typedef std::shared_ptr<const Element> ElementConstPtr;

  typedef std::weak_ptr<Element> ElementWeakPtr;

  typedef std::vector<ElementPtr> ElementPtr_V;


  class SDFORMAT_VISIBLE Element :
    public std::enable_shared_from_this<Element>
  {
    public: Element();

    public: virtual ~Element();

    public: ElementPtr Clone() const;

    public: ElementPtr Clone(sdf::Errors &_errors) const;

    public: void Copy(const ElementPtr _elem);

    public: void Copy(const ElementPtr _elem, sdf::Errors &_errors);

    public: ElementPtr GetParent() const;

    public: void SetParent(const ElementPtr _parent);

    public: void SetName(const std::string &_name);

    public: const std::string &GetName() const;

    public: void SetRequired(const std::string &_req);

    public: const std::string &GetRequired() const;

    public: void SetExplicitlySetInFile(const bool _value);

    public: bool GetExplicitlySetInFile() const;

    public: void SetCopyChildren(bool _value);

    public: bool GetCopyChildren() const;

    public: void SetReferenceSDF(const std::string &_value);

    public: std::string ReferenceSDF() const;

    public: void PrintDescription(const std::string &_prefix) const;

    public: void PrintDescription(sdf::Errors &_errors,
                                  const std::string &_prefix) const;

    public: void PrintValues(std::string _prefix,
                             const PrintConfig &_config = PrintConfig()) const;

    public: void PrintValues(sdf::Errors &_errors,
                             std::string _prefix,
                             const PrintConfig &_config = PrintConfig()) const;

    public: void PrintValues(const std::string &_prefix,
                             bool _includeDefaultElements,
                             bool _includeDefaultAttributes,
                             const PrintConfig &_config = PrintConfig()) const;

    public: void PrintValues(sdf::Errors &_errors,
                             const std::string &_prefix,
                             bool _includeDefaultElements,
                             bool _includeDefaultAttributes,
                             const PrintConfig &_config = PrintConfig()) const;

    public: void PrintDocLeftPane(std::string &_html,
                                  int _spacing, int &_index) const;

    public: void PrintDocRightPane(std::string &_html,
                                  int _spacing, int &_index) const;

    public: std::string ToString(
        const std::string &_prefix,
        const PrintConfig &_config = PrintConfig()) const;

    public: std::string ToString(
        sdf::Errors &_errors,
        const std::string &_prefix,
        const PrintConfig &_config = PrintConfig()) const;

    public: std::string ToString(
        const std::string &_prefix,
        bool _includeDefaultElements,
        bool _includeDefaultAttributes,
        const PrintConfig &_config = PrintConfig()) const;

    public: std::string ToString(
        sdf::Errors &_errors,
        const std::string &_prefix,
        bool _includeDefaultElements,
        bool _includeDefaultAttributes,
        const PrintConfig &_config = PrintConfig()) const;

    public: void AddAttribute(const std::string &_key,
                              const std::string &_type,
                              const std::string &_defaultvalue,
                              bool _required,
                              const std::string &_description = "");

    public: void AddAttribute(const std::string &_key,
                              const std::string &_type,
                              const std::string &_defaultvalue,
                              bool _required,
                              sdf::Errors &_errors,
                              const std::string &_description = "");

    public: void AddValue(const std::string &_type,
                          const std::string &_defaultValue, bool _required,
                          const std::string &_description = "");

    public: void AddValue(const std::string &_type,
                          const std::string &_defaultValue, bool _required,
                          sdf::Errors &_errors,
                          const std::string &_description = "");

    public: void AddValue(const std::string &_type,
                          const std::string &_defaultValue, bool _required,
                          const std::string &_minValue,
                          const std::string &_maxValue,
                          const std::string &_description = "");

    public: void AddValue(const std::string &_type,
                          const std::string &_defaultValue, bool _required,
                          const std::string &_minValue,
                          const std::string &_maxValue,
                          sdf::Errors &_errors,
                          const std::string &_description = "");

    public: ParamPtr GetAttribute(const std::string &_key) const;

    public: size_t GetAttributeCount() const;

    public: const Param_V &GetAttributes() const;

    public: ParamPtr GetAttribute(unsigned int _index) const;

    public: size_t GetElementDescriptionCount() const;

    public:
    GZ_DEPRECATED(16)
    ElementPtr GetElementDescription(unsigned int _index) const;

    public:
    GZ_DEPRECATED(16)
    ElementPtr GetElementDescription(const std::string &_key) const;

    public: ElementConstPtr ElementDescription(unsigned int _index) const;

    public: ElementConstPtr ElementDescription(const std::string &_key) const;

    public: ElementPtr MutableElementDescription(unsigned int _index);

    public: ElementPtr MutableElementDescription(const std::string &_key);

    public: bool HasElementDescription(const std::string &_name) const;

    public: bool HasAttribute(const std::string &_key) const;

    public: bool GetAttributeSet(const std::string &_key) const;

    public: void RemoveAttribute(const std::string &_key);

    public: void RemoveAllAttributes();

    public: ParamPtr GetValue() const;

    public: std::any GetAny(const std::string &_key = "") const;

    public: std::any GetAny(sdf::Errors &_errors,
                            const std::string &_key = "") const;

    public: template<typename T>
            T Get(sdf::Errors &_errors,
                  const std::string &_key = "") const;

    public: template<typename T>
            T Get(const std::string &_key = "") const;

    public: template<typename T>
            std::pair<T, bool> Get(sdf::Errors &_errors,
                                   const std::string &_key,
                                   const T &_defaultValue) const;
    public: template<typename T>
            std::pair<T, bool> Get(const std::string &_key,
                                   const T &_defaultValue) const;

    public: template<typename T>
            bool Get(const std::string &_key,
                     T &_param,
                     const T &_defaultValue) const;

    public: template<typename T>
            bool Get(sdf::Errors &_errors,
                     const std::string &_key,
                     T &_param,
                     const T &_defaultValue) const;

    public: template<typename T>
            bool Set(const T &_value);

    public: template<typename T>
            bool Set(sdf::Errors &_errors, const T &_value);

    public: bool HasElement(const std::string &_name) const;

    public: ElementPtr GetFirstElement() const;

    public: ElementPtr GetNextElement(const std::string &_name = "") const;

    public: std::set<std::string> GetElementTypeNames() const;

    public: bool HasUniqueChildNames(const std::string &_type = "") const;

    public: bool HasUniqueChildNames(sdf::Errors &_errors,
                const std::string &_type = "") const;

    public: bool HasUniqueChildNames(
                const std::string &_type,
                const std::vector<std::string> &_ignoreElements) const;

    public: bool HasUniqueChildNames(
                sdf::Errors &_errors,
                const std::string &_type,
                const std::vector<std::string> &_ignoreElements) const;

    public: std::map<std::string, std::size_t>
            CountNamedElements(const std::string &_type = "") const;

    public: std::map<std::string, std::size_t>
            CountNamedElements(sdf::Errors &_errors,
                               const std::string &_type = "") const;

    public: std::map<std::string, std::size_t> CountNamedElements(
                const std::string &_type,
                const std::vector<std::string> &_ignoreElements) const;

    public: std::map<std::string, std::size_t> CountNamedElements(
                sdf::Errors &_errors,
                const std::string &_type,
                const std::vector<std::string> &_ignoreElements) const;

    public: ElementPtr GetElement(const std::string &_name);

    public: ElementPtr GetElement(const std::string &_name,
                sdf::Errors &_errors);

    public: ElementPtr FindElement(const std::string &_name);

    public: ElementConstPtr FindElement(const std::string &_name) const;

    public: ElementPtr AddElement(const std::string &_name);

    public: ElementPtr AddElement(const std::string &_name,
                sdf::Errors &_errors);

    public: void InsertElement(ElementPtr _elem);

    public: void InsertElement(ElementPtr _elem, bool _setParentToSelf);

    public: void RemoveFromParent();

    public: void RemoveChild(ElementPtr _child);

    public: void RemoveChild(ElementPtr _child, sdf::Errors &_errors);

    public: void ClearElements();

    public: void Clear();

    public: void Update();

    public: void Update(sdf::Errors &_errors);

    public: void Reset();

    public: void SetIncludeElement(sdf::ElementPtr _includeElem);

    public: sdf::ElementPtr GetIncludeElement() const;

    public: void SetFilePath(const std::string &_path);

    public: const std::string &FilePath() const;

    public: void SetLineNumber(int _lineNumber);

    public: std::optional<int> LineNumber() const;

    public: void SetXmlPath(const std::string &_path);

    public: const std::string &XmlPath() const;

    public: void SetOriginalVersion(const std::string &_version);

    public: const std::string &OriginalVersion() const;

    public: std::string GetDescription() const;

    public: void SetDescription(const std::string &_desc);

    public: void AddElementDescription(ElementPtr _elem);

    public: ElementPtr GetElementImpl(const std::string &_name) const;

    public: static std::vector<std::string> NameUniquenessExceptions();

    private: void ToString(sdf::Errors &_errors,
                           std::ostringstream &_out,
                           const std::string &_prefix,
                           bool _includeDefaultElements,
                           bool _includeDefaultAttributes,
                           const PrintConfig &_config) const;

    private: void PrintValuesImpl(sdf::Errors &_errors,
                                  const std::string &_prefix,
                                  bool _includeDefaultElements,
                                  bool _includeDefaultAttributes,
                                  const PrintConfig &_config,
                                  std::ostringstream &_out) const;

    private: ParamPtr CreateParam(const std::string &_key,
                                  const std::string &_type,
                                  const std::string &_defaultValue,
                                  bool _required,
                                  sdf::Errors &_errors,
                                  const std::string &_description = "");

    private: std::unique_ptr<ElementPrivate> dataPtr;
  };

  class ElementPrivate
  {
    public: std::string name;

    public: std::string required;

    public: std::string description;

    public: bool copyChildren;

    public: ElementWeakPtr parent;
 
    // Attributes of this element
    public: Param_V attributes;
 
    // Value of this element
    public: ParamPtr value;
 
    // The existing child elements
    public: ElementPtr_V elements;
 
    // The possible child elements
    public: ElementPtr_V elementDescriptions;

    public: ElementPtr includeElement;

    public: std::string referenceSDF;

    public: std::string path;

    public: std::string originalVersion;

    public: bool explicitlySetInFile;

    public: std::optional<int> lineNumber;

    public: std::string xmlPath;

    public: std::unordered_set<ElementConstPtr> clonedElementDescriptions;

    public: void PrintAttributes(bool _includeDefaultAttributes,
                                 const PrintConfig &_config,
                                 std::ostringstream &_out) const;

    public: void PrintAttributes(sdf::Errors &_errors,
                                 bool _includeDefaultAttributes,
                                 const PrintConfig &_config,
                                 std::ostringstream &_out) const;

    public:
    std::optional<unsigned int> ElementDescriptionIndex(
        const std::string &_key);
  };

  template<typename T>
  T Element::Get(sdf::Errors &_errors, const std::string &_key) const
  {
    T result = T();
 
    std::pair<T, bool> ret = this->Get<T>(_errors, _key, result);
 
    return ret.first;
  }

  template<typename T>
  T Element::Get(const std::string &_key) const
  {
    T result = T();
 
    std::pair<T, bool> ret = this->Get<T>(_key, result);
 
    return ret.first;
  }

  template<typename T>
  bool Element::Get(sdf::Errors &_errors,
                    const std::string &_key,
                    T &_param,
                    const T &_defaultValue) const
  {
    std::pair<T, bool> ret = this->Get<T>(_errors, _key, _defaultValue);
    _param = ret.first;
    return ret.second;
  }

  template<typename T>
  bool Element::Get(const std::string &_key,
                    T &_param,
                    const T &_defaultValue) const
  {
    std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
    _param = ret.first;
    return ret.second;
  }

  template<typename T>
  std::pair<T, bool> Element::Get(const std::string &_key,
                                  const T &_defaultValue) const
  {
    sdf::Errors errors;
    std::pair<T, bool> result = this->Get<T>(errors, _key, _defaultValue);
    for(auto& error : errors)
    {
      internal::throwOrPrintError(sdferr, error);
    }
    return result;
  }

  template<typename T>
  std::pair<T, bool> Element::Get(sdf::Errors &_errors,
                                  const std::string &_key,
                                  const T &_defaultValue) const
  {
    std::pair<T, bool> result(_defaultValue, true);
 
    if (_key.empty() && this->dataPtr->value)
    {
      this->dataPtr->value->Get<T>(result.first, _errors);
    }
    else if (!_key.empty())
    {
      ParamPtr param = this->GetAttribute(_key);
      if (param)
      {
        param->Get(result.first, _errors);
      }
      else if (this->HasElement(_key))
      {
        result.first = this->GetElementImpl(_key)->Get<T>(_errors);
      }
      else if (this->HasElementDescription(_key))
      {
        result.first = this->ElementDescription(_key)->Get<T>(_errors);
      }
      else
      {
        result.second = false;
      }
    }
    else
    {
      result.second = false;
    }
 
    return result;
  }

  template<typename T>
  bool Element::Set(const T &_value)
  {
    sdf::Errors errors;
    bool result = this->Set<T>(errors, _value);
    for(auto& error : errors)
    {
      internal::throwOrPrintError(sdferr, error);
    }
    return result;
  }

  template<typename T>
  bool Element::Set(sdf::Errors &_errors, const T &_value)
  {
    if (this->dataPtr->value)
    {
      return this->dataPtr->value->Set(_value, _errors);
    }
    return false;
  }

  }
}
 
#ifdef _WIN32
#pragma warning(pop)
#endif
 
#endif