feat(macros): derive ParameterVariant for enums and newtypes

[azerupi]

The code in this PR was assisted by Claude Code.

Problem

Using a custom enum or newtype as a parameter is boilerplate heavy. It requires three trait implementations, and a constraints string kept in step with the type by hand:

#[derive(Clone, Debug, PartialEq)]
enum ControlMode {
    Velocity,
    Position,
    Effort,
}

impl From<ControlMode> for ParameterValue {
    fn from(value: ControlMode) -> Self {
        ParameterValue::String(
            match value {
                ControlMode::Velocity => "velocity",
                ControlMode::Position => "position",
                ControlMode::Effort => "torque",
            }
            .into(),
        )
    }
}

impl TryFrom<ParameterValue> for ControlMode {
    type Error = ParameterValueError;

    fn try_from(value: ParameterValue) -> Result<Self, Self::Error> {
        match value {
            ParameterValue::String(s) => match s.as_ref() {
                "velocity" => Ok(ControlMode::Velocity),
                "position" => Ok(ControlMode::Position),
                "torque" => Ok(ControlMode::Effort),
                other => Err(ParameterValueError::Invalid(format!(
                    "unknown ControlMode '{other}', expected one of: velocity, position, torque"
                ))),
            },
            _ => Err(ParameterValueError::TypeMismatch),
        }
    }
}

impl ParameterVariant for ControlMode {
    type Range = ();

    fn kind() -> ParameterKind {
        ParameterKind::String
    }

    fn type_constraints() -> Option<Arc<str>> {
        Some("one of: velocity, position, torque".into())
    }
}

declare_parameter_field!(ControlMode);

Solution

#[derive(ParameterVariant)] generates all of that. The representation follows from the shape of the type, so the enum above becomes:

/// Which quantity a controller closes the loop on.
#[derive(ParameterVariant, Clone, Copy, Debug, PartialEq)]
#[parameter(rename_all = "snake_case")]
enum ControlMode {
    Velocity,
    Position,
    #[parameter(rename = "torque")]
    Effort,
}

let mode = node.declare_parameter("mode").default(ControlMode::Velocity).mandatory()?;

match mode.get() {
    ControlMode::Velocity => ...,
    ControlMode::Position => ...,
    ControlMode::Effort   => ...,   // exhaustive, no impossible arm
}

The valid values reach the descriptor, so introspection reports them without any declaration restating them:

$ ros2 param describe /controller mode
  Constraints: one of: velocity, position, torque

$ ros2 param set /controller mode reverse
Setting parameter failed: unknown ControlMode 'reverse', expected one of:
velocity, position, torque

This works for 3 type patterns:

Written	Stored as
an enum whose variants carry no data	a string, one spelling per variant
#[parameter(transparent)] on a newtype or struct with one field	whatever the wrapped value is stored as
#[parameter(from_str)]	a string, via FromStr and Display

transparent uses the inner type's range and its validation, so units cost nothing:

#[derive(ParameterVariant, Clone, Copy, PartialEq, PartialOrd, Default)]
#[parameter(transparent)]
struct Meters(pub f64);

// range in metres, because the range type comes from the f64 inside
node.declare_parameter("depth").default(Meters(1.0)).range(0.0..=10.0).mandatory()?;

and a Port(u16) rejects 70000 exactly as a u16 does, because it is a u16 underneath.

from_str is for a type that already parses itself. The FromStr error becomes the reason a value was rejected, so it is worth writing well:

#[derive(ParameterVariant, Clone, Debug, PartialEq)]
#[parameter(from_str)]
struct Hostname(String);

A derived type is a parameter value everywhere: through the builder, as a field of a #[derive(ParameterSet)] struct, and through declare_parameter_with, since ParameterConversion::of_variant assembles a conversion from what the derive emits.

The derive also emits declare_parameter_field!, so a derived type is usable as a set field with no further work.