Plugin explicit flags (#11581)

# Description
#11492 fixed flags for builtin commands but I missed that plugins don't
use the same `has_flag` that builtins do. This PR addresses this.

Unfortunately this means that return value of `has_flag` needs to change
from `bool` to `Result<bool, ShellError>` to produce an error when
explicit value is not a boolean (just like in case of `has_flag` for
builtin commands. It is not possible to check this in
`EvaluatedCall::try_from_call` because

# User-Facing Changes
Passing explicit values to flags of plugin commands (like `--flag=true`
`--flag=false`) should work now.
BREAKING: changed return value of `EvaluatedCall::has_flag` method from
`bool` to `Result<bool, ShellError>`

# Tests + Formatting
Added tests and updated documentation and examples

crates/nu-plugin/src/protocol/evaluated_call.rs

@@ -53,10 +53,10 @@ impl EvaluatedCall {
         })
     }
 
-    /// Indicates whether named parameter is present in the arguments
-    ///
-    /// Typically this method would be used on a flag parameter, a named parameter
-    /// that does not take a value.
+    /// Check if a flag (named parameter that does not take a value) is set
+    /// Returns Ok(true) if flag is set or passed true value
+    /// Returns Ok(false) if flag is not set or passed false value
+    /// Returns Err if passed value is not a boolean
     ///
     /// # Examples
     /// Invoked as `my_command --foo`:
@@ -72,7 +72,7 @@ impl EvaluatedCall {
     /// #         None
     /// #     )],
     /// # };
-    /// assert!(call.has_flag("foo"));
+    /// assert!(call.has_flag("foo").unwrap());
     /// ```
     ///
     /// Invoked as `my_command --bar`:
@@ -88,16 +88,73 @@ impl EvaluatedCall {
     /// #         None
     /// #     )],
     /// # };
-    /// assert!(!call.has_flag("foo"));
+    /// assert!(!call.has_flag("foo").unwrap());
     /// ```
-    pub fn has_flag(&self, flag_name: &str) -> bool {
+    ///
+    /// Invoked as `my_command --foo=true`:
+    /// ```
+    /// # use nu_protocol::{Spanned, Span, Value};
+    /// # use nu_plugin::EvaluatedCall;
+    /// # let null_span = Span::new(0, 0);
+    /// # let call = EvaluatedCall {
+    /// #     head: null_span,
+    /// #     positional: Vec::new(),
+    /// #     named: vec![(
+    /// #         Spanned { item: "foo".to_owned(), span: null_span},
+    /// #         Some(Value::bool(true, Span::unknown()))
+    /// #     )],
+    /// # };
+    /// assert!(call.has_flag("foo").unwrap());
+    /// ```
+    ///
+    /// Invoked as `my_command --foo=false`:
+    /// ```
+    /// # use nu_protocol::{Spanned, Span, Value};
+    /// # use nu_plugin::EvaluatedCall;
+    /// # let null_span = Span::new(0, 0);
+    /// # let call = EvaluatedCall {
+    /// #     head: null_span,
+    /// #     positional: Vec::new(),
+    /// #     named: vec![(
+    /// #         Spanned { item: "foo".to_owned(), span: null_span},
+    /// #         Some(Value::bool(false, Span::unknown()))
+    /// #     )],
+    /// # };
+    /// assert!(!call.has_flag("foo").unwrap());
+    /// ```
+    ///
+    /// Invoked with wrong type as `my_command --foo=1`:
+    /// ```
+    /// # use nu_protocol::{Spanned, Span, Value};
+    /// # use nu_plugin::EvaluatedCall;
+    /// # let null_span = Span::new(0, 0);
+    /// # let call = EvaluatedCall {
+    /// #     head: null_span,
+    /// #     positional: Vec::new(),
+    /// #     named: vec![(
+    /// #         Spanned { item: "foo".to_owned(), span: null_span},
+    /// #         Some(Value::int(1, Span::unknown()))
+    /// #     )],
+    /// # };
+    /// assert!(call.has_flag("foo").is_err());
+    /// ```
+    pub fn has_flag(&self, flag_name: &str) -> Result<bool, ShellError> {
         for name in &self.named {
             if flag_name == name.0.item {
-                return true;
+                return match &name.1 {
+                    Some(Value::Bool { val, .. }) => Ok(*val),
+                    None => Ok(true),
+                    Some(result) => Err(ShellError::CantConvert {
+                        to_type: "bool".into(),
+                        from_type: result.get_type().to_string(),
+                        span: result.span(),
+                        help: Some("".into()),
+                    }),
+                };
             }
         }
 
-        false
+        Ok(false)
     }
 
     /// Returns the [`Value`] of an optional named argument
@@ -340,7 +397,7 @@ mod test {
         let name: Option<f64> = call.get_flag("name").unwrap();
         assert_eq!(name, Some(1.0));
 
-        assert!(call.has_flag("flag"));
+        assert!(call.has_flag("flag").unwrap());
 
         let required: f64 = call.req(0).unwrap();
         assert!((required - 1.0).abs() < f64::EPSILON);