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
43namespace 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
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
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
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
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
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.
void Copy(const ElementPtr _elem)
Copy values from an Element.
const std::string & XmlPath() const
Get the XML path of this element.
void RemoveChild(ElementPtr _child)
Remove a child element.
std::string GetDescription() const
Get a text description of the element.
const std::string & FilePath() const
Get the path to the SDF document where this element came from.
size_t GetAttributeCount() const
Get the number of attributes.
const std::string & GetRequired() const
Get the requirement string.
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.
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.
std::optional< int > LineNumber() const
Get the line number of this element within the SDF document.
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.
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...
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.
const std::string & OriginalVersion() const
Get the spec version that this was originally parsed from.
void RemoveAttribute(const std::string &_key)
Remove an attribute.
void SetCopyChildren(bool _value)
Set whether this element should copy its child elements during parsing.
void InsertElement(ElementPtr _elem)
Add an element object.
bool GetAttributeSet(const std::string &_key) const
Return true if the attribute was set (i.e.
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 RemoveAllAttributes()
Removes all attributes.
const std::string & GetName() const
Get the Element's name.
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.
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.
std::set< std::string > GetElementTypeNames() const
Get set of child element type names.
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.
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.
ParamPtr GetAttribute(unsigned int _index) const
Get an attribute using an index.
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.
const Param_V & GetAttributes() const
Get all the attribute params.
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.
static std::vector< std::string > NameUniquenessExceptions()
List of elements to which exceptions are made when checking for name uniqueness.
void SetFilePath(const std::string &_path)
Set the path to the SDF document where this element came from.
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