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 
88  public: void Copy(const ElementPtr _elem);
89 
93  public: ElementPtr GetParent() const;
94 
97  public: void SetParent(const ElementPtr _parent);
98 
101  public: void SetName(const std::string &_name);
102 
105  public: const std::string &GetName() const;
106 
114  public: void SetRequired(const std::string &_req);
115 
119  public: const std::string &GetRequired() const;
120 
126  public: void SetExplicitlySetInFile(const bool _value);
127 
130  public: bool GetExplicitlySetInFile() const;
131 
135  public: void SetCopyChildren(bool _value);
136 
140  public: bool GetCopyChildren() const;
141 
144  public: void SetReferenceSDF(const std::string &_value);
145 
148  public: std::string ReferenceSDF() const;
149 
152  public: void PrintDescription(const std::string &_prefix) const;
153 
157  public: void PrintValues(std::string _prefix,
158  const PrintConfig &_config = PrintConfig()) const;
159 
165  public: void PrintValues(const std::string &_prefix,
166  bool _includeDefaultElements,
167  bool _includeDefaultAttributes,
168  const PrintConfig &_config = PrintConfig()) const;
169 
176  public: void PrintDocLeftPane(std::string &_html,
177  int _spacing, int &_index) const;
178 
184  public: void PrintDocRightPane(std::string &_html,
185  int _spacing, int &_index) const;
186 
191  public: std::string ToString(
192  const std::string &_prefix,
193  const PrintConfig &_config = PrintConfig()) const;
194 
204  public: std::string ToString(
205  const std::string &_prefix,
206  bool _includeDefaultElements,
207  bool _includeDefaultAttributes,
208  const PrintConfig &_config = PrintConfig()) const;
209 
217  public: void AddAttribute(const std::string &_key,
218  const std::string &_type,
219  const std::string &_defaultvalue,
220  bool _required,
221  const std::string &_description = "");
222 
229  public: void AddValue(const std::string &_type,
230  const std::string &_defaultValue, bool _required,
231  const std::string &_description = "");
232 
242  public: void AddValue(const std::string &_type,
243  const std::string &_defaultValue, bool _required,
244  const std::string &_minValue,
245  const std::string &_maxValue,
246  const std::string &_description = "");
247 
251  public: ParamPtr GetAttribute(const std::string &_key) const;
252 
255  public: size_t GetAttributeCount() const;
256 
259  public: const Param_V &GetAttributes() const;
260 
264  public: ParamPtr GetAttribute(unsigned int _index) const;
265 
268  public: size_t GetElementDescriptionCount() const;
269 
273  public: ElementPtr GetElementDescription(unsigned int _index) const;
274 
278  public: ElementPtr GetElementDescription(const std::string &_key) const;
279 
283  public: bool HasElementDescription(const std::string &_name) const;
284 
288  public: bool HasAttribute(const std::string &_key) const;
289 
293  public: bool GetAttributeSet(const std::string &_key) const;
294 
297  public: void RemoveAttribute(const std::string &_key);
298 
300  public: void RemoveAllAttributes();
301 
304  public: ParamPtr GetValue() const;
305 
310  public: std::any GetAny(const std::string &_key = "") const;
311 
318  public: template<typename T>
319  T Get(const std::string &_key = "") const;
320 
327  public: template<typename T>
328  std::pair<T, bool> Get(const std::string &_key,
329  const T &_defaultValue) const;
330 
337  public: template<typename T>
338  bool Get(const std::string &_key,
339  T &_param,
340  const T &_defaultValue) const;
341 
345  public: template<typename T>
346  bool Set(const T &_value);
347 
351  public: bool HasElement(const std::string &_name) const;
352 
356  public: ElementPtr GetFirstElement() const;
357 
369  public: ElementPtr GetNextElement(const std::string &_name = "") const;
370 
373  public: std::set<std::string> GetElementTypeNames() const;
374 
382  public: bool HasUniqueChildNames(const std::string &_type = "") const;
383 
394  public: bool HasUniqueChildNames(
395  const std::string &_type,
396  const std::vector<std::string> &_ignoreElements) const;
397 
405  public: std::map<std::string, std::size_t>
406  CountNamedElements(const std::string &_type = "") const;
407 
418  public: std::map<std::string, std::size_t> CountNamedElements(
419  const std::string &_type,
420  const std::vector<std::string> &_ignoreElements) const;
421 
432  public: ElementPtr GetElement(const std::string &_name);
433 
443  public: ElementPtr FindElement(const std::string &_name);
444 
454  public: ElementConstPtr FindElement(const std::string &_name) const;
455 
459  public: ElementPtr AddElement(const std::string &_name);
460 
463  public: void InsertElement(ElementPtr _elem);
464 
470  public: void InsertElement(ElementPtr _elem, bool _setParentToSelf);
471 
473  public: void RemoveFromParent();
474 
477  public: void RemoveChild(ElementPtr _child);
478 
480  public: void ClearElements();
481 
484  public: void Clear();
485 
488  public: void Update();
489 
493  public: void Reset();
494 
500  public: void SetIncludeElement(sdf::ElementPtr _includeElem);
501 
507 
510  public: void SetFilePath(const std::string &_path);
511 
514  public: const std::string &FilePath() const;
515 
518  public: void SetLineNumber(int _lineNumber);
519 
523  public: std::optional<int> LineNumber() const;
524 
539  public: void SetXmlPath(const std::string &_path);
540 
543  public: const std::string &XmlPath() const;
544 
547  public: void SetOriginalVersion(const std::string &_version);
548 
551  public: const std::string &OriginalVersion() const;
552 
555  public: std::string GetDescription() const;
556 
559  public: void SetDescription(const std::string &_desc);
560 
563  public: void AddElementDescription(ElementPtr _elem);
564 
568  public: ElementPtr GetElementImpl(const std::string &_name) const;
569 
573  public: static std::vector<std::string> NameUniquenessExceptions();
574 
581  private: void ToString(const std::string &_prefix,
582  bool _includeDefaultElements,
583  bool _includeDefaultAttributes,
584  const PrintConfig &_config,
585  std::ostringstream &_out) const;
586 
593  private: void PrintValuesImpl(const std::string &_prefix,
594  bool _includeDefaultElements,
595  bool _includeDefaultAttributes,
596  const PrintConfig &_config,
597  std::ostringstream &_out) const;
598 
607  private: ParamPtr CreateParam(const std::string &_key,
608  const std::string &_type,
609  const std::string &_defaultValue,
610  bool _required,
611  const std::string &_description = "");
612 
613 
615  private: std::unique_ptr<ElementPrivate> dataPtr;
616  };
617 
621  {
623  public: std::string name;
624 
626  public: std::string required;
627 
629  public: std::string description;
630 
632  public: bool copyChildren;
633 
636 
637  // Attributes of this element
639 
640  // Value of this element
641  public: ParamPtr value;
642 
643  // The existing child elements
645 
646  // The possible child elements
648 
670 
672  public: std::string referenceSDF;
673 
675  public: std::string path;
676 
678  public: std::string originalVersion;
679 
681  public: bool explicitlySetInFile;
682 
684  public: std::optional<int> lineNumber;
685 
687  public: std::string xmlPath;
688 
693  public: void PrintAttributes(bool _includeDefaultAttributes,
694  const PrintConfig &_config,
695  std::ostringstream &_out) const;
696  };
697 
699  template<typename T>
700  T Element::Get(const std::string &_key) const
701  {
702  T result = T();
703 
704  std::pair<T, bool> ret = this->Get<T>(_key, result);
705 
706  return ret.first;
707  }
708 
710  template<typename T>
711  bool Element::Get(const std::string &_key,
712  T &_param,
713  const T &_defaultValue) const
714  {
715  std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
716  _param = ret.first;
717  return ret.second;
718  }
719 
721  template<typename T>
722  std::pair<T, bool> Element::Get(const std::string &_key,
723  const T &_defaultValue) const
724  {
725  std::pair<T, bool> result(_defaultValue, true);
726 
727  if (_key.empty() && this->dataPtr->value)
728  {
729  this->dataPtr->value->Get<T>(result.first);
730  }
731  else if (!_key.empty())
732  {
733  ParamPtr param = this->GetAttribute(_key);
734  if (param)
735  {
736  param->Get(result.first);
737  }
738  else if (this->HasElement(_key))
739  {
740  result.first = this->GetElementImpl(_key)->Get<T>();
741  }
742  else if (this->HasElementDescription(_key))
743  {
744  result.first = this->GetElementDescription(_key)->Get<T>();
745  }
746  else
747  {
748  result.second = false;
749  }
750  }
751  else
752  {
753  result.second = false;
754  }
755 
756  return result;
757  }
758 
760  template<typename T>
761  bool Element::Set(const T &_value)
762  {
763  if (this->dataPtr->value)
764  {
765  return this->dataPtr->value->Set(_value);
766  }
767  return false;
768  }
770  }
771 }
772 
773 #ifdef _WIN32
774 #pragma warning(pop)
775 #endif
776 
777 #endif
Definition: Element.hh:621
bool explicitlySetInFile
True if the element was set in the SDF file.
Definition: Element.hh:681
ElementWeakPtr parent
Element's parent.
Definition: Element.hh:635
std::string description
Element description.
Definition: Element.hh:629
void PrintAttributes(bool _includeDefaultAttributes, const PrintConfig &_config, std::ostringstream &_out) const
Generate the string (XML) for the attributes.
ElementPtr_V elements
Definition: Element.hh:644
std::string referenceSDF
Name of reference sdf.
Definition: Element.hh:672
bool copyChildren
True if element's children should be copied.
Definition: Element.hh:632
Param_V attributes
Definition: Element.hh:638
std::string required
True if element is required.
Definition: Element.hh:626
ParamPtr value
Definition: Element.hh:641
std::string name
Element name.
Definition: Element.hh:623
ElementPtr_V elementDescriptions
Definition: Element.hh:647
std::string originalVersion
Spec version that this was originally parsed from.
Definition: Element.hh:678
std::string xmlPath
XML path of this element.
Definition: Element.hh:687
std::string path
Path to file where this element came from.
Definition: Element.hh:675
std::optional< int > lineNumber
Line number in file where this element came from.
Definition: Element.hh:684
ElementPtr includeElement
The element that was used to load this entity.
Definition: Element.hh:669
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.
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 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 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::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.
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.
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.
void SetReferenceSDF(const std::string &_value)
Set reference SDF element.
size_t GetElementDescriptionCount() const
Get the number of element descriptions.
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:32
T Get(const std::string &_key="") const
Get the value of a key.
Definition: Element.hh:700
bool Set(const T &_value)
Set the value of this element.
Definition: Element.hh:761
std::shared_ptr< Param > ParamPtr
Definition: Param.hh:65
std::vector< ParamPtr > Param_V
Definition: Param.hh:69
std::vector< ElementPtr > ElementPtr_V
Definition: Element.hh:66
std::shared_ptr< const Element > ElementConstPtr
Definition: Element.hh:58
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