raisim::RaiSimTinyXmlWrapper

class · #include <raisim/RaiSimTinyXmlWrapper.hpp>

Read-only convenience wrapper around a TinyXML element, used by the RaiSim XML, URDF and MJCF loaders. Errors are reported through RSFATAL with the file name, row and column. A wrapper created from a file owns the document; wrappers returned by getChildren() point into it and must not outlive the root wrapper. A default-constructed wrapper is a dummy node: the *IfExists getters return false and the other accessors are fatal.

Constructors & destructor

RaiSimTinyXmlWrapper

RaiSimTinyXmlWrapper() = default

RaiSimTinyXmlWrapper(
    const std::string &filePath,
    const std::string &childElement)

Load a document and select its first top-level element with the given name. Fatal if the file cannot be read or has no such element.

Parameters

Parameter	Description
filePath (in)	path to an XML file, or the XML text itself if it contains '<'
childElement (in)	name of the top-level element, e.g. "raisim" or "robot"

Public member functions

setFileName

void setFileName(const std::string &name)

Set the file name used in error messages.

Parameters

Parameter	Description
name (in)	file name

getChildren

std::vector<RaiSimTinyXmlWrapper> getChildren(const std::string &child) const

Parameters

Parameter	Description
child (in)	element name

Returns the child elements with the given name, in document order

std::vector<RaiSimTinyXmlWrapper> getChildren() const

Returns all child elements, in document order

removeFirstChild

bool removeFirstChild(const std::string &child)

Remove the first child element with the given name from the document.

Parameters

Parameter	Description
child (in)	element name

Returns true if a child was removed

getChildrenMust

std::vector<RaiSimTinyXmlWrapper> getChildrenMust(const std::string &child) const

Same as getChildren(const std::string&), but fatal if there is no such child.

Parameters

Parameter	Description
child (in)	element name

Returns the child elements with the given name (not empty)

std::vector<RaiSimTinyXmlWrapper> getChildrenMust() const

Same as getChildren(), but fatal if the element has no child elements.

Returns all child elements (not empty)

getChildrenWithAttribute

template <typename T>
std::vector<RaiSimTinyXmlWrapper> getChildrenWithAttribute(
    const std::string &att,
    T value)

Parameters

Parameter	Description
att (in)	attribute name
value (in)	attribute value to match (read with getAttributeIfExists())

Returns the child elements whose attribute equals value

getAttributeMust

template <typename T>
T getAttributeMust(const std::string &attName) const

Read an attribute with getAttributeIfExists(); fatal if it is missing.

Parameters

Parameter	Description
attName (in)	attribute name

Returns the parsed value

setAttribute

template <typename T>
void setAttribute(const std::string &name, T attribute)

Set an attribute on the in-memory element.

Parameters

Parameter	Description
name (in)	attribute name
attribute (in)	value

errorMessage

void errorMessage(const std::string &msg) const

Report a fatal error that names this element's file, row, column and node name.

Parameters

Parameter	Description
msg (in)	error description

getAttributeIfExists

template <typename T>
bool getAttributeIfExists(const std::string &attName, T &attribute) const

Read a numeric list into a resizable container (e.g. std::vector<double> or VecDyn). Values are comma- or whitespace-separated; malformed or empty lists are fatal.

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the values (resized to their count)

Returns false if the attribute does not exist

template <size_t n>
bool getAttributeIfExists(
    const std::string &attName,
    Vec<n> &attribute) const

Read exactly n numbers; any other count is fatal.

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the values

Returns false if the attribute does not exist

bool getAttributeIfExists(const std::string &attName, int &attribute) const

Read an int with TinyXML's parser (attribute is left unchanged if the text is not a number).

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the value

Returns false if the attribute does not exist

bool getAttributeIfExists(
    const std::string &attName,
    double &attribute) const

Read a double with TinyXML's parser (attribute is left unchanged if the text is not a number).

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the value

Returns false if the attribute does not exist

bool getAttributeIfExists(
    const std::string &attName,
    std::string &attribute) const

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the raw text

Returns false if the attribute does not exist

bool getAttributeIfExists(
    const std::string &attName,
    unsigned long &attribute) const

