diff --git a/changelog.d/1608.breaking.md b/changelog.d/1608.breaking.md new file mode 100644 index 0000000000..40a241e415 --- /dev/null +++ b/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 diff --git a/src/compiler/expression/function_call.rs b/src/compiler/expression/function_call.rs index d537bd2200..3cb763fe65 100644 --- a/src/compiler/expression/function_call.rs +++ b/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] { &[] } diff --git a/src/compiler/function.rs b/src/compiler/function.rs index aa810de98d..607ca57e49 100644 --- a/src/compiler/function.rs +++ b/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. diff --git a/src/stdlib/abs.rs b/src/stdlib/abs.rs index 2f6b193828..2f865f668d 100644 --- a/src/stdlib/abs.rs +++ b/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", diff --git a/src/stdlib/append.rs b/src/stdlib/append.rs index 6ca666664b..1950971e0c 100644 --- a/src/stdlib/append.rs +++ b/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 { diff --git a/src/stdlib/array.rs b/src/stdlib/array.rs index 052dc944af..b69b7beefa 100644 --- a/src/stdlib/array.rs +++ b/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", diff --git a/src/stdlib/assert.rs b/src/stdlib/assert.rs index b497ba60d4..91e26a6284 100644 --- a/src/stdlib/assert.rs +++ b/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 { diff --git a/src/stdlib/assert_eq.rs b/src/stdlib/assert_eq.rs index e14582f05f..473f5fcc14 100644 --- a/src/stdlib/assert_eq.rs +++ b/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 { diff --git a/src/stdlib/basename.rs b/src/stdlib/basename.rs index b62a29012c..04a38a3f70 100644 --- a/src/stdlib/basename.rs +++ b/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", diff --git a/src/stdlib/boolean.rs b/src/stdlib/boolean.rs index 822a5eb041..fbd8b7c1d8 100644 --- a/src/stdlib/boolean.rs +++ b/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", diff --git a/src/stdlib/casing/camelcase.rs b/src/stdlib/casing/camelcase.rs index c1e70f2ebe..a529225f0c 100644 --- a/src/stdlib/casing/camelcase.rs +++ b/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 { diff --git a/src/stdlib/casing/kebabcase.rs b/src/stdlib/casing/kebabcase.rs index 3998012e91..473082c516 100644 --- a/src/stdlib/casing/kebabcase.rs +++ b/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 { diff --git a/src/stdlib/casing/pascalcase.rs b/src/stdlib/casing/pascalcase.rs index 0bca53b56d..2cad5daee0 100644 --- a/src/stdlib/casing/pascalcase.rs +++ b/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 { diff --git a/src/stdlib/casing/screamingsnakecase.rs b/src/stdlib/casing/screamingsnakecase.rs index a1f37008cd..47fbd32bf3 100644 --- a/src/stdlib/casing/screamingsnakecase.rs +++ b/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 { diff --git a/src/stdlib/casing/snakecase.rs b/src/stdlib/casing/snakecase.rs index 7957235aa8..e53228e747 100644 --- a/src/stdlib/casing/snakecase.rs +++ b/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 { diff --git a/src/stdlib/ceil.rs b/src/stdlib/ceil.rs index 024fc9fd04..35f235ab16 100644 --- a/src/stdlib/ceil.rs +++ b/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 { diff --git a/src/stdlib/chunks.rs b/src/stdlib/chunks.rs index 515f227e44..c75a5f9662 100644 --- a/src/stdlib/chunks.rs +++ b/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 { diff --git a/src/stdlib/community_id.rs b/src/stdlib/community_id.rs index 3013c5ec96..f1611b2a92 100644 --- a/src/stdlib/community_id.rs +++ b/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 { diff --git a/src/stdlib/compact.rs b/src/stdlib/compact.rs index 6012359c84..37bff9f92b 100644 --- a/src/stdlib/compact.rs +++ b/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 { diff --git a/src/stdlib/contains.rs b/src/stdlib/contains.rs index c9b89a4a80..8705811ba4 100644 --- a/src/stdlib/contains.rs +++ b/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 { diff --git a/src/stdlib/contains_all.rs b/src/stdlib/contains_all.rs index 1ffb992bae..b6d9396d63 100644 --- a/src/stdlib/contains_all.rs +++ b/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 { diff --git a/src/stdlib/crc.rs b/src/stdlib/crc.rs index 3c210fab29..40de439251 100644 --- a/src/stdlib/crc.rs +++ b/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 { diff --git a/src/stdlib/decode_base16.rs b/src/stdlib/decode_base16.rs index 6624514880..4e052d5b91 100644 --- a/src/stdlib/decode_base16.rs +++ b/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", diff --git a/src/stdlib/decode_base64.rs b/src/stdlib/decode_base64.rs index fb1ef44d4a..bac2d2425e 100644 --- a/src/stdlib/decode_base64.rs +++ b/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 { diff --git a/src/stdlib/decode_gzip.rs b/src/stdlib/decode_gzip.rs index a10d4ea3eb..d7a2f2e6e7 100644 --- a/src/stdlib/decode_gzip.rs +++ b/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", diff --git a/src/stdlib/decode_lz4.rs b/src/stdlib/decode_lz4.rs index 0aade9231e..f1d457b018 100644 --- a/src/stdlib/decode_lz4.rs +++ b/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! { diff --git a/src/stdlib/decode_mime_q.rs b/src/stdlib/decode_mime_q.rs index fa45cca6eb..86d282a94a 100644 --- a/src/stdlib/decode_mime_q.rs +++ b/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", diff --git a/src/stdlib/decode_percent.rs b/src/stdlib/decode_percent.rs index 1839ae4425..4eb1b0cb30 100644 --- a/src/stdlib/decode_percent.rs +++ b/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", diff --git a/src/stdlib/decode_punycode.rs b/src/stdlib/decode_punycode.rs index 3e25ff87de..54ab00ec95 100644 --- a/src/stdlib/decode_punycode.rs +++ b/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 { diff --git a/src/stdlib/decode_snappy.rs b/src/stdlib/decode_snappy.rs index 139d19ca73..77489d1eae 100644 --- a/src/stdlib/decode_snappy.rs +++ b/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", diff --git a/src/stdlib/decode_zlib.rs b/src/stdlib/decode_zlib.rs index 14d7a495d5..279a3d27d8 100644 --- a/src/stdlib/decode_zlib.rs +++ b/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", diff --git a/src/stdlib/decode_zstd.rs b/src/stdlib/decode_zstd.rs index 625a6252b2..3aa78b6348 100644 --- a/src/stdlib/decode_zstd.rs +++ b/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", diff --git a/src/stdlib/decrypt.rs b/src/stdlib/decrypt.rs index 5f929ba215..3676ccbb96 100644 --- a/src/stdlib/decrypt.rs +++ b/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 { diff --git a/src/stdlib/decrypt_ip.rs b/src/stdlib/decrypt_ip.rs index bc926f3e8f..f7294cd6d2 100644 --- a/src/stdlib/decrypt_ip.rs +++ b/src/stdlib/decrypt_ip.rs @@ -57,6 +57,17 @@ impl Function for DecryptIp { "decrypt_ip" } + fn usage(&self) -> &'static str { + indoc! {" + Decrypts an IP address that was previously encrypted, restoring the original IP address. + + Supported Modes: + + * AES128 - Decrypts an IP address that was scrambled using AES-128 encryption. Can transform between IPv4 and IPv6. + * PFX (Prefix-preserving) - Decrypts an IP address that was encrypted with prefix-preserving mode, where network hierarchy was maintained. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/del.rs b/src/stdlib/del.rs index f66f5ba5bb..6a162685a5 100644 --- a/src/stdlib/del.rs +++ b/src/stdlib/del.rs @@ -39,6 +39,14 @@ impl Function for Del { "del" } + fn usage(&self) -> &'static str { + indoc! {" + Removes the field specified by the static `path` from the target. + + For dynamic path deletion, see the `remove` function. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/dirname.rs b/src/stdlib/dirname.rs index 16fa76e656..778763cbd1 100644 --- a/src/stdlib/dirname.rs +++ b/src/stdlib/dirname.rs @@ -27,6 +27,10 @@ impl Function for DirName { "dirname" } + fn usage(&self) -> &'static str { + "Returns the directory component of the given `path`. This is similar to the Unix `dirname` command. The directory component is the path with the final component removed." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/dns_lookup.rs b/src/stdlib/dns_lookup.rs index 16fbece815..006ca7beb6 100644 --- a/src/stdlib/dns_lookup.rs +++ b/src/stdlib/dns_lookup.rs @@ -338,6 +338,10 @@ impl Function for DnsLookup { "dns_lookup" } + fn usage(&self) -> &'static str { + "Performs a DNS lookup on the provided domain name. This function performs network calls and blocks on each request until a response is received. It is not recommended for frequent or performance-critical workflows." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/downcase.rs b/src/stdlib/downcase.rs index a182161ec7..eda01542a5 100644 --- a/src/stdlib/downcase.rs +++ b/src/stdlib/downcase.rs @@ -12,6 +12,10 @@ impl Function for Downcase { "downcase" } + fn usage(&self) -> &'static str { + "Downcases the `value` string, where downcase is defined according to the Unicode Derived Core Property Lowercase." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/encode_base16.rs b/src/stdlib/encode_base16.rs index fb75a39264..a56ae02569 100644 --- a/src/stdlib/encode_base16.rs +++ b/src/stdlib/encode_base16.rs @@ -13,6 +13,10 @@ impl Function for EncodeBase16 { "encode_base16" } + fn usage(&self) -> &'static str { + "Encodes the `value` to [Base16](https://en.wikipedia.org/wiki/Hexadecimal))." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/encode_base64.rs b/src/stdlib/encode_base64.rs index 997cda2258..5810cc2be1 100644 --- a/src/stdlib/encode_base64.rs +++ b/src/stdlib/encode_base64.rs @@ -34,6 +34,10 @@ impl Function for EncodeBase64 { "encode_base64" } + fn usage(&self) -> &'static str { + "Encodes the `value` to [Base64](https://en.wikipedia.org/wiki/Base64)." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/encode_gzip.rs b/src/stdlib/encode_gzip.rs index 4c5facbcf8..9f1457e620 100644 --- a/src/stdlib/encode_gzip.rs +++ b/src/stdlib/encode_gzip.rs @@ -39,6 +39,10 @@ impl Function for EncodeGzip { "encode_gzip" } + fn usage(&self) -> &'static str { + "Encodes the `value` to [Gzip](https://www.gzip.org/)." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Encode to Gzip", diff --git a/src/stdlib/encode_json.rs b/src/stdlib/encode_json.rs index 790f4ef7d2..f491f06ae7 100644 --- a/src/stdlib/encode_json.rs +++ b/src/stdlib/encode_json.rs @@ -23,6 +23,10 @@ impl Function for EncodeJson { "encode_json" } + fn usage(&self) -> &'static str { + "Encodes the `value` to JSON." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/encode_key_value.rs b/src/stdlib/encode_key_value.rs index dbd15b2125..bcea480789 100644 --- a/src/stdlib/encode_key_value.rs +++ b/src/stdlib/encode_key_value.rs @@ -37,6 +37,10 @@ impl Function for EncodeKeyValue { "encode_key_value" } + fn usage(&self) -> &'static str { + "Encodes the `value` into key-value format with customizable delimiters. Default delimiters match the [logfmt](https://brandur.org/logfmt) format." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/encode_logfmt.rs b/src/stdlib/encode_logfmt.rs index c4f876775b..0e25274692 100644 --- a/src/stdlib/encode_logfmt.rs +++ b/src/stdlib/encode_logfmt.rs @@ -10,6 +10,10 @@ impl Function for EncodeLogfmt { "encode_logfmt" } + fn usage(&self) -> &'static str { + "Encodes the `value` to [logfmt](https://brandur.org/logfmt)." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/encode_lz4.rs b/src/stdlib/encode_lz4.rs index a6cbbe91a0..540a027b7a 100644 --- a/src/stdlib/encode_lz4.rs +++ b/src/stdlib/encode_lz4.rs @@ -20,6 +20,14 @@ impl Function for EncodeLz4 { "encode_lz4" } + fn usage(&self) -> &'static str { + indoc! {" + 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! { title: "Encode to Lz4", diff --git a/src/stdlib/encode_percent.rs b/src/stdlib/encode_percent.rs index 081b79c04d..9ad38753ca 100644 --- a/src/stdlib/encode_percent.rs +++ b/src/stdlib/encode_percent.rs @@ -84,6 +84,10 @@ impl Function for EncodePercent { "encode_percent" } + fn usage(&self) -> &'static str { + "Encodes a `value` with [percent encoding](https://url.spec.whatwg.org/#percent-encoded-bytes) to safely be used in URLs." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/encode_punycode.rs b/src/stdlib/encode_punycode.rs index 9e885cbf1b..f1e20973fc 100644 --- a/src/stdlib/encode_punycode.rs +++ b/src/stdlib/encode_punycode.rs @@ -10,6 +10,10 @@ impl Function for EncodePunycode { "encode_punycode" } + fn usage(&self) -> &'static str { + "Encodes a `value` to [punycode](https://en.wikipedia.org/wiki/Punycode). Useful for internationalized domain names ([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 { diff --git a/src/stdlib/encode_snappy.rs b/src/stdlib/encode_snappy.rs index 02c68e123e..7f95574cbd 100644 --- a/src/stdlib/encode_snappy.rs +++ b/src/stdlib/encode_snappy.rs @@ -20,6 +20,10 @@ impl Function for EncodeSnappy { "encode_snappy" } + fn usage(&self) -> &'static str { + "Encodes the `value` to Snappy." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Encode to Snappy", diff --git a/src/stdlib/encode_zlib.rs b/src/stdlib/encode_zlib.rs index 2e5eed9bca..2da61924f3 100644 --- a/src/stdlib/encode_zlib.rs +++ b/src/stdlib/encode_zlib.rs @@ -40,6 +40,10 @@ impl Function for EncodeZlib { "encode_zlib" } + fn usage(&self) -> &'static str { + "Encodes the `value` to [Zlib](https://www.zlib.net)." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Encode to Zlib", diff --git a/src/stdlib/encode_zstd.rs b/src/stdlib/encode_zstd.rs index f96520cf41..3326dd61b9 100644 --- a/src/stdlib/encode_zstd.rs +++ b/src/stdlib/encode_zstd.rs @@ -24,6 +24,10 @@ impl Function for EncodeZstd { "encode_zstd" } + fn usage(&self) -> &'static str { + "Encodes the `value` to [Zstandard](https://facebook.github.io/zstd)." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Encode to Zstd", diff --git a/src/stdlib/encrypt.rs b/src/stdlib/encrypt.rs index 68a25878ce..e98317168d 100644 --- a/src/stdlib/encrypt.rs +++ b/src/stdlib/encrypt.rs @@ -179,6 +179,47 @@ impl Function for Encrypt { "encrypt" } + fn usage(&self) -> &'static str { + indoc! {" + Encrypts 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 { diff --git a/src/stdlib/encrypt_ip.rs b/src/stdlib/encrypt_ip.rs index 22162c7abc..1bccf16888 100644 --- a/src/stdlib/encrypt_ip.rs +++ b/src/stdlib/encrypt_ip.rs @@ -41,6 +41,17 @@ impl Function for EncryptIp { "encrypt_ip" } + fn usage(&self) -> &'static str { + indoc! {" + Encrypts an IP address, transforming it into a different valid IP address. + + Supported Modes: + + * AES128 - Scrambles the entire IP address using AES-128 encryption. Can transform between IPv4 and IPv6. + * PFX (Prefix-preserving) - Maintains network hierarchy by ensuring that IP addresses within the same network are encrypted to addresses that also share a common network. This preserves prefix relationships while providing confidentiality. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/ends_with.rs b/src/stdlib/ends_with.rs index 7eeb65e509..2e923d2690 100644 --- a/src/stdlib/ends_with.rs +++ b/src/stdlib/ends_with.rs @@ -15,6 +15,10 @@ impl Function for EndsWith { "ends_with" } + fn usage(&self) -> &'static str { + "Determines whether the `value` string ends with the specified `substring`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/exists.rs b/src/stdlib/exists.rs index 12f1da4979..50d246bddc 100644 --- a/src/stdlib/exists.rs +++ b/src/stdlib/exists.rs @@ -8,6 +8,16 @@ impl Function for Exists { "exists" } + fn usage(&self) -> &'static str { + indoc! {" + Checks whether the `path` exists for the target. + + This function distinguishes between a missing path + and a path with a `null` value. A regular path lookup, + such as `.foo`, cannot distinguish between the two cases + since it always returns `null` if the path doesn't exist. + "} + } fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "field", diff --git a/src/stdlib/filter.rs b/src/stdlib/filter.rs index dca58ffacb..ebd5b90281 100644 --- a/src/stdlib/filter.rs +++ b/src/stdlib/filter.rs @@ -47,6 +47,26 @@ impl Function for Filter { "filter" } + fn usage(&self) -> &'static str { + indoc! {" + Filter elements from a collection. + + This function currently *does not* support recursive iteration. + + The function uses the function closure syntax to allow reading + the key-value or index-value combination for each item in the + collection. + + The same scoping rules apply to closure blocks as they do for + regular blocks. This means that any variable defined in parent scopes + is accessible, and mutations to those variables are preserved, + but any new variables instantiated in the closure block are + unavailable outside of the block. + + See the examples below to learn about the closure syntax. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/find.rs b/src/stdlib/find.rs index a2220a0945..931dda55f2 100644 --- a/src/stdlib/find.rs +++ b/src/stdlib/find.rs @@ -21,6 +21,10 @@ impl Function for Find { "find" } + fn usage(&self) -> &'static str { + "Determines from left to right the start position of the first found element in `value` that matches `pattern`. Returns `-1` if not found." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/flatten.rs b/src/stdlib/flatten.rs index 0a794a9cc6..8ccd3901ec 100644 --- a/src/stdlib/flatten.rs +++ b/src/stdlib/flatten.rs @@ -32,6 +32,10 @@ impl Function for Flatten { "flatten" } + fn usage(&self) -> &'static str { + "Flattens the `value` into a single-level representation." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/float.rs b/src/stdlib/float.rs index 31a2b42e37..efd0f4ae31 100644 --- a/src/stdlib/float.rs +++ b/src/stdlib/float.rs @@ -15,6 +15,10 @@ impl Function for Float { "float" } + fn usage(&self) -> &'static str { + "Returns `value` if it is a float, otherwise returns an error. This enables the type checker to guarantee that the returned value is a float and can be used in any function that expects a float." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/floor.rs b/src/stdlib/floor.rs index 2863f97881..205c2c22a6 100644 --- a/src/stdlib/floor.rs +++ b/src/stdlib/floor.rs @@ -30,6 +30,10 @@ impl Function for Floor { "floor" } + fn usage(&self) -> &'static str { + "Rounds the `value` down to the specified `precision`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/for_each.rs b/src/stdlib/for_each.rs index 54f49fa0d0..476ccd3c69 100644 --- a/src/stdlib/for_each.rs +++ b/src/stdlib/for_each.rs @@ -27,6 +27,25 @@ impl Function for ForEach { "for_each" } + fn usage(&self) -> &'static str { + indoc! {" + Iterate over a collection. + + This function currently *does not* support recursive iteration. + + The function uses the \"function closure syntax\" to allow reading + the key/value or index/value combination for each item in the + collection. + + The same scoping rules apply to closure blocks as they do for + regular blocks. This means that any variable defined in parent scopes + is accessible, and mutations to those variables are preserved, + but any new variables instantiated in the closure block are + unavailable outside of the block. + + See the examples below to learn about the closure syntax. + "} + } fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/format_int.rs b/src/stdlib/format_int.rs index 394ac15506..a9a1c1748c 100644 --- a/src/stdlib/format_int.rs +++ b/src/stdlib/format_int.rs @@ -31,6 +31,10 @@ impl Function for FormatInt { "format_int" } + fn usage(&self) -> &'static str { + "Formats the integer `value` into a string representation using the given base/radix." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/format_number.rs b/src/stdlib/format_number.rs index 8559e5a602..5de7cfbcac 100644 --- a/src/stdlib/format_number.rs +++ b/src/stdlib/format_number.rs @@ -90,6 +90,10 @@ impl Function for FormatNumber { "format_number" } + fn usage(&self) -> &'static str { + "Formats the `value` into a string representation of the number." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/format_timestamp.rs b/src/stdlib/format_timestamp.rs index c473e03340..81aa187753 100644 --- a/src/stdlib/format_timestamp.rs +++ b/src/stdlib/format_timestamp.rs @@ -24,6 +24,10 @@ impl Function for FormatTimestamp { "format_timestamp" } + fn usage(&self) -> &'static str { + "Formats `value` into a string representation of the timestamp." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/from_unix_timestamp.rs b/src/stdlib/from_unix_timestamp.rs index e7de242cb2..b408cef886 100644 --- a/src/stdlib/from_unix_timestamp.rs +++ b/src/stdlib/from_unix_timestamp.rs @@ -34,6 +34,14 @@ impl Function for FromUnixTimestamp { "from_unix_timestamp" } + fn usage(&self) -> &'static str { + indoc! {" + Converts the `value` integer from a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) to a VRL `timestamp`. + + Converts from the number of seconds since the Unix epoch by default. To convert from milliseconds or nanoseconds, set the `unit` argument to `milliseconds` or `nanoseconds`. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/get.rs b/src/stdlib/get.rs index d8e0ad1d23..357d2f55b3 100644 --- a/src/stdlib/get.rs +++ b/src/stdlib/get.rs @@ -45,6 +45,17 @@ impl Function for Get { "get" } + fn usage(&self) -> &'static str { + indoc! {" + Dynamically get the value of a given path. + + If you know the path you want to look up, use + static paths such as `.foo.bar[1]` to get the value of that + path. However, if you do not know the path names, + use the dynamic `get` function to get the requested value. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/get_env_var.rs b/src/stdlib/get_env_var.rs index 3b0bad7978..62d583e3a8 100644 --- a/src/stdlib/get_env_var.rs +++ b/src/stdlib/get_env_var.rs @@ -15,6 +15,10 @@ impl Function for GetEnvVar { "get_env_var" } + fn usage(&self) -> &'static str { + "Returns the value of the environment variable specified by `name`." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "name", diff --git a/src/stdlib/get_hostname.rs b/src/stdlib/get_hostname.rs index 9b2a1b8442..aed2f92a12 100644 --- a/src/stdlib/get_hostname.rs +++ b/src/stdlib/get_hostname.rs @@ -17,6 +17,10 @@ impl Function for GetHostname { "get_hostname" } + fn usage(&self) -> &'static str { + "Returns the local system's hostname." + } + #[cfg(not(target_arch = "wasm32"))] fn compile( &self, diff --git a/src/stdlib/get_timezone_name.rs b/src/stdlib/get_timezone_name.rs index a2e3bedec4..508ce7516c 100644 --- a/src/stdlib/get_timezone_name.rs +++ b/src/stdlib/get_timezone_name.rs @@ -26,6 +26,18 @@ impl Function for GetTimezoneName { "get_timezone_name" } + fn usage(&self) -> &'static str { + indoc! {r#" + Returns the name of the timezone in the Vector configuration (see + [global configuration options](/docs/reference/configuration/global-options)). + If the configuration is set to `local`, then it attempts to + determine the name of the timezone from the host OS. If this + is not possible, then it returns the fixed offset of the + local timezone for the current time in the format `"[+-]HH:MM"`, + for example, `"+02:00"`. + "#} + } + #[cfg(not(feature = "__mock_return_values_for_tests"))] fn examples(&self) -> &'static [Example] { &[example! { diff --git a/src/stdlib/haversine.rs b/src/stdlib/haversine.rs index 0b97ad4e03..acc4232fa8 100644 --- a/src/stdlib/haversine.rs +++ b/src/stdlib/haversine.rs @@ -77,6 +77,10 @@ impl Function for Haversine { "haversine" } + fn usage(&self) -> &'static str { + "Calculates [haversine](https://en.wikipedia.org/wiki/Haversine_formula) distance and bearing between two points." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/hmac.rs b/src/stdlib/hmac.rs index 0ca5512a13..ee268198bf 100644 --- a/src/stdlib/hmac.rs +++ b/src/stdlib/hmac.rs @@ -40,6 +40,20 @@ impl Function for Hmac { "hmac" } + fn usage(&self) -> &'static str { + indoc! {" + Calculates a [HMAC](https://en.wikipedia.org/wiki/HMAC) of the `value` using the given `key`. + The hashing `algorithm` used can be optionally specified. + + For most use cases, the resulting bytestream should be encoded into a hex or base64 + string using either [encode_base16](/docs/reference/vrl/functions/#encode_base16) or + [encode_base64](/docs/reference/vrl/functions/#encode_base64). + + 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 { diff --git a/src/stdlib/http_request.rs b/src/stdlib/http_request.rs index c8a220380c..24028be777 100644 --- a/src/stdlib/http_request.rs +++ b/src/stdlib/http_request.rs @@ -267,6 +267,10 @@ impl Function for HttpRequest { "http_request" } + fn usage(&self) -> &'static str { + "Makes an HTTP request to the specified URL. This function performs synchronous blocking operations and is not recommended for frequent or performance-critical workflows due to potential network-related delays." + } + #[cfg(not(feature = "test"))] fn examples(&self) -> &'static [Example] { &[] diff --git a/src/stdlib/includes.rs b/src/stdlib/includes.rs index 88f0eddb12..b4e89d93f1 100644 --- a/src/stdlib/includes.rs +++ b/src/stdlib/includes.rs @@ -14,6 +14,10 @@ impl Function for Includes { "includes" } + fn usage(&self) -> &'static str { + "Determines whether the `value` array includes the specified `item`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/integer.rs b/src/stdlib/integer.rs index 5057f81bb1..8317f8dd3a 100644 --- a/src/stdlib/integer.rs +++ b/src/stdlib/integer.rs @@ -15,6 +15,10 @@ impl Function for Integer { "int" } + fn usage(&self) -> &'static str { + "Returns `value` if it is an integer, otherwise returns an error. This enables the type checker to guarantee that the returned value is an integer and can be used in any function that expects an integer." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/ip_aton.rs b/src/stdlib/ip_aton.rs index e33a2dc07e..c735d90d76 100644 --- a/src/stdlib/ip_aton.rs +++ b/src/stdlib/ip_aton.rs @@ -17,6 +17,15 @@ impl Function for IpAton { "ip_aton" } + fn usage(&self) -> &'static str { + indoc! {" + Converts IPv4 address in numbers-and-dots notation into network-order + bytes represented as an integer. + + This behavior mimics [inet_aton](https://linux.die.net/man/3/inet_aton). + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/ip_cidr_contains.rs b/src/stdlib/ip_cidr_contains.rs index 05f681cdff..a6a3ebdfe7 100644 --- a/src/stdlib/ip_cidr_contains.rs +++ b/src/stdlib/ip_cidr_contains.rs @@ -65,6 +65,10 @@ impl Function for IpCidrContains { "ip_cidr_contains" } + fn usage(&self) -> &'static str { + "Determines whether the `ip` is contained in the block referenced by the `cidr`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/ip_ntoa.rs b/src/stdlib/ip_ntoa.rs index 6184a58cf2..b067db953d 100644 --- a/src/stdlib/ip_ntoa.rs +++ b/src/stdlib/ip_ntoa.rs @@ -18,6 +18,15 @@ impl Function for IpNtoa { "ip_ntoa" } + fn usage(&self) -> &'static str { + indoc! {" + Converts numeric representation of IPv4 address in network-order bytes + to numbers-and-dots notation. + + This behavior mimics [inet_ntoa](https://linux.die.net/man/3/inet_ntoa). + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/ip_ntop.rs b/src/stdlib/ip_ntop.rs index 1d0457c56d..76527db369 100644 --- a/src/stdlib/ip_ntop.rs +++ b/src/stdlib/ip_ntop.rs @@ -25,6 +25,14 @@ impl Function for IpNtop { "ip_ntop" } + fn usage(&self) -> &'static str { + indoc! {" + Converts IPv4 and IPv6 addresses from binary to text form. + + This behavior mimics [inet_ntop](https://linux.die.net/man/3/inet_ntop). + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/ip_pton.rs b/src/stdlib/ip_pton.rs index 643f1f006d..32c548200d 100644 --- a/src/stdlib/ip_pton.rs +++ b/src/stdlib/ip_pton.rs @@ -24,6 +24,17 @@ impl Function for IpPton { "ip_pton" } + fn usage(&self) -> &'static str { + indoc! {" + Converts IPv4 and IPv6 addresses from text to binary form. + + * The binary form of IPv4 addresses is 4 bytes (32 bits) long. + * The binary form of IPv6 addresses is 16 bytes (128 bits) long. + + This behavior mimics [inet_pton](https://linux.die.net/man/3/inet_pton). + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/ip_subnet.rs b/src/stdlib/ip_subnet.rs index 21483c0cb4..b73e89470c 100644 --- a/src/stdlib/ip_subnet.rs +++ b/src/stdlib/ip_subnet.rs @@ -42,6 +42,12 @@ impl Function for IpSubnet { "ip_subnet" } + fn usage(&self) -> &'static str { + indoc! {" + Extracts the subnet address from the `ip` using the supplied `subnet`. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/ip_to_ipv6.rs b/src/stdlib/ip_to_ipv6.rs index d9d5f0c34e..12791520cd 100644 --- a/src/stdlib/ip_to_ipv6.rs +++ b/src/stdlib/ip_to_ipv6.rs @@ -20,6 +20,10 @@ impl Function for IpToIpv6 { "ip_to_ipv6" } + fn usage(&self) -> &'static str { + "Converts the `ip` to an IPv6 address." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/ipv6_to_ipv4.rs b/src/stdlib/ipv6_to_ipv4.rs index e2f7bdcbe8..57d25bde9d 100644 --- a/src/stdlib/ipv6_to_ipv4.rs +++ b/src/stdlib/ipv6_to_ipv4.rs @@ -23,6 +23,13 @@ impl Function for Ipv6ToIpV4 { "ipv6_to_ipv4" } + fn usage(&self) -> &'static str { + indoc! {" + Converts the `ip` to an IPv4 address. `ip` is returned unchanged if it's already an IPv4 address. If `ip` is + currently an IPv6 address then it needs to be IPv4 compatible, otherwise an error is thrown. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_array.rs b/src/stdlib/is_array.rs index a27e082ae9..d2903c1f19 100644 --- a/src/stdlib/is_array.rs +++ b/src/stdlib/is_array.rs @@ -9,6 +9,10 @@ impl Function for IsArray { "is_array" } + fn usage(&self) -> &'static str { + "Check if the `value`'s type is an array." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_boolean.rs b/src/stdlib/is_boolean.rs index 900b71af93..539b00570a 100644 --- a/src/stdlib/is_boolean.rs +++ b/src/stdlib/is_boolean.rs @@ -9,6 +9,10 @@ impl Function for IsBoolean { "is_boolean" } + fn usage(&self) -> &'static str { + "Check if the `value`'s type is a boolean." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_empty.rs b/src/stdlib/is_empty.rs index 200739ff72..2d518c0cf8 100644 --- a/src/stdlib/is_empty.rs +++ b/src/stdlib/is_empty.rs @@ -27,6 +27,10 @@ impl Function for IsEmpty { "is_empty" } + fn usage(&self) -> &'static str { + "Check if the object, array, or string has a length of `0`." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_float.rs b/src/stdlib/is_float.rs index 910e96fd36..85fcd95b3c 100644 --- a/src/stdlib/is_float.rs +++ b/src/stdlib/is_float.rs @@ -9,6 +9,10 @@ impl Function for IsFloat { "is_float" } + fn usage(&self) -> &'static str { + "Check if the `value`'s type is a float." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_integer.rs b/src/stdlib/is_integer.rs index e809433f76..be61de1bf1 100644 --- a/src/stdlib/is_integer.rs +++ b/src/stdlib/is_integer.rs @@ -9,6 +9,10 @@ impl Function for IsInteger { "is_integer" } + fn usage(&self) -> &'static str { + "Check if the value`'s type is an integer." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_ipv4.rs b/src/stdlib/is_ipv4.rs index 1f265fb148..19cb1d721e 100644 --- a/src/stdlib/is_ipv4.rs +++ b/src/stdlib/is_ipv4.rs @@ -14,6 +14,16 @@ impl Function for IsIpv4 { "is_ipv4" } + fn usage(&self) -> &'static str { + indoc! {" + Check if the string is a valid IPv4 address or not. + + An [IPv4-mapped](https://datatracker.ietf.org/doc/html/rfc6890) or + [IPv4-compatible](https://datatracker.ietf.org/doc/html/rfc6890) IPv6 address is not considered + valid for the purpose of this function. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_ipv6.rs b/src/stdlib/is_ipv6.rs index 5a41675c33..11e1b4442d 100644 --- a/src/stdlib/is_ipv6.rs +++ b/src/stdlib/is_ipv6.rs @@ -14,6 +14,10 @@ impl Function for IsIpv6 { "is_ipv6" } + fn usage(&self) -> &'static str { + "Check if the string is a valid IPv6 address or not." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_json.rs b/src/stdlib/is_json.rs index 2c4b450302..2ef1df4bdb 100644 --- a/src/stdlib/is_json.rs +++ b/src/stdlib/is_json.rs @@ -51,6 +51,10 @@ impl Function for IsJson { "is_json" } + fn usage(&self) -> &'static str { + "Check if the string is a valid JSON document." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/is_null.rs b/src/stdlib/is_null.rs index ff061a9478..fe34d20b92 100644 --- a/src/stdlib/is_null.rs +++ b/src/stdlib/is_null.rs @@ -9,6 +9,10 @@ impl Function for IsNull { "is_null" } + fn usage(&self) -> &'static str { + "Check if `value`'s type is `null`. For a more relaxed function, see [`is_nullish`](/docs/reference/vrl/functions#is_nullish)." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_nullish.rs b/src/stdlib/is_nullish.rs index bcc77730a8..398cabc8c4 100644 --- a/src/stdlib/is_nullish.rs +++ b/src/stdlib/is_nullish.rs @@ -13,6 +13,10 @@ impl Function for IsNullish { "is_nullish" } + fn usage(&self) -> &'static str { + r#"Determines whether `value` is nullish. Returns `true` if the specified `value` is `null`, an empty string, a string containing only whitespace, or the string `"-"`. Returns `false` otherwise."# + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_object.rs b/src/stdlib/is_object.rs index ddbd4b0543..948c0b94c5 100644 --- a/src/stdlib/is_object.rs +++ b/src/stdlib/is_object.rs @@ -9,6 +9,10 @@ impl Function for IsObject { "is_object" } + fn usage(&self) -> &'static str { + "Check if `value`'s type is an object." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_regex.rs b/src/stdlib/is_regex.rs index acdeb0dd47..e40740033c 100644 --- a/src/stdlib/is_regex.rs +++ b/src/stdlib/is_regex.rs @@ -9,6 +9,10 @@ impl Function for IsRegex { "is_regex" } + fn usage(&self) -> &'static str { + "Check if `value`'s type is a regex." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_string.rs b/src/stdlib/is_string.rs index ea19efb63f..2e4dc377af 100644 --- a/src/stdlib/is_string.rs +++ b/src/stdlib/is_string.rs @@ -9,6 +9,10 @@ impl Function for IsString { "is_string" } + fn usage(&self) -> &'static str { + "Check if `value`'s type is a string." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/is_timestamp.rs b/src/stdlib/is_timestamp.rs index aa8303aca1..7d564727e9 100644 --- a/src/stdlib/is_timestamp.rs +++ b/src/stdlib/is_timestamp.rs @@ -9,6 +9,10 @@ impl Function for IsTimestamp { "is_timestamp" } + fn usage(&self) -> &'static str { + "Check if `value`'s type is a timestamp." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/join.rs b/src/stdlib/join.rs index f92ce93187..b3456536f9 100644 --- a/src/stdlib/join.rs +++ b/src/stdlib/join.rs @@ -24,6 +24,10 @@ impl Function for Join { "join" } + fn usage(&self) -> &'static str { + "Joins each string in the `value` array into a single string, with items optionally separated from one another by a `separator`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/keys.rs b/src/stdlib/keys.rs index c68d8f92fc..fec1bff8b0 100644 --- a/src/stdlib/keys.rs +++ b/src/stdlib/keys.rs @@ -14,6 +14,10 @@ impl Function for Keys { "keys" } + fn usage(&self) -> &'static str { + "Returns the keys from the object passed into the function." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/length.rs b/src/stdlib/length.rs index 8f218274de..97fa9f1116 100644 --- a/src/stdlib/length.rs +++ b/src/stdlib/length.rs @@ -23,6 +23,17 @@ impl Function for Length { "length" } + fn usage(&self) -> &'static str { + indoc! {" + Returns the length of the `value`. + + * If `value` is an array, returns the number of elements. + * If `value` is an object, returns the number of top-level keys. + * If `value` is a string, returns the number of bytes in the string. If + you want the number of characters, see `strlen`. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/log.rs b/src/stdlib/log.rs index 4f04c3a2e5..d9e02444a9 100644 --- a/src/stdlib/log.rs +++ b/src/stdlib/log.rs @@ -8,6 +8,10 @@ impl Function for Log { "log" } + fn usage(&self) -> &'static str { + "Logs the `value` to [stdout](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) at the specified `level`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/map_keys.rs b/src/stdlib/map_keys.rs index 0dee28b350..bc32fe69d4 100644 --- a/src/stdlib/map_keys.rs +++ b/src/stdlib/map_keys.rs @@ -28,6 +28,42 @@ impl Function for MapKeys { "map_keys" } + fn usage(&self) -> &'static str { + indoc! {" + Map the keys within an object. + + If `recursive` is enabled, the function iterates into nested + objects, using the following rules: + + 1. Iteration starts at the root. + 2. For every nested object type: + - First return the key of the object type itself. + - Then recurse into the object, and loop back to item (1) + in this list. + - Any mutation done on a nested object *before* recursing into + it, are preserved. + 3. For every nested array type: + - First return the key of the array type itself. + - Then find all objects within the array, and apply item (2) + to each individual object. + + The above rules mean that `map_keys` with + `recursive` enabled finds *all* keys in the target, + regardless of whether nested objects are nested inside arrays. + + The function uses the function closure syntax to allow reading + the key for each item in the object. + + The same scoping rules apply to closure blocks as they do for + regular blocks. This means that any variable defined in parent scopes + is accessible, and mutations to those variables are preserved, + but any new variables instantiated in the closure block are + unavailable outside of the block. + + See the examples below to learn about the closure syntax. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/map_values.rs b/src/stdlib/map_values.rs index c77b4a49c5..014ee5f137 100644 --- a/src/stdlib/map_values.rs +++ b/src/stdlib/map_values.rs @@ -32,6 +32,34 @@ impl Function for MapValues { "map_values" } + fn usage(&self) -> &'static str { + indoc! {" + Map the values within a collection. + + If `recursive` is enabled, the function iterates into nested + collections, using the following rules: + + 1. Iteration starts at the root. + 2. For every nested collection type: + - First return the collection type itself. + - Then recurse into the collection, and loop back to item (1) + in the list + - Any mutation done on a collection *before* recursing into it, + are preserved. + + The function uses the function closure syntax to allow mutating + the value for each item in the collection. + + The same scoping rules apply to closure blocks as they do for + regular blocks, meaning, any variable defined in parent scopes + are accessible, and mutations to those variables are preserved, + but any new variables instantiated in the closure block are + unavailable outside of the block. + + Check out the examples below to learn about the closure syntax. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/match.rs b/src/stdlib/match.rs index 3f4f75ca8b..069231a8c9 100644 --- a/src/stdlib/match.rs +++ b/src/stdlib/match.rs @@ -21,6 +21,10 @@ impl Function for Match { "match" } + fn usage(&self) -> &'static str { + "Determines whether the `value` matches the `pattern`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/match_any.rs b/src/stdlib/match_any.rs index f4a5411239..95c4b2ae16 100644 --- a/src/stdlib/match_any.rs +++ b/src/stdlib/match_any.rs @@ -14,6 +14,10 @@ impl Function for MatchAny { "match_any" } + fn usage(&self) -> &'static str { + "Determines whether `value` matches any of the given `patterns`. All patterns are checked in a single pass over the target string, giving this function a potential performance advantage over the multiple calls in the `match` function." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/match_array.rs b/src/stdlib/match_array.rs index 3bb20d47c3..9d40f9c874 100644 --- a/src/stdlib/match_array.rs +++ b/src/stdlib/match_array.rs @@ -27,6 +27,10 @@ impl Function for MatchArray { "match_array" } + fn usage(&self) -> &'static str { + "Determines whether the elements in the `value` array matches the `pattern`. By default, it checks that at least one element matches, but can be set to determine if all the elements match." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/match_datadog_query.rs b/src/stdlib/match_datadog_query.rs index b6a986649c..f85fee000d 100644 --- a/src/stdlib/match_datadog_query.rs +++ b/src/stdlib/match_datadog_query.rs @@ -19,6 +19,10 @@ impl Function for MatchDatadogQuery { "match_datadog_query" } + fn usage(&self) -> &'static str { + "Matches an object against a [Datadog Search Syntax](https://docs.datadoghq.com/logs/explorer/search_syntax/) query." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/md5.rs b/src/stdlib/md5.rs index b3cc9d6be7..5b2e82756f 100644 --- a/src/stdlib/md5.rs +++ b/src/stdlib/md5.rs @@ -14,6 +14,10 @@ impl Function for Md5 { "md5" } + fn usage(&self) -> &'static str { + "Calculates an md5 hash of the `value`." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/merge.rs b/src/stdlib/merge.rs index b3228ce11b..19f4c6bf3b 100644 --- a/src/stdlib/merge.rs +++ b/src/stdlib/merge.rs @@ -9,6 +9,10 @@ impl Function for Merge { "merge" } + fn usage(&self) -> &'static str { + "Merges the `from` object into the `to` object." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/mod_func.rs b/src/stdlib/mod_func.rs index 4991b61c7a..e62b907c99 100644 --- a/src/stdlib/mod_func.rs +++ b/src/stdlib/mod_func.rs @@ -13,6 +13,10 @@ impl Function for Mod { "mod" } + fn usage(&self) -> &'static str { + "Calculates the remainder of `value` divided by `modulus`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/now.rs b/src/stdlib/now.rs index a49635b171..2eb9fb3e91 100644 --- a/src/stdlib/now.rs +++ b/src/stdlib/now.rs @@ -9,6 +9,10 @@ impl Function for Now { "now" } + fn usage(&self) -> &'static str { + "Returns the current timestamp in the UTC timezone with nanosecond precision." + } + #[cfg(not(feature = "__mock_return_values_for_tests"))] fn examples(&self) -> &'static [Example] { &[example! { diff --git a/src/stdlib/object.rs b/src/stdlib/object.rs index 7f43fd2843..c5c462bfef 100644 --- a/src/stdlib/object.rs +++ b/src/stdlib/object.rs @@ -15,6 +15,10 @@ impl Function for Object { "object" } + fn usage(&self) -> &'static str { + "Returns `value` if it is an object, otherwise returns an error. This enables the type checker to guarantee that the returned value is an object and can be used in any function that expects an object." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/object_from_array.rs b/src/stdlib/object_from_array.rs index 2f29579960..d765a93dda 100644 --- a/src/stdlib/object_from_array.rs +++ b/src/stdlib/object_from_array.rs @@ -46,6 +46,16 @@ impl Function for ObjectFromArray { "object_from_array" } + fn usage(&self) -> &'static str { + indoc! {" + Iterate over either one array of arrays or a pair of arrays and create an object out of all the key-value pairs contained in them. + With one array of arrays, any entries with no value use `null` instead. + Any keys that are `null` skip the corresponding value. + + If a single parameter is given, it must contain an array of all the input arrays. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_apache_log.rs b/src/stdlib/parse_apache_log.rs index 2317762f9f..27f468dff2 100644 --- a/src/stdlib/parse_apache_log.rs +++ b/src/stdlib/parse_apache_log.rs @@ -43,6 +43,13 @@ impl Function for ParseApacheLog { "parse_apache_log" } + fn usage(&self) -> &'static str { + indoc! {" + Parses Apache access and error log lines. Lines can be in [`common`](https://httpd.apache.org/docs/current/logs.html#common), + [`combined`](https://httpd.apache.org/docs/current/logs.html#combined), or the default [`error`](https://httpd.apache.org/docs/current/logs.html#errorlog) format. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_aws_alb_log.rs b/src/stdlib/parse_aws_alb_log.rs index 28f6524533..5e5fd41089 100644 --- a/src/stdlib/parse_aws_alb_log.rs +++ b/src/stdlib/parse_aws_alb_log.rs @@ -26,6 +26,10 @@ impl Function for ParseAwsAlbLog { "parse_aws_alb_log" } + fn usage(&self) -> &'static str { + "Parses `value` in the [Elastic Load Balancer Access format](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html#access-log-entry-examples)." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_aws_cloudwatch_log_subscription_message.rs b/src/stdlib/parse_aws_cloudwatch_log_subscription_message.rs index 34c1960bc1..25dba31fb4 100644 --- a/src/stdlib/parse_aws_cloudwatch_log_subscription_message.rs +++ b/src/stdlib/parse_aws_cloudwatch_log_subscription_message.rs @@ -87,6 +87,10 @@ impl Function for ParseAwsCloudWatchLogSubscriptionMessage { "parse_aws_cloudwatch_log_subscription_message" } + fn usage(&self) -> &'static str { + "Parses AWS CloudWatch Logs events (configured through AWS Cloudwatch subscriptions) from the `aws_kinesis_firehose` source." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Parse AWS Cloudwatch Log subscription message", diff --git a/src/stdlib/parse_aws_vpc_flow_log.rs b/src/stdlib/parse_aws_vpc_flow_log.rs index 98d811db56..991c9a1faa 100644 --- a/src/stdlib/parse_aws_vpc_flow_log.rs +++ b/src/stdlib/parse_aws_vpc_flow_log.rs @@ -21,6 +21,10 @@ impl Function for ParseAwsVpcFlowLog { "parse_aws_vpc_flow_log" } + fn usage(&self) -> &'static str { + "Parses `value` in the [VPC Flow Logs format](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs.html)." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_bytes.rs b/src/stdlib/parse_bytes.rs index 8a9b439042..59fb954c2e 100644 --- a/src/stdlib/parse_bytes.rs +++ b/src/stdlib/parse_bytes.rs @@ -84,6 +84,10 @@ impl Function for ParseBytes { "parse_bytes" } + fn usage(&self) -> &'static str { + "Parses the `value` into a human-readable bytes format specified by `unit` and `base`." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_cef.rs b/src/stdlib/parse_cef.rs index 83b165d3bd..ca09d827a1 100644 --- a/src/stdlib/parse_cef.rs +++ b/src/stdlib/parse_cef.rs @@ -51,6 +51,10 @@ impl Function for ParseCef { "parse_cef" } + fn usage(&self) -> &'static str { + "Parses the `value` in CEF (Common Event Format) format. Ignores everything up to CEF header. Empty values are returned as empty strings. Surrounding quotes are removed from values." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_common_log.rs b/src/stdlib/parse_common_log.rs index bdd8f632c5..0e0b1d31ee 100644 --- a/src/stdlib/parse_common_log.rs +++ b/src/stdlib/parse_common_log.rs @@ -27,6 +27,10 @@ impl Function for ParseCommonLog { "parse_common_log" } + fn usage(&self) -> &'static str { + "Parses the `value` using the [Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF)." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_csv.rs b/src/stdlib/parse_csv.rs index 736184a3dd..821c19f7e0 100644 --- a/src/stdlib/parse_csv.rs +++ b/src/stdlib/parse_csv.rs @@ -38,6 +38,10 @@ impl Function for ParseCsv { "parse_csv" } + fn usage(&self) -> &'static str { + "Parses a single CSV formatted row. Only the first row is parsed in case of multiline input value." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_duration.rs b/src/stdlib/parse_duration.rs index 103c7e9496..fe56c0031a 100644 --- a/src/stdlib/parse_duration.rs +++ b/src/stdlib/parse_duration.rs @@ -72,6 +72,10 @@ impl Function for ParseDuration { "parse_duration" } + fn usage(&self) -> &'static str { + "Parses the `value` into a human-readable duration format specified by `unit`." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_etld.rs b/src/stdlib/parse_etld.rs index c751d96a81..71f3c77c81 100644 --- a/src/stdlib/parse_etld.rs +++ b/src/stdlib/parse_etld.rs @@ -12,6 +12,10 @@ impl Function for ParseEtld { "parse_etld" } + fn usage(&self) -> &'static str { + "Parses the [eTLD](https://developer.mozilla.org/en-US/docs/Glossary/eTLD) from `value` representing domain name." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_float.rs b/src/stdlib/parse_float.rs index 3897633b09..c8498a3e3e 100644 --- a/src/stdlib/parse_float.rs +++ b/src/stdlib/parse_float.rs @@ -13,6 +13,10 @@ impl Function for ParseFloat { "parse_float" } + fn usage(&self) -> &'static str { + "Parses the string `value` representing a floating point number in base 10 to a float." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/parse_glog.rs b/src/stdlib/parse_glog.rs index 1961b9a593..fc27174d0a 100644 --- a/src/stdlib/parse_glog.rs +++ b/src/stdlib/parse_glog.rs @@ -77,6 +77,10 @@ impl Function for ParseGlog { "parse_glog" } + fn usage(&self) -> &'static str { + "Parses the `value` using the [glog (Google Logging Library)](https://github.com/google/glog) format." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Parse using glog", diff --git a/src/stdlib/parse_grok.rs b/src/stdlib/parse_grok.rs index 0e4fb47f6b..8c5eb9d6d9 100644 --- a/src/stdlib/parse_grok.rs +++ b/src/stdlib/parse_grok.rs @@ -90,6 +90,10 @@ impl Function for ParseGrok { "parse_grok" } + fn usage(&self) -> &'static str { + "Parses the `value` using the [`grok`](https://github.com/daschl/grok/tree/master/patterns) format. All patterns [listed here](https://github.com/daschl/grok/tree/master/patterns) are supported." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_groks.rs b/src/stdlib/parse_groks.rs index 871a80c9de..95f0f653a6 100644 --- a/src/stdlib/parse_groks.rs +++ b/src/stdlib/parse_groks.rs @@ -77,6 +77,10 @@ impl Function for ParseGroks { "parse_groks" } + fn usage(&self) -> &'static str { + "Parses the `value` using multiple [`grok`](https://github.com/daschl/grok/tree/master/patterns) patterns. All patterns [listed here](https://github.com/daschl/grok/tree/master/patterns) are supported." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_influxdb.rs b/src/stdlib/parse_influxdb.rs index 3b049c66f8..87054c8d90 100644 --- a/src/stdlib/parse_influxdb.rs +++ b/src/stdlib/parse_influxdb.rs @@ -134,6 +134,10 @@ impl Function for ParseInfluxDB { "parse an InfluxDB line protocol string into a list of vector-compatible metrics" } + fn usage(&self) -> &'static str { + "Parses the `value` as an [InfluxDB line protocol](https://docs.influxdata.com/influxdb/cloud/reference/syntax/line-protocol/) string, producing a list of Vector-compatible metrics." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/parse_int.rs b/src/stdlib/parse_int.rs index 52bfb9001a..5200ccaf39 100644 --- a/src/stdlib/parse_int.rs +++ b/src/stdlib/parse_int.rs @@ -41,6 +41,10 @@ impl Function for ParseInt { "parse_int" } + fn usage(&self) -> &'static str { + "Parses the string `value` representing a number in an optional base/radix to an integer." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_key_value.rs b/src/stdlib/parse_key_value.rs index c7d6f33f51..dc3c9c43a4 100644 --- a/src/stdlib/parse_key_value.rs +++ b/src/stdlib/parse_key_value.rs @@ -74,6 +74,15 @@ impl Function for ParseKeyValue { "parse_key_value" } + fn usage(&self) -> &'static str { + indoc! {r#" + Parses the `value` in key-value format. Also known as [logfmt](https://brandur.org/logfmt). + + * Keys and values can be wrapped with `"`. + * `"` characters can be escaped using `\`. + "#} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_klog.rs b/src/stdlib/parse_klog.rs index d0d3384387..ad423bd271 100644 --- a/src/stdlib/parse_klog.rs +++ b/src/stdlib/parse_klog.rs @@ -101,6 +101,10 @@ impl Function for ParseKlog { "parse_klog" } + fn usage(&self) -> &'static str { + "Parses the `value` using the [klog](https://github.com/kubernetes/klog) format used by Kubernetes components." + } + fn examples(&self) -> &'static [Example] { EXAMPLES.as_slice() } diff --git a/src/stdlib/parse_linux_authorization.rs b/src/stdlib/parse_linux_authorization.rs index aa6021d43c..dde5a28057 100644 --- a/src/stdlib/parse_linux_authorization.rs +++ b/src/stdlib/parse_linux_authorization.rs @@ -36,6 +36,10 @@ impl Function for ParseLinuxAuthorization { "parse_linux_authorization" } + fn usage(&self) -> &'static str { + "Parses Linux authorization logs usually found under either `/var/log/auth.log` (for Debian-based systems) or `/var/log/secure` (for RedHat-based systems) according to [Syslog](https://en.wikipedia.org/wiki/Syslog) format." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/parse_logfmt.rs b/src/stdlib/parse_logfmt.rs index 8e4443273c..907c83c82a 100644 --- a/src/stdlib/parse_logfmt.rs +++ b/src/stdlib/parse_logfmt.rs @@ -9,6 +9,16 @@ impl Function for ParseLogFmt { "parse_logfmt" } + fn usage(&self) -> &'static str { + indoc! {r#" + Parses the `value` in [logfmt](https://brandur.org/logfmt). + + * Keys and values can be wrapped using the `"` character. + * `"` characters can be escaped by the `\` character. + * As per this [logfmt specification](https://pkg.go.dev/github.com/kr/logfmt#section-documentation), the `parse_logfmt` function accepts standalone keys and assigns them a Boolean value of `true`. + "#} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/parse_nginx_log.rs b/src/stdlib/parse_nginx_log.rs index 7666eae3a4..a38a60f803 100644 --- a/src/stdlib/parse_nginx_log.rs +++ b/src/stdlib/parse_nginx_log.rs @@ -40,6 +40,10 @@ impl Function for ParseNginxLog { "parse_nginx_log" } + fn usage(&self) -> &'static str { + "Parses Nginx access and error log lines. Lines can be in [`combined`](https://nginx.org/en/docs/http/ngx_http_log_module.html), [`ingress_upstreaminfo`](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/log-format/), [`main`](https://hg.nginx.org/pkg-oss/file/tip/debian/debian/nginx.conf) or [`error`](https://github.com/nginx/nginx/blob/branches/stable-1.18/src/core/ngx_log.c#L102) format." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_query_string.rs b/src/stdlib/parse_query_string.rs index 0829778f0d..2211d4db8c 100644 --- a/src/stdlib/parse_query_string.rs +++ b/src/stdlib/parse_query_string.rs @@ -9,6 +9,10 @@ impl Function for ParseQueryString { "parse_query_string" } + fn usage(&self) -> &'static str { + "Parses the `value` as a query string." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_regex.rs b/src/stdlib/parse_regex.rs index 5d2c9024c9..1176b48a9b 100644 --- a/src/stdlib/parse_regex.rs +++ b/src/stdlib/parse_regex.rs @@ -20,6 +20,14 @@ impl Function for ParseRegex { "parse_regex" } + fn usage(&self) -> &'static str { + indoc! {" + Parses the `value` using the provided [Regex](https://en.wikipedia.org/wiki/Regular_expression) `pattern`. + + This function differs from the `parse_regex_all` function in that it returns only the first match. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_regex_all.rs b/src/stdlib/parse_regex_all.rs index ad30c2c1db..68d5837d3a 100644 --- a/src/stdlib/parse_regex_all.rs +++ b/src/stdlib/parse_regex_all.rs @@ -21,6 +21,14 @@ impl Function for ParseRegexAll { "parse_regex_all" } + fn usage(&self) -> &'static str { + indoc! {" + Parses the `value` using the provided [Regex](https://en.wikipedia.org/wiki/Regular_expression) `pattern`. + + This function differs from the `parse_regex` function in that it returns _all_ matches, not just the first. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_ruby_hash.rs b/src/stdlib/parse_ruby_hash.rs index 974b4b1986..67e8adabaa 100644 --- a/src/stdlib/parse_ruby_hash.rs +++ b/src/stdlib/parse_ruby_hash.rs @@ -13,6 +13,10 @@ impl Function for ParseRubyHash { "parse_ruby_hash" } + fn usage(&self) -> &'static str { + "Parses the `value` as ruby hash." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Parse ruby hash", diff --git a/src/stdlib/parse_syslog.rs b/src/stdlib/parse_syslog.rs index bed793b076..9b4f5d0988 100644 --- a/src/stdlib/parse_syslog.rs +++ b/src/stdlib/parse_syslog.rs @@ -26,6 +26,10 @@ impl Function for ParseSyslog { "parse_syslog" } + fn usage(&self) -> &'static str { + "Parses the `value` in [Syslog](https://en.wikipedia.org/wiki/Syslog) format." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/parse_timestamp.rs b/src/stdlib/parse_timestamp.rs index 5a74487802..ab0b0a8bbe 100644 --- a/src/stdlib/parse_timestamp.rs +++ b/src/stdlib/parse_timestamp.rs @@ -39,6 +39,10 @@ impl Function for ParseTimestamp { "parse_timestamp" } + fn usage(&self) -> &'static str { + "Parses the `value` in [strptime](https://docs.rs/chrono/latest/chrono/format/strftime/index.html#specifiers) `format`." + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/parse_tokens.rs b/src/stdlib/parse_tokens.rs index 9833df2f9b..f882af2911 100644 --- a/src/stdlib/parse_tokens.rs +++ b/src/stdlib/parse_tokens.rs @@ -22,6 +22,16 @@ impl Function for ParseTokens { "parse_tokens" } + fn usage(&self) -> &'static str { + indoc! {r#" + Parses the `value` in token format. A token is considered to be one of the following: + + * A word surrounded by whitespace. + * Text delimited by double quotes: `".."`. Quotes can be included in the token if they are escaped by a backslash (`\`). + * Text delimited by square brackets: `[..]`. Closing square brackets can be included in the token if they are escaped by a backslash (`\`). + "#} + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Parse tokens", diff --git a/src/stdlib/parse_url.rs b/src/stdlib/parse_url.rs index 9501b8a7ad..ff80d556b7 100644 --- a/src/stdlib/parse_url.rs +++ b/src/stdlib/parse_url.rs @@ -10,6 +10,10 @@ impl Function for ParseUrl { "parse_url" } + fn usage(&self) -> &'static str { + "Parses the `value` in [URL](https://en.wikipedia.org/wiki/URL) format." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/parse_xml.rs b/src/stdlib/parse_xml.rs index 608c8dcd90..938ae1ba68 100644 --- a/src/stdlib/parse_xml.rs +++ b/src/stdlib/parse_xml.rs @@ -9,6 +9,10 @@ impl Function for ParseXml { "parse_xml" } + fn usage(&self) -> &'static str { + "Parses the `value` as XML." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Parse XML", diff --git a/src/stdlib/pop.rs b/src/stdlib/pop.rs index 76586239e7..ed76d83da1 100644 --- a/src/stdlib/pop.rs +++ b/src/stdlib/pop.rs @@ -14,6 +14,10 @@ impl Function for Pop { "pop" } + fn usage(&self) -> &'static str { + "Removes the last item from the `value` array." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/push.rs b/src/stdlib/push.rs index fe97f824bc..a544b3da3d 100644 --- a/src/stdlib/push.rs +++ b/src/stdlib/push.rs @@ -14,6 +14,10 @@ impl Function for Push { "push" } + fn usage(&self) -> &'static str { + "Adds the `item` to the end of the `value` array." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/random_bool.rs b/src/stdlib/random_bool.rs index 5b5072262a..065f9f294d 100644 --- a/src/stdlib/random_bool.rs +++ b/src/stdlib/random_bool.rs @@ -16,6 +16,10 @@ impl Function for RandomBool { "random_bool" } + fn usage(&self) -> &'static str { + "Returns a random boolean." + } + fn parameters(&self) -> &'static [Parameter] { &[] } diff --git a/src/stdlib/random_bytes.rs b/src/stdlib/random_bytes.rs index 626107715e..446049cc9e 100644 --- a/src/stdlib/random_bytes.rs +++ b/src/stdlib/random_bytes.rs @@ -22,6 +22,10 @@ impl Function for RandomBytes { "random_bytes" } + fn usage(&self) -> &'static str { + "A cryptographically secure random number generator. Returns a string value containing the number of random bytes requested." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "length", diff --git a/src/stdlib/random_float.rs b/src/stdlib/random_float.rs index f4f4dfcf04..a9a2a6011c 100644 --- a/src/stdlib/random_float.rs +++ b/src/stdlib/random_float.rs @@ -36,6 +36,10 @@ impl Function for RandomFloat { "random_float" } + fn usage(&self) -> &'static str { + "Returns a random float between [min, max)." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/random_int.rs b/src/stdlib/random_int.rs index 5e1d5674bc..731eaa1edb 100644 --- a/src/stdlib/random_int.rs +++ b/src/stdlib/random_int.rs @@ -31,6 +31,10 @@ impl Function for RandomInt { "random_int" } + fn usage(&self) -> &'static str { + "Returns a random integer between [min, max)." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/redact.rs b/src/stdlib/redact.rs index be5ab270b3..b01361b6eb 100644 --- a/src/stdlib/redact.rs +++ b/src/stdlib/redact.rs @@ -25,6 +25,17 @@ impl Function for Redact { "redact" } + fn usage(&self) -> &'static str { + indoc! {" + Redact sensitive data in `value` such as: + + - [US social security card numbers](https://www.ssa.gov/history/ssn/geocard.html) + - Other forms of personally identifiable information with custom patterns + + This can help achieve compliance by ensuring sensitive data does not leave your network. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/remove.rs b/src/stdlib/remove.rs index a4b32aa23c..e043afa441 100644 --- a/src/stdlib/remove.rs +++ b/src/stdlib/remove.rs @@ -48,6 +48,19 @@ impl Function for Remove { "remove" } + fn usage(&self) -> &'static str { + indoc! {" + Dynamically remove the value for a given path. + + If you know the path you want to remove, use + the `del` function and static paths such as `del(.foo.bar[1])` + to remove the value at that path. The `del` function returns the + deleted value, and is more performant than `remove`. + However, if you do not know the path names, use the dynamic + `remove` function to remove the value at the provided path. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/replace.rs b/src/stdlib/replace.rs index dd8ac55e5f..6b6bada3ff 100644 --- a/src/stdlib/replace.rs +++ b/src/stdlib/replace.rs @@ -47,6 +47,21 @@ impl Function for Replace { "replace" } + fn usage(&self) -> &'static str { + indoc! {" + Replaces all matching instances of `pattern` in `value`. + + The `pattern` argument accepts regular expression capture groups. + + **Note when using capture groups**: + - You will need to escape the `$` by using `$$` to avoid Vector interpreting it as an + [environment variable when loading configuration](/docs/reference/environment_variables/#escaping) + - If you want a literal `$` in the replacement pattern, you will also need to escape this + with `$$`. When combined with environment variable interpolation in config files this + means you will need to use `$$$$` to have a literal `$` in the replacement pattern. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/replace_with.rs b/src/stdlib/replace_with.rs index 0ce2e52775..8b9c96c41f 100644 --- a/src/stdlib/replace_with.rs +++ b/src/stdlib/replace_with.rs @@ -109,6 +109,26 @@ impl Function for ReplaceWith { "replace_with" } + fn usage(&self) -> &'static str { + indoc! {" + Replaces all matching instances of `pattern` using a closure. + + The `pattern` argument accepts a regular expression that can use capture groups. + + The function uses the function closure syntax to compute the replacement values. + + The closure takes a single parameter, which is an array, where the first item is always + present and contains the entire string that matched `pattern`. The items from index one on + contain the capture groups of the corresponding index. If a capture group is optional, the + value may be null if it didn't match. + + The value returned by the closure must be a string and will replace the section of + the input that was matched. + + This returns a new string with the replacements, the original string is not mutated. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/reverse_dns.rs b/src/stdlib/reverse_dns.rs index db540231af..5ba922f4c2 100644 --- a/src/stdlib/reverse_dns.rs +++ b/src/stdlib/reverse_dns.rs @@ -46,6 +46,10 @@ impl Function for ReverseDns { "reverse_dns" } + fn usage(&self) -> &'static str { + "Performs a reverse DNS lookup on the provided IP address to retrieve the associated hostname." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/round.rs b/src/stdlib/round.rs index a2e396312f..2037585bbe 100644 --- a/src/stdlib/round.rs +++ b/src/stdlib/round.rs @@ -27,6 +27,10 @@ impl Function for Round { "round" } + fn usage(&self) -> &'static str { + "Rounds the `value` to the specified `precision`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/seahash.rs b/src/stdlib/seahash.rs index 123e5d66bc..e0b8c3c0e1 100644 --- a/src/stdlib/seahash.rs +++ b/src/stdlib/seahash.rs @@ -14,6 +14,13 @@ impl Function for Seahash { "seahash" } + fn usage(&self) -> &'static str { + indoc! {" + Calculates a [Seahash](https://docs.rs/seahash/latest/seahash/) hash of the `value`. + **Note**: Due to limitations in the underlying VRL data types, this function converts the unsigned 64-bit integer SeaHash result to a signed 64-bit integer. Results higher than the signed 64-bit integer maximum value wrap around to negative values. + "} + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/set.rs b/src/stdlib/set.rs index 725266c9f3..17d0fb229a 100644 --- a/src/stdlib/set.rs +++ b/src/stdlib/set.rs @@ -47,6 +47,18 @@ impl Function for Set { "set" } + fn usage(&self) -> &'static str { + indoc! {" + Dynamically insert data into the path of a given object or array. + + If you know the path you want to assign a value to, + use static path assignments such as `.foo.bar[1] = true` for + improved performance and readability. However, if you do not + know the path names, use the dynamic `set` function to + insert the data into the object or array. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/sha1.rs b/src/stdlib/sha1.rs index 13cebc2b79..1da82dcb8f 100644 --- a/src/stdlib/sha1.rs +++ b/src/stdlib/sha1.rs @@ -14,6 +14,10 @@ impl Function for Sha1 { "sha1" } + fn usage(&self) -> &'static str { + "Calculates a [SHA-1](https://en.wikipedia.org/wiki/SHA-1) hash of the `value`." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/sha2.rs b/src/stdlib/sha2.rs index 9386889572..017b1b9a75 100644 --- a/src/stdlib/sha2.rs +++ b/src/stdlib/sha2.rs @@ -35,6 +35,10 @@ impl Function for Sha2 { "sha2" } + fn usage(&self) -> &'static str { + "Calculates a [SHA-2](https://en.wikipedia.org/wiki/SHA-2) hash of the `value`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/sha3.rs b/src/stdlib/sha3.rs index 3335dfd33e..d299afdfa9 100644 --- a/src/stdlib/sha3.rs +++ b/src/stdlib/sha3.rs @@ -31,6 +31,10 @@ impl Function for Sha3 { "sha3" } + fn usage(&self) -> &'static str { + "Calculates a [SHA-3](https://en.wikipedia.org/wiki/SHA-3) hash of the `value`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/shannon_entropy.rs b/src/stdlib/shannon_entropy.rs index dfd75ccd31..a94b1ee002 100644 --- a/src/stdlib/shannon_entropy.rs +++ b/src/stdlib/shannon_entropy.rs @@ -103,6 +103,10 @@ impl Function for ShannonEntropy { "shannon_entropy" } + fn usage(&self) -> &'static str { + "Generates [Shannon entropy](https://en.wikipedia.org/wiki/Entropy_(information_theory)) from given string. It can generate it based on string bytes, codepoints, or graphemes." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/sieve.rs b/src/stdlib/sieve.rs index 84b88625cc..e94a954b81 100644 --- a/src/stdlib/sieve.rs +++ b/src/stdlib/sieve.rs @@ -41,6 +41,15 @@ impl Function for Sieve { "sieve" } + fn usage(&self) -> &'static str { + indoc! {" + Keeps only matches of `pattern` in `value`. + + This can be used to define patterns that are allowed in the string and + remove everything else. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/slice.rs b/src/stdlib/slice.rs index e856280eb1..6a7b2918c0 100644 --- a/src/stdlib/slice.rs +++ b/src/stdlib/slice.rs @@ -50,6 +50,16 @@ impl Function for Slice { "slice" } + fn usage(&self) -> &'static str { + indoc! {" + Returns a slice of `value` between the `start` and `end` positions. + + If the `start` and `end` parameters are negative, they refer to positions counting from the right of the + string or array. If `end` refers to a position that is greater than the length of the string or array, + a slice up to the end of the string or array is returned. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/split.rs b/src/stdlib/split.rs index 116b2032a4..90be87e79f 100644 --- a/src/stdlib/split.rs +++ b/src/stdlib/split.rs @@ -37,6 +37,10 @@ impl Function for Split { "split" } + fn usage(&self) -> &'static str { + "Splits the `value` string using `pattern`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/split_path.rs b/src/stdlib/split_path.rs index b157af1a63..c7fb0c40a8 100644 --- a/src/stdlib/split_path.rs +++ b/src/stdlib/split_path.rs @@ -19,6 +19,10 @@ impl Function for SplitPath { "split_path" } + fn usage(&self) -> &'static str { + "Splits the given `path` into its constituent components, returning an array of strings. Each component represents a part of the file system path hierarchy." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/starts_with.rs b/src/stdlib/starts_with.rs index c397e836ac..4fed90546d 100644 --- a/src/stdlib/starts_with.rs +++ b/src/stdlib/starts_with.rs @@ -72,6 +72,10 @@ impl Function for StartsWith { "starts_with" } + fn usage(&self) -> &'static str { + "Determines whether `value` begins with `substring`." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/string.rs b/src/stdlib/string.rs index 851ce56a9d..3487053bba 100644 --- a/src/stdlib/string.rs +++ b/src/stdlib/string.rs @@ -15,6 +15,10 @@ impl Function for String { "string" } + fn usage(&self) -> &'static str { + "Returns `value` if it is a string, otherwise returns an error. This enables the type checker to guarantee that the returned value is a string and can be used in any function that expects a string." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/strip_ansi_escape_codes.rs b/src/stdlib/strip_ansi_escape_codes.rs index a3238b18da..022f39d223 100644 --- a/src/stdlib/strip_ansi_escape_codes.rs +++ b/src/stdlib/strip_ansi_escape_codes.rs @@ -15,6 +15,10 @@ impl Function for StripAnsiEscapeCodes { "strip_ansi_escape_codes" } + fn usage(&self) -> &'static str { + "Strips [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code) from `value`." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/strip_whitespace.rs b/src/stdlib/strip_whitespace.rs index bd04b7797f..5948562fb7 100644 --- a/src/stdlib/strip_whitespace.rs +++ b/src/stdlib/strip_whitespace.rs @@ -8,6 +8,10 @@ impl Function for StripWhitespace { "strip_whitespace" } + fn usage(&self) -> &'static str { + "Strips whitespace from the start and end of `value`, where whitespace is defined by the [Unicode `White_Space` property](https://en.wikipedia.org/wiki/Unicode_character_property#Whitespace)." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/strlen.rs b/src/stdlib/strlen.rs index 71d47c71a9..846ca309f6 100644 --- a/src/stdlib/strlen.rs +++ b/src/stdlib/strlen.rs @@ -14,6 +14,16 @@ impl Function for Strlen { "strlen" } + fn usage(&self) -> &'static str { + indoc! {" + Returns the number of UTF-8 characters in `value`. This differs from + `length` which counts the number of bytes of a string. + + **Note**: This is the count of [Unicode scalar values](https://www.unicode.org/glossary/#unicode_scalar_value) + which can sometimes differ from [Unicode code points](https://www.unicode.org/glossary/#code_point). + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/tag_types_externally.rs b/src/stdlib/tag_types_externally.rs index ba8762fde1..09e724a990 100644 --- a/src/stdlib/tag_types_externally.rs +++ b/src/stdlib/tag_types_externally.rs @@ -9,6 +9,15 @@ impl Function for TagTypesExternally { "tag_types_externally" } + fn usage(&self) -> &'static str { + indoc! {" + Adds type information to all (nested) scalar values in the provided `value`. + + The type information is added externally, meaning that `value` has the form of `\"type\": value` after this + transformation. + "} + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/tally.rs b/src/stdlib/tally.rs index 2b44a33274..496589c049 100644 --- a/src/stdlib/tally.rs +++ b/src/stdlib/tally.rs @@ -32,6 +32,10 @@ impl Function for Tally { "tally" } + fn usage(&self) -> &'static str { + "Counts the occurrences of each string value in the provided array and returns an object with the counts." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "tally", diff --git a/src/stdlib/tally_value.rs b/src/stdlib/tally_value.rs index 2032913237..f5e0d7084e 100644 --- a/src/stdlib/tally_value.rs +++ b/src/stdlib/tally_value.rs @@ -13,6 +13,10 @@ impl Function for TallyValue { "tally_value" } + fn usage(&self) -> &'static str { + "Counts the number of times a specific value appears in the provided array." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "count matching values", diff --git a/src/stdlib/timestamp.rs b/src/stdlib/timestamp.rs index e44ca69672..f9f80c9a89 100644 --- a/src/stdlib/timestamp.rs +++ b/src/stdlib/timestamp.rs @@ -15,6 +15,10 @@ impl Function for Timestamp { "timestamp" } + fn usage(&self) -> &'static str { + "Returns `value` if it is a timestamp, otherwise returns an error. This enables the type checker to guarantee that the returned value is a timestamp and can be used in any function that expects a timestamp." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_bool.rs b/src/stdlib/to_bool.rs index 60bd1349f8..f1aece3002 100644 --- a/src/stdlib/to_bool.rs +++ b/src/stdlib/to_bool.rs @@ -24,6 +24,10 @@ impl Function for ToBool { "to_bool" } + fn usage(&self) -> &'static str { + "Coerces the `value` into a boolean." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_float.rs b/src/stdlib/to_float.rs index 31b4f6cfef..de7a146b27 100644 --- a/src/stdlib/to_float.rs +++ b/src/stdlib/to_float.rs @@ -37,6 +37,10 @@ impl Function for ToFloat { "to_float" } + fn usage(&self) -> &'static str { + "Coerces the `value` into a float." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_int.rs b/src/stdlib/to_int.rs index bad81290c5..b820f9a0fb 100644 --- a/src/stdlib/to_int.rs +++ b/src/stdlib/to_int.rs @@ -26,6 +26,10 @@ impl Function for ToInt { "to_int" } + fn usage(&self) -> &'static str { + "Coerces the `value` into an integer." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_regex.rs b/src/stdlib/to_regex.rs index 2ecc631125..09fc05daad 100644 --- a/src/stdlib/to_regex.rs +++ b/src/stdlib/to_regex.rs @@ -17,6 +17,10 @@ impl Function for ToRegex { "to_regex" } + fn usage(&self) -> &'static str { + "Coerces the `value` into a regex." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_string.rs b/src/stdlib/to_string.rs index 533ba3fa22..b2e3a19108 100644 --- a/src/stdlib/to_string.rs +++ b/src/stdlib/to_string.rs @@ -23,6 +23,10 @@ impl Function for ToString { "to_string" } + fn usage(&self) -> &'static str { + "Coerces the `value` into a string." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_syslog_facility.rs b/src/stdlib/to_syslog_facility.rs index 700706eb24..74a0177235 100644 --- a/src/stdlib/to_syslog_facility.rs +++ b/src/stdlib/to_syslog_facility.rs @@ -41,6 +41,10 @@ impl Function for ToSyslogFacility { "to_syslog_facility" } + fn usage(&self) -> &'static str { + r#"Converts the `value`, a Syslog [facility code](https://en.wikipedia.org/wiki/Syslog#Facility), into its corresponding Syslog keyword. For example, `0` into `"kern"`, `1` into `"user"`, etc."# + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_syslog_facility_code.rs b/src/stdlib/to_syslog_facility_code.rs index e57477200b..f364ed1222 100644 --- a/src/stdlib/to_syslog_facility_code.rs +++ b/src/stdlib/to_syslog_facility_code.rs @@ -41,6 +41,10 @@ impl Function for ToSyslogFacilityCode { "to_syslog_facility_code" } + fn usage(&self) -> &'static str { + "Converts the `value`, a Syslog [facility keyword](https://en.wikipedia.org/wiki/Syslog#Facility), into a Syslog integer facility code (`0` to `23`)." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_syslog_level.rs b/src/stdlib/to_syslog_level.rs index 368adfd98a..92f5baad17 100644 --- a/src/stdlib/to_syslog_level.rs +++ b/src/stdlib/to_syslog_level.rs @@ -25,6 +25,10 @@ impl Function for ToSyslogLevel { "to_syslog_level" } + fn usage(&self) -> &'static str { + r#"Converts the `value`, a Syslog [severity level](https://en.wikipedia.org/wiki/Syslog#Severity_level), into its corresponding keyword, i.e. 0 into `"emerg"`, 1 into `"alert"`, etc."# + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_syslog_severity.rs b/src/stdlib/to_syslog_severity.rs index 563991fa9f..352142591a 100644 --- a/src/stdlib/to_syslog_severity.rs +++ b/src/stdlib/to_syslog_severity.rs @@ -25,6 +25,10 @@ impl Function for ToSyslogSeverity { "to_syslog_severity" } + fn usage(&self) -> &'static str { + "Converts the `value`, a Syslog [log level keyword](https://en.wikipedia.org/wiki/Syslog#Severity_level), into a Syslog integer severity level (`0` to `7`)." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/to_unix_timestamp.rs b/src/stdlib/to_unix_timestamp.rs index 4e983f1961..745f216357 100644 --- a/src/stdlib/to_unix_timestamp.rs +++ b/src/stdlib/to_unix_timestamp.rs @@ -23,6 +23,14 @@ impl Function for ToUnixTimestamp { "to_unix_timestamp" } + fn usage(&self) -> &'static str { + indoc! {" + Converts the `value` timestamp into a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time). + + Returns the number of seconds since the Unix epoch by default. To return the number in milliseconds or nanoseconds, set the `unit` argument to `milliseconds` or `nanoseconds`. + "} + } + fn examples(&self) -> &'static [Example] { &[ example! { diff --git a/src/stdlib/truncate.rs b/src/stdlib/truncate.rs index 92019ea5e4..1673a4c0a0 100644 --- a/src/stdlib/truncate.rs +++ b/src/stdlib/truncate.rs @@ -32,6 +32,10 @@ impl Function for Truncate { "truncate" } + fn usage(&self) -> &'static str { + "Truncates the `value` string up to the `limit` number of characters." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/type_def.rs b/src/stdlib/type_def.rs index 185fa4aab7..adb3949237 100644 --- a/src/stdlib/type_def.rs +++ b/src/stdlib/type_def.rs @@ -13,7 +13,7 @@ fn type_def(type_def: &VrlTypeDef) -> Value { /// A debug function to print the type definition of an expression at runtime. /// /// This function is *UNDOCUMENTED* and *UNSTABLE*. It is *NOT* to be advertised -/// to users of Vector, even though it is technically useable by others. +/// to users of Vector, even though it is technically usable by others. #[derive(Clone, Copy, Debug)] pub struct TypeDef; @@ -22,6 +22,14 @@ impl Function for TypeDef { "type_def" } + fn usage(&self) -> &'static str { + indoc! {" + Returns the type definition of an expression at runtime. + + This is a debug function that is *UNSTABLE*. Behavior is *NOT* guaranteed even though it is technically usable. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/unflatten.rs b/src/stdlib/unflatten.rs index 74d79de922..e76cbcf7e8 100644 --- a/src/stdlib/unflatten.rs +++ b/src/stdlib/unflatten.rs @@ -103,6 +103,10 @@ impl Function for Unflatten { "unflatten" } + fn usage(&self) -> &'static str { + "Unflattens the `value` into a nested representation." + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter { diff --git a/src/stdlib/unique.rs b/src/stdlib/unique.rs index c75cb30852..53b8f03b5d 100644 --- a/src/stdlib/unique.rs +++ b/src/stdlib/unique.rs @@ -15,6 +15,14 @@ impl Function for Unique { "unique" } + fn usage(&self) -> &'static str { + indoc! {" + Returns the unique values for an array. + + The first occurrence of each element is kept. + "} + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Unique", diff --git a/src/stdlib/unnest.rs b/src/stdlib/unnest.rs index 921f40095c..450bddf52c 100644 --- a/src/stdlib/unnest.rs +++ b/src/stdlib/unnest.rs @@ -61,6 +61,17 @@ impl Function for Unnest { "unnest" } + fn usage(&self) -> &'static str { + indoc! {" + Unnest an array field from an object to create an array of objects using that field; keeping all other fields. + + Assigning the array result of this to `.` results in multiple events being emitted from `remap`. See the + [`remap` transform docs](/docs/reference/configuration/transforms/remap/#emitting-multiple-log-events) for more details. + + This is also referred to as `explode` in some languages. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "path", diff --git a/src/stdlib/upcase.rs b/src/stdlib/upcase.rs index d4acf46866..af3b401b9a 100644 --- a/src/stdlib/upcase.rs +++ b/src/stdlib/upcase.rs @@ -12,6 +12,10 @@ impl Function for Upcase { "upcase" } + fn usage(&self) -> &'static str { + "Upcases `value`, where upcase is defined according to the Unicode Derived Core Property Uppercase." + } + fn examples(&self) -> &'static [Example] { &[example! { title: "Upcase a string", diff --git a/src/stdlib/uuid_from_friendly_id.rs b/src/stdlib/uuid_from_friendly_id.rs index 683e04d030..3b479ad2ba 100644 --- a/src/stdlib/uuid_from_friendly_id.rs +++ b/src/stdlib/uuid_from_friendly_id.rs @@ -23,6 +23,10 @@ impl Function for UuidFromFriendlyId { "uuid_from_friendly_id" } + fn usage(&self) -> &'static str { + "Convert a Friendly ID (base62 encoding a 128-bit word) to a UUID." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/uuid_v4.rs b/src/stdlib/uuid_v4.rs index edb862e5f6..eac5dc4007 100644 --- a/src/stdlib/uuid_v4.rs +++ b/src/stdlib/uuid_v4.rs @@ -16,6 +16,10 @@ impl Function for UuidV4 { "uuid_v4" } + fn usage(&self) -> &'static str { + "Generates a random [UUIDv4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) string." + } + #[cfg(not(feature = "__mock_return_values_for_tests"))] fn examples(&self) -> &'static [Example] { &[example! { diff --git a/src/stdlib/uuid_v7.rs b/src/stdlib/uuid_v7.rs index 0e7ea4c57d..1cb4952b7a 100644 --- a/src/stdlib/uuid_v7.rs +++ b/src/stdlib/uuid_v7.rs @@ -34,6 +34,10 @@ impl Function for UuidV7 { "uuid_v7" } + fn usage(&self) -> &'static str { + "Generates a random [UUIDv7](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#name-uuid-version-7) string." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "timestamp", diff --git a/src/stdlib/validate_json_schema.rs b/src/stdlib/validate_json_schema.rs index 24bcd8b8b7..a6490e1d4b 100644 --- a/src/stdlib/validate_json_schema.rs +++ b/src/stdlib/validate_json_schema.rs @@ -104,6 +104,10 @@ impl Function for ValidateJsonSchema { "validate_json_schema" } + fn usage(&self) -> &'static str { + "Check if `value` conforms to a JSON Schema definition. This function validates a JSON payload against a JSON Schema definition. It can be used to ensure that the data structure and types in `value` match the expectations defined in `schema_definition`." + } + fn examples(&self) -> &'static [Example] { EXAMPLES.as_slice() } diff --git a/src/stdlib/values.rs b/src/stdlib/values.rs index 8eb3d6152a..c9661ee3a6 100644 --- a/src/stdlib/values.rs +++ b/src/stdlib/values.rs @@ -14,6 +14,10 @@ impl Function for Values { "values" } + fn usage(&self) -> &'static str { + "Returns the values from the object passed into the function." + } + fn parameters(&self) -> &'static [Parameter] { &[Parameter { keyword: "value", diff --git a/src/stdlib/zip.rs b/src/stdlib/zip.rs index c30137cfcf..e9a15dcfa3 100644 --- a/src/stdlib/zip.rs +++ b/src/stdlib/zip.rs @@ -39,6 +39,18 @@ impl Function for Zip { "zip" } + fn usage(&self) -> &'static str { + indoc! {" + Iterate over several arrays in parallel, producing a new array containing arrays of items from each source. + The resulting array will be as long as the shortest input array, with all the remaining elements dropped. + This function is modeled from the `zip` function [in Python](https://docs.python.org/3/library/functions.html#zip), + but similar methods can be found in [Ruby](https://docs.ruby-lang.org/en/master/Array.html#method-i-zip) + and [Rust](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html#method.zip). + + If a single parameter is given, it must contain an array of all the input arrays. + "} + } + fn parameters(&self) -> &'static [Parameter] { &[ Parameter {