Ariles

branch	HEAD v2	pkg_catkin_2 (ROS/catkin package)	pkg_freebsd_2 (FreeBSD package)
CI status
package

Contents

• Links
• Introduction
  • Use cases
• Minimal example
• Visitors
• Supported types
• Dependencies and compilation
• Related software

Links

• Documentation (Doxygen): https://asherikov.github.io/ariles/2/
• GitHub: https://github.com/asherikov/ariles
• Legacy 1.x.x version: https://github.com/asherikov/ariles/tree/head_1 (migration guide https://asherikov.github.io/ariles/2/md_doc_migration_1to2.html)

Introduction

Loosely speaking, ariles is a C++ reflection library, i.e., it provides meta-programming APIs for implementation of class visitors (processors). It also provides a number of (de)serializers based on these APIs, e.g., YAML, JSON, XML, ROS parameter server; and serialization wrappers for some types, e.g., STL containers, smart pointers, Eigen matrices, etc.

Use cases

1. Parsing and generation of configuration files. Unlike some common serialization libraries, e.g., boost::serialization, ariles tries to be flexible while parsing by:
   • silently ignoring unused entries (if possible),
   • ignoring ordering of entries (if possible),
   • not discriminating attributes from childs in XML,
   • optionally ignoring missing entries.
2. Conversion between different formats, for example, YAML <-> ROS parameter server. Note that the conversion is not data-agnostic, i.e., the complete data structure must be represented in C++ code.
3. Flattening of a class hierarchy to a list of name-value pairs (string-double), which is useful for collection of time-series data.
4. Exporting of numerical data to an Octave script for debugging purposes.
5. Implemetation of parsers for specific data formats, e.g., URDF.

Minimal example

Class [./tests/api_v2/types/minimal.h]:

class Configurable : public ariles2::DefaultBase
{
    #define ARILES2_DEFAULT_ID "ConfigurableEntryName" // optional, defaults to 'ariles'
    #define ARILES2_ENTRIES(v) \
        ARILES2_TYPED_ENTRY(v, integer_member, int)
    #include ARILES2_INITIALIZE
};

Serialization:

Configurable configurable;
configurable.integer_member = 10;
ariles2::apply<ariles2::yaml_cpp::Writer>("config.yaml", configurable);
ariles2::apply<ariles2::yaml_cpp::Writer>(std::cout, configurable);

Result:

ConfigurableEntryName:
    integer_member: 10

Deserialization:

ariles2::apply<ariles2::yaml_cpp::Reader>("config.yaml", configurable);

Conversion:

// read class from a file
ariles2::apply<ariles2::yaml_cpp::Reader>("config.yaml", configurable);
// dump class to ROS parameter server
ariles2::apply<ariles2::rosparam::Writer>(nh, configurable, "/some_namespace/");

See demo for more exaples: https://asherikov.github.io/ariles/2/DEMO.html [./tests/api_v2/demo_api_v2.cpp]

Visitors

ariles includes a number of optional visitors that support various data representation formats, in particular:

• YAML via yaml-cpp: https://asherikov.github.io/ariles/2/group__yaml__cpp.html.
• msgpack via msgpack-c: https://asherikov.github.io/ariles/2/group__msgpack.html.
• JSON via RapidJSON, with optional Jsonnet preprocessing: https://asherikov.github.io/ariles/2/group__rapidjson.html and https://asherikov.github.io/ariles/2/group__jsonnet.html.
• XML via PugiXML: https://asherikov.github.io/ariles/2/group__pugixml.html
• Octave script, output only, no dependencies: https://asherikov.github.io/ariles/2/group__octave.html
• ROS parameter server, via standard ROS libs: https://asherikov.github.io/ariles/2/group__ros.html
• A set of key-value pairs, output only, no dependencies: https://asherikov.github.io/ariles/2/group__namevalue.html
• graphviz dot files for diagram generation: https://asherikov.github.io/ariles/2/group__graphviz.html

The complete list of modules is available at https://asherikov.github.io/ariles/2/modules.html

Supported data types

ariles provides serialization wrappers for the follwing types:

• Fundametal types: integers, floats, booleans.
• Some STL classes (WIP): std::string, std::vector, std::map, std::pair, std::shared_ptr, std::unique_ptr.
• Eigen types: matrices, transforms, quaternions.
• Boost classes: boost::optional, boost::movelib::unique_ptr. boost::shared_ptr.
• Better enums -> https://github.com/aantron/better-enums.

Dependencies and compilation

Dependencies

• cmake >= 3.0
• C++11 compatible compiler
• boost

Visitors and corresponding dependencies can be enabled or disabled via cmake options, the same applies to data types which depend on external libraries.

Compilation with catkin

An example catkin package is provided in pkg_catkin_2 branch of the main repository -> https://github.com/asherikov/ariles/tree/pkg_catkin_2.

Related software

• https://github.com/PickNikRobotics/rosparam_shortcuts: a set of wrapper functions to read individual parameters from ROS parameter server. This tool serves pretty much the same purpose as ariles2::rosparam::Reader, but its functionality is more limited.
• https://billyquith.github.io/ponder/: C++14 reflection library, supports serialization to XML and JSON. Unlike ariles it is more focused on reflection per se rather than applications, for example, it allows to set value by string name of a class member, handles class methods, etc. Ponder does not rely as much on preprocessor macro, but is more verbose.
• https://github.com/bytemaster/boost_reflect: discontinued C++ reflection library, similar to ponder. Partially inspired ariles 2.x.x API.
• https://github.com/apolukhin/magic_get (aka pfr): C++14 library providing tuple like methods for aggregate initializable structures. Addresses a somewhat different but related problem.
• Serialization libraries, e.g., boost::serialization, https://github.com/USCiLab/cereal.