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/sdf_config.h"
30 #include "sdf/system_util.hh"
31 #include "sdf/Types.hh"
32 
33 #ifdef _WIN32
34 // Disable warning C4251 which is triggered by
35 // std::enable_shared_from_this
36 #pragma warning(push)
37 #pragma warning(disable: 4251)
38 #endif
39 
42 namespace sdf
43 {
44  // Inline bracket to help doxygen filtering.
45  inline namespace SDF_VERSION_NAMESPACE {
46  //
47 
48  class ElementPrivate;
50 
53  typedef std::shared_ptr<Element> ElementPtr;
54 
57  typedef std::weak_ptr<Element> ElementWeakPtr;
58 
61  typedef std::vector<ElementPtr> ElementPtr_V;
62 
65 
69  public std::enable_shared_from_this<Element>
70  {
72  public: Element();
73 
75  public: virtual ~Element();
76 
79  public: ElementPtr Clone() const;
80 
83  public: void Copy(const ElementPtr _elem);
84 
88  public: ElementPtr GetParent() const;
89 
92  public: void SetParent(const ElementPtr _parent);
93 
96  public: void SetName(const std::string &_name);
97 
100  public: const std::string &GetName() const;
101 
108  public: void SetRequired(const std::string &_req);
109 
113  public: const std::string &GetRequired() const;
114 
118  public: void SetCopyChildren(bool _value);
119 
123  public: bool GetCopyChildren() const;
124 
127  public: void SetReferenceSDF(const std::string &_value);
128 
131  public: std::string ReferenceSDF() const;
132 
135  public: void PrintDescription(const std::string &_prefix) const;
136 
139  public: void PrintValues(std::string _prefix) const;
140 
147  public: void PrintDocLeftPane(std::string &_html,
148  int _spacing, int &_index) const;
149 
155  public: void PrintDocRightPane(std::string &_html,
156  int _spacing, int &_index) const;
157 
161  public: std::string ToString(const std::string &_prefix) const;
162 
170  public: void AddAttribute(const std::string &_key,
171  const std::string &_type,
172  const std::string &_defaultvalue,
173  bool _required,
174  const std::string &_description="");
175 
182  public: void AddValue(const std::string &_type,
183  const std::string &_defaultValue, bool _required,
184  const std::string &_description="");
185 
189  public: ParamPtr GetAttribute(const std::string &_key) const;
190 
193  public: size_t GetAttributeCount() const;
194 
198  public: ParamPtr GetAttribute(unsigned int _index) const;
199 
202  public: size_t GetElementDescriptionCount() const;
203 
207  public: ElementPtr GetElementDescription(unsigned int _index) const;
208 
212  public: ElementPtr GetElementDescription(const std::string &_key) const;
213 
217  public: bool HasElementDescription(const std::string &_name) const;
218 
222  public: bool HasAttribute(const std::string &_key) const;
223 
227  public: bool GetAttributeSet(const std::string &_key) const;
228 
231  public: ParamPtr GetValue() const;
232 
237  public: std::any GetAny(const std::string &_key = "") const;
238 
245  public: template<typename T>
246  T Get(const std::string &_key = "") const;
247 
254  public: template<typename T>
255  std::pair<T, bool> Get(const std::string &_key,
256  const T &_defaultValue) const;
257 
264  public: template<typename T>
265  bool Get(const std::string &_key,
266  T &_param,
267  const T &_defaultValue) const;
268 
272  public: template<typename T>
273  bool Set(const T &_value);
274 
278  public: bool HasElement(const std::string &_name) const;
279 
283  public: ElementPtr GetFirstElement() const;
284 
296  public: ElementPtr GetNextElement(const std::string &_name = "") const;
297 
300  public: std::set<std::string> GetElementTypeNames() const;
301 
309  public: bool HasUniqueChildNames(const std::string &_type = "") const;
310 
318  public: std::map<std::string, std::size_t>
319  CountNamedElements(const std::string &_type = "") const;
320 
330  public: ElementPtr GetElement(const std::string &_name);
331 
335  public: ElementPtr AddElement(const std::string &_name);
336 
339  public: void InsertElement(ElementPtr _elem);
340 
342  public: void RemoveFromParent();
343 
346  public: void RemoveChild(ElementPtr _child);
347 
349  public: void ClearElements();
350 
353  public: void Clear();
354 
357  public: void Update();
358 
362  public: void Reset();
363 
366  public: void SetInclude(const std::string &_filename);
367 
370  public: std::string GetInclude() const;
371 
374  public: void SetFilePath(const std::string &_path);
375 
378  public: const std::string &FilePath() const;
379 
382  public: void SetOriginalVersion(const std::string &_version);
383 
386  public: const std::string &OriginalVersion() const;
387 
390  public: std::string GetDescription() const;
391 
394  public: void SetDescription(const std::string &_desc);
395 
398  public: void AddElementDescription(ElementPtr _elem);
399 
403  public: ElementPtr GetElementImpl(const std::string &_name) const;
404 
408  private: void ToString(const std::string &_prefix,
409  std::ostringstream &_out) const;
410 
414  private: void PrintValuesImpl(const std::string &_prefix,
415  std::ostringstream &_out) const;
416 
425  private: ParamPtr CreateParam(const std::string &_key,
426  const std::string &_type,
427  const std::string &_defaultValue,
428  bool _required,
429  const std::string &_description="");
430 
431 
433  private: std::unique_ptr<ElementPrivate> dataPtr;
434  };
435 
439  {
441  public: std::string name;
442 
444  public: std::string required;
445 
447  public: std::string description;
448 
450  public: bool copyChildren;
451 
454 
455  // Attributes of this element
457 
458  // Value of this element
459  public: ParamPtr value;
460 
461  // The existing child elements
463 
464  // The possible child elements
466 
468  public: std::string includeFilename;
469 
471  public: std::string referenceSDF;
472 
474  public: std::string path;
475 
477  public: std::string originalVersion;
478  };
479 
481  template<typename T>
482  T Element::Get(const std::string &_key) const
483  {
484  T result = T();
485 
486  std::pair<T, bool> ret = this->Get<T>(_key, result);
487 
488  return ret.first;
489  }
490 
492  template<typename T>
493  bool Element::Get(const std::string &_key,
494  T &_param,
495  const T &_defaultValue) const
496  {
497  std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
498  _param = ret.first;
499  return ret.second;
500  }
501 
503  template<typename T>
504  std::pair<T, bool> Element::Get(const std::string &_key,
505  const T &_defaultValue) const
506  {
507  std::pair<T, bool> result(_defaultValue, true);
508 
509  if (_key.empty() && this->dataPtr->value)
510  {
511  this->dataPtr->value->Get<T>(result.first);
512  }
513  else if (!_key.empty())
514  {
515  ParamPtr param = this->GetAttribute(_key);
516  if (param)
517  {
518  param->Get(result.first);
519  }
520  else if (this->HasElement(_key))
521  {
522  result.first = this->GetElementImpl(_key)->Get<T>();
523  }
524  else if (this->HasElementDescription(_key))
525  {
526  result.first = this->GetElementDescription(_key)->Get<T>();
527  }
528  else
529  {
530  result.second = false;
531  }
532  }
533  else
534  {
535  result.second = false;
536  }
537 
538  return result;
539  }
540 
542  template<typename T>
543  bool Element::Set(const T &_value)
544  {
545  if (this->dataPtr->value)
546  {
547  this->dataPtr->value->Set(_value);
548  return true;
549  }
550  return false;
551  }
553  }
554 }
555 
556 #ifdef _WIN32
557 #pragma warning(pop)
558 #endif
559 
560 #endif
sdf::v9::ElementPrivate::elements
ElementPtr_V elements
Definition: Element.hh:462
sdf::v9::Element::GetName
const std::string & GetName() const
Get the Element's name.
sdf::v9::Element::GetElement
ElementPtr GetElement(const std::string &_name)
Return a pointer to the child element with the provided name.
sdf::v9::Element::Reset
void Reset()
Call reset on each element and element description before deleting all of them.
sdf::v9::Element::RemoveChild
void RemoveChild(ElementPtr _child)
Remove a child element.
sdf::v9::Element::Update
void Update()
Call the Update() callback on each element, as well as the embedded Param.
sdf::v9::Element::GetValue
ParamPtr GetValue() const
Get the param of the elements value return A Param pointer to the value of this element.
sdf::v9::ElementPrivate::name
std::string name
Element name.
Definition: Element.hh:441
sdf::v9::ElementPrivate::originalVersion
std::string originalVersion
Spec version that this was originally parsed from.
Definition: Element.hh:477
sdf::v9::Element::AddElement
ElementPtr AddElement(const std::string &_name)
Add a named element.
sdf::v9::Element::GetParent
ElementPtr GetParent() const
Get a pointer to this Element's parent.
sdf
namespace for Simulation Description Format parser
Definition: Actor.hh:33
sdf::v9::Element::OriginalVersion
const std::string & OriginalVersion() const
Get the spec version that this was originally parsed from.
sdf::v9::Element::GetElementDescription
ElementPtr GetElementDescription(unsigned int _index) const
Get an element description using an index.
sdf::v9::Element::AddElementDescription
void AddElementDescription(ElementPtr _elem)
Add a new element description.
sdf::v9::Element::GetAttribute
ParamPtr GetAttribute(const std::string &_key) const
Get the param of an attribute.
sdf::v9::Element::GetCopyChildren
bool GetCopyChildren() const
Return true if this Element's child elements should be copied during parsing.
sdf::v9::Element::GetAttribute
ParamPtr GetAttribute(unsigned int _index) const
Get an attribute using an index.
sdf::v9::Element::InsertElement
void InsertElement(ElementPtr _elem)
Add an element object.
sdf::v9::ElementWeakPtr
std::weak_ptr< Element > ElementWeakPtr
Definition: Element.hh:57
sdf::v9::ElementPrivate::value
ParamPtr value
Definition: Element.hh:459
sdf::v9::Element::SetName
void SetName(const std::string &_name)
Set the name of the Element.
sdf::v9::Element::AddAttribute
void AddAttribute(const std::string &_key, const std::string &_type, const std::string &_defaultvalue, bool _required, const std::string &_description="")
Add an attribute value.
sdf::v9::Element::SetRequired
void SetRequired(const std::string &_req)
Set the requirement type.
sdf::v9::Element::GetAny
std::any GetAny(const std::string &_key="") const
Get the element value/attribute as a std::any.
sdf::v9::Element::SetInclude
void SetInclude(const std::string &_filename)
Set the include filename to the passed in filename.
sdf::v9::Element::SetCopyChildren
void SetCopyChildren(bool _value)
Set whether this element should copy its child elements during parsing.
sdf::v9::Element::CountNamedElements
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...
Types.hh
sdf::v9::Element::GetRequired
const std::string & GetRequired() const
Get the requirement string.
sdf::v9::ElementPrivate
Definition: Element.hh:439
sdf::v9::Element::GetNextElement
ElementPtr GetNextElement(const std::string &_name="") const
Get the next sibling of this element.
sdf::v9::Element::Element
Element()
Constructor.
sdf::v9::ParamPtr
std::shared_ptr< Param > ParamPtr
Definition: Param.hh:57
sdf::v9::Element::Clone
ElementPtr Clone() const
Create a copy of this Element.
SDFORMAT_VISIBLE
#define SDFORMAT_VISIBLE
Definition: system_util.hh:48
sdf::v9::Element::SetFilePath
void SetFilePath(const std::string &_path)
Set the path to the SDF document where this element came from.
sdf::v9::ElementPrivate::copyChildren
bool copyChildren
True if element's children should be copied.
Definition: Element.hh:450
sdf::v9::ElementPrivate::path
std::string path
Path to file where this element came from.
Definition: Element.hh:474
sdf::v9::Param_V
std::vector< ParamPtr > Param_V
Definition: Param.hh:61
sdf::v9::Element::Clear
void Clear()
Remove all child elements and reset file path and original version.
sdf::v9::Element::RemoveFromParent
void RemoveFromParent()
Remove this element from its parent.
sdf::v9::Element::HasElementDescription
bool HasElementDescription(const std::string &_name) const
Return true if an element description exists.
sdf::v9::Element::PrintDocRightPane
void PrintDocRightPane(std::string &_html, int _spacing, int &_index) const
Helper function for SDF::PrintDoc.
sdf::v9::Element::GetFirstElement
ElementPtr GetFirstElement() const
Get the first child element.
sdf::v9::Element::AddValue
void AddValue(const std::string &_type, const std::string &_defaultValue, bool _required, const std::string &_description="")
Add a value to this Element.
sdf::v9::Element::~Element
virtual ~Element()
Destructor.
sdf::v9::Element::GetAttributeSet
bool GetAttributeSet(const std::string &_key) const
Return true if the attribute was set (i.e.
Param.hh
sdf::v9::ElementPrivate::parent
ElementWeakPtr parent
Element's parent.
Definition: Element.hh:453
sdf::v9::Element::ToString
std::string ToString(const std::string &_prefix) const
Convert the element values to a string representation.
sdf::v9::ElementPrivate::required
std::string required
True if element is required.
Definition: Element.hh:444
sdf::v9::Element::ReferenceSDF
std::string ReferenceSDF() const
Get the name of the reference SDF element.
sdf::v9::Element::GetAttributeCount
size_t GetAttributeCount() const
Get the number of attributes.
sdf::v9::Element::GetDescription
std::string GetDescription() const
Get a text description of the element.
sdf::v9::ElementPrivate::description
std::string description
Element description.
Definition: Element.hh:447
sdf::v9::Element::PrintValues
void PrintValues(std::string _prefix) const
Output Element's values to stdout.
sdf::v9::Element::GetInclude
std::string GetInclude() const
Get the include filename.
sdf::v9::Element::PrintDescription
void PrintDescription(const std::string &_prefix) const
Output Element's description to stdout.
sdf::v9::Element
SDF Element class.
Definition: Element.hh:70
sdf::v9::Element::ClearElements
void ClearElements()
Remove all child elements.
sdf::v9::Element::HasUniqueChildNames
bool HasUniqueChildNames(const std::string &_type="") const
Checks whether any child elements of the specified element type have identical name attribute values ...
sdf::v9::ElementPrivate::attributes
Param_V attributes
Definition: Element.hh:456
sdf::v9::ElementPrivate::referenceSDF
std::string referenceSDF
Name of reference sdf.
Definition: Element.hh:471
sdf::v9::ElementPtr
std::shared_ptr< Element > ElementPtr
Definition: Element.hh:53
sdf::v9::Element::SetOriginalVersion
void SetOriginalVersion(const std::string &_version)
Set the spec version that this was originally parsed from.
sdf::v9::ElementPrivate::includeFilename
std::string includeFilename
name of the include file that was used to create this element
Definition: Element.hh:468
sdf::v9::Element::GetElementImpl
ElementPtr GetElementImpl(const std::string &_name) const
Get a pointer to the named element.
sdf::v9::Element::SetDescription
void SetDescription(const std::string &_desc)
Set a text description for the element.
sdf::v9::ElementPrivate::elementDescriptions
ElementPtr_V elementDescriptions
Definition: Element.hh:465
sdf::v9::Element::SetReferenceSDF
void SetReferenceSDF(const std::string &_value)
Set reference SDF element.
sdf::v9::Element::Copy
void Copy(const ElementPtr _elem)
Copy values from an Element.
sdf::v9::Element::HasAttribute
bool HasAttribute(const std::string &_key) const
Return true if an attribute exists.
system_util.hh
sdf::v9::Element::PrintDocLeftPane
void PrintDocLeftPane(std::string &_html, int _spacing, int &_index) const
Helper function for SDF::PrintDoc.
sdf::v9::Element::SetParent
void SetParent(const ElementPtr _parent)
Set the parent of this Element.
sdf::v9::Element::GetElementTypeNames
std::set< std::string > GetElementTypeNames() const
Get set of child element type names.
sdf::v9::Element::GetElementDescription
ElementPtr GetElementDescription(const std::string &_key) const
Get an element description using a key.
sdf::v9::Element::GetElementDescriptionCount
size_t GetElementDescriptionCount() const
Get the number of element descriptions.
sdf::v9::Element::HasElement
bool HasElement(const std::string &_name) const
Return true if the named element exists.
sdf::v9::ElementPtr_V
std::vector< ElementPtr > ElementPtr_V
Definition: Element.hh:61
sdf::v9::Element::FilePath
const std::string & FilePath() const
Get the path to the SDF document where this element came from.