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 
506  public: sdf::ElementPtr GetIncludeElement() const;
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
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::elements
ElementPtr_V elements
Definition: Element.hh:644
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::path
std::string path
Path to file where this element came from.
Definition: Element.hh:675
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::includeElement
ElementPtr includeElement
The element that was used to load this entity.
Definition: Element.hh:669
sdf::SDF_VERSION_NAMESPACE::Element
SDF Element class.
Definition: Element.hh:73
sdf::SDF_VERSION_NAMESPACE::Element::GetAttribute
ParamPtr GetAttribute(const std::string &_key) const
Get the param of an attribute.
sdf
namespace for Simulation Description Format parser
Definition: Actor.hh:34
PrintConfig.hh
sdf::SDF_VERSION_NAMESPACE::Element
class IGNITION_SDFORMAT_VISIBLE Element
Definition: Element.hh:50
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::lineNumber
std::optional< int > lineNumber
Line number in file where this element came from.
Definition: Element.hh:684
sdf::SDF_VERSION_NAMESPACE::PrintConfig
This class contains configuration options for printing elements.
Definition: PrintConfig.hh:31
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::referenceSDF
std::string referenceSDF
Name of reference sdf.
Definition: Element.hh:672
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::originalVersion
std::string originalVersion
Spec version that this was originally parsed from.
Definition: Element.hh:678
sdf::SDF_VERSION_NAMESPACE::ElementConstPtr
std::shared_ptr< const Element > ElementConstPtr
Definition: Element.hh:58
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::name
std::string name
Element name.
Definition: Element.hh:623
Types.hh
sdf_config.h
sdf::SDF_VERSION_NAMESPACE::ParamPtr
std::shared_ptr< Param > ParamPtr
Definition: Param.hh:65
SDFORMAT_VISIBLE
#define SDFORMAT_VISIBLE
Definition: system_util.hh:25
sdf::SDF_VERSION_NAMESPACE::Element::HasElement
bool HasElement(const std::string &_name) const
Return true if the named element exists.
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::description
std::string description
Element description.
Definition: Element.hh:629
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::value
ParamPtr value
Definition: Element.hh:641
sdf::SDF_VERSION_NAMESPACE::Element::Get
T Get(const std::string &_key="") const
Get the value of a key.
Definition: Element.hh:700
Param.hh
sdf::SDF_VERSION_NAMESPACE::Element::GetElementDescription
ElementPtr GetElementDescription(unsigned int _index) const
Get an element description using an index.
sdf::SDF_VERSION_NAMESPACE::Element::GetElementImpl
ElementPtr GetElementImpl(const std::string &_name) const
Get a pointer to the named element.
sdf::SDF_VERSION_NAMESPACE::Element::HasElementDescription
bool HasElementDescription(const std::string &_name) const
Return true if an element description exists.
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::elementDescriptions
ElementPtr_V elementDescriptions
Definition: Element.hh:647
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::copyChildren
bool copyChildren
True if element's children should be copied.
Definition: Element.hh:632
sdf::SDF_VERSION_NAMESPACE::ElementPrivate
Definition: Element.hh:620
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::xmlPath
std::string xmlPath
XML path of this element.
Definition: Element.hh:687
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::required
std::string required
True if element is required.
Definition: Element.hh:626
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::attributes
Param_V attributes
Definition: Element.hh:638
sdf::SDF_VERSION_NAMESPACE::ElementPtr_V
std::vector< ElementPtr > ElementPtr_V
Definition: Element.hh:66
sdf::SDF_VERSION_NAMESPACE::ElementWeakPtr
std::weak_ptr< Element > ElementWeakPtr
Definition: Element.hh:62
sdf::SDF_VERSION_NAMESPACE::Element::Set
bool Set(const T &_value)
Set the value of this element.
Definition: Element.hh:761
system_util.hh
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::parent
ElementWeakPtr parent
Element's parent.
Definition: Element.hh:635
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::PrintAttributes
void PrintAttributes(bool _includeDefaultAttributes, const PrintConfig &_config, std::ostringstream &_out) const
Generate the string (XML) for the attributes.
sdf::SDF_VERSION_NAMESPACE::ElementPtr
std::shared_ptr< Element > ElementPtr
Definition: Element.hh:54
sdf::SDF_VERSION_NAMESPACE::ElementPrivate::explicitlySetInFile
bool explicitlySetInFile
True if the element was set in the SDF file.
Definition: Element.hh:681
sdf::SDF_VERSION_NAMESPACE::Param_V
std::vector< ParamPtr > Param_V
Definition: Param.hh:69