I think it is!
See Why does the ROS2 Python launch files look like XML written in Python? - #7 by wjwwood
Agreed, that’s definitely a documentation issue. For some context, we started by only having the Python API due to time constraints, so we documented how to use it for making launch files a bit, in order to have something. Later we finished the frontends which let you use XML and YAML. I’ve always believed these should be what most people should use most of the time.
Honestly in my experience launch is still pretty XML-friendly and the YAML can be a little weirdly XML-like in some cases. Unfortunately I never have had time to try to learn the launch internals enough to tackle this, for example:
opened 04:56PM - 27 Mar 23 UTC
help wanted
### Expected behavior
With no clear documentation I could find, I expected to… be able to write a YAML launch file argument declaration in a way that mirrors Python launch files.
For example, I want to translate the following, taken from [`ur_robot_driver/launch/ur_control.launch.py`](https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/blob/main/ur_robot_driver/launch/ur_control.launch.py#L357):
```python
DeclareLaunchArgument(
"ur_type",
description="Type/series of used UR robot.",
choices=["ur3", "ur3e", "ur5", "ur5e", "ur10", "ur10e", "ur16e"],
default_value="ur5e",
)
```
YAML allows list syntax in a couple of different ways, so I expected I might be able to write:
```YAML
- arg:
name: ur_type
default: ur5e
choices: [ur3, ur3e, ur5, ur5e, ur10, ur10e, ur16e]
description: Robot to use in the examples.
```
There's a required change of `default_value` to `default`, but that is clear [from the official docs' examples](https://docs.ros.org/en/rolling/How-To-Guides/Launch-file-different-formats.html).
### Actual behavior
I couldn't find any documentation that YAML launch supported choices. However, I dug around in the source code and in issues/PRs, and figured out that it was possible to do it in XML (for example, #529)
I had to iterate through the following errors:
```
[ERROR] [launch]: Caught exception in launch (see debug for traceback):
Caught exception when trying to load file of format [yaml]:
Unexpected key(s) found in `arg`: {'choices'}
...
[ERROR] [launch]: Caught exception in launch (see debug for traceback):
Caught exception when trying to load file of format [yaml]:
Attribute choice of Entity arg expected to be a list of dictionaries.
...
[ERROR] [launch]: Caught exception in launch (see debug for traceback):
Caught exception when trying to load file of format [yaml]:
Can not find attribute value in Entity choice
```
In the end, this appears to be ~~the~~ a valid way to supply argument choices in a YAML launch file:
```YAML
- arg:
name: ur_type
default: ur5e
choice: [value: ur3, value: ur3e, value: ur5, value: ur5e, value: ur10, value: ur10e, value: ur16e]
description: Robot to use in the examples.
```
With this argument declaration, I get the desired validation behavior when passing an incorrect command-line value of `ur_type:=ur5x`, and no errors if I pass one of the suggested/declared choices:
```
ros2 launch ur_examples_gazebo_classic ur_sim_examples.launch.yaml ur_type:=ur5x
[INFO] [launch]: All log files can be found below /home/dan/.ros/log/2023-03-27-12-06-31-631160-schelkunoff-530229
[INFO] [launch]: Default logging verbosity is set to INFO
[ERROR] [launch.actions.declare_launch_argument]:
Argument "ur_type" provided value "ur5x" is not valid.
Valid options are: ['ur3', 'ur3e', 'ur5', 'ur5e', 'ur10', 'ur10e', 'ur16e']
```
However, this is pretty non-obvious.
It seems like the frontend is parsing YAML the same way as XML. In XML, each choice is expected to be its own XML tag with a value, like [this test](https://github.com/ros2/launch/blob/5d860a8693aed53ee80b0ec63cb45a8ffbd005ec/launch_xml/test/launch_xml/test_arg.py#L26) added in #529:
```XML
<launch>
<arg name="my_arg" default="asd" description="something">
<choice value="asd"/>
<choice value="bsd"/>
</arg>
</launch>
```
Reasonable and intuitive for XML, but it seems unexpected for YAML.
I don't understand the launch system well enough to propose a PR for the YAML frontend that would allow `choices` specified as a YAML list/sequence.
I plan to propose a documentation PR for `ros2_documentation`. This is a nice feature for launch args, and I couldn't find clear documentation of argument choices for Python and XML, I just had a Python example in hand from the UR packages.
I think for now the best thing to do is raise awareness and start using XML as much as possible.
For those things that really are easier and better to do in imperative Python,OpaqueFunction is always an option.