Skip to main content

moqros_cli/
params.rs

1//! Parsing the command line and ROS parameters into the flags.
2
3use std::any::TypeId;
4use std::collections::HashSet;
5
6use anyhow::{Context, bail};
7use clap::error::ErrorKind;
8use clap::{ArgAction, Command, Parser};
9use moqros::ros::r2r;
10use moqros::ros::r2r::ParameterValue;
11
12/// Create the ROS node and parse `T` from the command line and the node's ROS parameters.
13///
14/// Arguments between `--ros-args` and `--` are left to rcl, so the binaries accept
15/// remapping (`-r __node:=…`, `-r __ns:=…`), `-p` and `--params-file` like any ROS
16/// node. Each ROS parameter named after an argument (`bitrate`, `keyframe_interval_ms`,
17/// …) fills that argument: flags win over parameters, which win over environment
18/// variables and defaults.
19pub fn init<T: Parser>(node_name: &str) -> anyhow::Result<(T, r2r::Node)> {
20	let args = strip_ros_args(std::env::args());
21	// Answer `--help` and `--version` without bringing up ROS.
22	if let Some(err) = help_or_version(T::command(), &args) {
23		err.exit();
24	}
25
26	let ctx = r2r::Context::create().context("failed to create ROS context")?;
27	let node = r2r::Node::create(ctx, node_name, "").context("failed to create ROS node")?;
28
29	let flags = param_flags(
30		&T::command(),
31		node.params
32			.lock()
33			.unwrap()
34			.iter()
35			.map(|(name, param)| (name.as_str(), &param.value)),
36	)?;
37	let cli = match parse_args(args, flags) {
38		Ok(cli) => cli,
39		Err(ParseError::CommandLine(err)) => err.exit(),
40		Err(ParseError::Param(err)) => {
41			// Just clap's first line; its usage hints are about the command line.
42			let message = err.to_string();
43			let message = message.lines().next().unwrap_or_default().trim_start_matches("error: ");
44			bail!("invalid ROS parameter: {message}");
45		}
46	};
47	Ok((cli, node))
48}
49
50/// Drop the ROS arguments (`--ros-args … [--]`, possibly repeated) from `args`.
51pub fn strip_ros_args(args: impl IntoIterator<Item = String>) -> Vec<String> {
52	let mut in_ros_args = false;
53	args.into_iter()
54		.filter(|arg| match (in_ros_args, arg.as_str()) {
55			(false, "--ros-args") | (true, "--") => {
56				in_ros_args = !in_ros_args;
57				false
58			}
59			_ => !in_ros_args,
60		})
61		.collect()
62}
63
64/// The error to exit with if `args` ask for help or the version.
65///
66/// Clap answers these as soon as it meets the flag, before checking anything else.
67fn help_or_version(command: Command, args: &[String]) -> Option<clap::Error> {
68	let err = command.try_get_matches_from(args).err()?;
69	matches!(err.kind(), ErrorKind::DisplayHelp | ErrorKind::DisplayVersion).then_some(err)
70}
71
72/// Why [`parse_args`] failed.
73#[derive(Debug)]
74enum ParseError {
75	/// The command line itself is invalid.
76	CommandLine(clap::Error),
77	/// The command line is fine on its own, so a ROS parameter is invalid.
78	Param(clap::Error),
79}
80
81/// Parse `T` from `args` (program name first, ROS arguments already stripped) and
82/// `param_flags`.
83///
84/// The parameter flags go right after the program name. With `args_override_self` a
85/// later occurrence of a flag wins, so the command line overrides them, while
86/// environment variables and defaults only apply to flags given neither way. Repeatable
87/// flags collect every occurrence instead, so parameter flags that the command line
88/// gives again are dropped up front.
89fn parse_args<T: Parser>(args: Vec<String>, param_flags: Vec<String>) -> Result<T, ParseError> {
90	let flag = |arg: &str| arg.split_once('=').map_or(arg, |(flag, _)| flag).to_string();
91	let given: HashSet<String> = args
92		.iter()
93		.skip(1)
94		.filter(|arg| arg.starts_with("--"))
95		.map(|arg| flag(arg))
96		.collect();
97	let param_flags: Vec<String> = param_flags
98		.into_iter()
99		.filter(|param| !given.contains(&flag(param)))
100		.collect();
101	let parse = |param_flags: Vec<String>| {
102		let mut args = args.iter().cloned();
103		let args = args.next().into_iter().chain(param_flags).chain(args);
104		let matches = T::command().args_override_self(true).try_get_matches_from(args)?;
105		T::from_arg_matches(&matches)
106	};
107	parse(param_flags).map_err(|err| match parse(Vec::new()) {
108		Ok(_) => ParseError::Param(err),
109		Err(err) => ParseError::CommandLine(err),
110	})
111}
112
113/// Command-line flags (`--name=value`) for the ROS parameters named after an argument
114/// of `command`.
115fn param_flags<'a>(
116	command: &Command,
117	params: impl IntoIterator<Item = (&'a str, &'a ParameterValue)>,
118) -> anyhow::Result<Vec<String>> {
119	let mut flags = Vec::new();
120	for (name, value) in params {
121		let Some((long, arg)) = command
122			.get_arguments()
123			.find(|arg| arg.get_id() == name)
124			.and_then(|arg| Some((arg.get_long()?, arg)))
125		else {
126			// r2r reads `use_sim_time` itself.
127			if name != "use_sim_time" {
128				tracing::warn!(name, "ignoring unknown ROS parameter");
129			}
130			continue;
131		};
132		let value = match value {
133			// An empty YAML value: leave the flag to its environment variable or default.
134			ParameterValue::NotSet => continue,
135			ParameterValue::Bool(value) => value.to_string(),
136			ParameterValue::Integer(value) => value.to_string(),
137			// Keep the fraction of whole numbers for strings (`1.0` stays `1.0`), but drop
138			// it for numbers so `2000000.0` still fits an integer flag.
139			ParameterValue::Double(value) if arg.get_value_parser().type_id() == TypeId::of::<String>() => {
140				format!("{value:?}")
141			}
142			ParameterValue::Double(value) => value.to_string(),
143			ParameterValue::String(value) => value.clone(),
144			// A list fills a repeatable flag, one occurrence per element.
145			ParameterValue::StringArray(values) if matches!(arg.get_action(), ArgAction::Append) => {
146				flags.extend(values.iter().map(|value| format!("--{long}={value}")));
147				continue;
148			}
149			value => bail!("ROS parameter `{name}` has unsupported type: {value:?}"),
150		};
151		// One token, so values starting with `-` aren't taken for flags.
152		flags.push(format!("--{long}={value}"));
153	}
154	Ok(flags)
155}
156
157#[cfg(test)]
158mod tests {
159	use clap::CommandFactory;
160
161	use super::*;
162	use crate::{EncoderArgs, Format, QosArgs, RelayArgs, RepublishArgs, TopicSpec};
163
164	fn strip(args: &[&str]) -> Vec<String> {
165		strip_ros_args(args.iter().map(|arg| arg.to_string()))
166	}
167
168	#[derive(Debug, Parser)]
169	#[command(version = "1.2.3")]
170	struct TestCli {
171		#[arg(long, default_value = "/image_raw")]
172		topic: String,
173
174		#[arg(long)]
175		broadcast: Option<String>,
176
177		#[arg(long, default_value_t = 30.0)]
178		fps: f32,
179
180		#[arg(long, default_value_t = 2000)]
181		keyframe_interval_ms: u64,
182
183		#[arg(long, value_enum, default_value_t = Format::Video)]
184		format: Format,
185
186		#[arg(id = "type", long = "type")]
187		ros_type: Option<String>,
188
189		#[arg(long, default_value_t = moqros::DataMode::default())]
190		mode: moqros::DataMode,
191
192		#[command(flatten)]
193		relay: RelayArgs,
194
195		#[command(flatten)]
196		qos: QosArgs,
197	}
198
199	#[derive(Debug, Parser)]
200	struct MultiCli {
201		#[arg(long, default_value = "/image_raw")]
202		topic: Vec<TopicSpec>,
203	}
204
205	/// Only parsed by `params_override_env`, in a child process of its own.
206	#[derive(Debug, Parser)]
207	struct EnvCli {
208		#[arg(long, env = "MOQROS_TEST_BITRATE", default_value_t = 1)]
209		bitrate: u32,
210	}
211
212	fn flags<T: Parser>(params: &[(&str, ParameterValue)]) -> anyhow::Result<Vec<String>> {
213		param_flags(&T::command(), params.iter().map(|(name, value)| (*name, value)))
214	}
215
216	fn args(args: &[&str]) -> Vec<String> {
217		std::iter::once("bin")
218			.chain(args.iter().copied())
219			.map(String::from)
220			.collect()
221	}
222
223	fn parse<T: Parser>(args_: &[&str], params: &[(&str, ParameterValue)]) -> Result<T, ParseError> {
224		parse_args(args(args_), flags::<T>(params).unwrap())
225	}
226
227	fn string(value: &str) -> ParameterValue {
228		ParameterValue::String(value.to_string())
229	}
230
231	#[test]
232	fn strips_ros_args() {
233		assert_eq!(strip(&["bin", "--topic", "a"]), ["bin", "--topic", "a"]);
234		assert_eq!(
235			strip(&[
236				"bin",
237				"--topic",
238				"a",
239				"--ros-args",
240				"-r",
241				"__node:=n",
242				"-p",
243				"bitrate:=1"
244			]),
245			["bin", "--topic", "a"]
246		);
247		assert_eq!(
248			strip(&[
249				"bin",
250				"--ros-args",
251				"-r",
252				"__ns:=/x",
253				"--",
254				"--reliable",
255				"--ros-args",
256				"-p",
257				"a:=1"
258			]),
259			["bin", "--reliable"]
260		);
261	}
262
263	#[test]
264	fn params_fill_flags() {
265		let cli: TestCli = parse(
266			&[],
267			&[
268				("topic", string("/front/image_raw")),
269				("keyframe_interval_ms", ParameterValue::Integer(500)),
270				("reliable", ParameterValue::Bool(true)),
271				("url", string("http://relay:4443/anon")),
272			],
273		)
274		.unwrap();
275		assert_eq!(cli.topic, "/front/image_raw");
276		assert_eq!(cli.keyframe_interval_ms, 500);
277		assert!(cli.qos.reliable);
278		assert_eq!(cli.relay.url.as_str(), "http://relay:4443/anon");
279		assert!(!cli.relay.insecure);
280		assert_eq!(cli.broadcast, None);
281	}
282
283	#[test]
284	fn client_cert_flags_come_in_pairs() {
285		let cli: TestCli = parse(
286			&["--tls-cert", "/certs/robot.pem"],
287			&[("tls_key", string("/certs/robot.key"))],
288		)
289		.unwrap();
290		let config = cli.relay.config();
291		assert_eq!(
292			config.tls_cert.as_deref(),
293			Some(std::path::Path::new("/certs/robot.pem"))
294		);
295		assert_eq!(
296			config.tls_key.as_deref(),
297			Some(std::path::Path::new("/certs/robot.key"))
298		);
299		assert!(parse::<TestCli>(&["--tls-cert", "/certs/robot.pem"], &[]).is_err());
300		assert!(parse::<TestCli>(&["--tls-key", "/certs/robot.key"], &[]).is_err());
301	}
302
303	#[test]
304	fn data_params_fill_flags() {
305		let cli: TestCli = parse(&[], &[]).unwrap();
306		assert_eq!(
307			(cli.format, cli.ros_type, cli.mode),
308			(Format::Video, None, moqros::DataMode::Snapshot)
309		);
310
311		let cli: TestCli = parse(
312			&[],
313			&[
314				("format", string("json")),
315				("type", string("sensor_msgs/msg/Imu")),
316				("mode", string("stream")),
317			],
318		)
319		.unwrap();
320		assert_eq!(cli.format, Format::Json);
321		assert_eq!(cli.format.data(), Some(moqros::DataFormat::Json));
322		assert_eq!(cli.ros_type.as_deref(), Some("sensor_msgs/msg/Imu"));
323		assert_eq!(cli.mode, moqros::DataMode::Stream);
324
325		let cli: TestCli = parse(&["--format", "cdr", "--type", "std_msgs/msg/String"], &[]).unwrap();
326		assert_eq!(cli.format.data(), Some(moqros::DataFormat::Cdr));
327		assert_eq!(cli.ros_type.as_deref(), Some("std_msgs/msg/String"));
328		assert!(matches!(
329			parse::<TestCli>(&[], &[("format", string("xml"))]),
330			Err(ParseError::Param(_))
331		));
332	}
333
334	#[derive(Debug, Parser)]
335	struct EncoderCli {
336		#[command(flatten)]
337		encoder: EncoderArgs,
338	}
339
340	#[test]
341	fn encoder_params_fill_flags() {
342		let cli: EncoderCli = parse(&[], &[]).unwrap();
343		assert_eq!(cli.encoder.settings().hardware, moqros::Hardware::Auto);
344
345		let params = [("codec", string("av1")), ("hw", string("off"))];
346		let settings = parse::<EncoderCli>(&[], &params).unwrap().encoder.settings();
347		assert_eq!(
348			(settings.codec, settings.hardware),
349			(moqros::Codec::Av1, moqros::Hardware::Off)
350		);
351
352		let cli: EncoderCli = parse(&["--hw", "require"], &params).unwrap();
353		assert_eq!(cli.encoder.hw, moqros::Hardware::Require);
354		assert!(parse::<EncoderCli>(&["--hw", "gpu"], &[]).is_err());
355	}
356
357	#[derive(Debug, Parser)]
358	struct RepublishCli {
359		#[command(flatten)]
360		republish: RepublishArgs,
361	}
362
363	#[test]
364	fn republish_params_fill_flags() {
365		let params = [
366			("frame_id", string("camera")),
367			("stamp", string("receive")),
368			("max_height", ParameterValue::Integer(480)),
369			("encoding", string("bgr8")),
370		];
371		let options = parse::<RepublishCli>(&[], &params).unwrap().republish.options();
372		assert_eq!(
373			options,
374			crate::RepublishOptions {
375				frame_id: Some("camera".into()),
376				stamp: moqros::ros::StampSource::Receive,
377				max_height: Some(480),
378				encoding: moqros::PixelFormat::Bgr8,
379			}
380		);
381		let cli: RepublishCli = parse(&["--max-height", "360"], &params).unwrap();
382		assert_eq!(cli.republish.max_height, Some(360));
383		assert!(parse::<RepublishCli>(&[], &[("encoding", string("yuyv"))]).is_err());
384	}
385
386	#[test]
387	fn command_line_overrides_params() {
388		let params = [
389			("topic", string("/param")),
390			("reliable", ParameterValue::Bool(true)),
391			("insecure", ParameterValue::Bool(false)),
392		];
393		let cli: TestCli = parse(&["--topic", "/flag", "--reliable=false", "--insecure"], &params).unwrap();
394		assert_eq!(cli.topic, "/flag");
395		assert!(!cli.qos.reliable);
396		assert!(cli.relay.insecure);
397	}
398
399	/// Setting a variable while other tests read the environment is undefined behavior,
400	/// so this test reruns itself in a child process for each value of the variable.
401	#[test]
402	fn params_override_env() {
403		const VAR: &str = "MOQROS_TEST_BITRATE";
404		let bitrate = ("bitrate", ParameterValue::Integer(2));
405		match std::env::var(VAR).ok().as_deref() {
406			None => {
407				for value in ["bogus", "4"] {
408					let output = std::process::Command::new(std::env::current_exe().unwrap())
409						.args(["--exact", "params::tests::params_override_env"])
410						.env(VAR, value)
411						.output()
412						.unwrap();
413					let stdout = String::from_utf8_lossy(&output.stdout);
414					assert!(
415						output.status.success() && stdout.contains("1 passed"),
416						"{VAR}={value}:\n{stdout}"
417					);
418				}
419			}
420			// An invalid variable is never looked at when a parameter or flag is set.
421			Some("bogus") => {
422				assert_eq!(parse::<EnvCli>(&[], std::slice::from_ref(&bitrate)).unwrap().bitrate, 2);
423				assert_eq!(parse::<EnvCli>(&["--bitrate", "3"], &[]).unwrap().bitrate, 3);
424				assert!(matches!(parse::<EnvCli>(&[], &[]), Err(ParseError::CommandLine(_))));
425				let help = help_or_version(EnvCli::command(), &args(&["--help"]));
426				assert_eq!(help.map(|err| err.kind()), Some(ErrorKind::DisplayHelp));
427			}
428			Some(value) => {
429				assert_eq!(value, "4");
430				assert_eq!(parse::<EnvCli>(&[], &[]).unwrap().bitrate, 4);
431				assert_eq!(parse::<EnvCli>(&[], std::slice::from_ref(&bitrate)).unwrap().bitrate, 2);
432				assert_eq!(parse::<EnvCli>(&["--bitrate=3"], &[bitrate]).unwrap().bitrate, 3);
433			}
434		}
435	}
436
437	#[test]
438	fn doubles_keep_their_fraction() {
439		let cli: TestCli = parse(
440			&[],
441			&[
442				("broadcast", ParameterValue::Double(1.0)),
443				("fps", ParameterValue::Double(12.5)),
444			],
445		)
446		.unwrap();
447		assert_eq!(cli.broadcast.as_deref(), Some("1.0"));
448		assert_eq!(cli.fps, 12.5);
449
450		// Whole numbers still fit integer flags.
451		let cli: TestCli = parse(&[], &[("keyframe_interval_ms", ParameterValue::Double(500.0))]).unwrap();
452		assert_eq!(cli.keyframe_interval_ms, 500);
453
454		// YAML `fps: 15` is an integer parameter.
455		let cli: TestCli = parse(&[], &[("fps", ParameterValue::Integer(15))]).unwrap();
456		assert_eq!(cli.fps, 15.0);
457	}
458
459	#[test]
460	fn values_starting_with_a_dash_stay_values() {
461		let cli: TestCli = parse(&[], &[("broadcast", string("-x"))]).unwrap();
462		assert_eq!(cli.broadcast.as_deref(), Some("-x"));
463	}
464
465	#[test]
466	fn unset_and_unknown_params_are_ignored() {
467		let params = [
468			("broadcast", ParameterValue::NotSet),
469			("use_sim_time", ParameterValue::Bool(false)),
470			("bitrat", ParameterValue::Integer(1)),
471			("keyframe-interval-ms", ParameterValue::Integer(1)),
472			// Clap's own arguments aren't parameters.
473			("help", ParameterValue::Bool(true)),
474			("version", string("2")),
475		];
476		assert!(flags::<TestCli>(&params).unwrap().is_empty());
477	}
478
479	#[test]
480	fn arrays_fill_repeatable_flags() {
481		let topics = |cli: MultiCli| cli.topic.into_iter().map(|spec| spec.topic).collect::<Vec<_>>();
482		assert_eq!(topics(parse(&[], &[]).unwrap()), ["/image_raw"]);
483		let params = [(
484			"topic",
485			ParameterValue::StringArray(vec!["/a".into(), "/b,format=json".into()]),
486		)];
487		let cli: MultiCli = parse(&[], &params).unwrap();
488		assert_eq!(cli.topic[1].format, Some(Format::Json));
489		assert_eq!(topics(cli), ["/a", "/b"]);
490		// A single string still works, and the command line replaces the whole list.
491		assert_eq!(topics(parse(&[], &[("topic", string("/c"))]).unwrap()), ["/c"]);
492		assert_eq!(topics(parse(&["--topic", "/d"], &params).unwrap()), ["/d"]);
493	}
494
495	#[test]
496	fn arrays_are_rejected() {
497		let params = [("topic", ParameterValue::StringArray(vec!["/a".into()]))];
498		let err = flags::<TestCli>(&params).unwrap_err();
499		assert!(err.to_string().contains("`topic`"), "{err}");
500	}
501
502	#[test]
503	fn invalid_param_values_are_blamed_on_the_param() {
504		for (name, value) in [("keyframe_interval_ms", "soon"), ("url", "not a url")] {
505			match parse::<TestCli>(&[], &[(name, string(value))]) {
506				Err(ParseError::Param(err)) => assert_eq!(err.kind(), ErrorKind::ValueValidation, "{name}"),
507				other => panic!("{name}: {other:?}"),
508			}
509		}
510	}
511
512	#[test]
513	fn invalid_command_lines_are_blamed_on_the_command_line() {
514		let params = [("keyframe_interval_ms", string("soon"))];
515		for args in [&["--fps=fast"][..], &["--unknown"]] {
516			assert!(
517				matches!(parse::<TestCli>(args, &params), Err(ParseError::CommandLine(_))),
518				"{args:?}"
519			);
520		}
521	}
522
523	#[test]
524	fn detects_help_and_version() {
525		let kind = |args_: &[&str]| help_or_version(TestCli::command(), &args(args_)).map(|err| err.kind());
526		assert_eq!(kind(&["--help"]), Some(ErrorKind::DisplayHelp));
527		assert_eq!(kind(&["-V"]), Some(ErrorKind::DisplayVersion));
528		// Arguments after the help flag aren't looked at.
529		assert_eq!(kind(&["-h", "--fps=fast"]), Some(ErrorKind::DisplayHelp));
530		assert_eq!(kind(&["--topic", "/a"]), None);
531		assert_eq!(kind(&["--fps=fast"]), None);
532	}
533}