Read a decimal unsigned integer; malformed or out-of-range text is fatal.

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the value

Returns false if the attribute does not exist

bool getAttributeIfExists(
    const std::string &attName,
    unsigned long long &attribute) const

Read a decimal unsigned integer ("-1" means the maximum value, as written by RaiSimTinyXmlWriterElement).

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the value

Returns false if the attribute does not exist

bool getAttributeIfExists(
    const std::string &attName,
    ObjectType &attribute) const

Read an object type name (see stringToObjectType()).

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the type (UNRECOGNIZED for unknown names)

Returns false if the attribute does not exist

template <typename T>
bool getAttributeIfExists(
    const std::string &arg,
    const std::string &arg2,
    T &attribute)

Read the first existing attribute among two alternative names.

Parameters

Parameter	Description
arg (in)	first name
arg2 (in)	second name
attribute (out)	receives the value

Returns false if neither attribute exists

template <typename T>
bool getAttributeIfExists(
    const std::string &arg,
    const std::string &arg2,
    const std::string &arg3,
    T &attribute)

Read the first existing attribute among three alternative names.

Parameters

Parameter	Description
arg (in)	first name
arg2 (in)	second name
arg3 (in)	third name
attribute (out)	receives the value

Returns false if none of the attributes exists

getDynamicVectorAttributeIfExists

bool getDynamicVectorAttributeIfExists(
    const std::string &attName,
    VecDyn &attribute,
    size_t expectedSize) const

Read a dynamic numeric vector with an explicit expected dimension. An empty XML value is accepted only when expectedSize is zero.

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	receives the values
expectedSize (in)	required number of values; a different count is fatal

Returns false if the attribute does not exist

getDynamicVectorAttributeMust

VecDyn getDynamicVectorAttributeMust(
    const std::string &attName,
    size_t expectedSize) const

Same as getDynamicVectorAttributeIfExists(), but fatal if the attribute is missing.

Parameters

Parameter	Description
attName (in)	attribute name
expectedSize (in)	required number of values

Returns the values

getAncestorAttributeIfExists

bool getAncestorAttributeIfExists(
    const std::string &attName,
    std::string &attribute) const

Read a string attribute of the nearest ancestor element that has it.

Parameters

Parameter	Description
attName (in)	attribute name
attribute (out)	attribute value (unchanged if no ancestor has it)

Returns true if an ancestor has the attribute

getFullTree

std::string getFullTree() const

Returns the element path from the root, e.g. "raisim/objects/sphere/"

getFileName

const std::string &getFileName() const

Returns the file name used in error messages

getNodeName

const std::string &getNodeName() const

Returns the element name. Must not be called on a dummy node

expandIncludes

void expandIncludes(const std::string &directory)

Replace every <include file="..."/> element below this one by the children of the root element of that file, as MJCF includes are, and the included files' includes in turn. As in MuJoCo, a relative path is looked for in directory, the main file's, and then in the directory of the file that has the include; each included element with a file attribute gets kIncludeDirAttribute. Fatal if a file cannot be read, includes itself (directly or through others), or an <include> has children.

Parameters

Parameter	Description
directory (in)	directory of the main file

inheritChild

void inheritChild(
    const RaiSimTinyXmlWrapper &other,
    const std::string &name,
    const std::vector<std::string> &alternatives={})

Give this element's first child named name the attributes of other's first child of that name that it lacks; if it has no such child, append a copy of other's. Of a group of alternatives (such as the ways to give an orientation), none is inherited if the child has one.

Parameters

Parameter	Description
other (in)	element to inherit from
name (in)	element name
alternatives (in)	attributes of which the child takes at most one

mergeRepeatedChildren

void mergeRepeatedChildren(const std::string &name)

Merge every later child element named name into the first one: its children are appended to the first's and its attributes override the first's, as MJCF merges a repeated section such as worldbody or asset (after includes).

Parameters

Parameter	Description
name (in)	element name

Public attributes

kIncludeDirAttribute

static constexpr const char *kIncludeDirAttribute

The attribute expandIncludes() gives each included element with a file attribute: the directory of the file it was included from, where MuJoCo also looks for that file.