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 
113  public: void SetRequired(const std::string &_req);
114 
118  public: const std::string &GetRequired() const;
119 
125  public: void SetExplicitlySetInFile(const bool _value);
126 
129  public: bool GetExplicitlySetInFile() const;
130 
134  public: void SetCopyChildren(bool _value);
135 
139  public: bool GetCopyChildren() const;
140 
143  public: void SetReferenceSDF(const std::string &_value);
144 
147  public: std::string ReferenceSDF() const;
148 
151  public: void PrintDescription(const std::string &_prefix) const;
152 
155  public: void PrintValues(std::string _prefix) const;
156 
161  public: void PrintValues(const std::string &_prefix,
162  bool _includeDefaultElements,
163  bool _includeDefaultAttributes) const;
164 
171  public: void PrintDocLeftPane(std::string &_html,
172  int _spacing, int &_index) const;
173 
179  public: void PrintDocRightPane(std::string &_html,
180  int _spacing, int &_index) const;
181 
185  public: std::string ToString(const std::string &_prefix) const;
186 
195  public: std::string ToString(const std::string &_prefix,
196  bool _includeDefaultElements,
197  bool _includeDefaultAttributes) const;
198 
206  public: void AddAttribute(const std::string &_key,
207  const std::string &_type,
208  const std::string &_defaultvalue,
209  bool _required,
210  const std::string &_description = "");
211 
218  public: void AddValue(const std::string &_type,
219  const std::string &_defaultValue, bool _required,
220  const std::string &_description = "");
221 
231  public: void AddValue(const std::string &_type,
232  const std::string &_defaultValue, bool _required,
233  const std::string &_minValue,
234  const std::string &_maxValue,
235  const std::string &_description = "");
236 
240  public: ParamPtr GetAttribute(const std::string &_key) const;
241 
244  public: size_t GetAttributeCount() const;
245 
249  public: ParamPtr GetAttribute(unsigned int _index) const;
250 
253  public: size_t GetElementDescriptionCount() const;
254 
258  public: ElementPtr GetElementDescription(unsigned int _index) const;
259 
263  public: ElementPtr GetElementDescription(const std::string &_key) const;
264 
268  public: bool HasElementDescription(const std::string &_name) const;
269 
273  public: bool HasAttribute(const std::string &_key) const;
274 
278  public: bool GetAttributeSet(const std::string &_key) const;
279 
282  public: void RemoveAttribute(const std::string &_key);
283 
285  public: void RemoveAllAttributes();
286 
289  public: ParamPtr GetValue() const;
290 
295  public: std::any GetAny(const std::string &_key = "") const;
296 
303  public: template<typename T>
304  T Get(const std::string &_key = "") const;
305 
312  public: template<typename T>
313  std::pair<T, bool> Get(const std::string &_key,
314  const T &_defaultValue) const;
315 
322  public: template<typename T>
323  bool Get(const std::string &_key,
324  T &_param,
325  const T &_defaultValue) const;
326 
330  public: template<typename T>
331  bool Set(const T &_value);
332 
336  public: bool HasElement(const std::string &_name) const;
337 
341  public: ElementPtr GetFirstElement() const;
342 
354  public: ElementPtr GetNextElement(const std::string &_name = "") const;
355 
358  public: std::set<std::string> GetElementTypeNames() const;
359 
367  public: bool HasUniqueChildNames(const std::string &_type = "") const;
368 
379  public: bool HasUniqueChildNames(
380  const std::string &_type,
381  const std::vector<std::string> &_ignoreElements) const;
382 
390  public: std::map<std::string, std::size_t>
391  CountNamedElements(const std::string &_type = "") const;
392 
403  public: std::map<std::string, std::size_t> CountNamedElements(
404  const std::string &_type,
405  const std::vector<std::string> &_ignoreElements) const;
406 
417  public: ElementPtr GetElement(const std::string &_name);
418 
428  public: ElementPtr FindElement(const std::string &_name);
429 
439  public: ElementConstPtr FindElement(const std::string &_name) const;
440 
444  public: ElementPtr AddElement(const std::string &_name);
445 
448  public: void InsertElement(ElementPtr _elem);
449 
451  public: void RemoveFromParent();
452 
455  public: void RemoveChild(ElementPtr _child);
456 
458  public: void ClearElements();
459 
462  public: void Clear();
463 
466  public: void Update();
467 
471  public: void Reset();
472 
475  public: void SetInclude(const std::string &_filename) SDF_DEPRECATED(11.0);
476 
479  public: std::string GetInclude() const SDF_DEPRECATED(11.0);
480 
486  public: void SetIncludeElement(sdf::ElementPtr _includeElem);
487 
492  public: sdf::ElementPtr GetIncludeElement() const;
493 
496  public: void SetFilePath(const std::string &_path);
497 
500  public: const std::string &FilePath() const;
501 
504  public: void SetLineNumber(int _lineNumber);
505 
509  public: std::optional<int> LineNumber() const;
510 
525  public: void SetXmlPath(const std::string &_path);
526 
529  public: const std::string &XmlPath() const;
530 
533  public: void SetOriginalVersion(const std::string &_version);
534 
537  public: const std::string &OriginalVersion() const;
538 
541  public: std::string GetDescription() const;
542 
545  public: void SetDescription(const std::string &_desc);
546 
549  public: void AddElementDescription(ElementPtr _elem);
550 
554  public: ElementPtr GetElementImpl(const std::string &_name) const;
555 
559  public: static std::vector<std::string> NameUniquenessExceptions();
560 
566  private: void ToString(const std::string &_prefix,
567  bool _includeDefaultElements,
568  bool _includeDefaultAttributes,
569  std::ostringstream &_out) const;
570 
576  private: void PrintValuesImpl(const std::string &_prefix,
577  bool _includeDefaultElements,
578  bool _includeDefaultAttributes,
579  std::ostringstream &_out) const;
580 
589  private: ParamPtr CreateParam(const std::string &_key,
590  const std::string &_type,
591  const std::string &_defaultValue,
592  bool _required,
593  const std::string &_description = "");
594 
595 
597  private: std::unique_ptr<ElementPrivate> dataPtr;
598  };
599 
603  {
605  public: std::string name;
606 
608  public: std::string required;
609 
611  public: std::string description;
612 
614  public: bool copyChildren;
615 
617  public: ElementWeakPtr parent;
618 
619  // Attributes of this element
621 
622  // Value of this element
623  public: ParamPtr value;
624 
625  // The existing child elements
626  public: ElementPtr_V elements;
627 
628  // The possible child elements
629  public: ElementPtr_V elementDescriptions;
630 
651  public: ElementPtr includeElement;
652 
654  public: std::string includeFilename;
655 
657  public: std::string referenceSDF;
658 
660  public: std::string path;
661 
663  public: std::string originalVersion;
664 
666  public: bool explicitlySetInFile;
667 
669  public: std::optional<int> lineNumber;
670 
672  public: std::string xmlPath;
673  };
674 
676  template<typename T>
677  T Element::Get(const std::string &_key) const
678  {
679  T result = T();
680 
681  std::pair<T, bool> ret = this->Get<T>(_key, result);
682 
683  return ret.first;
684  }
685 
687  template<typename T>
688  bool Element::Get(const std::string &_key,
689  T &_param,
690  const T &_defaultValue) const
691  {
692  std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
693  _param = ret.first;
694  return ret.second;
695  }
696 
698  template<typename T>
699  std::pair<T, bool> Element::Get(const std::string &_key,
700  const T &_defaultValue) const
701  {
702  std::pair<T, bool> result(_defaultValue, true);
703 
704  if (_key.empty() && this->dataPtr->value)
705  {
706  this->dataPtr->value->Get<T>(result.first);
707  }
708  else if (!_key.empty())
709  {
710  ParamPtr param = this->GetAttribute(_key);
711  if (param)
712  {
713  param->Get(result.first);
714  }
715  else if (this->HasElement(_key))
716  {
717  result.first = this->GetElementImpl(_key)->Get<T>();
718  }
719  else if (this->HasElementDescription(_key))
720  {
721  result.first = this->GetElementDescription(_key)->Get<T>();
722  }
723  else
724  {
725  result.second = false;
726  }
727  }
728  else
729  {
730  result.second = false;
731  }
732 
733  return result;
734  }
735 
737  template<typename T>
738  bool Element::Set(const T &_value)
739  {
740  if (this->dataPtr->value)
741  {
742  this->dataPtr->value->Set(_value);
743  return true;
744  }
745  return false;
746  }
748  }
749 }
750 
751 #ifdef _WIN32
752 #pragma warning(pop)
753 #endif
754 
755 #endif
std::string required
True if element is required.
Definition: Element.hh:608
std::string includeFilename
name of the include file that was used to create this element
Definition: Element.hh:654
std::shared_ptr< Param > ParamPtr
Definition: Param.hh:60
std::string name
Element name.
Definition: Element.hh:605
std::vector< ElementPtr > ElementPtr_V
Definition: Element.hh:65
std::vector< ParamPtr > Param_V
Definition: Param.hh:64
Param_V attributes
Definition: Element.hh:620
ParamPtr value
Definition: Element.hh:623
std::shared_ptr< Element > ElementPtr
Definition: Element.hh:53
std::weak_ptr< Element > ElementWeakPtr
Definition: Element.hh:61
ElementPtr includeElement
The element that was used to load this entity.
Definition: Element.hh:651
std::string path
Path to file where this element came from.
Definition: Element.hh:660
std::string xmlPath
XML path of this element.
Definition: Element.hh:672
ElementPtr_V elementDescriptions
Definition: Element.hh:629
std::optional< int > lineNumber
Line number in file where this element came from.
Definition: Element.hh:669
bool Set(const T &_value)
Set the value of this element.
Definition: Element.hh:738
std::string referenceSDF
Name of reference sdf.
Definition: Element.hh:657
std::string description
Element description.
Definition: Element.hh:611
#define SDFORMAT_VISIBLE
Use to represent "symbol visible" if supported.
Definition: system_util.hh:25
bool copyChildren
True if element&#39;s children should be copied.
Definition: Element.hh:614
class SDFORMAT_VISIBLE Element
Definition: Element.hh:49
std::string originalVersion
Spec version that this was originally parsed from.
Definition: Element.hh:663
ElementWeakPtr parent
Element&#39;s parent.
Definition: Element.hh:617
T Get(const std::string &_key="") const
Get the value of a key.
Definition: Element.hh:677
SDF Element class.
Definition: Element.hh:72
namespace for Simulation Description Format parser
Definition: Actor.hh:33
ElementPtr_V elements
Definition: Element.hh:626
bool explicitlySetInFile
True if the element was set in the SDF file.
Definition: Element.hh:666
#define SDF_DEPRECATED(version)
Definition: Types.hh:39
std::shared_ptr< const Element > ElementConstPtr
Definition: Element.hh:57