vectordotdev · binarylogic · Jan 20, 2021 · Jan 20, 2021
@@ -13,7 +13,7 @@ remap: expressions: assignment: {
 
 	grammar: {
 		source: """
-			target ~ operator ~ expression
+			target ~ ("," ~ error)? ~ operator ~ expression
 			"""
 		definitions: {
 			target: {
@@ -22,6 +22,12 @@ remap: expressions: assignment: {
 					with an optional second variable for error handling if the right-hand side is fallible.
 					"""
 			}
+			error: {
+				description: """
+					The `error` allows for optional assignment to errors when the right-hand side expression is
+					fallible. This is commonly used when invoking fallible functions.
+					"""
+			}
 			operator: {
 				description: """
 					The `operator` delimits the `target` and `expression` and defines assignment conditions.

@@ -18,7 +18,10 @@ remap: {
 		notices:     [string, ...string] | *[]
 
 		arguments: [...#Argument]
-		return: [remap.#Type, ...remap.#Type]
+		return: {
+			types: [remap.#Type, ...remap.#Type]
+			rules?: [string, ...string]
+		}
 		internal_failure_reasons: [...string]
 		examples?: [remap.#Example, ...remap.#Example]
 	}

@@ -16,7 +16,7 @@ remap: functions: append: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["array"]
+	return: types: ["array"]
 	category: "Array"
 	description: """
 		Adds each item from an array to the end of another array.

@@ -18,7 +18,7 @@ remap: functions: assert: {
 	internal_failure_reasons: [
 		"`condition` evaluates to `false`",
 	]
-	return: ["null"]
+	return: types: ["null"]
 	category: "Debug"
 	description: #"""
 		Checks a given condition.

@@ -17,7 +17,12 @@ remap: functions: ceil: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["timestamp"]
+	return: {
+		types: ["integer", "float"]
+		rules: [
+			"If `precision` is `0`, then an integer is returned, otherwise a float is returned.",
+		]
+	}
 	category: "Number"
 	description: #"""
 		Rounds the given number up to the specified `precision`.

@@ -52,7 +52,12 @@ remap: functions: compact: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["array", "map"]
+	return: {
+		types: ["array", "map"]
+		rules: [
+			"The return type will match the `value` type.",
+		]
+	}
 	category: "Enumerate"
 	description: #"""
 		Compacts an `array` or `map` by removing "empty" values.

@@ -23,7 +23,7 @@ remap: functions: contains: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["boolean"]
+	return: types: ["boolean"]
 	category: "String"
 	description: #"""
 		Determines if the provided `value` contains a given `substring`.

@@ -12,7 +12,7 @@ remap: functions: decode_base64: {
 	internal_failure_reasons: [
 		"`value` is not a valid encoded base64 string.",
 	]
-	return: ["string"]
+	return: types: ["string"]
 	category:    "Codec"
 	description: """
 		Decodes the provided `value` (a [Base64](\(urls.base64)) string) into it's original string.

@@ -10,7 +10,12 @@ remap: functions: del: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["any"]
+	return: {
+		types: ["any"]
+		rules: [
+			"The return is the value of the field being deleted.",
+		]
+	}
 	category: "Event"
 	description: #"""
 		Removes the field specified by the given path from the event object.

@@ -10,7 +10,7 @@ remap: functions: downcase: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["string"]
 	category: "String"
 	description: #"""
 		Returns a copy of `value` that is entirely lowercase.

@@ -17,7 +17,7 @@ remap: functions: encode_base64: {
 		},
 		{
 			name:        "charset"
-			description: ""
+			description: "The character set to use when encoding the data."
 			required:    false
 			type: ["string"]
 			default: "standard"
@@ -28,7 +28,7 @@ remap: functions: encode_base64: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["string"]
 	category: "Codec"
 	description: #"""
 		Encodes the provided `value` to [Base64](\(urls.base64)) either padded or non-padded and

@@ -10,7 +10,7 @@ remap: functions: encode_json: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["string"]
 	category: "Codec"
 	description: """
 		Encodes the provided `value` into JSON.

@@ -23,7 +23,7 @@ remap: functions: ends_with: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["boolean"]
+	return: types: ["boolean"]
 	category: "String"
 	description: #"""
 		Determines if the provided `value` ends with a given `substring`.

@@ -11,7 +11,7 @@ remap: functions: exists: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["boolean"]
+	return: types: ["boolean"]
 	category: "Event"
 	description: #"""
 		Checks if the given `path` exists. Nested paths and arrays can also be checked.

@@ -10,7 +10,12 @@ remap: functions: flatten: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["array", "map"]
+	return: {
+		types: ["array", "map"]
+		rules: [
+			"The return type will match the `value` type.",
+		]
+	}
 	category: "Enumerate"
 	description: #"""
 		Returns a nested `array` or `map` that has been flattened to a single level.

@@ -17,7 +17,12 @@ remap: functions: floor: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["timestamp"]
+	return: {
+		types: ["integer", "float"]
+		rules: [
+			"If `precision` is `0`, then an integer is returned, otherwise a float is returned.",
+		]
+	}
 	category: "Number"
 	description: #"""
 		Rounds the given `value` down to the specified `precision`.

@@ -30,7 +30,7 @@ remap: functions: format_number: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["string"]
 	category: "Number"
 	description: #"""
 		Formats the given `value` into a string representation of the number.

@@ -16,7 +16,7 @@ remap: functions: format_timestamp: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["string"]
 	category: "Timestamp"
 	description: #"""
 		Formats the provided `value` into a `string` as described by `format`.

@@ -13,7 +13,7 @@ remap: functions: get_env_var: {
 		"Environment variable `name` does not exist",
 		"Value of environment variable `name` is not valid unicode",
 	]
-	return: ["string"]
+	return: types: ["string"]
 	category: "System"
 	description: #"""
 		Get the value of an environment variable. If the variable does not exists, an error is returned.

@@ -16,7 +16,7 @@ remap: functions: includes: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["boolean"]
+	return: types: ["boolean"]
 	category: "Enumerate"
 	description: """
 		Determines whether the provided `values` contains the provided `item`.

@@ -19,7 +19,7 @@ remap: functions: ip_cidr_contains: {
 		"`cidr` is not a valid CIDR",
 		"`ip` is not a valid IP address",
 	]
-	return: ["boolean"]
+	return: types: ["boolean"]
 	category: "IP"
 	description: #"""
 		Returns `true` if the given `ip` is contained within the block referenced by the `cidr`.

@@ -22,7 +22,7 @@ remap: functions: ip_subnet: {
 		"`ip` is not a valid IP address",
 		"`subnet` is not a valid subnet.",
 	]
-	return: ["string"]
+	return: types: ["string"]
 	category: "IP"
 	description: #"""
 		Extracts the subnet address from the given `ip` using the supplied `subnet`.

@@ -12,13 +12,16 @@ remap: functions: ip_to_ipv6: {
 	internal_failure_reasons: [
 		"`ip` is not a valid IP address",
 	]
-	return: ["string"]
+	return: {
+		types: ["string"]
+		rules: [
+			"If `ip` is already an IPv6 address it is passed through untouched.",
+			"If `ip` is a IPv4 address then it converted to IPv4 mapped IPv6 addresses.",
+		]
+	}
 	category: "IP"
 	description: #"""
 		Converts the provided `ip` to an IPv6 address.
-
-		If the parameter is already an IPv6 address it is passed through untouched. IPv4 addresses are converted to
-		IPv4 mapped IPv6 addresses.
 		"""#
 	examples: [
 		{

@@ -13,13 +13,15 @@ remap: functions: ipv6_to_ipv4: {
 		"`ip` is not a valid IP address",
 		"`ip` is an IPv6 address that is not compatible with IPv4",
 	]
-	return: ["string"]
+	return: {
+		types: ["string"]
+		rules: [
+			"If the parameter is already an IPv4 address it is passed through untouched. If it is an IPv6 address it has to be an IPv4 compatible address.",
+		]
+	}
 	category: "IP"
 	description: #"""
 		Converts the provided `ip` to an IPv4 address.
-
-		If the parameter is already an IPv4 address it is passed through untouched. If it is an IPv6 address it has
-		to be an IPv4 compatible address.
 		"""#
 	examples: [
 		{

@@ -10,16 +10,17 @@ remap: functions: is_nullish: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["boolean"]
+	return: {
+		types: ["boolean"]
+		rules: [
+			#"If `value` is `null`, then `true` is returned."#,
+			#"If `value` is `"-"`, then `true` is returned."#,
+			#"If `value` is whitespace, as defined by [Unicode `White_Space` property](\#(urls.unicode_whitespace)), then `true` is returned."#,
+		]
+	}
 	category: "Type"
 	description: #"""
-		Determines whether the provided `value` is "nullish,"
-
-		Nullish indicates the absence of a meaningful value. The following are considered nullish in VRL:
-
-		* `null`
-		* `"-"` (A single dash)
-		* Whitespace as defined by [Unicode `White_Space` property](\(urls.unicode_whitespace))
+		Determines whether the provided `value` is "nullish,". Nullish indicates the absence of a meaningful value.
 		"""#
 	examples: [
 		{

@@ -10,14 +10,17 @@ remap: functions: length: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["integer"]
+	return: {
+		types: ["integer"]
+		rules: [
+			"If `value` is an array, the size of the array is returned.",
+			"If `value` is a string, the size of the string is returned.",
+			"If `value` is a map, the number of map keys is returned (nested keys are ignored)",
+		]
+	}
 	category: "Enumerate"
 	description: """
-		Returns the length of the input:
-
-		* If an array, the size of the array
-		* If a string, the number of bytes in the string
-		* If a map, the number of keys in the map (nested keys are ignored)
+		Returns the length of the input.
 		"""
 	examples: [
 		{

@@ -24,7 +24,7 @@ remap: functions: log: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["null"]
+	return: types: ["null"]
 	category:    "Debug"
 	description: """
 		Logs the supplied error message to Vector's [stdout](\(urls.stdout)) at the specified log

@@ -16,7 +16,7 @@ remap: functions: match: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["boolean"]
+	return: types: ["boolean"]
 	category: "String"
 	description: """
 		Returns `true` if the provided `value` matches the provided `pattern`.

@@ -10,7 +10,7 @@ remap: functions: md5: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["string"]
 	category: "Hash"
 	description: #"""
 		Calculates an md5 hash of a given `value`.

@@ -23,7 +23,7 @@ remap: functions: merge: {
 		},
 	]
 	internal_failure_reasons: []
-	return: ["string"]
+	return: types: ["map"]
 	category: "Map"
 	description: #"""
 		Merges the `from` map provided into the `to` map.

@@ -3,7 +3,7 @@ package metadata
 remap: functions: now: {
 	arguments: []
 	internal_failure_reasons: []
-	return: ["timestamp"]
+	return: types: ["timestamp"]
 	category: "Timestamp"
 	description: #"""
 		Returns the current timestamp in the UTC timezone with nanosecond precision.

@@ -12,7 +12,7 @@ remap: functions: parse_aws_alb_log: {
 	internal_failure_reasons: [
 		"`value` is not a properly formatted AWS ALB log",
 	]
-	return: ["map"]
+	return: types: ["map"]
 	category: "Parse"
 	description: #"""
 		Parses a Elastic Load Balancer Access log into it's constituent components.