/usr/include/sdformat-6.0/sdf/Element.hh is in libsdformat6-dev 6.0.0+dfsg-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 | /*
* Copyright 2015 Open Source Robotics Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/
#ifndef _SDF_ELEMENT_HH_
#define _SDF_ELEMENT_HH_
#include <memory>
#include <string>
#include <utility>
#include <vector>
#include "sdf/Param.hh"
#include "sdf/system_util.hh"
#include "sdf/Types.hh"
#ifdef _WIN32
// Disable warning C4251 which is triggered by
// std::enable_shared_from_this
#pragma warning(push)
#pragma warning(disable: 4251)
#endif
/// \ingroup sdf_parser
/// \brief namespace for Simulation Description Format parser
namespace sdf
{
class ElementPrivate;
class SDFORMAT_VISIBLE Element;
/// \def ElementPtr
/// \brief Shared pointer to an SDF Element
typedef std::shared_ptr<Element> ElementPtr;
/// \def ElementWeakPtr
/// \brief Weak pointer to an SDF Element
typedef std::weak_ptr<Element> ElementWeakPtr;
/// \def ElementPtr_V
/// \brief Vector of ElementPtr
typedef std::vector<ElementPtr> ElementPtr_V;
/// \addtogroup sdf
/// \{
/// \class Element Element.hh sdf/sdf.hh
/// \brief SDF Element class
class SDFORMAT_VISIBLE Element :
public std::enable_shared_from_this<Element>
{
/// \brief Constructor.
public: Element();
/// \brief Destructor.
public: virtual ~Element();
/// \brief Create a copy of this Element.
/// \return A copy of this Element.
public: ElementPtr Clone() const;
/// \brief Copy values from an Element.
/// \param[in] _elem Element to copy value from.
public: void Copy(const ElementPtr _elem);
/// \brief Get a pointer to this Element's parent.
/// \return Pointer to this Element's parent, NULL if there is no
/// parent.
public: ElementPtr GetParent() const;
/// \brief Set the parent of this Element.
/// \param[in] _parent Paren for this element.
public: void SetParent(const ElementPtr _parent);
/// \brief Set the name of the Element.
/// \param[in] _name The new name for this Element.
public: void SetName(const std::string &_name);
/// \brief Get the Element's name.
/// \return The name of this Element.
public: const std::string &GetName() const;
/// \brief Set the requirement type.
/// \param[in] _req Requirement type for this element:
/// 0: Not required.
/// 1: Exactly one element is required.
/// +: One or more elements are required.
/// *: Zero or more elements are required.
public: void SetRequired(const std::string &_req);
/// \brief Get the requirement string.
/// \return The requirement string.
/// \sa Element::SetRequired
public: const std::string &GetRequired() const;
/// \brief Set whether this element should copy its child elements
/// during parsing.
/// \param[in] _value True to copy Element's children.
public: void SetCopyChildren(bool _value);
/// \brief Return true if this Element's child elements should be copied
/// during parsing.
/// \return True to copy child elements during parsing.
public: bool GetCopyChildren() const;
/// \brief Set reference SDF element.
/// \param[in] _value Name of the reference sdf element.
public: void SetReferenceSDF(const std::string &_value);
/// \brief Get the name of the reference SDF element.
/// \return Name of the reference SDF element.
public: std::string ReferenceSDF() const;
/// \brief Output Element's description to stdout.
/// \param[in] _prefix String value to prefix to the output.
public: void PrintDescription(const std::string &_prefix) const;
/// \brief Output Element's values to stdout.
/// \param[in] _prefix String value to prefix to the output.
public: void PrintValues(std::string _prefix) const;
/// \brief Helper function for SDF::PrintDoc
///
/// This generates the SDF html documentation.
/// \param[out] _html Accumulated HTML for output.
/// \param[in] _spacing Amount of spacing for this element.
/// \param[in] _index Unique index for this element.
public: void PrintDocLeftPane(std::string &_html,
int _spacing, int &_index) const;
/// \brief Helper function for SDF::PrintDoc
///
/// This generates the SDF html documentation.
/// \param[out] _html Accumulated HTML for output.
/// \param[in] _spacing Amount of spacing for this element.
public: void PrintDocRightPane(std::string &_html,
int _spacing, int &_index) const;
/// \brief Convert the element values to a string representation.
/// \param[in] _prefix String value to prefix to the output.
/// \return The string representation.
public: std::string ToString(const std::string &_prefix) const;
/// \brief Add an attribute value.
/// \param[in] _key Key value.
/// \param[in] _type Type of data the attribute will hold.
/// \param[in] _defaultValue Default value for the attribute.
/// \param[in] _required Requirement string. \as Element::SetRequired.
/// \param[in] _description A text description of the attribute.
/// \throws sdf::AssertionInternalError if an invalid type is given.
public: void AddAttribute(const std::string &_key,
const std::string &_type,
const std::string &_defaultvalue,
bool _required,
const std::string &_description="");
/// \brief Add a value to this Element.
/// \param[in] _type Type of data the attribute will hold.
/// \param[in] _defaultValue Default value for the attribute.
/// \param[in] _required Requirement string. \as Element::SetRequired.
/// \param[in] _description A text description of the attribute.
/// \throws sdf::AssertionInternalError if an invalid type is given.
public: void AddValue(const std::string &_type,
const std::string &_defaultValue, bool _required,
const std::string &_description="");
/// \brief Get the param of an attribute.
/// \param[in] _key the name of the attribute.
/// \return The parameter attribute value. NULL if the key is invalid.
public: ParamPtr GetAttribute(const std::string &_key) const;
/// \brief Get the number of attributes.
/// \return The number of attributes.
public: size_t GetAttributeCount() const;
/// \brief Get an attribute using an index.
/// \param[in] _index the index of the attribute to get.
/// \return A Param pointer to the attribute.
public: ParamPtr GetAttribute(unsigned int _index) const;
/// \brief Get the number of element descriptions.
/// \return The number of element descriptions.
public: size_t GetElementDescriptionCount() const;
/// \brief Get an element description using an index
/// \param[in] _index the index of the element description to get.
/// \return An Element pointer to the found element.
public: ElementPtr GetElementDescription(unsigned int _index) const;
/// \brief Get an element description using a key
/// \param[in] _key the key to use to find the element.
/// \return An Element pointer to the found element.
public: ElementPtr GetElementDescription(const std::string &_key) const;
/// \brief Return true if an element description exists.
/// \param[in] _name the name of the element to find.
/// \return True if the element description exists, false otherwise.
public: bool HasElementDescription(const std::string &_name) const;
/// \brief Return true if an attribute exists.
/// \param[in] _key the key to use to find the attribute.
/// \return True if the attribute exists, false otherwise.
public: bool HasAttribute(const std::string &_key) const;
/// \brief Return true if the attribute was set (i.e. not default value)
/// \param[in] _key the key to use to find the attribute.
/// \return True if the attribute is set, false otherwise.
public: bool GetAttributeSet(const std::string &_key) const;
/// \brief Get the param of the elements value
/// return A Param pointer to the value of this element.
public: ParamPtr GetValue() const;
/// \brief Get the element value/attribute as a boost::any.
/// \param[in] _key The key of the attribute. If empty, get the value of
/// the element. Defaults to empty.
/// \return The element as a boost::any.
public: boost::any GetAny(const std::string &_key = "") const;
/// \brief Get the value of a key. This function assumes the _key
/// exists.
/// \param[in] _key the name of a child attribute or element.
/// \return The value of the _key.
/// \sa std::pair<T, bool> Get(const std::string &_key,
/// const T &_defaultValue)
public: template<typename T>
T Get(const std::string &_key = "") const;
/// \brief Get the value of a key.
/// \param[in] _key the name of a child attribute or element.
/// \param[in] _defaultValue a default value to use if _key is not
/// found.
/// \return A pair where the first element is the value of _key, and the
/// second element is true when the _key was found and false otherwise.
public: template<typename T>
std::pair<T, bool> Get(const std::string &_key,
const T &_defaultValue) const;
/// \brief Get the value of a key.
/// \param[in] _key the name of a child attribute or element.
/// \param[out] _param the parameter output
/// \param[in] _defaultValue a default value to use if _key is not
/// found.
/// \return True when the _key was found and false otherwise.
public: template<typename T>
bool Get(const std::string &_key,
T &_param,
const T &_defaultValue) const;
/// \brief Set the value of this element.
/// \param[in] _value the value to set.
/// \return True if the value was successfully set, false otherwise.
public: template<typename T>
bool Set(const T &_value);
/// \brief Return true if the named element exists.
/// \param[in] _name the name of the element to look for.
/// \return True if the named element was found, false otherwise.
public: bool HasElement(const std::string &_name) const;
/// \brief Get the first child element.
/// \return A smart pointer to the first child of this element, or
/// sdf::ElementPtr(nullptr) if there are no children.
public: ElementPtr GetFirstElement() const;
/// \brief Get the next sibling of this element.
/// \param[in] _name if given then filter siblings by their xml tag.
/// \remarks This function does not alter or store any state
/// Repeated calls to "GetNextElement()" with the same string will
/// always return a pointer to the same element.
/// \return A pointer to the next element if it exists,
/// sdf::ElementPtr(nullptr) otherwise.
///
/// This can be used in combination with GetFirstElement() to walk the SDF
/// tree. First call parent->GetFirstElement() to get the first child. Call
/// child = child->GetNextElement() to iterate through the children.
public: ElementPtr GetNextElement(const std::string &_name = "") const;
/// \brief Return a pointer to the child element with the provided name.
///
/// A new child element, with the provided name, is added to this element
/// if there is no existing child element.
/// \remarks If there are multiple elements with the given tag, it returns
/// the first one.
/// \param[in] _name Name of the child element to retreive.
/// \return Pointer to the existing child element, or a new child
/// element if an existing child element did not exist.
public: ElementPtr GetElement(const std::string &_name);
/// \brief Add a named element.
/// \param[in] _name the name of the element to add.
/// \return A pointer to the newly created Element object.
public: ElementPtr AddElement(const std::string &_name);
/// \brief Add an element object.
/// \param[in] _elem the element object to add.
public: void InsertElement(ElementPtr _elem);
/// \brief Remove this element from its parent.
public: void RemoveFromParent();
/// \brief Remove a child element.
/// \param[in] _child Pointer to the child to remove.
public: void RemoveChild(ElementPtr _child);
/// \brief Remove all child elements.
public: void ClearElements();
/// \brief Call the Update() callback on each element, as well as
/// the embedded Param.
public: void Update();
/// \brief Call reset on each element and element description
/// before deleting all of them. Also clear out the
/// embedded Param.
public: void Reset();
/// \brief Set the include filename to the passed in filename.
/// \param[in] _filename the filename to set the include filename to.
public: void SetInclude(const std::string &_filename);
/// \brief Get the include filename.
/// \return The include filename.
public: std::string GetInclude() const;
/// \brief Get a text description of the element.
/// \return The text description of the element.
public: std::string GetDescription() const;
/// \brief Set a text description for the element.
/// \param[in] _desc the text description to set for the element.
public: void SetDescription(const std::string &_desc);
/// \brief Add a new element description
/// \param[in] _elem the Element object to add to the descriptions.
public: void AddElementDescription(ElementPtr _elem);
/// \brief Get a pointer to the named element.
/// \param[in] _name the name of the element to look for.
/// \return A pointer to the named element if found, nullptr otherwise.
public: ElementPtr GetElementImpl(const std::string &_name) const;
/// \brief Generate a string (XML) representation of this object.
/// \param[in] _prefix arbitrary prefix to put on the string.
/// \param[out] _out the std::ostreamstream to write output to.
private: void ToString(const std::string &_prefix,
std::ostringstream &_out) const;
/// \brief Generate a string (XML) representation of this object.
/// \param[in] _prefix arbitrary prefix to put on the string.
/// \param[out] _out the std::ostreamstream to write output to.
private: void PrintValuesImpl(const std::string &_prefix,
std::ostringstream &_out) const;
/// \brief Create a new Param object and return it.
/// \param[in] _key Key for the parameter.
/// \param[in] _type String name for the value type (double,
/// int,...).
/// \param[in] _defaultValue Default value.
/// \param[in] _required True if the parameter is required to be set.
/// \param[in] _description Description of the parameter.
/// \return A pointer to the new Param object.
private: ParamPtr CreateParam(const std::string &_key,
const std::string &_type,
const std::string &_defaultValue,
bool _required,
const std::string &_description="");
/// \brief Private data pointer
private: std::unique_ptr<ElementPrivate> dataPtr;
};
/// \internal
/// \brief Private data for Element
class ElementPrivate
{
/// \brief Element name
public: std::string name;
/// \brief True if element is required
public: std::string required;
/// \brief Element description
public: std::string description;
/// \brief True if element's children should be copied.
public: bool copyChildren;
/// \brief Element's parent
public: ElementWeakPtr parent;
// Attributes of this element
public: Param_V attributes;
// Value of this element
public: ParamPtr value;
// The existing child elements
public: ElementPtr_V elements;
// The possible child elements
public: ElementPtr_V elementDescriptions;
/// name of the include file that was used to create this element
public: std::string includeFilename;
/// \brief Name of reference sdf.
public: std::string referenceSDF;
};
///////////////////////////////////////////////
template<typename T>
T Element::Get(const std::string &_key) const
{
T result = T();
std::pair<T, bool> ret = this->Get<T>(_key, result);
return ret.first;
}
///////////////////////////////////////////////
template<typename T>
bool Element::Get(const std::string &_key,
T &_param,
const T &_defaultValue) const
{
std::pair<T, bool> ret = this->Get<T>(_key, _defaultValue);
_param = ret.first;
return ret.second;
}
///////////////////////////////////////////////
template<typename T>
std::pair<T, bool> Element::Get(const std::string &_key,
const T &_defaultValue) const
{
std::pair<T, bool> result(_defaultValue, true);
if (_key.empty() && this->dataPtr->value)
{
this->dataPtr->value->Get<T>(result.first);
}
else if (!_key.empty())
{
ParamPtr param = this->GetAttribute(_key);
if (param)
{
param->Get(result.first);
}
else if (this->HasElement(_key))
{
result.first = this->GetElementImpl(_key)->Get<T>();
}
else if (this->HasElementDescription(_key))
{
result.first = this->GetElementDescription(_key)->Get<T>();
}
else
{
result.second = false;
}
}
else
{
result.second = false;
}
return result;
}
///////////////////////////////////////////////
template<typename T>
bool Element::Set(const T &_value)
{
if (this->dataPtr->value)
{
this->dataPtr->value->Set(_value);
return true;
}
return false;
}
/// \}
}
#ifdef _WIN32
#pragma warning(pop)
#endif
#endif
|