Module ros_args 

--ros-args parsing: the producer of the remap FALLBACK tier.

crate::names::resolve_name_layered resolves a name through two tiers — the launch projection (authoritative) and a fallback. This module is the fallback’s producer: it reads a process argument vector the way rcl does and yields the remap rules it carries.

Whose grammar

rcl’s, as documented in ROS 2 Humble’s installed headers (rcl/arguments.h, rcl_parse_arguments; rcl/remap.h, rcl_remap_topic_name):

• ROS arguments are scoped by --ros-args and end at -- or at the end of the vector. A vector may open several scopes. Everything outside a scope is a non-ROS argument and is left alone.
• -r / --remap is followed by ONE token, [node:]from:=to. A node: prefix restricts the rule to the node of that NAME.
• Rules are kept in argv order, and the first rule that matches a name wins — foo:=bar bar:=baz sends foo to bar, never baz.
• A -r followed by anything but a valid rule fails the parse.
• -p / --param is followed by ONE token, [node:]name:=value, and --params-file by a path. Both are parameter OVERRIDES (phase-482 W5, RFC-0015 §9.4’s POSIX row): reported through parse_ros_args_events, installed with Executor::install_argv_params, and applied when a node declares the parameter. The file is the caller’s to read — this module has no file system — and parse_params_yaml reads its text.

What is REFUSED, and why each one

Every flag this parser does not honour is a RosArgsError, never a skip. Silently dropping a ROS argument is the defect nros::init_with_args was written to stop (a -r chatter:=/other that compiles and then publishes on chatter). rclcpp is no more lenient: rclcpp::init throws UnknownROSArgsError for any ROS argument rcl left unparsed.

• __node / __name / __ns remaps — node IDENTITY. RFC-0046 makes the launch the authority on a node’s name and namespace, with the code’s default beneath it; an argv identity rung has not been ruled on.
• rostopic:// / rosservice:// rules — kind-qualified remaps, which rcl itself marks unfinished (TODO(sloretz) add documentation about rostopic:// when it is supported).
• -e/--enclave, --log-level, --log-config-file, the --{enable,disable}-*-logs switches, and any other token inside a scope.

no_std, no allocation

The parse borrows from the arguments it is given and reports each rule through a callback, so a board that reads its arguments from flash or a settings store (RFC-0015 §9.4’s other rows) can drive it without an allocator.

Structs

ParamArg

The -p/--param override one argument carried: [node:]name:=value, borrowed from the argument it was parsed out of. Also what parse_params_yaml reports for each value in a parameter file.

ParamsYamlError

Why a parameter file was refused: the 1-based line, the line as written, and the reason. Every construct the subset does not read is a refusal, never a skip — a value silently dropped from a file is the same “compiles and differs” the argv parse exists to stop.

RemapArg

The -r/--remap rule one argument carried: [node:]from:=to, borrowed from the argument it was parsed out of.

Enums

ApplyError

Why apply_ros_args refused an argument vector.

RosArg

One thing a --ros-args scope said, in argv order.

RosArgsError

Why an argument vector was refused. Each variant names the offending token.

Constants

MAX_PARAMS_FILE_NAME_LEN

The longest dotted name parse_params_yaml builds (group.sub.name).

Functions

apply_ros_args

Parse args and, given an executor, install its -r rules as the FALLBACK tier — the whole of “honour --ros-args” for a caller with no allocator (the C++ ABI, nros_cpp_install_argv_remaps).

argv_fallback

The installed argv rules that apply to the node named node_name (in namespace), as a fallback tier for crate::names::resolve_name_layered.

install_argv_remaps

Install parsed -r rules in executor’s remap table as its FALLBACK tier.

parse_param_rule

Parse one [node:]name:=value override. An empty value is allowed (it is an empty string parameter); an empty or blank name is not.

parse_params_yaml

Read a ROS 2 parameter file’s TEXT — the --params-file format — and report each value through on_param, in file order.

parse_remap_rule

Parse one [node:]from:=to rule.

parse_ros_args

Parse args the way rcl_parse_arguments does, reporting each remap rule in argv order through on_remap.

parse_ros_args_events

Parse args like parse_ros_args, reporting remaps AND parameter overrides (-p, --params-file) in argv order — phase-482 W5.