Important considerations about configuration files and the usage of yarp methods find() and findGroup()

[randaz81]

In brief:

If you are a developer, check if your rfmodule/device/application is using config files with the following syntax:

wrong ini file:
my_parameter_list 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0

wrong xml file:
<param name="my_parameter_list "> 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 </param>

This syntax is NOT correct and might be not supported in the future. Please use the parenthesis to represent a list of values :

correct ini file:
my_parameter_list (100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0)

correct xml file
<param name="my_parameter_list "> (100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0 100.0) </param>

Regarding the source code that parses the list of parameters, you should use something like:

yarp::os::Bottle* tempBot = config.find("my_parameter_list ").asList();
if (tempBot)
{
   for (size_t i=0; i<tempBot->size(); i++)
   {
   // you can now use tempBot->get(i) to read the elements of the list
   }
} 

instead of:

yarp::os::Bottle tempBot = config.findGroup("my_parameter_list");
{
   for (size_t i=0; i<tempBot.size(); i++)
   {
   // beware tempBot.get(0) is the the parameter name 
   }
} 

---

Actions:

• Please stick to this policy in all newly written configuration files and c++ parsers: use the parenthesis for list of values and the method find(). Avoid using the method findGroup().
• If it is possible, try to fix the configuration files and parsers which do not respect this convention. This will result in a breaking change, so "possible" means "if the change involves only a reasonably limited set of files without causing problems to uninformed users ".

---

Long explanations:

As discussed in #3081, we are currently trying to automatize the cumbersome and error-prone process of the parameters parsing using a new tool that automatically generates the required code and the documentation.
We thus refactored many yarp devices with manually written parsers, fixing the errors we encountered along the process and noticing the most frequent ones.
One of these errors is indeed the use of the findGroup() method.
This method was originally developed to obtain a subgroup (subsection) of parameters from a larger one. Let's consider the following .ini example:

param_a 10.0
param_b 11.0
param_b 12.0

[section_a]
param1 val1
param2 val2
param3 val3

[section_b]
list1 p1 p2 p3 p4 p5
list2 (p1 p2 p3 p4 p5)

The following method:

Property config;
// ...
yarp::os::Bottle tempBot = config.findGroup("section_a")

will return a Bottle of 4 elements which are:

- section_a
- param1 val1
- param1 val2
- param3 val3

which can be further processed to obtain the contents of the individual parameters as follows:

string s1 = tempBot.find("param1")->asString();
string s2 = tempBot.find("param2")->asString();
string s3 = tempBot.find("param3")->asString();

This way of using findGroup() is fine. However, problems arise if it is used on a key that is not a section, since the method will return a valid bottle also in this case (a better design of the method should imply its failure in the case it is called on something that is not a section). The resulting bottle contains the key and its value (2 elements) or a list of n+1 elements in the case of a vector. For example:

yarp::os::Bottle section_b = config.findGroup("section_b")
yarp::os::Bottle tempBot1a = section_c.findGroup("list1") //returns a bottle of 6 elements: the key and 5 strings
yarp::os::Bottle tempBot2a = section_c.findGroup("list2") //returns a bottle of 2 elements: the key and a bottle containing 5 elements

The second example must be noticed carefully: a list included by the parenthesis is transformed into a bottle which requires an additional level of parsing.
This behavior is NOT correct and it is NOT consistent with the behavior of the method find(), as shown below:

yarp::os::Bottle section_b = config.findGroup("section_b")
yarp::os::Bottle* tempBot1b = section_c.find("list1") // returns a string, this is ok
yarp::os::Bottle* tempBot2b = section_c.find("list2") // returns a (pointer to) bottle of 5 elements, this is ok

Therefore, if the user modifies the configuration file, adding the parenthesis (which is the correct syntax) without knowing how the parser is designed, i.e. which method is using: find() or findGroup(), it will result in an incorrect parsing.
This is bad also from the design point of view. Given a configuration file, a parser should not give different results depending on which method is used.

Please note that all automatically generated parsers use the find() method and assume that list of values are included between parenthesis.

[pattacini]

cc @robotology/everyone

[traversaro]

fyi @xela-95

[traversaro]

For reference, gazebo-yarp-plugins and gz-sim-yarp-plugins have been updated to support the recommended way of specifying vector variables in the following two PRs:

• Add support for loading vector from configuration files with parenthesis gazebo-yarp-plugins#677, released in gazebo-yarp-plugins 4.12.0
• Add support for loading vector from configuration files with parenthesis gz-sim-yarp-plugins#141, released in gz-sim-yarp-plugins 0.2.0

So if you use YARP plugins for gazebo and you want to use the recommended style for vector variable, now you can!

fyi @xela-95