Skip to main content

nu_protocol/engine/
named_flags.rs

1//! Helpers for signature-aware named flag handling (null omit/pass-through and
2//! long-key record flag spreads).
3//!
4//! Used by IR evaluation before dispatch and by const evaluation when building
5//! IR-shaped calls.
6
7use std::sync::Arc;
8
9use crate::{
10    CompareTypes, Flag, Record, ShellError, Signature, Span, Value, engine::Argument,
11    ir::DataSlice, shell_error::generic::GenericError,
12};
13
14/// Whether a named flag's value type accepts `nothing`/`null`.
15#[inline]
16pub fn flag_type_accepts_nothing(flag: &Flag) -> bool {
17    flag.type_accepts_nothing()
18}
19
20pub fn find_signature_flag<'a>(
21    signature: &'a Signature,
22    long: &[u8],
23    short: &[u8],
24) -> Option<&'a Flag> {
25    signature.named.iter().find(|flag| {
26        (!long.is_empty() && flag.long.as_bytes() == long)
27            || (!short.is_empty()
28                && flag.short.is_some_and(|c| {
29                    let mut buf = [0u8; 4];
30                    c.encode_utf8(&mut buf).as_bytes() == short
31                }))
32    })
33}
34
35pub fn data_from_name_and_short(name: &str, short: &str) -> (Arc<[u8]>, DataSlice, DataSlice) {
36    let data: Vec<u8> = name.bytes().chain(short.bytes()).collect();
37    let data: Arc<[u8]> = data.into();
38    // Flag names are parser identifiers — never near u32::MAX.
39    #[allow(clippy::cast_possible_truncation)]
40    let name_len = name.len() as u32;
41    #[allow(clippy::cast_possible_truncation)]
42    let short_len = short.len() as u32;
43    let name = DataSlice {
44        start: 0,
45        len: name_len,
46    };
47    let short = DataSlice {
48        start: name_len,
49        len: short_len,
50    };
51    (data, name, short)
52}
53
54/// Expand a record into named/flag arguments for a call.
55///
56/// - `null` field values: passed through if the flag type accepts `nothing`, otherwise omitted
57/// - switch flags (`--flag` with no value): `true` sets the flag, `false`/`null` omit it
58/// - valued flags: non-null values become `--name value` (type-checked against the signature)
59pub fn expand_flag_record(
60    signature: &Signature,
61    record: Record,
62    spread_span: Span,
63) -> Result<Vec<Argument>, ShellError> {
64    let mut out = Vec::with_capacity(record.len());
65    for (key, val) in record {
66        let Some(flag) = signature.get_long_flag(&key) else {
67            return Err(ShellError::Generic(GenericError::new(
68                format!("Unknown flag `{key}` in spread record"),
69                format!("`{key}` is not a named argument of this command"),
70                spread_span,
71            )));
72        };
73
74        let short = flag
75            .short
76            .map(|c| {
77                let mut buf = [0u8; 4];
78                c.encode_utf8(&mut buf).to_string()
79            })
80            .unwrap_or_default();
81        let (data, name_slice, short_slice) = data_from_name_and_short(&flag.long, &short);
82
83        if flag.arg.is_none() {
84            // Switch: only `true` sets the flag; `false`/`null` omit (like `--flag=false`).
85            match val {
86                Value::Bool { val: true, .. } => {
87                    out.push(Argument::Flag {
88                        data,
89                        name: name_slice,
90                        short: short_slice,
91                        span: spread_span,
92                    });
93                }
94                Value::Bool { val: false, .. } | Value::Nothing { .. } => {}
95                other => {
96                    return Err(ShellError::CantConvert {
97                        to_type: "bool".into(),
98                        from_type: other.get_type().to_string(),
99                        span: other.span(),
100                        help: Some(format!(
101                            "spread field `{key}` is a switch; use true/false or omit/null"
102                        )),
103                    });
104                }
105            }
106        } else if val.is_nothing() && !flag_type_accepts_nothing(&flag) {
107            // Null → omit when the flag type does not accept nothing.
108        } else {
109            if !val.is_nothing()
110                && let Some(shape) = &flag.arg
111            {
112                let expected = shape.to_type();
113                if !val.is_assignable_to(&expected) {
114                    return Err(ShellError::CantConvert {
115                        to_type: expected.to_string(),
116                        from_type: val.get_type().to_string(),
117                        span: val.span(),
118                        help: Some(format!(
119                            "spread field `{key}` does not match the type of `--{key}`"
120                        )),
121                    });
122                }
123            }
124            out.push(Argument::Named {
125                data,
126                name: name_slice,
127                short: short_slice,
128                span: spread_span,
129                val,
130            });
131        }
132    }
133    Ok(out)
134}
135
136/// Whether this signature can accept a list rest spread.
137pub fn can_rest_spread(signature: &Signature) -> bool {
138    signature.rest_positional.is_some() || signature.allows_unknown_args
139}
140
141/// Error when a list is spread into a command that has no rest parameter to receive it.
142pub fn list_spread_without_rest_error(spread_span: Span) -> ShellError {
143    ShellError::Generic(GenericError::new(
144        "Cannot spread a list into this command",
145        "This command has no ...rest parameter to receive a list spread. Use a record to spread named flags, e.g. ...{flag: value}",
146        spread_span,
147    ))
148}
149
150/// Error when a list (or null rest-mode) is spread while required positionals remain unbound.
151pub fn list_spread_before_required_error(spread_span: Span) -> ShellError {
152    ShellError::Generic(GenericError::new(
153        "Cannot spread a list before required positional arguments are provided",
154        "List spreads fill rest arguments. Provide required positionals first, or use a record to spread named flags, e.g. ...{flag: value}",
155        spread_span,
156    ))
157}
158
159/// Apply signature-aware null handling and expand record spreads for engine [`Argument`]s.
160///
161/// List spreads are rejected when the command has no rest parameter (and does not allow
162/// unknown args), so `...$list` cannot be silently dropped on named-only commands.
163pub fn normalize_engine_arguments(
164    signature: &Signature,
165    args: Vec<Argument>,
166) -> Result<Vec<Argument>, ShellError> {
167    let mut expanded = Vec::with_capacity(args.len());
168
169    for arg in args {
170        match arg {
171            Argument::Named {
172                data,
173                name,
174                short,
175                span,
176                val: Value::Nothing { .. },
177            } => {
178                let accepts = find_signature_flag(signature, &data[name], &data[short])
179                    .is_some_and(flag_type_accepts_nothing);
180                if accepts {
181                    expanded.push(Argument::Named {
182                        data,
183                        name,
184                        short,
185                        span,
186                        val: Value::nothing(span),
187                    });
188                }
189                // else: null → omit
190            }
191            Argument::Spread {
192                vals,
193                span: spread_span,
194            } => match vals {
195                Value::Record { val, .. } => {
196                    expanded.extend(expand_flag_record(
197                        signature,
198                        val.into_owned(),
199                        spread_span,
200                    )?);
201                }
202                Value::List { .. } => {
203                    if !can_rest_spread(signature) {
204                        return Err(list_spread_without_rest_error(spread_span));
205                    }
206                    expanded.push(Argument::Spread {
207                        vals,
208                        span: spread_span,
209                    });
210                }
211                Value::Nothing { .. } | Value::Error { .. } => {
212                    expanded.push(Argument::Spread {
213                        vals,
214                        span: spread_span,
215                    });
216                }
217                other => {
218                    return Err(ShellError::CannotSpreadAsList { span: other.span() });
219                }
220            },
221            other => expanded.push(other),
222        }
223    }
224
225    Ok(expanded)
226}