nu_plugin_protocol/evaluated_call.rs
1use nu_protocol::{
2 FromValue, ShellError, Span, Spanned, Value,
3 ast::{self, Expression},
4 engine::{Call, CallImpl, EngineState, Stack},
5 ir,
6};
7use serde::{Deserialize, Serialize};
8
9/// A representation of the plugin's invocation command including command line args
10///
11/// The `EvaluatedCall` contains information about the way a `Plugin` was invoked representing the
12/// [`Span`] corresponding to the invocation as well as the arguments it was invoked with. It is
13/// one of the items passed to `PluginCommand::run()`, along with the plugin reference, the engine
14/// interface, and a [`Value`] that represents the input.
15///
16/// The evaluated call is used with the Plugins because the plugin doesn't have
17/// access to the Stack and the EngineState the way a built in command might. For that
18/// reason, before encoding the message to the plugin all the arguments to the original
19/// call (which are expressions) are evaluated and passed to Values
20#[derive(Debug, Clone, Serialize, Deserialize)]
21pub struct EvaluatedCall {
22 /// Span of the command invocation
23 pub head: Span,
24 /// Values of positional arguments
25 pub positional: Vec<Value>,
26 /// Names and values of named arguments
27 pub named: Vec<(Spanned<String>, Option<Value>)>,
28}
29
30impl EvaluatedCall {
31 /// Create a new [`EvaluatedCall`] with the given head span.
32 pub fn new(head: Span) -> EvaluatedCall {
33 EvaluatedCall {
34 head,
35 positional: vec![],
36 named: vec![],
37 }
38 }
39
40 /// Add a positional argument to an [`EvaluatedCall`].
41 ///
42 /// # Example
43 ///
44 /// ```rust
45 /// # use nu_protocol::{Value, Span, IntoSpanned};
46 /// # use nu_plugin_protocol::EvaluatedCall;
47 /// # let head = Span::test_data();
48 /// let mut call = EvaluatedCall::new(head);
49 /// call.add_positional(Value::test_int(1337));
50 /// ```
51 pub fn add_positional(&mut self, value: Value) -> &mut Self {
52 self.positional.push(value);
53 self
54 }
55
56 /// Add a named argument to an [`EvaluatedCall`].
57 ///
58 /// # Example
59 ///
60 /// ```rust
61 /// # use nu_protocol::{Value, Span, IntoSpanned};
62 /// # use nu_plugin_protocol::EvaluatedCall;
63 /// # let head = Span::test_data();
64 /// let mut call = EvaluatedCall::new(head);
65 /// call.add_named("foo".into_spanned(head), Value::test_string("bar"));
66 /// ```
67 pub fn add_named(&mut self, name: Spanned<impl Into<String>>, value: Value) -> &mut Self {
68 self.named.push((name.map(Into::into), Some(value)));
69 self
70 }
71
72 /// Add a flag argument to an [`EvaluatedCall`]. A flag argument is a named argument with no
73 /// value.
74 ///
75 /// # Example
76 ///
77 /// ```rust
78 /// # use nu_protocol::{Value, Span, IntoSpanned};
79 /// # use nu_plugin_protocol::EvaluatedCall;
80 /// # let head = Span::test_data();
81 /// let mut call = EvaluatedCall::new(head);
82 /// call.add_flag("pretty".into_spanned(head));
83 /// ```
84 pub fn add_flag(&mut self, name: Spanned<impl Into<String>>) -> &mut Self {
85 self.named.push((name.map(Into::into), None));
86 self
87 }
88
89 /// Builder variant of [`.add_positional()`](Self::add_positional).
90 pub fn with_positional(mut self, value: Value) -> Self {
91 self.add_positional(value);
92 self
93 }
94
95 /// Builder variant of [`.add_named()`](Self::add_named).
96 pub fn with_named(mut self, name: Spanned<impl Into<String>>, value: Value) -> Self {
97 self.add_named(name, value);
98 self
99 }
100
101 /// Builder variant of [`.add_flag()`](Self::add_flag).
102 pub fn with_flag(mut self, name: Spanned<impl Into<String>>) -> Self {
103 self.add_flag(name);
104 self
105 }
106
107 /// Try to create an [`EvaluatedCall`] from a command `Call`.
108 pub fn try_from_call(
109 call: &Call,
110 engine_state: &EngineState,
111 stack: &mut Stack,
112 eval_expression_fn: fn(&EngineState, &mut Stack, &Expression) -> Result<Value, ShellError>,
113 ) -> Result<Self, ShellError> {
114 match &call.inner {
115 CallImpl::AstRef(call) => {
116 Self::try_from_ast_call(call, engine_state, stack, eval_expression_fn)
117 }
118 CallImpl::AstBox(call) => {
119 Self::try_from_ast_call(call, engine_state, stack, eval_expression_fn)
120 }
121 CallImpl::IrRef(call) => Self::try_from_ir_call(call, stack),
122 CallImpl::IrBox(call) => Self::try_from_ir_call(call, stack),
123 }
124 }
125
126 fn try_from_ast_call(
127 call: &ast::Call,
128 engine_state: &EngineState,
129 stack: &mut Stack,
130 eval_expression_fn: fn(&EngineState, &mut Stack, &Expression) -> Result<Value, ShellError>,
131 ) -> Result<Self, ShellError> {
132 let positional =
133 call.rest_iter_flattened(0, |expr| eval_expression_fn(engine_state, stack, expr))?;
134
135 let mut named = Vec::with_capacity(call.named_len());
136 for (string, _, expr) in call.named_iter() {
137 let value = match expr {
138 None => None,
139 Some(expr) => Some(eval_expression_fn(engine_state, stack, expr)?),
140 };
141
142 named.push((string.clone(), value))
143 }
144
145 Ok(Self {
146 head: call.head,
147 positional,
148 named,
149 })
150 }
151
152 fn try_from_ir_call(call: &ir::Call, stack: &Stack) -> Result<Self, ShellError> {
153 let positional = call.rest_iter_flattened(stack, 0)?;
154
155 let mut named = Vec::with_capacity(call.named_len(stack));
156 named.extend(
157 call.named_iter(stack)
158 .map(|(name, value)| (name.map(|s| s.to_owned()), value.cloned())),
159 );
160
161 Ok(Self {
162 head: call.head,
163 positional,
164 named,
165 })
166 }
167
168 /// Check if a flag (named parameter that does not take a value) is set
169 /// Returns Ok(true) if flag is set or passed true value
170 /// Returns Ok(false) if flag is not set or passed false value
171 /// Returns Err if passed value is not a boolean
172 ///
173 /// # Examples
174 /// Invoked as `my_command --foo`:
175 /// ```
176 /// # use nu_protocol::{Spanned, Span, Value};
177 /// # use nu_plugin_protocol::EvaluatedCall;
178 /// # let null_span = Span::new(0, 0);
179 /// # let call = EvaluatedCall {
180 /// # head: null_span,
181 /// # positional: Vec::new(),
182 /// # named: vec![(
183 /// # Spanned { item: "foo".to_owned(), span: null_span},
184 /// # None
185 /// # )],
186 /// # };
187 /// assert!(call.has_flag("foo").unwrap());
188 /// ```
189 ///
190 /// Invoked as `my_command --bar`:
191 /// ```
192 /// # use nu_protocol::{Spanned, Span, Value};
193 /// # use nu_plugin_protocol::EvaluatedCall;
194 /// # let null_span = Span::new(0, 0);
195 /// # let call = EvaluatedCall {
196 /// # head: null_span,
197 /// # positional: Vec::new(),
198 /// # named: vec![(
199 /// # Spanned { item: "bar".to_owned(), span: null_span},
200 /// # None
201 /// # )],
202 /// # };
203 /// assert!(!call.has_flag("foo").unwrap());
204 /// ```
205 ///
206 /// Invoked as `my_command --foo=true`:
207 /// ```
208 /// # use nu_protocol::{Spanned, Span, Value};
209 /// # use nu_plugin_protocol::EvaluatedCall;
210 /// # let null_span = Span::new(0, 0);
211 /// # let call = EvaluatedCall {
212 /// # head: null_span,
213 /// # positional: Vec::new(),
214 /// # named: vec![(
215 /// # Spanned { item: "foo".to_owned(), span: null_span},
216 /// # Some(Value::bool(true, Span::unknown()))
217 /// # )],
218 /// # };
219 /// assert!(call.has_flag("foo").unwrap());
220 /// ```
221 ///
222 /// Invoked as `my_command --foo=false`:
223 /// ```
224 /// # use nu_protocol::{Spanned, Span, Value};
225 /// # use nu_plugin_protocol::EvaluatedCall;
226 /// # let null_span = Span::new(0, 0);
227 /// # let call = EvaluatedCall {
228 /// # head: null_span,
229 /// # positional: Vec::new(),
230 /// # named: vec![(
231 /// # Spanned { item: "foo".to_owned(), span: null_span},
232 /// # Some(Value::bool(false, Span::unknown()))
233 /// # )],
234 /// # };
235 /// assert!(!call.has_flag("foo").unwrap());
236 /// ```
237 ///
238 /// Invoked with wrong type as `my_command --foo=1`:
239 /// ```
240 /// # use nu_protocol::{Spanned, Span, Value};
241 /// # use nu_plugin_protocol::EvaluatedCall;
242 /// # let null_span = Span::new(0, 0);
243 /// # let call = EvaluatedCall {
244 /// # head: null_span,
245 /// # positional: Vec::new(),
246 /// # named: vec![(
247 /// # Spanned { item: "foo".to_owned(), span: null_span},
248 /// # Some(Value::int(1, Span::unknown()))
249 /// # )],
250 /// # };
251 /// assert!(call.has_flag("foo").is_err());
252 /// ```
253 pub fn has_flag(&self, flag_name: &str) -> Result<bool, ShellError> {
254 for name in &self.named {
255 if flag_name == name.0.item {
256 return match &name.1 {
257 Some(Value::Bool { val, .. }) => Ok(*val),
258 None => Ok(true),
259 Some(result) => Err(ShellError::CantConvert {
260 to_type: "bool".into(),
261 from_type: result.get_type().to_string(),
262 span: result.span(),
263 help: Some("".into()),
264 }),
265 };
266 }
267 }
268
269 Ok(false)
270 }
271
272 /// Returns the [`Span`] of the name of an optional named argument.
273 ///
274 /// This can be used in errors for named arguments that don't take values.
275 pub fn get_flag_span(&self, flag_name: &str) -> Option<Span> {
276 self.named
277 .iter()
278 .find(|(name, _)| name.item == flag_name)
279 .map(|(name, _)| name.span)
280 }
281
282 /// Returns the [`Value`] of an optional named argument
283 ///
284 /// # Examples
285 /// Invoked as `my_command --foo 123`:
286 /// ```
287 /// # use nu_protocol::{Spanned, Span, Value};
288 /// # use nu_plugin_protocol::EvaluatedCall;
289 /// # let null_span = Span::new(0, 0);
290 /// # let call = EvaluatedCall {
291 /// # head: null_span,
292 /// # positional: Vec::new(),
293 /// # named: vec![(
294 /// # Spanned { item: "foo".to_owned(), span: null_span},
295 /// # Some(Value::int(123, null_span))
296 /// # )],
297 /// # };
298 /// let opt_foo = match call.get_flag_value("foo") {
299 /// Some(Value::Int { val, .. }) => Some(val),
300 /// None => None,
301 /// _ => panic!(),
302 /// };
303 /// assert_eq!(opt_foo, Some(123));
304 /// ```
305 ///
306 /// Invoked as `my_command`:
307 /// ```
308 /// # use nu_protocol::{Spanned, Span, Value};
309 /// # use nu_plugin_protocol::EvaluatedCall;
310 /// # let null_span = Span::new(0, 0);
311 /// # let call = EvaluatedCall {
312 /// # head: null_span,
313 /// # positional: Vec::new(),
314 /// # named: vec![],
315 /// # };
316 /// let opt_foo = match call.get_flag_value("foo") {
317 /// Some(Value::Int { val, .. }) => Some(val),
318 /// None => None,
319 /// _ => panic!(),
320 /// };
321 /// assert_eq!(opt_foo, None);
322 /// ```
323 pub fn get_flag_value(&self, flag_name: &str) -> Option<Value> {
324 for name in &self.named {
325 if flag_name == name.0.item {
326 return name.1.clone();
327 }
328 }
329
330 None
331 }
332
333 /// Returns the [`Value`] of a given (zero indexed) positional argument, if present
334 ///
335 /// Examples:
336 /// Invoked as `my_command a b c`:
337 /// ```
338 /// # use nu_protocol::{Spanned, Span, Value};
339 /// # use nu_plugin_protocol::EvaluatedCall;
340 /// # let null_span = Span::new(0, 0);
341 /// # let call = EvaluatedCall {
342 /// # head: null_span,
343 /// # positional: vec![
344 /// # Value::string("a".to_owned(), null_span),
345 /// # Value::string("b".to_owned(), null_span),
346 /// # Value::string("c".to_owned(), null_span),
347 /// # ],
348 /// # named: vec![],
349 /// # };
350 /// let arg = match call.nth(1) {
351 /// Some(Value::String { val, .. }) => val,
352 /// _ => panic!(),
353 /// };
354 /// assert_eq!(arg, "b".to_owned());
355 ///
356 /// let arg = call.nth(7);
357 /// assert!(arg.is_none());
358 /// ```
359 pub fn nth(&self, pos: usize) -> Option<Value> {
360 self.positional.get(pos).cloned()
361 }
362
363 /// Returns the value of a named argument interpreted as type `T`
364 ///
365 /// # Examples
366 /// Invoked as `my_command --foo 123`:
367 /// ```
368 /// # use nu_protocol::{Spanned, Span, Value};
369 /// # use nu_plugin_protocol::EvaluatedCall;
370 /// # let null_span = Span::new(0, 0);
371 /// # let call = EvaluatedCall {
372 /// # head: null_span,
373 /// # positional: Vec::new(),
374 /// # named: vec![(
375 /// # Spanned { item: "foo".to_owned(), span: null_span},
376 /// # Some(Value::int(123, null_span))
377 /// # )],
378 /// # };
379 /// let foo = call.get_flag::<i64>("foo");
380 /// assert_eq!(foo.unwrap(), Some(123));
381 /// ```
382 ///
383 /// Invoked as `my_command --bar 123`:
384 /// ```
385 /// # use nu_protocol::{Spanned, Span, Value};
386 /// # use nu_plugin_protocol::EvaluatedCall;
387 /// # let null_span = Span::new(0, 0);
388 /// # let call = EvaluatedCall {
389 /// # head: null_span,
390 /// # positional: Vec::new(),
391 /// # named: vec![(
392 /// # Spanned { item: "bar".to_owned(), span: null_span},
393 /// # Some(Value::int(123, null_span))
394 /// # )],
395 /// # };
396 /// let foo = call.get_flag::<i64>("foo");
397 /// assert_eq!(foo.unwrap(), None);
398 /// ```
399 ///
400 /// Invoked as `my_command --foo abc`:
401 /// ```
402 /// # use nu_protocol::{Spanned, Span, Value};
403 /// # use nu_plugin_protocol::EvaluatedCall;
404 /// # let null_span = Span::new(0, 0);
405 /// # let call = EvaluatedCall {
406 /// # head: null_span,
407 /// # positional: Vec::new(),
408 /// # named: vec![(
409 /// # Spanned { item: "foo".to_owned(), span: null_span},
410 /// # Some(Value::string("abc".to_owned(), null_span))
411 /// # )],
412 /// # };
413 /// let foo = call.get_flag::<i64>("foo");
414 /// assert!(foo.is_err());
415 /// ```
416 pub fn get_flag<T: FromValue>(&self, name: &str) -> Result<Option<T>, ShellError> {
417 if let Some(value) = self.get_flag_value(name) {
418 FromValue::from_value(value).map(Some)
419 } else {
420 Ok(None)
421 }
422 }
423
424 /// Retrieve the Nth and all following positional arguments as type `T`
425 ///
426 /// # Example
427 /// Invoked as `my_command zero one two three`:
428 /// ```
429 /// # use nu_protocol::{Spanned, Span, Value};
430 /// # use nu_plugin_protocol::EvaluatedCall;
431 /// # let null_span = Span::new(0, 0);
432 /// # let call = EvaluatedCall {
433 /// # head: null_span,
434 /// # positional: vec![
435 /// # Value::string("zero".to_owned(), null_span),
436 /// # Value::string("one".to_owned(), null_span),
437 /// # Value::string("two".to_owned(), null_span),
438 /// # Value::string("three".to_owned(), null_span),
439 /// # ],
440 /// # named: Vec::new(),
441 /// # };
442 /// let args = call.rest::<String>(0);
443 /// assert_eq!(args.unwrap(), vec!["zero", "one", "two", "three"]);
444 ///
445 /// let args = call.rest::<String>(2);
446 /// assert_eq!(args.unwrap(), vec!["two", "three"]);
447 /// ```
448 pub fn rest<T: FromValue>(&self, starting_pos: usize) -> Result<Vec<T>, ShellError> {
449 self.positional
450 .iter()
451 .skip(starting_pos)
452 .map(|value| FromValue::from_value(value.clone()))
453 .collect()
454 }
455
456 /// Retrieve the value of an optional positional argument interpreted as type `T`
457 ///
458 /// Returns the value of a (zero indexed) positional argument of type `T`.
459 /// Alternatively returns [`None`] if the positional argument does not exist
460 /// or an error that can be passed back to the shell on error.
461 pub fn opt<T: FromValue>(&self, pos: usize) -> Result<Option<T>, ShellError> {
462 if let Some(value) = self.nth(pos) {
463 FromValue::from_value(value).map(Some)
464 } else {
465 Ok(None)
466 }
467 }
468
469 /// Retrieve the value of a mandatory positional argument as type `T`
470 ///
471 /// Expect a positional argument of type `T` and return its value or, if the
472 /// argument does not exist or is of the wrong type, return an error that can
473 /// be passed back to the shell.
474 pub fn req<T: FromValue>(&self, pos: usize) -> Result<T, ShellError> {
475 if let Some(value) = self.nth(pos) {
476 FromValue::from_value(value)
477 } else if self.positional.is_empty() {
478 Err(ShellError::AccessEmptyContent { span: self.head })
479 } else {
480 Err(ShellError::AccessBeyondEnd {
481 max_idx: self.positional.len() - 1,
482 span: self.head,
483 })
484 }
485 }
486}
487
488#[cfg(test)]
489mod test {
490 use super::*;
491 use nu_protocol::{Span, Spanned, Value};
492
493 #[test]
494 fn call_to_value() {
495 let call = EvaluatedCall {
496 head: Span::new(0, 10),
497 positional: vec![
498 Value::float(1.0, Span::new(0, 10)),
499 Value::string("something", Span::new(0, 10)),
500 ],
501 named: vec![
502 (
503 Spanned {
504 item: "name".to_string(),
505 span: Span::new(0, 10),
506 },
507 Some(Value::float(1.0, Span::new(0, 10))),
508 ),
509 (
510 Spanned {
511 item: "flag".to_string(),
512 span: Span::new(0, 10),
513 },
514 None,
515 ),
516 ],
517 };
518
519 let name: Option<f64> = call.get_flag("name").unwrap();
520 assert_eq!(name, Some(1.0));
521
522 assert!(call.has_flag("flag").unwrap());
523
524 let required: f64 = call.req(0).unwrap();
525 assert!((required - 1.0).abs() < f64::EPSILON);
526
527 let optional: Option<String> = call.opt(1).unwrap();
528 assert_eq!(optional, Some("something".to_string()));
529
530 let rest: Vec<String> = call.rest(1).unwrap();
531 assert_eq!(rest, vec!["something".to_string()]);
532 }
533}