feat(stdlib)!: Add required usage method to all functions

changelog.d/1608.breaking.md

@@ -0,0 +1,4 @@
+The `usage()` method on the `Function` trait is now required. Custom VRL functions must implement this
+method to return a `&'static str` describing the function's purpose.
+
+authors: thomasqueirozb

src/compiler/expression/function_call.rs

@@ -1272,6 +1272,10 @@ mod tests {
             "test"
         }
 
+        fn usage(&self) -> &'static str {
+            "Test function"
+        }
+
         fn examples(&self) -> &'static [crate::compiler::function::Example] {
             &[]
         }

src/compiler/function.rs

@@ -31,9 +31,7 @@ pub trait Function: Send + Sync + fmt::Debug {
     }
 
     /// A more elaborate multi-paragraph description on how to use the function.
-    fn usage(&self) -> &'static str {
-        "TODO"
-    }
+    fn usage(&self) -> &'static str;
 
     /// One or more examples demonstrating usage of the function in VRL source
     /// code.

src/stdlib/abs.rs

@@ -20,6 +20,10 @@ impl Function for Abs {
         "abs"
     }
 
+    fn usage(&self) -> &'static str {
+        "Computes the absolute value of `value`."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/append.rs

@@ -15,6 +15,10 @@ impl Function for Append {
         "append"
     }
 
+    fn usage(&self) -> &'static str {
+        "Appends each item in the `items` array to the end of the `value` array."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/array.rs

@@ -15,6 +15,10 @@ impl Function for Array {
         "array"
     }
 
+    fn usage(&self) -> &'static str {
+        "Returns `value` if it is an array, otherwise returns an error. This enables the type checker to guarantee that the returned value is an array and can be used in any function that expects an array."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/assert.rs

@@ -27,6 +27,10 @@ impl Function for Assert {
         "assert"
     }
 
+    fn usage(&self) -> &'static str {
+        "Asserts the `condition`, which must be a Boolean expression. The program is aborted with `message` if the condition evaluates to `false`."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/assert_eq.rs

@@ -25,6 +25,10 @@ impl Function for AssertEq {
         "assert_eq"
     }
 
+    fn usage(&self) -> &'static str {
+        "Asserts that two expressions, `left` and `right`, have the same value. The program is aborted with `message` if they do not have the same value."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/basename.rs

@@ -18,6 +18,10 @@ impl Function for BaseName {
         "basename"
     }
 
+    fn usage(&self) -> &'static str {
+        "Returns the filename component of the given `path`. This is similar to the Unix `basename` command. If the path ends in a directory separator, the function returns the name of the directory."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/boolean.rs

@@ -15,6 +15,10 @@ impl Function for Boolean {
         "bool"
     }
 
+    fn usage(&self) -> &'static str {
+        "The value to check if it is a Boolean."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/casing/camelcase.rs

@@ -11,6 +11,10 @@ impl Function for Camelcase {
         "camelcase"
     }
 
+    fn usage(&self) -> &'static str {
+        "Takes the `value` string, and turns it into camelCase. Optionally, you can pass in the existing case of the function, or else an attempt is made to determine the case automatically."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/casing/kebabcase.rs

@@ -11,6 +11,10 @@ impl Function for Kebabcase {
         "kebabcase"
     }
 
+    fn usage(&self) -> &'static str {
+        "Takes the `value` string, and turns it into kebab-case. Optionally, you can pass in the existing case of the function, or else we will try to figure out the case automatically."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/casing/pascalcase.rs

@@ -11,6 +11,10 @@ impl Function for Pascalcase {
         "pascalcase"
     }
 
+    fn usage(&self) -> &'static str {
+        "Takes the `value` string, and turns it into PascalCase. Optionally, you can pass in the existing case of the function, or else we will try to figure out the case automatically."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/casing/screamingsnakecase.rs

@@ -11,6 +11,10 @@ impl Function for ScreamingSnakecase {
         "screamingsnakecase"
     }
 
+    fn usage(&self) -> &'static str {
+        "Takes the `value` string, and turns it into SCREAMING_SNAKE case. Optionally, you can pass in the existing case of the function, or else we will try to figure out the case automatically."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/casing/snakecase.rs

