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::shared_ptr<const Element> ElementConstPtr;
58 
61  typedef std::weak_ptr<Element> ElementWeakPtr;
62 
65  typedef std::vector<ElementPtr> ElementPtr_V;
66 
69 
73  public std::enable_shared_from_this<Element>
74  {
76  public: Element();
77 
79  public: virtual ~Element();
80 
83  public: ElementPtr Clone() const;
84 
87  public: void Copy(const ElementPtr _elem);
88 
92  public: ElementPtr GetParent() const;
93 
96  public: void SetParent(const ElementPtr _parent);
97 
100  public: void SetName(const std::string &_name);
101 
104  public: const std::string &GetName() const;
105 
112  public: void SetRequired(const std::string &_req);
113 
117  public: const std::string &GetRequired() const;
118 
124  public: void SetExplicitlySetInFile(const bool _value);
125 
128  public: bool GetExplicitlySetInFile() const;
129 
133  public: void SetCopyChildren(bool _value);
134 
138  public: bool GetCopyChildren() const;
139 
142  public: void SetReferenceSDF(const std::string &_value);
143 
146  public: std::string ReferenceSDF() const;
147 
150  public: void PrintDescription(const std::string &_prefix) const;
151 
154  public: void PrintValues(std::string _prefix) const;
155 
160  public: void PrintValues(const std::string &_prefix,
161  bool _includeDefaultElements,
162  bool _includeDefaultAttributes) const;
163 
170  public: void PrintDocLeftPane(std::string &_html,
171  int _spacing, int &_index) const;
172 
178  public: void PrintDocRightPane(std::string &_html,
179  int _spacing, int &_index) const;
180 
184  public: std::string ToString(const std::string &_prefix) const;
185 
194  public: std::string ToString(const std::string &_prefix,
195  bool _includeDefaultElements,
196  bool _includeDefaultAttributes) const;
197 
205  public: void AddAttribute(const std::string &_key,
206  const std::string &_type,
207  const std::string &_defaultvalue,
208  bool _required,
209  const std::string &_description = "");
210 
217  public: void AddValue(const std::string &_type,
218  const std::string &_defaultValue, bool _required,
219  const std::string &_description = "");
220 
224  public: ParamPtr GetAttribute(const std::string &_key) const;
225 
228  public: size_t GetAttributeCount() const;
229 
233  public: ParamPtr GetAttribute(unsigned int _index) const;
234 
237  public: size_t GetElementDescriptionCount() const;
238 
242  public: ElementPtr GetElementDescription(unsigned int _index) const;
243 
247  public: ElementPtr GetElementDescription(const std::string &_key) const;
248 
252  public: bool HasElementDescription(const std::string &_name) const;
253 
257  public: bool HasAttribute(const std::string &_key) const;
258 
262  public: bool GetAttributeSet(const std::string &_key) const;
263 
266  public: void RemoveAttribute(const std::string &_key);
267 
269  public: void RemoveAllAttributes();
270 
273  public: ParamPtr GetValue() const;
274 
279  public: std::any GetAny(const std::string &_key = "") const;
280 
287  public: template<typename T>
288  T Get(const std::string &_key = "") const;
289 
296  public: template<typename T>
297  std::pair<T, bool> Get(const std::string &_key,
298  const T &_defaultValue) const;
299 
306  public: template<typename T>
307  bool Get(const std::string &_key,
308  T &_param,
309  const T &_defaultValue) const;
310 
314  public: template<typename T>
315  bool Set(const T &_value);
316 
320  public: bool HasElement(const std::string &_name) const;
321 
325  public: ElementPtr GetFirstElement() const;
326 
338  public: ElementPtr GetNextElement(const std::string &_name = "") const;
339 
342  public: std::set<std::string> GetElementTypeNames() const;
343 
351  public: bool HasUniqueChildNames(const std::string &_type = "") const;
352 
360  public: std::map<std::string, std::size_t>
361  CountNamedElements(const std::string &_type = "") const;
362 
373  public: ElementPtr GetElement(const std::string &_name);
374 
384  public: ElementPtr FindElement(const std::string &_name);
385 
395  public: ElementConstPtr FindElement(const std::string &_name) const;
396 
400  public: ElementPtr AddElement(const std::string &_name);
401 
404  public: void InsertElement(ElementPtr _elem);
405 
407  public: void RemoveFromParent();
408 
411  public: void RemoveChild(ElementPtr _child);
412 
414  public: void ClearElements();
415 
418  public: void Clear();
419 
422  public: void Update();
423 
427  public: void Reset();
428 
431  public: void SetInclude(const std::string &_filename);
432 
435  public: std::string GetInclude() const;
436 
439  public: void SetFilePath(const std::string &_path);
440 
443  public: const std::string &FilePath() const;
444 
447  public: void SetOriginalVersion(const std::string &_version);
448 
451  public: const std::string &OriginalVersion() const;
452 
455  public: std::string GetDescription() const;
456 
459  public: void SetDescription(const std::string &_desc);
460 
463  public: void AddElementDescription(ElementPtr _elem);
464 
468  public: ElementPtr GetElementImpl(const std::string &_name) const;
469 
475  private: void ToString(const std::string &_prefix,
476  bool _includeDefaultElements,
477  bool _includeDefaultAttributes,
478  std::ostringstream &_out) const;
479 
485  private: void PrintValuesImpl(const std::string &_prefix,
486  bool _includeDefaultElements,
487  bool _includeDefaultAttributes,
488  std::ostringstream &_out) const;
489 
498  private: ParamPtr CreateParam(const std::string &_key,
499  const std::string &_type,
500  const std::string &_defaultValue,
501  bool _required,
502  const std::string &_description = "");
503 
504 
506  private: std::unique_ptr<ElementPrivate> dataPtr;
507  };
508 
512  {
514  public: std::string name;
515 
517  public: std::string required;
518 
520  public: std::string description;
521 
523  public: bool copyChildren;
524 
527 
528  // Attributes of this element
530 
531  // Value of this element
532  public: ParamPtr value;
533 
534  // The existing child elements
536 
537  // The possible child elements
539 
541  public: std::string includeFilename;
542 
544  public: std::string referenceSDF;
545 
547  public: std::string path;
548 
550  public: std::string originalVersion;
551 
553  public: bool explicitlySetInFile;
554  };
555 
557  template<typename T>
558  T Element::Get(const std::string &_key) const
559  {
560  T result = T();
561 
562  std::pair<T, bool> ret = this->Get<T>(_key, result);
563 
564  return ret.first;
565  }
566 
568  template<typename T>
569  bool Element::Get(const std::string &_key,
570  T &_param,
571  const T &_defaultValue) const
572  {
573  std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
574  _param = ret.first;
575  return ret.second;
576  }
577 
579  template<typename T>
580  std::pair<T, bool> Element::Get(const std::string &_key,
581  const T &_defaultValue) const
582  {
583  std::pair<T, bool> result(_defaultValue, true);
584 
585  if (_key.empty() && this->dataPtr->value)
586  {
587  this->dataPtr->value->Get<T>(result.first);
588  }
589  else if (!_key.empty())
590  {
591  ParamPtr param = this->GetAttribute(_key);
592  if (param)
593  {
594  param->Get(result.first);
595  }
596  else if (this->HasElement(_key))
597  {
598  result.first = this->GetElementImpl(_key)->Get<T>();
599  }
600  else if (this->HasElementDescription(_key))
601  {
602  result.first = this->GetElementDescription(_key)->Get<T>();
603  }
604  else
605  {
606  result.second = false;
607  }
608  }
609  else
610  {
611  result.second = false;
612  }
613 
614  return result;
615  }
616 
618  template<typename T>
619  bool Element::Set(const T &_value)
620  {
621  if (this->dataPtr->value)
622  {
623  this->dataPtr->value->Set(_value);
624  return true;
625  }
626  return false;
627  }
629  }
630 }
631 
632 #ifdef _WIN32
633 #pragma warning(pop)
634 #endif
635 
636 #endif
Definition: Element.hh:512
std::string required
True if element is required.
Definition: Element.hh:517
ElementWeakPtr parent
Element's parent.
Definition: Element.hh:526
bool copyChildren
True if element's children should be copied.
Definition: Element.hh:523
Param_V attributes
Definition: Element.hh:529
ElementPtr_V elements
Definition: Element.hh:535
std::string referenceSDF
Name of reference sdf.
Definition: Element.hh:544
bool explicitlySetInFile
True if the element was set in the SDF file.
Definition: Element.hh:553
ElementPtr_V elementDescriptions
Definition: Element.hh:538
std::string description
Element description.
Definition: Element.hh:520
std::string name
Element name.
Definition: Element.hh:514
std::string originalVersion
Spec version that this was originally parsed from.
Definition: Element.hh:550
ParamPtr value
Definition: Element.hh:532
std::string path
Path to file where this element came from.
Definition: Element.hh:547
std::string includeFilename
name of the include file that was used to create this element
Definition: Element.hh:541
SDF Element class.
Definition: Element.hh:74
void AddAttribute(const std::string &_key, const std::string &_type, const std::string &_defaultvalue, bool _required, const std::string &_description="")
Add an attribute value.
Element()
Constructor.
void RemoveAllAttributes()
Removes all attributes.
void PrintValues(std::string _prefix) const
Output Element's values to stdout.
void Update()
Call the Update() callback on each element, as well as the embedded Param.
ParamPtr GetAttribute(unsigned int _index) const
Get an attribute using an index.
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...
ElementPtr GetElement(const std::string &_name)
Return a pointer to the child element with the provided name.
ElementPtr GetNextElement(const std::string &_name="") const
Get the next sibling of this element.
void Copy(const ElementPtr _elem)
Copy values from an Element.
void AddElementDescription(ElementPtr _elem)
Add a new element description.
void Clear()
Remove all child elements and reset file path and original version.
std::string ReferenceSDF() const
Get the name of the reference SDF element.
const std::string & GetRequired() const
Get the requirement string.
void SetName(const std::string &_name)
Set the name of the Element.
ElementPtr Clone() const
Create a copy of this Element.
ElementPtr FindElement(const std::string &_name)
Return a pointer to the child element with the provided name.
void SetExplicitlySetInFile(const bool _value)
Set if the element and children where set or default in the original file.
ElementPtr GetFirstElement() const
Get the first child element.
bool HasElement(const std::string &_name) const
Return true if the named element exists.
void SetFilePath(const std::string &_path)
Set the path to the SDF document where this element came from.
void RemoveFromParent()
Remove this element from its parent.
ElementPtr GetParent() const
Get a pointer to this Element's parent.
bool HasElementDescription(const std::string &_name) const
Return true if an element description exists.
void SetRequired(const std::string &_req)
Set the requirement type.
ElementPtr GetElementImpl(const std::string &_name) const
Get a pointer to the named element.
bool GetExplicitlySetInFile() const
Return if the element was been explicitly set in the file.
size_t GetElementDescriptionCount() const
Get the number of element descriptions.
void SetInclude(const std::string &_filename)
Set the include filename to the passed in filename.
ParamPtr GetAttribute(const std::string &_key) const
Get the param of an attribute.
std::string GetDescription() const
Get a text description of the element.
ElementPtr GetElementDescription(const std::string &_key) const
Get an element description using a key.
std::string ToString(const std::string &_prefix) const
Convert the element values to a string representation.
void PrintDescription(const std::string &_prefix) const
Output Element's description to stdout.
ElementPtr GetElementDescription(unsigned int _index) const
Get an element description using an index.
void InsertElement(ElementPtr _elem)
Add an element object.
void ClearElements()
Remove all child elements.
void AddValue(const std::string &_type, const std::string &_defaultValue, bool _required, const std::string &_description="")
Add a value to this Element.
void PrintDocRightPane(std::string &_html, int _spacing, int &_index) const
Helper function for SDF::PrintDoc.
void RemoveAttribute(const std::string &_key)
Remove an attribute.
void SetCopyChildren(bool _value)
Set whether this element should copy its child elements during parsing.
std::any GetAny(const std::string &_key="") const
Get the element value/attribute as a std::any.
ParamPtr GetValue() const
Get the param of the elements value return A Param pointer to the value of this element.
virtual ~Element()
Destructor.
const std::string & FilePath() const
Get the path to the SDF document where this element came from.
void SetOriginalVersion(const std::string &_version)
Set the spec version that this was originally parsed from.
const std::string & OriginalVersion() const
Get the spec version that this was originally parsed from.
void SetParent(const ElementPtr _parent)
Set the parent of this Element.
void PrintValues(const std::string &_prefix, bool _includeDefaultElements, bool _includeDefaultAttributes) const
Output Element's values to stdout.
std::string ToString(const std::string &_prefix, bool _includeDefaultElements, bool _includeDefaultAttributes) const
Convert the element values to a string representation.
ElementPtr AddElement(const std::string &_name)
Add a named element.
bool HasUniqueChildNames(const std::string &_type="") const
Checks whether any child elements of the specified element type have identical name attribute values ...
const std::string & GetName() const
Get the Element's name.
bool HasAttribute(const std::string &_key) const
Return true if an attribute exists.
void SetReferenceSDF(const std::string &_value)
Set reference SDF element.
std::string GetInclude() const
Get the include filename.
bool GetCopyChildren() const
Return true if this Element's child elements should be copied during parsing.
std::set< std::string > GetElementTypeNames() const
Get set of child element type names.
void Reset()
Call reset on each element and element description before deleting all of them.
ElementConstPtr FindElement(const std::string &_name) const
Return a pointer to the child element with the provided name.
void RemoveChild(ElementPtr _child)
Remove a child element.
bool GetAttributeSet(const std::string &_key) const
Return true if the attribute was set (i.e.
void SetDescription(const std::string &_desc)
Set a text description for the element.
size_t GetAttributeCount() const
Get the number of attributes.
void PrintDocLeftPane(std::string &_html, int _spacing, int &_index) const
Helper function for SDF::PrintDoc.
std::weak_ptr< Element > ElementWeakPtr
Definition: Element.hh:61
std::shared_ptr< const Element > ElementConstPtr
Definition: Element.hh:57
std::shared_ptr< Param > ParamPtr
Definition: Param.hh:57
std::vector< ElementPtr > ElementPtr_V
Definition: Element.hh:65
std::shared_ptr< Element > ElementPtr
Definition: Element.hh:53
std::vector< ParamPtr > Param_V
Definition: Param.hh:61
namespace for Simulation Description Format parser
Definition: Actor.hh:33
#define SDFORMAT_VISIBLE
Use to represent "symbol visible" if supported.
Definition: system_util.hh:48