feat!(stdlib): Add required optional default to Parameter

benches/kind.rs

@@ -27,6 +27,8 @@ fn benchmark_kind_display(c: &mut Criterion) {
             keyword: "",
             kind: param.basis,
             required: false,
+            description: "",
+            default: None,
         };
 
         let kind = parameter.kind();

changelog.d/1610.breaking.md

@@ -0,0 +1,4 @@
+The `Parameter` struct now requires a `description` field. Custom VRL functions must provide a
+description for each parameter when defining the `parameters()` method.
+
+authors: thomasqueirozb

src/compiler/expression.rs

@@ -428,3 +428,25 @@ impl From<Value> for Expr {
         }
     }
 }
+
+// Helper trait
+#[allow(clippy::missing_errors_doc)]
+pub trait ExpressionExt {
+    fn map_resolve(&self, ctx: &mut Context) -> Result<Option<Value>, ExpressionError>;
+    fn map_resolve_with_default<F>(&self, ctx: &mut Context, default_fn: F) -> Resolved
+    where
+        F: FnOnce() -> Value;
+}
+
+impl ExpressionExt for Option<Box<dyn Expression>> {
+    fn map_resolve(&self, ctx: &mut Context) -> Result<Option<Value>, ExpressionError> {
+        self.as_ref().map(|expr| expr.resolve(ctx)).transpose()
+    }
+
+    fn map_resolve_with_default<F>(&self, ctx: &mut Context, default_fn: F) -> Resolved
+    where
+        F: FnOnce() -> Value,
+    {
+        Ok(self.map_resolve(ctx)?.unwrap_or_else(default_fn))
+    }
+}

src/compiler/expression/function_call.rs

@@ -1286,16 +1286,22 @@ mod tests {
                     keyword: "one",
                     kind: kind::INTEGER,
                     required: false,
+                    description: "one",
+                    default: None,
                 },
                 Parameter {
                     keyword: "two",
                     kind: kind::INTEGER,
                     required: false,
+                    description: "two",
+                    default: None,
                 },
                 Parameter {
                     keyword: "three",
                     kind: kind::INTEGER,
                     required: false,
+                    description: "three",
+                    default: None,
                 },
             ]
         }

src/compiler/function.rs