@@ -13,6 +13,10 @@ impl Function for Snakecase {
         "snakecase"
     }
 
+    fn usage(&self) -> &'static str {
+        "Takes the `value` string, and turns it into snake-case. Optionally, you can pass in the existing case of the function, or else we will try to figure out the case automatically."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/ceil.rs

@@ -29,6 +29,10 @@ impl Function for Ceil {
         "ceil"
     }
 
+    fn usage(&self) -> &'static str {
+        "Rounds the `value` up to the specified `precision`."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/chunks.rs

@@ -27,6 +27,10 @@ impl Function for Chunks {
         "chunks"
     }
 
+    fn usage(&self) -> &'static str {
+        "Chunks `value` into slices of length `chunk_size` bytes."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/community_id.rs

@@ -65,6 +65,10 @@ impl Function for CommunityID {
         "community_id"
     }
 
+    fn usage(&self) -> &'static str {
+        "Generates an ID based on the [Community ID Spec](https://github.com/corelight/community-id-spec)."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/compact.rs

@@ -61,6 +61,10 @@ impl Function for Compact {
         "compact"
     }
 
+    fn usage(&self) -> &'static str {
+        "Compacts the `value` by removing empty values, where empty values are defined using the available parameters."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/contains.rs

@@ -15,6 +15,10 @@ impl Function for Contains {
         "contains"
     }
 
+    fn usage(&self) -> &'static str {
+        "Determines whether the `value` string contains the specified `substring`."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/contains_all.rs

@@ -27,6 +27,10 @@ impl Function for ContainsAll {
         "contains_all"
     }
 
+    fn usage(&self) -> &'static str {
+        "Determines whether the `value` string contains all the specified `substrings`."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/crc.rs

@@ -472,6 +472,14 @@ impl Function for Crc {
         "crc"
     }
 
+    fn usage(&self) -> &'static str {
+        indoc! {
+            "Calculates a CRC of the `value`.The CRC `algorithm` used can be optionally specified.
+
+            This function is infallible if either the default `algorithm` value or a recognized-valid compile-time `algorithm` string literal is used. Otherwise, it is fallible."
+        }
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/decode_base16.rs

