Element.hh
Go to the documentation of this file.
1 /*
2  * Copyright 2015 Open Source Robotics Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  */
17 #ifndef SDF_ELEMENT_HH_
18 #define SDF_ELEMENT_HH_
19 
20 #include <any>
21 #include <map>
22 #include <memory>
23 #include <set>
24 #include <string>
25 #include <utility>
26 #include <vector>
27 
28 #include "sdf/Param.hh"
29 #include "sdf/PrintConfig.hh"
30 #include "sdf/sdf_config.h"
31 #include "sdf/system_util.hh"
32 #include "sdf/Types.hh"
33 
34 #ifdef _WIN32
35 // Disable warning C4251 which is triggered by
36 // std::enable_shared_from_this
37 #pragma warning(push)
38 #pragma warning(disable: 4251)
39 #endif
40 
43 namespace sdf
44 {
45  // Inline bracket to help doxygen filtering.
46  inline namespace SDF_VERSION_NAMESPACE {
47  //
48 
49  class ElementPrivate;
51 
54  typedef std::shared_ptr<Element> ElementPtr;
55 
58  typedef std::shared_ptr<const Element> ElementConstPtr;
59 
62  typedef std::weak_ptr<Element> ElementWeakPtr;
63 
66  typedef std::vector<ElementPtr> ElementPtr_V;
67 
70 
74  public std::enable_shared_from_this<Element>
75  {
77  public: Element();
78 
80  public: virtual ~Element();
81 
84  public: ElementPtr Clone() const;
85 
89  public: ElementPtr Clone(sdf::Errors &_errors) const;
90 
93  public: void Copy(const ElementPtr _elem);
94 
98  public: void Copy(const ElementPtr _elem, sdf::Errors &_errors);
99 
103  public: ElementPtr GetParent() const;
104 
107  public: void SetParent(const ElementPtr _parent);
108 
111  public: void SetName(const std::string &_name);
112 
115  public: const std::string &GetName() const;
116 
124  public: void SetRequired(const std::string &_req);
125 
129  public: const std::string &GetRequired() const;
130 
136  public: void SetExplicitlySetInFile(const bool _value);
137 
140  public: bool GetExplicitlySetInFile() const;
141 
145  public: void SetCopyChildren(bool _value);
146 
150  public: bool GetCopyChildren() const;
151 
154  public: void SetReferenceSDF(const std::string &_value);
155 
158  public: std::string ReferenceSDF() const;
159 
162  public: void PrintDescription(const std::string &_prefix) const;
163 
167  public: void PrintValues(std::string _prefix,
168  const PrintConfig &_config = PrintConfig()) const;
169 
175  public: void PrintValues(const std::string &_prefix,
176  bool _includeDefaultElements,
177  bool _includeDefaultAttributes,
178  const PrintConfig &_config = PrintConfig()) const;
179 
186  public: void PrintDocLeftPane(std::string &_html,
187  int _spacing, int &_index) const;
188 
194  public: void PrintDocRightPane(std::string &_html,
195  int _spacing, int &_index) const;
196 
201  public: std::string ToString(
202  const std::string &_prefix,
203  const PrintConfig &_config = PrintConfig()) const;
204 
214  public: std::string ToString(
215  const std::string &_prefix,
216  bool _includeDefaultElements,
217  bool _includeDefaultAttributes,
218  const PrintConfig &_config = PrintConfig()) const;
219 
227  public: void AddAttribute(const std::string &_key,
228  const std::string &_type,
229  const std::string &_defaultvalue,
230  bool _required,
231  const std::string &_description = "");
232 
241  public: void AddAttribute(const std::string &_key,
242  const std::string &_type,
243  const std::string &_defaultvalue,
244  bool _required,
245  sdf::Errors &_errors,
246  const std::string &_description = "");
247 
254  public: void AddValue(const std::string &_type,
255  const std::string &_defaultValue, bool _required,
256  const std::string &_description = "");
257 
265  public: void AddValue(const std::string &_type,
266  const std::string &_defaultValue, bool _required,
267  sdf::Errors &_errors,
268  const std::string &_description = "");
269 
279  public: void AddValue(const std::string &_type,
280  const std::string &_defaultValue, bool _required,
281  const std::string &_minValue,
282  const std::string &_maxValue,
283  const std::string &_description = "");
284 
295  public: void AddValue(const std::string &_type,
296  const std::string &_defaultValue, bool _required,
297  const std::string &_minValue,
298  const std::string &_maxValue,
299  sdf::Errors &_errors,
300  const std::string &_description = "");
301 
305  public: ParamPtr GetAttribute(const std::string &_key) const;
306 
309  public: size_t GetAttributeCount() const;
310 
313  public: const Param_V &GetAttributes() const;
314 
318  public: ParamPtr GetAttribute(unsigned int _index) const;
319 
322  public: size_t GetElementDescriptionCount() const;
323 
327  public: ElementPtr GetElementDescription(unsigned int _index) const;
328 
332  public: ElementPtr GetElementDescription(const std::string &_key) const;
333 
337  public: bool HasElementDescription(const std::string &_name) const;
338 
342  public: bool HasAttribute(const std::string &_key) const;
343 
347  public: bool GetAttributeSet(const std::string &_key) const;
348 
351  public: void RemoveAttribute(const std::string &_key);
352 
354  public: void RemoveAllAttributes();
355 
358  public: ParamPtr GetValue() const;
359 
364  public: std::any GetAny(const std::string &_key = "") const;
365 
371  public: std::any GetAny(sdf::Errors &_errors,
372  const std::string &_key = "") const;
373 
380  public: template<typename T>
381  T Get(const std::string &_key = "") const;
382 
389  public: template<typename T>
390  std::pair<T, bool> Get(const std::string &_key,
391  const T &_defaultValue) const;
392 
399  public: template<typename T>
400  bool Get(const std::string &_key,
401  T &_param,
402  const T &_defaultValue) const;
403 
407  public: template<typename T>
408  bool Set(const T &_value);
409 
413  public: bool HasElement(const std::string &_name) const;
414 
418  public: ElementPtr GetFirstElement() const;
419 
431  public: ElementPtr GetNextElement(const std::string &_name = "") const;
432 
435  public: std::set<std::string> GetElementTypeNames() const;
436 
444  public: bool HasUniqueChildNames(const std::string &_type = "") const;
445 
456  public: bool HasUniqueChildNames(
457  const std::string &_type,
458  const std::vector<std::string> &_ignoreElements) const;
459 
467  public: std::map<std::string, std::size_t>
468  CountNamedElements(const std::string &_type = "") const;
469 
480  public: std::map<std::string, std::size_t> CountNamedElements(
481  const std::string &_type,
482  const std::vector<std::string> &_ignoreElements) const;
483 
494  public: ElementPtr GetElement(const std::string &_name);
495 
507  public: ElementPtr GetElement(const std::string &_name,
508  sdf::Errors &_errors);
509 
519  public: ElementPtr FindElement(const std::string &_name);
520 
530  public: ElementConstPtr FindElement(const std::string &_name) const;
531 
535  public: ElementPtr AddElement(const std::string &_name);
536 
541  public: ElementPtr AddElement(const std::string &_name,
542  sdf::Errors &_errors);
543 
546  public: void InsertElement(ElementPtr _elem);
547 
553  public: void InsertElement(ElementPtr _elem, bool _setParentToSelf);
554 
556  public: void RemoveFromParent();
557 
560  public: void RemoveChild(ElementPtr _child);
561 
565  public: void RemoveChild(ElementPtr _child, sdf::Errors &_errors);
566 
568  public: void ClearElements();
569 
572  public: void Clear();
573 
576  public: void Update();
577 
581  public: void Reset();
582 
588  public: void SetIncludeElement(sdf::ElementPtr _includeElem);
589 
595 
598  public: void SetFilePath(const std::string &_path);
599 
602  public: const std::string &FilePath() const;
603 
606  public: void SetLineNumber(int _lineNumber);
607 
611  public: std::optional<int> LineNumber() const;
612 
627  public: void SetXmlPath(const std::string &_path);
628 
631  public: const std::string &XmlPath() const;
632 
635  public: void SetOriginalVersion(const std::string &_version);
636 
639  public: const std::string &OriginalVersion() const;
640 
643  public: std::string GetDescription() const;
644 
647  public: void SetDescription(const std::string &_desc);
648 
651  public: void AddElementDescription(ElementPtr _elem);
652 
656  public: ElementPtr GetElementImpl(const std::string &_name) const;
657 
661  public: static std::vector<std::string> NameUniquenessExceptions();
662 
669  private: void ToString(const std::string &_prefix,
670  bool _includeDefaultElements,
671  bool _includeDefaultAttributes,
672  const PrintConfig &_config,
673  std::ostringstream &_out) const;
674 
681  private: void PrintValuesImpl(const std::string &_prefix,
682  bool _includeDefaultElements,
683  bool _includeDefaultAttributes,
684  const PrintConfig &_config,
685  std::ostringstream &_out) const;
686 
696  private: ParamPtr CreateParam(const std::string &_key,
697  const std::string &_type,
698  const std::string &_defaultValue,
699  bool _required,
700  sdf::Errors &_errors,
701  const std::string &_description = "");
702 
704  private: std::unique_ptr<ElementPrivate> dataPtr;
705  };
706 
710  {
712  public: std::string name;
713 
715  public: std::string required;
716 
718  public: std::string description;
719 
721  public: bool copyChildren;
722 
725 
726  // Attributes of this element
728 
729  // Value of this element
730  public: ParamPtr value;
731 
732  // The existing child elements
734 
735  // The possible child elements
737 
759 
761  public: std::string referenceSDF;
762 
764  public: std::string path;
765 
767  public: std::string originalVersion;
768 
770  public: bool explicitlySetInFile;
771 
773  public: std::optional<int> lineNumber;
774 
776  public: std::string xmlPath;
777 
782  public: void PrintAttributes(bool _includeDefaultAttributes,
783  const PrintConfig &_config,
784  std::ostringstream &_out) const;
785  };
786 
788  template<typename T>
789  T Element::Get(const std::string &_key) const
790  {
791  T result = T();
792 
793  std::pair<T, bool> ret = this->Get<T>(_key, result);
794 
795  return ret.first;
796  }
797 
799  template<typename T>
800  bool Element::Get(const std::string &_key,
801  T &_param,
802  const T &_defaultValue) const
803  {
804  std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
805  _param = ret.first;
806  return ret.second;
807  }
808 
810  template<typename T>
811  std::pair<T, bool> Element::Get(const std::string &_key,
812  const T &_defaultValue) const
813  {
814  std::pair<T, bool> result(_defaultValue, true);
815 
816  if (_key.empty() && this->dataPtr->value)
817  {
818  this->dataPtr->value->Get<T>(result.first);
819  }
820  else if (!_key.empty())
821  {
822  ParamPtr param = this->GetAttribute(_key);
823  if (param)
824  {
825  param->Get(result.first);
826  }
827  else if (this->HasElement(_key))
828  {
829  result.first = this->GetElementImpl(_key)->Get<T>();
830  }
831  else if (this->HasElementDescription(_key))
832  {
833  result.first = this->GetElementDescription(_key)->Get<T>();
834  }
835  else
836  {
837  result.second = false;
838  }
839  }
840  else
841  {
842  result.second = false;
843  }
844 
845  return result;
846  }
847 
849  template<typename T>
850  bool Element::Set(const T &_value)
851  {
852  if (this->dataPtr->value)
853  {
854  this->dataPtr->value->Set(_value);
855  return true;
856  }
857  return false;
858  }
860  }
861 }
862 
863 #ifdef _WIN32
864 #pragma warning(pop)
865 #endif
866 
867 #endif
Definition: Element.hh:710
bool explicitlySetInFile
True if the element was set in the SDF file.
Definition: Element.hh:770
ElementWeakPtr parent
Element's parent.
Definition: Element.hh:724
std::string description
Element description.
Definition: Element.hh:718
void PrintAttributes(bool _includeDefaultAttributes, const PrintConfig &_config, std::ostringstream &_out) const
Generate the string (XML) for the attributes.
ElementPtr_V elements
Definition: Element.hh:733
std::string referenceSDF
Name of reference sdf.
Definition: Element.hh:761
bool copyChildren
True if element's children should be copied.
Definition: Element.hh:721
Param_V attributes
Definition: Element.hh:727
std::string required
True if element is required.
Definition: Element.hh:715
ParamPtr value
Definition: Element.hh:730
std::string name
Element name.
Definition: Element.hh:712
ElementPtr_V elementDescriptions
Definition: Element.hh:736
std::string originalVersion
Spec version that this was originally parsed from.
Definition: Element.hh:767
std::string xmlPath
XML path of this element.
Definition: Element.hh:776
std::string path
Path to file where this element came from.
Definition: Element.hh:764
std::optional< int > lineNumber
Line number in file where this element came from.
Definition: Element.hh:773
ElementPtr includeElement
The element that was used to load this entity.
Definition: Element.hh:758
SDF Element class.
Definition: Element.hh:75
void SetOriginalVersion(const std::string &_version)
Set the spec version that this was originally parsed from.
const std::string & GetRequired() const
Get the requirement string.
void Copy(const ElementPtr _elem)
Copy values from an Element.
void RemoveChild(ElementPtr _child)
Remove a child element.
std::string GetDescription() const
Get a text description of the element.
size_t GetAttributeCount() const
Get the number of attributes.
ElementPtr GetNextElement(const std::string &_name="") const
Get the next sibling of this element.
ParamPtr GetValue() const
Get the param of the elements value return A Param pointer to the value of this element.
bool HasElementDescription(const std::string &_name) const
Return true if an element description exists.
void AddElementDescription(ElementPtr _elem)
Add a new element description.
const std::string & FilePath() const
Get the path to the SDF document where this element came from.
void Clear()
Remove all child elements and reset file path and original version.
void Reset()
Call reset on each element and element description before deleting all of them.
std::string ReferenceSDF() const
Get the name of the reference SDF element.
void Update()
Call the Update() callback on each element, as well as the embedded Param.
void PrintValues(const std::string &_prefix, bool _includeDefaultElements, bool _includeDefaultAttributes, const PrintConfig &_config=PrintConfig()) const
Output Element's values to stdout.
const std::string & OriginalVersion() const
Get the spec version that this was originally parsed from.
void SetLineNumber(int _lineNumber)
Set the line number of this element within the SDF document.
ElementPtr AddElement(const std::string &_name, sdf::Errors &_errors)
Add a named element.
void SetRequired(const std::string &_req)
Set the requirement type.
std::string ToString(const std::string &_prefix, bool _includeDefaultElements, bool _includeDefaultAttributes, const PrintConfig &_config=PrintConfig()) const
Convert the element values to a string representation.
void RemoveAttribute(const std::string &_key)
Remove an attribute.
void SetCopyChildren(bool _value)
Set whether this element should copy its child elements during parsing.
const Param_V & GetAttributes() const
Get all the attribute params.
void InsertElement(ElementPtr _elem)
Add an element object.
bool GetAttributeSet(const std::string &_key) const
Return true if the attribute was set (i.e.
void RemoveAllAttributes()
Removes all attributes.
void Copy(const ElementPtr _elem, sdf::Errors &_errors)
Copy values from an Element.
void SetIncludeElement(sdf::ElementPtr _includeElem)
Set the element that was used to load this element.
void ClearElements()
Remove all child elements.
void AddValue(const std::string &_type, const std::string &_defaultValue, bool _required, const std::string &_minValue, const std::string &_maxValue, const std::string &_description="")
Add a value to this Element.
bool HasUniqueChildNames(const std::string &_type, const std::vector< std::string > &_ignoreElements) const
Checks whether any child elements of the specified element type, except those listed in _ignoreElemen...
void SetExplicitlySetInFile(const bool _value)
Set if the element and children where set or default in the original file.
void InsertElement(ElementPtr _elem, bool _setParentToSelf)
Add an element object, and optionally set the given element's parent to this object.
ElementPtr GetElementImpl(const std::string &_name) const
Get a pointer to the named element.
ElementPtr GetElementDescription(const std::string &_key) const
Get an element description using a key.
void AddAttribute(const std::string &_key, const std::string &_type, const std::string &_defaultvalue, bool _required, sdf::Errors &_errors, const std::string &_description="")
Add an attribute value.
void SetParent(const ElementPtr _parent)
Set the parent of this Element.
void PrintDocRightPane(std::string &_html, int _spacing, int &_index) const
Helper function for SDF::PrintDoc.
std::any GetAny(sdf::Errors &_errors, const std::string &_key="") const
Get the element value/attribute as a std::any.
std::map< std::string, std::size_t > CountNamedElements(const std::string &_type, const std::vector< std::string > &_ignoreElements) const
Count the number of child elements of the specified element type that have the same name attribute va...
std::optional< int > LineNumber() const
Get the line number of this element within the SDF document.
ParamPtr GetAttribute(const std::string &_key) const
Get the param of an attribute.
bool GetCopyChildren() const
Return true if this Element's child elements should be copied during parsing.
ElementPtr GetElementDescription(unsigned int _index) const
Get an element description using an index.
sdf::ElementPtr GetIncludeElement() const
Get the element that was used to load this element.
void SetXmlPath(const std::string &_path)
Private data pointer.
void RemoveFromParent()
Remove this element from its parent.
bool GetExplicitlySetInFile() const
Return if the element was been explicitly set in the file.
std::any GetAny(const std::string &_key="") const
Get the element value/attribute as a std::any.
void AddValue(const std::string &_type, const std::string &_defaultValue, bool _required, const std::string &_description="")
Add a value to this Element.
void PrintDescription(const std::string &_prefix) const
Output Element's description to stdout.
std::map< std::string, std::size_t > CountNamedElements(const std::string &_type="") const
Count the number of child elements of the specified element type that have the same name attribute va...
void PrintValues(std::string _prefix, const PrintConfig &_config=PrintConfig()) const
Output Element's values to stdout.
void AddAttribute(const std::string &_key, const std::string &_type, const std::string &_defaultvalue, bool _required, const std::string &_description="")
Add an attribute value.
void AddValue(const std::string &_type, const std::string &_defaultValue, bool _required, sdf::Errors &_errors, const std::string &_description="")
Add a value to this Element.
bool HasAttribute(const std::string &_key) const
Return true if an attribute exists.
bool HasElement(const std::string &_name) const
Return true if the named element exists.
void PrintDocLeftPane(std::string &_html, int _spacing, int &_index) const
Helper function for SDF::PrintDoc.
void SetDescription(const std::string &_desc)
Set a text description for the element.
ElementPtr Clone(sdf::Errors &_errors) const
Create a copy of this Element.
const std::string & XmlPath() const
Get the XML path of this element.
ParamPtr GetAttribute(unsigned int _index) const
Get an attribute using an index.
std::set< std::string > GetElementTypeNames() const
Get set of child element type names.
static std::vector< std::string > NameUniquenessExceptions()
List of elements to which exceptions are made when checking for name uniqueness.
bool HasUniqueChildNames(const std::string &_type="") const
Checks whether any child elements of the specified element type have identical name attribute values ...
ElementPtr AddElement(const std::string &_name)
Add a named element.
ElementPtr Clone() const
Create a copy of this Element.
std::string ToString(const std::string &_prefix, const PrintConfig &_config=PrintConfig()) const
Convert the element values to a string representation.
ElementPtr GetElement(const std::string &_name, sdf::Errors &_errors)
Return a pointer to the child element with the provided name.
void SetReferenceSDF(const std::string &_value)
Set reference SDF element.
void RemoveChild(ElementPtr _child, sdf::Errors &_errors)
Remove a child element.
size_t GetElementDescriptionCount() const
Get the number of element descriptions.
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="")
Add a value to this Element.
ElementPtr GetFirstElement() const
Get the first child element.
ElementPtr FindElement(const std::string &_name)
Return a pointer to the child element with the provided name.
ElementPtr GetElement(const std::string &_name)
Return a pointer to the child element with the provided name.
ElementConstPtr FindElement(const std::string &_name) const
Return a pointer to the child element with the provided name.
ElementPtr GetParent() const
Get a pointer to this Element's parent.
void SetFilePath(const std::string &_path)
Set the path to the SDF document where this element came from.
const std::string & GetName() const
Get the Element's name.
void SetName(const std::string &_name)
Set the name of the Element.
This class contains configuration options for printing elements.
Definition: PrintConfig.hh:33
T Get(const std::string &_key="") const
Get the value of a key.
Definition: Element.hh:789
bool Set(const T &_value)
Set the value of this element.
Definition: Element.hh:850
std::shared_ptr< Param > ParamPtr
Definition: Param.hh:70
std::vector< ParamPtr > Param_V
Definition: Param.hh:74
std::vector< ElementPtr > ElementPtr_V
Definition: Element.hh:66
std::shared_ptr< const Element > ElementConstPtr
Definition: Element.hh:58
std::vector< Error > Errors
A vector of Error.
Definition: Types.hh:80
std::weak_ptr< Element > ElementWeakPtr
Definition: Element.hh:62
std::shared_ptr< Element > ElementPtr
Definition: Element.hh:54
namespace for Simulation Description Format parser
Definition: Actor.hh:35
#define SDFORMAT_VISIBLE
Use to represent "symbol visible" if supported.
Definition: system_util.hh:25