@@ -161,6 +161,19 @@ pub struct Parameter {
     /// If it isn't, the function can be called without errors, even if the
     /// argument matching this parameter is missing.
     pub required: bool,
+
+    /// A description of what this parameter does.
+    pub description: &'static str,
+
+    /// The default value for this parameter, if any.
+    ///
+    /// Notes on creating a `Option<&'static Value>`:
+    ///
+    /// * If the inner [`Value`] is copiable, such as [`Value::Integer`], you likely won't have issues.
+    /// * If the value can contain owned data, such as [`Value::Bytes`], use [`LazyLock`](std::sync::LazyLock)
+    ///   to create static [`Value`] instances. If you are already in a [`LazyLock`](std::sync::LazyLock) block,
+    ///   you'll have to create another [`LazyLock`](std::sync::LazyLock) in order to make both static.
+    pub default: Option<&'static Value>,
 }
 
 impl Parameter {
@@ -650,6 +663,8 @@ mod tests {
                 keyword: "",
                 kind: parameter_kind,
                 required: false,
+                description: "",
+                default: None,
             };
 
             assert_eq!(parameter.kind(), kind, "{title}");

src/compiler/mod.rs

@@ -11,7 +11,7 @@ use crate::compiler::unused_expression_checker::check_for_unused_results;
 pub use compiler::{CompilationResult, Compiler};
 pub use context::Context;
 pub use datetime::TimeZone;
-pub use expression::{Expression, FunctionExpression};
+pub use expression::{Expression, ExpressionExt, FunctionExpression};
 pub use expression_error::{ExpressionError, Resolved};
 pub use function::{Function, Parameter};
 pub use program::{Program, ProgramInfo};

src/compiler/prelude.rs

@@ -19,8 +19,8 @@ pub use crate::{func_args, test_function, test_type_def};
 
 pub use super::Resolved;
 pub use super::{
-    Context, Expression, ExpressionError, Function, FunctionExpression, Parameter, TimeZone,
-    TypeDef, expression,
+    Context, Expression, ExpressionError, ExpressionExt, Function, FunctionExpression, Parameter,
+    TimeZone, TypeDef, expression,
     function::{self, ArgumentList, Closure, Compiled, Example, FunctionCompileContext, closure},
     state::{self, TypeInfo, TypeState},
     type_def,

src/parsing/xml.rs

@@ -31,6 +31,14 @@ pub static XML_RE: LazyLock<Regex> = LazyLock::new(|| {
         .expect("trim regex failed")
 });
 
+pub static DEFAULT_INCLUDE_ATTR: LazyLock<Value> = LazyLock::new(|| Value::Boolean(true));
+pub static DEFAULT_ATTR_PREFIX: LazyLock<Value> = LazyLock::new(|| Value::Bytes(Bytes::from("@")));
+pub static DEFAULT_TEXT_KEY: LazyLock<Value> = LazyLock::new(|| Value::Bytes(Bytes::from("text")));
+pub static DEFAULT_ALWAYS_USE_TEXT_KEY: LazyLock<Value> = LazyLock::new(|| Value::Boolean(false));
+pub static DEFAULT_PARSE_BOOL: LazyLock<Value> = LazyLock::new(|| Value::Boolean(true));
+pub static DEFAULT_PARSE_NULL: LazyLock<Value> = LazyLock::new(|| Value::Boolean(true));
+pub static DEFAULT_PARSE_NUMBER: LazyLock<Value> = LazyLock::new(|| Value::Boolean(true));
+
 /// Configuration to determine which XML options will be used when
 /// parsing a roxmltree `Node`.
 #[derive(Debug, Clone)]
@@ -93,34 +101,40 @@ pub fn parse_xml(value: Value, options: ParseOptions) -> Resolved {
         Some(value) => value.try_boolean()?,
         None => true,
     };
-    let include_attr = match options.include_attr {
-        Some(value) => value.try_boolean()?,
-        None => true,
-    };
-    let attr_prefix = match options.attr_prefix {
-        Some(value) => Cow::from(value.try_bytes_utf8_lossy()?.into_owned()),
-        None => Cow::from("@"),
-    };
-    let text_key = match options.text_key {
-        Some(value) => Cow::from(value.try_bytes_utf8_lossy()?.into_owned()),
-        None => Cow::from("text"),
-    };
-    let always_use_text_key = match options.always_use_text_key {
-        Some(value) => value.try_boolean()?,
-        None => false,
-    };
-    let parse_bool = match options.parse_bool {
-        Some(value) => value.try_boolean()?,
-        None => true,
-    };
-    let parse_null = match options.parse_null {
-        Some(value) => value.try_boolean()?,
-        None => true,
-    };
-    let parse_number = match options.parse_number {
-        Some(value) => value.try_boolean()?,
-        None => true,
-    };
+    let include_attr = options
+        .include_attr
+        .unwrap_or_else(|| DEFAULT_INCLUDE_ATTR.clone())
+        .try_boolean()?;
+    let attr_prefix = Cow::from(
+        options
+            .attr_prefix
+            .unwrap_or_else(|| DEFAULT_ATTR_PREFIX.clone())
+            .try_bytes_utf8_lossy()?
+            .into_owned(),
+    );
+    let text_key = Cow::from(
+        options
+            .text_key
+            .unwrap_or_else(|| DEFAULT_TEXT_KEY.clone())
+            .try_bytes_utf8_lossy()?
+            .into_owned(),
+    );
+    let always_use_text_key = options
+        .always_use_text_key
+        .unwrap_or_else(|| DEFAULT_ALWAYS_USE_TEXT_KEY.clone())
+        .try_boolean()?;
+    let parse_bool = options
+        .parse_bool
+        .unwrap_or_else(|| DEFAULT_PARSE_BOOL.clone())
+        .try_boolean()?;
+    let parse_null = options
+        .parse_null
+        .unwrap_or_else(|| DEFAULT_PARSE_NULL.clone())
+        .try_boolean()?;
+    let parse_number = options
+        .parse_number
+        .unwrap_or_else(|| DEFAULT_PARSE_NUMBER.clone())
+        .try_boolean()?;
     let config = ParseXmlConfig {
         include_attr,
         attr_prefix,

src/stdlib/abs.rs

@@ -29,6 +29,8 @@ impl Function for Abs {
             keyword: "value",
             kind: kind::FLOAT | kind::INTEGER,
             required: true,
+            description: "The number to calculate the absolute value.",
+            default: None,
         }]
     }
 

src/stdlib/append.rs

@@ -25,11 +25,15 @@ impl Function for Append {
                 keyword: "value",
                 kind: kind::ARRAY,
                 required: true,
+                description: "The initial array.",
+                default: None,
             },
             Parameter {
                 keyword: "items",
                 kind: kind::ARRAY,
                 required: true,
+                description: "The items to append.",
+                default: None,
             },
         ]
     }

src/stdlib/array.rs

@@ -24,6 +24,8 @@ impl Function for Array {
             keyword: "value",
             kind: kind::ANY,
             required: true,
+            description: "The value to check if it is an array.",
+            default: None,
         }]
     }
 

src/stdlib/assert.rs