@@ -17,6 +17,10 @@ impl Function for DecodeBase16 {
         "decode_base16"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (a [Base16](https://en.wikipedia.org/wiki/Hexadecimal) string) into its original string."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/decode_base64.rs

@@ -38,6 +38,10 @@ impl Function for DecodeBase64 {
         "decode_base64"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (a [Base64](https://en.wikipedia.org/wiki/Base64) string) into its original string."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/decode_gzip.rs

@@ -21,6 +21,10 @@ impl Function for DecodeGzip {
         "decode_gzip"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (a [Gzip](https://www.gzip.org/) string) into its original string."
+    }
+
     fn examples(&self) -> &'static [Example] {
         &[example! {
             title: "Decode Gzip data",

src/stdlib/decode_lz4.rs

@@ -14,6 +14,12 @@ impl Function for DecodeLz4 {
         "decode_lz4"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (an lz4 string) into its original string. `buf_size` is the size of the buffer to decode into, this must be equal to or larger than the uncompressed size.
+        If `prepended_size` is set to `true`, it expects the original uncompressed size to be prepended to the compressed data.
+        `prepended_size` is useful for some implementations of lz4 that require the original size to be known before decoding."
+    }
+
     fn examples(&self) -> &'static [Example] {
         &[
             example! {

src/stdlib/decode_mime_q.rs

@@ -20,6 +20,10 @@ impl Function for DecodeMimeQ {
         "decode_mime_q"
     }
 
+    fn usage(&self) -> &'static str {
+        "Replaces q-encoded or base64-encoded [encoded-word](https://datatracker.ietf.org/doc/html/rfc2047#section-2)) substrings in the `value` with their original string."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/decode_percent.rs

@@ -17,6 +17,10 @@ impl Function for DecodePercent {
         "decode_percent"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes a [percent-encoded](https://url.spec.whatwg.org/#percent-encoded-bytes) `value` like a URL."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[Parameter {
             keyword: "value",

src/stdlib/decode_punycode.rs

@@ -10,6 +10,10 @@ impl Function for DecodePunycode {
         "decode_punycode"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes a [punycode](https://en.wikipedia.org/wiki/Punycode) encoded `value`, such as an internationalized domain name ([IDN](https://en.wikipedia.org/wiki/Internationalized_domain_name)). This function assumes that the value passed is meant to be used in IDN context and that it is either a domain name or a part of it."
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {

src/stdlib/decode_snappy.rs

@@ -20,6 +20,10 @@ impl Function for DecodeSnappy {
         "decode_snappy"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (a Snappy string) into its original string."
+    }
+
     fn examples(&self) -> &'static [Example] {
         &[example! {
             title: "Decode Snappy data",

src/stdlib/decode_zlib.rs

@@ -21,6 +21,10 @@ impl Function for DecodeZlib {
         "decode_zlib"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (a [Zlib](https://www.zlib.net) string) into its original string."
+    }
+
     fn examples(&self) -> &'static [Example] {
         &[example! {
             title: "Decode Zlib data",

src/stdlib/decode_zstd.rs

@@ -19,6 +19,10 @@ impl Function for DecodeZstd {
         "decode_zstd"
     }
 
+    fn usage(&self) -> &'static str {
+        "Decodes the `value` (a [Zstandard](https://facebook.github.io/zstd) string) into its original string."
+    }
+
     fn examples(&self) -> &'static [Example] {
         &[example! {
             title: "Decode Zstd data",

src/stdlib/decrypt.rs

@@ -116,6 +116,47 @@ impl Function for Decrypt {
         "decrypt"
     }
 
+    fn usage(&self) -> &'static str {
+        indoc! {"
+            Decrypts a string with a symmetric encryption algorithm.
+
+            Supported Algorithms:
+
+            * AES-256-CFB (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CFB (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CFB (key = 16 bytes, iv = 16 bytes)
+            * AES-256-OFB (key = 32 bytes, iv = 16 bytes)
+            * AES-192-OFB  (key = 24 bytes, iv = 16 bytes)
+            * AES-128-OFB (key = 16 bytes, iv = 16 bytes)
+            * AES-128-SIV (key = 32 bytes, iv = 16 bytes)
+            * AES-256-SIV (key = 64 bytes, iv = 16 bytes)
+            * Deprecated - AES-256-CTR (key = 32 bytes, iv = 16 bytes)
+            * Deprecated - AES-192-CTR (key = 24 bytes, iv = 16 bytes)
+            * Deprecated - AES-128-CTR (key = 16 bytes, iv = 16 bytes)
+            * AES-256-CTR-LE (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CTR-LE (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CTR-LE (key = 16 bytes, iv = 16 bytes)
+            * AES-256-CTR-BE (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CTR-BE (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CTR-BE (key = 16 bytes, iv = 16 bytes)
+            * AES-256-CBC-PKCS7 (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CBC-PKCS7 (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CBC-PKCS7 (key = 16 bytes, iv = 16 bytes)
+            * AES-256-CBC-ANSIX923 (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CBC-ANSIX923 (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CBC-ANSIX923 (key = 16 bytes, iv = 16 bytes)
+            * AES-256-CBC-ISO7816 (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CBC-ISO7816 (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CBC-ISO7816 (key = 16 bytes, iv = 16 bytes)
+            * AES-256-CBC-ISO10126 (key = 32 bytes, iv = 16 bytes)
+            * AES-192-CBC-ISO10126 (key = 24 bytes, iv = 16 bytes)
+            * AES-128-CBC-ISO10126 (key = 16 bytes, iv = 16 bytes)
+            * CHACHA20-POLY1305 (key = 32 bytes, iv = 12 bytes)
+            * XCHACHA20-POLY1305 (key = 32 bytes, iv = 24 bytes)
+            * XSALSA20-POLY1305 (key = 32 bytes, iv = 24 bytes)
+        "}
+    }
+
     fn parameters(&self) -> &'static [Parameter] {
         &[
             Parameter {