chore(remap): docs for the Remap type functions (#6446)

Co-authored-by: binarylogic <[email protected]>

docs/reference/remap.cue

@@ -35,7 +35,7 @@ package metadata
 		warnings?: [string, ...string]
 	}
 
-	#Type: "any" | "array" | "boolean" | "float" | "integer" | "map" | "null" | "path" | "string" | "regex" | "timestamp"
+	#Type: "any" | "array" | "boolean" | "float" | "integer" | "object" | "null" | "path" | "string" | "regex" | "timestamp"
 
 	concepts:    _
 	description: string

docs/reference/remap/expressions/assignment.cue

@@ -54,7 +54,7 @@ remap: expressions: assignment: {
 				description: """
 					If the `target` is a variable, the `expression` can be any expression.
 
-					If the `target` is a path, the `expression` can be any expression that returns a supported map
+					If the `target` is a path, the `expression` can be any expression that returns a supported object
 					value type (i.e. not a regular expression).
 					"""
 			}

docs/reference/remap/expressions/block.cue

@@ -5,7 +5,7 @@ remap: expressions: block: {
 	description: """
 		A _block_ expression is a sequence of one or more expressions within matching brace brackets.
 
-		Blocks can't be empty. Instead, empty blocks (`{}`) are treated as blank maps.
+		Blocks can't be empty. Instead, empty blocks (`{}`) are treated as blank objects.
 		"""
 	return: """
 		Returns the result of the last evaluated expression within the block.

docs/reference/remap/expressions/function_call.cue

@@ -10,7 +10,7 @@ remap: expressions: function_call: {
 		be [handled](\(urls.vrl_errors_reference)) and null is returned.
 
 		Functions can _only_ return a single value. If multiple values are relevant, you should wrap them in a data
-		structure fit to hold them, such as an array or map (note that VRL doesn't support tuples).
+		structure fit to hold them, such as an array or object (note that VRL doesn't support tuples).
 		"""
 
 	grammar: {

docs/reference/remap/expressions/path.cue

@@ -4,7 +4,7 @@ remap: expressions: path: {
 	title: "Path"
 	description: """
 		A _path_ expression is a sequence of period-delimited segments that represent the location of a value
-		within a map.
+		within an object.
 		"""
 	return: """
 		Returns the value of the path location.
@@ -57,10 +57,10 @@ remap: expressions: path: {
 							Dynamic paths are currently not supported.
 							"""
 					}
-					nested_maps: {
-						title: "Nested map paths"
+					nested_objects: {
+						title: "Nested object paths"
 						description: """
-							Nested map values are accessed by delimiting each ancestor path with `.`:
+							Nested object values are accessed by delimiting each ancestor path with `.`:
 
 							```vrl
 							.parent.child

docs/reference/remap/functions.cue

@@ -27,7 +27,7 @@ remap: {
 		examples?: [remap.#Example, ...remap.#Example]
 	}
 
-	#FunctionCategory: "Array" | "Codec" | "Coerce" | "Debug" | "Enumerate" | "Event" | "Hash" | "IP" | "Map" | "Number" | "Parse" | "Random" | "String" | "System" | "Timestamp" | "Type"
+	#FunctionCategory: "Array" | "Codec" | "Coerce" | "Debug" | "Enumerate" | "Event" | "Hash" | "IP" | "Number" | "Object" | "Parse" | "Random" | "String" | "System" | "Timestamp" | "Type"
 
 	functions: [Name=string]: #Function & {
 		name: Name

docs/reference/remap/functions/array.cue

@@ -0,0 +1,34 @@
+package metadata
+
+remap: functions: array: {
+	category: "Type"
+	description: """
+		Errors if `value` is not an array, if `value` is an array it is returned.
+
+		This allows the type checker to guarantee that the returned value is an array and can be used in any function
+		that expects this type.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The value to ensure is an array."
+			required:    true
+			type: ["any"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not an array.",
+	]
+	return: types: ["array"]
+	examples: [
+		{
+			title: "Declare an array type"
+			input: log: value: [1, 2, 3]
+			source: #"""
+				array(.value)
+				"""#
+			return: input.log.value
+		},
+	]
+}

docs/reference/remap/functions/bool.cue

@@ -0,0 +1,40 @@
+package metadata
+
+remap: functions: bool: {
+	category: "Type"
+	description: """
+		Errors if `value` is not a boolean, if `value` is a boolean it is returned.
+
+		This allows the type checker to guarantee that the returned value is a boolean and can be used in any function
+		that expects this type.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The value to ensure is a boolean."
+			required:    true
+			type: ["any"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not a boolean.",
+	]
+	return: {
+		types: ["boolean"]
+		rules: [
+			#"If `value` is a boolean then it is returned."#,
+			#"Otherwise an error is raised."#,
+		]
+	}
+	examples: [
+		{
+			title: "Declare a boolean type"
+			input: log: value: false
+			source: #"""
+				bool(.value)
+				"""#
+			return: input.log.value
+		},
+	]
+}

docs/reference/remap/functions/compact.cue

@@ -11,9 +11,9 @@ remap: functions: compact: {
 	arguments: [
 		{
 			name:        "value"
-			description: "The map or array to compact."
+			description: "The object or array to compact."
 			required:    true
-			type: ["array", "map"]
+			type: ["array", "object"]
 		},
 		{
 			name:        "recursive"
@@ -37,8 +37,8 @@ remap: functions: compact: {
 			type: ["boolean"]
 		},
 		{
-			name:        "map"
-			description: "Should an empty map be treated as an empty value."
+			name:        "object"
+			description: "Should an empty object be treated as an empty value."
 			required:    false
 			default:     true
 			type: ["boolean"]
@@ -60,7 +60,7 @@ remap: functions: compact: {
 	]
 	internal_failure_reasons: []
 	return: {
-		types: ["array", "map"]
+		types: ["array", "object"]
 		rules: [
 			"The return type will match the `value` type.",
 		]
@@ -74,7 +74,7 @@ remap: functions: compact: {
 			return: ["foo", "bar", "buzz"]
 		},
 		{
-			title: "Compact a map"
+			title: "Compact an object"
 			source: #"""
 				compact({"field1": 1, "field2": "", "field3": [], "field4": null}, string: true, array: true, null: true)
 				"""#

docs/reference/remap/functions/flatten.cue

@@ -9,14 +9,14 @@ remap: functions: flatten: {
 	arguments: [
 		{
 			name:        "value"
-			description: "The array or map to flatten."
+			description: "The array or object to flatten."
 			required:    true
-			type: ["array", "map"]
+			type: ["array", "object"]
 		},
 	]
 	internal_failure_reasons: []
 	return: {
-		types: ["array", "map"]
+		types: ["array", "object"]
 		rules: [
 			"The return type will match the `value` type.",
 		]
@@ -31,7 +31,7 @@ remap: functions: flatten: {
 			return: [1, 2, 3, 4, 5, 6, 7, 8, 9]
 		},
 		{
-			title: "Flatten map"
+			title: "Flatten object"
 			source: #"""
 				flatten({
 					"parent1": {

docs/reference/remap/functions/float.cue

@@ -0,0 +1,40 @@
+package metadata
+
+remap: functions: float: {
+	category: "Type"
+	description: """
+		Errors if `value` is not a float, if `value` is a float it is returned.
+
+		This allows the type checker to guarantee that the returned value is a float and can be used in any function
+		that expects this type.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The value to ensure is a float."
+			required:    true
+			type: ["any"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not a float.",
+	]
+	return: {
+		types: ["float"]
+		rules: [
+			#"If `value` is an float then it is returned."#,
+			#"Otherwise an error is raised."#,
+		]
+	}
+	examples: [
+		{
+			title: "Delcare a float type"
+			input: log: value: 42
+			source: #"""
+				float(.radius)
+				"""#
+			return: input.log.value
+		},
+	]
+}

docs/reference/remap/functions/get_hostname.cue

@@ -15,7 +15,7 @@ remap: functions: get_hostname: {
 			title: "Get hostname"
 			input: log: {}
 			source: #"""
-				.hostname = get_hostname!()
+				.hostname = get_hostname()
 				"""#
 			output: log: hostname: "localhost.localdomain"
 		},

docs/reference/remap/functions/int.cue

@@ -0,0 +1,34 @@
+package metadata
+
+remap: functions: int: {
+	category: "Type"
+	description: """
+		Errors if `value` is not an integer, if `value` is an integer it is returned.
+
+		This allows the type checker to guarantee that the returned value is an integer and can be used in any function
+		that expects this type.
+		"""
+
+	arguments: [
+		{
+			name:        "value"
+			description: "The value to ensure is an integer."
+			required:    true
+			type: ["any"]
+		},
+	]
+	internal_failure_reasons: [
+		"`value` is not an integer.",
+	]
+	return: types: ["integer"]
+	examples: [
+		{
+			title: "Declare an integer type"
+			input: log: value: 42
+			source: #"""
+				int(.value)
+				"""#
+			return: input.log.value
+		},
+	]
+}

docs/reference/remap/functions/length.cue

@@ -9,9 +9,9 @@ remap: functions: length: {
 	arguments: [
 		{
 			name:        "value"
-			description: "The array or map"
+			description: "The array or object"
 			required:    true
-			type: ["array", "map", "string"]
+			type: ["array", "object", "string"]
 		},
 	]
 	internal_failure_reasons: []
@@ -26,7 +26,7 @@ remap: functions: length: {
 
 	examples: [
 		{
-			title: "Length (map)"
+			title: "Length (object)"
 			source: """
 				length({
 					"portland": "Trail Blazers"
@@ -36,7 +36,7 @@ remap: functions: length: {
 			return: 2
 		},
 		{
-			title: "Length (nested map)"
+			title: "Length (nested object)"
 			source: """
 				length({
 					"home": {

docs/reference/remap/functions/merge.cue

@@ -1,9 +1,9 @@
 package metadata
 
 remap: functions: merge: {
-	category: "Map"
+	category: "Object"
 	description: """
-		Merges the `from` map into the `to` map.
+		Merges the `from` object into the `to` object.
 		"""
 
 	arguments: [
@@ -17,7 +17,7 @@ remap: functions: merge: {
 			name:        "from"
 			description: "The object to merge from."
 			required:    true
-			type: ["map"]
+			type: ["object"]
 		},
 		{
 			name:        "deep"
@@ -29,10 +29,10 @@ remap: functions: merge: {
 	]
 	internal_failure_reasons: []
 	return: {
-		types: ["map"]
+		types: ["object"]
 		rules: [
-			#"If a key exists in both maps, the field from the `from` map is chosen."#,
-			#"If `deep` is specified, and a key exists in both maps, and both these fields are also maps, then those maps will merge recursively as well."#,
+			#"If a key exists in both objects, the field from the `from` object is chosen."#,
+			#"If `deep` is specified, and a key exists in both objects, and both these fields are also objects, then those objects will merge recursively as well."#,
 		]
 	}