@@ -37,11 +37,18 @@ impl Function for Assert {
                 keyword: "condition",
                 kind: kind::BOOLEAN,
                 required: true,
+                description: "The condition to check.",
+                default: None,
             },
             Parameter {
                 keyword: "message",
                 kind: kind::BYTES,
                 required: false,
+                description:
+                    "An optional custom error message. If the equality assertion fails, `message` is
+appended to the default message prefix. See the [examples](#assert-examples) below
+for a fully formed log message sample.",
+                default: None,
             },
         ]
     }

src/stdlib/assert_eq.rs

@@ -35,16 +35,25 @@ impl Function for AssertEq {
                 keyword: "left",
                 kind: kind::ANY,
                 required: true,
+                description: "The value to check for equality against `right`.",
+                default: None,
             },
             Parameter {
                 keyword: "right",
                 kind: kind::ANY,
                 required: true,
+                description: "The value to check for equality against `left`.",
+                default: None,
             },
             Parameter {
                 keyword: "message",
                 kind: kind::BYTES,
                 required: false,
+                description:
+                    "An optional custom error message. If the equality assertion fails, `message` is
+appended to the default message prefix. See the [examples](#assert_eq-examples)
+below for a fully formed log message sample.",
+                default: None,
             },
         ]
     }

src/stdlib/basename.rs

@@ -27,6 +27,8 @@ impl Function for BaseName {
             keyword: "value",
             kind: kind::BYTES,
             required: true,
+            description: "The path from which to extract the basename.",
+            default: None,
         }]
     }
 

src/stdlib/boolean.rs

@@ -24,6 +24,8 @@ impl Function for Boolean {
             keyword: "value",
             kind: kind::ANY,
             required: true,
+            description: "The value to check if it is a Boolean.",
+            default: None,
         }]
     }
 

src/stdlib/casing/camelcase.rs

@@ -21,11 +21,15 @@ impl Function for Camelcase {
                 keyword: "value",
                 kind: kind::BYTES,
                 required: true,
+                description: "The string to convert to camelCase.",
+                default: None,
             },
             Parameter {
                 keyword: "original_case",
                 kind: kind::BYTES,
                 required: false,
+                description: "Optional hint on the original case type. Must be one of: kebab-case, camelCase, PascalCase, SCREAMING_SNAKE, snake_case",
+                default: None,
             },
         ]
     }

src/stdlib/casing/kebabcase.rs

@@ -21,11 +21,15 @@ impl Function for Kebabcase {
                 keyword: "value",
                 kind: kind::BYTES,
                 required: true,
+                description: "The string to convert to kebab-case.",
+                default: None,
             },
             Parameter {
                 keyword: "original_case",
                 kind: kind::BYTES,
                 required: false,
+                description: "Optional hint on the original case type. Must be one of: kebab-case, camelCase, PascalCase, SCREAMING_SNAKE, snake_case",
+                default: None,
             },
         ]
     }

src/stdlib/casing/pascalcase.rs

@@ -21,11 +21,15 @@ impl Function for Pascalcase {
                 keyword: "value",
                 kind: kind::BYTES,
                 required: true,
+                description: "The string to convert to PascalCase.",
+                default: None,
             },
             Parameter {
                 keyword: "original_case",
                 kind: kind::BYTES,
                 required: false,
+                description: "Optional hint on the original case type. Must be one of: kebab-case, camelCase, PascalCase, SCREAMING_SNAKE, snake_case",
+                default: None,
             },
         ]
     }

src/stdlib/casing/screamingsnakecase.rs

@@ -21,11 +21,15 @@ impl Function for ScreamingSnakecase {
                 keyword: "value",
                 kind: kind::BYTES,
                 required: true,
+                description: "The string to convert to SCREAMING_SNAKE case.",
+                default: None,
             },
             Parameter {
                 keyword: "original_case",
                 kind: kind::BYTES,
                 required: false,
+                description: "Optional hint on the original case type. Must be one of: kebab-case, camelCase, PascalCase, SCREAMING_SNAKE, snake_case",
+                default: None,
             },
         ]
     }

src/stdlib/casing/snakecase.rs

@@ -23,16 +23,34 @@ impl Function for Snakecase {
                 keyword: "value",
                 kind: kind::BYTES,
                 required: true,
+                description: "The string to convert to snake-case.",
+                default: None,
             },
             Parameter {
                 keyword: "original_case",
                 kind: kind::BYTES,
                 required: false,
+                description: "Optional hint on the original case type. Must be one of: kebab-case, camelCase, PascalCase, SCREAMING_SNAKE, snake_case",
+                default: None,
             },
             Parameter {
                 keyword: "excluded_boundaries",
                 kind: kind::ARRAY,
                 required: false,
+                description: indoc! {"
+                    Case boundaries to exclude during conversion.
+
+                    Valid values include:
+                    - lower_upper
+                    - upper_lower
+                    - upper_upper
+                    - acronym
+                    - lower_digit
+                    - upper_digit
+                    - digit_lower
+                    - digit_upper
+                "},
+                default: None,
             },
         ]
     }