diff --git a/docs/reference/remap.cue b/docs/reference/remap.cue index 8eb41dee8a723..585ecb1dcd79d 100644 --- a/docs/reference/remap.cue +++ b/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 diff --git a/docs/reference/remap/expressions/assignment.cue b/docs/reference/remap/expressions/assignment.cue index d758044e1db73..0d231f6391412 100644 --- a/docs/reference/remap/expressions/assignment.cue +++ b/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). """ } diff --git a/docs/reference/remap/expressions/block.cue b/docs/reference/remap/expressions/block.cue index c103b009b5cf4..15688b4992880 100644 --- a/docs/reference/remap/expressions/block.cue +++ b/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. diff --git a/docs/reference/remap/expressions/function_call.cue b/docs/reference/remap/expressions/function_call.cue index 77a3df962fb2d..d3f9d3490add0 100644 --- a/docs/reference/remap/expressions/function_call.cue +++ b/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: { diff --git a/docs/reference/remap/expressions/path.cue b/docs/reference/remap/expressions/path.cue index 2f0563542db07..e67ebfeaf70e8 100644 --- a/docs/reference/remap/expressions/path.cue +++ b/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 diff --git a/docs/reference/remap/functions.cue b/docs/reference/remap/functions.cue index 7c77fbc6eee92..228ac2576da2d 100644 --- a/docs/reference/remap/functions.cue +++ b/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 diff --git a/docs/reference/remap/functions/array.cue b/docs/reference/remap/functions/array.cue new file mode 100644 index 0000000000000..1a0f795f26b5b --- /dev/null +++ b/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 + }, + ] +} diff --git a/docs/reference/remap/functions/bool.cue b/docs/reference/remap/functions/bool.cue new file mode 100644 index 0000000000000..08433cf036ac5 --- /dev/null +++ b/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 + }, + ] +} diff --git a/docs/reference/remap/functions/compact.cue b/docs/reference/remap/functions/compact.cue index dd9186b8e0ae4..e92929769b4e7 100644 --- a/docs/reference/remap/functions/compact.cue +++ b/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) """# diff --git a/docs/reference/remap/functions/flatten.cue b/docs/reference/remap/functions/flatten.cue index e6f53ff9643ab..6c4ad18085cd9 100644 --- a/docs/reference/remap/functions/flatten.cue +++ b/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": { diff --git a/docs/reference/remap/functions/float.cue b/docs/reference/remap/functions/float.cue new file mode 100644 index 0000000000000..e09833d5a3d3b --- /dev/null +++ b/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 + }, + ] +} diff --git a/docs/reference/remap/functions/get_hostname.cue b/docs/reference/remap/functions/get_hostname.cue index 7cf67b17d9ae2..545bb4db5477b 100644 --- a/docs/reference/remap/functions/get_hostname.cue +++ b/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" }, diff --git a/docs/reference/remap/functions/int.cue b/docs/reference/remap/functions/int.cue new file mode 100644 index 0000000000000..c8fb1123f2eb9 --- /dev/null +++ b/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 + }, + ] +} diff --git a/docs/reference/remap/functions/length.cue b/docs/reference/remap/functions/length.cue index f59ddfc9a6c17..48a29b3a898c4 100644 --- a/docs/reference/remap/functions/length.cue +++ b/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": { diff --git a/docs/reference/remap/functions/merge.cue b/docs/reference/remap/functions/merge.cue index 524254febec3a..c8c90d70f7edf 100644 --- a/docs/reference/remap/functions/merge.cue +++ b/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."#, ] } diff --git a/docs/reference/remap/functions/object.cue b/docs/reference/remap/functions/object.cue new file mode 100644 index 0000000000000..01284d8db1095 --- /dev/null +++ b/docs/reference/remap/functions/object.cue @@ -0,0 +1,43 @@ +package metadata + +remap: functions: object: { + category: "Type" + description: """ + Errors if `value` is not an object, if `value` is an object it is returned. + + This allows the type checker to guarantee that the returned value is an object and can be used in any function + that expects this type. + """ + + arguments: [ + { + name: "value" + description: "The value to ensure is an object." + required: true + type: ["any"] + }, + ] + internal_failure_reasons: [ + "`value` is not an object.", + ] + return: { + types: ["object"] + rules: [ + #"If `value` is an object then it is returned."#, + #"Otherwise an error is raised."#, + ] + } + examples: [ + { + title: "Declare an object type" + input: log: value: { + field1: "value1" + field2: "value2" + } + source: #""" + object(.value) + """# + return: input.log.value + }, + ] +} diff --git a/docs/reference/remap/functions/parse_aws_alb_log.cue b/docs/reference/remap/functions/parse_aws_alb_log.cue index d051d69275516..cd03495d11480 100644 --- a/docs/reference/remap/functions/parse_aws_alb_log.cue +++ b/docs/reference/remap/functions/parse_aws_alb_log.cue @@ -17,7 +17,7 @@ remap: functions: parse_aws_alb_log: { internal_failure_reasons: [ "`value` is not a properly formatted AWS ALB log", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_aws_cloudwatch_log_subscription_message.cue b/docs/reference/remap/functions/parse_aws_cloudwatch_log_subscription_message.cue index c1ac14c326d90..443ee1200a8d8 100644 --- a/docs/reference/remap/functions/parse_aws_cloudwatch_log_subscription_message.cue +++ b/docs/reference/remap/functions/parse_aws_cloudwatch_log_subscription_message.cue @@ -18,7 +18,7 @@ remap: functions: parse_aws_cloudwatch_log_subscription_message: { internal_failure_reasons: [ "`value` is not a properly formatted AWS Cloudwatch Log subscription message", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_aws_vpc_flow_log.cue b/docs/reference/remap/functions/parse_aws_vpc_flow_log.cue index 5c6dca01790f0..9aaf6ddfcbfad 100644 --- a/docs/reference/remap/functions/parse_aws_vpc_flow_log.cue +++ b/docs/reference/remap/functions/parse_aws_vpc_flow_log.cue @@ -23,7 +23,7 @@ remap: functions: parse_aws_vpc_flow_log: { internal_failure_reasons: [ "`value` is not a properly formatted AWS VPC Flow log", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_common_log.cue b/docs/reference/remap/functions/parse_common_log.cue index f89ced2cb7dda..e66203c351b61 100644 --- a/docs/reference/remap/functions/parse_common_log.cue +++ b/docs/reference/remap/functions/parse_common_log.cue @@ -31,7 +31,7 @@ remap: functions: parse_common_log: { "`timestamp_format` is not a valid format string", "timestamp in `value` fails to parse via the provided `timestamp_format`", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_glog.cue b/docs/reference/remap/functions/parse_glog.cue index 0dc478a847f2a..1993bacfbd62c 100644 --- a/docs/reference/remap/functions/parse_glog.cue +++ b/docs/reference/remap/functions/parse_glog.cue @@ -16,7 +16,7 @@ remap: functions: parse_glog: { internal_failure_reasons: [ "`value` does not match the `glog` format", ] - return: types: ["map"] + return: types: ["object"] examples: [ { title: "Parse via glog" diff --git a/docs/reference/remap/functions/parse_grok.cue b/docs/reference/remap/functions/parse_grok.cue index e8b1be3b803fc..f221772e8a07d 100644 --- a/docs/reference/remap/functions/parse_grok.cue +++ b/docs/reference/remap/functions/parse_grok.cue @@ -38,7 +38,7 @@ remap: functions: parse_grok: { internal_failure_reasons: [ "`value` fails to parse via the provided `pattern`", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_json.cue b/docs/reference/remap/functions/parse_json.cue index 4dbedd00702e9..d45c231fa4e61 100644 --- a/docs/reference/remap/functions/parse_json.cue +++ b/docs/reference/remap/functions/parse_json.cue @@ -23,7 +23,7 @@ remap: functions: parse_json: { internal_failure_reasons: [ "`value` is not a valid JSON formatted payload", ] - return: types: ["boolean", "integer", "float", "string", "map", "array", "null"] + return: types: ["boolean", "integer", "float", "string", "object", "array", "null"] examples: [ { diff --git a/docs/reference/remap/functions/parse_key_value.cue b/docs/reference/remap/functions/parse_key_value.cue index d75f9fec151d4..bee419579407e 100644 --- a/docs/reference/remap/functions/parse_key_value.cue +++ b/docs/reference/remap/functions/parse_key_value.cue @@ -39,7 +39,7 @@ remap: functions: parse_key_value: { internal_failure_reasons: [ "`value` is not a properly formatted key/value string", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_regex.cue b/docs/reference/remap/functions/parse_regex.cue index c646b7eac12d0..be5a06705b56b 100644 --- a/docs/reference/remap/functions/parse_regex.cue +++ b/docs/reference/remap/functions/parse_regex.cue @@ -37,10 +37,10 @@ remap: functions: parse_regex: { "`value` fails to parse via the provided `pattern`", ] return: { - types: ["map"] + types: ["object"] rules: [ "Matches will return the capture groups corresponding to the leftmost matches in the text.", - "If no match is found an empty map is returned.", + "If no match is found an error is raised.", ] } diff --git a/docs/reference/remap/functions/parse_regex_all.cue b/docs/reference/remap/functions/parse_regex_all.cue index cd52d6469fcea..7b99c9e0b3a43 100644 --- a/docs/reference/remap/functions/parse_regex_all.cue +++ b/docs/reference/remap/functions/parse_regex_all.cue @@ -30,7 +30,7 @@ remap: functions: parse_regex_all: { types: ["array"] rules: [ "Matches will return all capture groups corresponding to the leftmost matches in the text.", - "If no match is found an empty map is returned.", + "If no match is found an error is raised.", ] } diff --git a/docs/reference/remap/functions/parse_syslog.cue b/docs/reference/remap/functions/parse_syslog.cue index c91b04de8b25e..48087502ef508 100644 --- a/docs/reference/remap/functions/parse_syslog.cue +++ b/docs/reference/remap/functions/parse_syslog.cue @@ -27,7 +27,7 @@ remap: functions: parse_syslog: { internal_failure_reasons: [ "`value` is not a properly formatted Syslog log", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/parse_url.cue b/docs/reference/remap/functions/parse_url.cue index 05f953bedcff8..7572067d12466 100644 --- a/docs/reference/remap/functions/parse_url.cue +++ b/docs/reference/remap/functions/parse_url.cue @@ -17,7 +17,7 @@ remap: functions: parse_url: { internal_failure_reasons: [ "`value` is not a properly formatted URL", ] - return: types: ["map"] + return: types: ["object"] examples: [ { diff --git a/docs/reference/remap/functions/string.cue b/docs/reference/remap/functions/string.cue new file mode 100644 index 0000000000000..7cc5b1d6fd04f --- /dev/null +++ b/docs/reference/remap/functions/string.cue @@ -0,0 +1,40 @@ +package metadata + +remap: functions: string: { + category: "Type" + description: """ + Errors if `value` is not a string, if `value` is a string it is returned. + + This allows the type checker to guarantee that the returned value is a string and can be used in any function + that expects this type. + """ + + arguments: [ + { + name: "value" + description: "The value to ensure is a string." + required: true + type: ["any"] + }, + ] + internal_failure_reasons: [ + "`value` is not a string.", + ] + return: { + types: ["string"] + rules: [ + #"If `value` is a string then it is returned."#, + #"Otherwise an error is raised."#, + ] + } + examples: [ + { + title: "Delcare a string type" + input: log: message: '{"field": "value"}' + source: #""" + string(.message) + """# + return: input.log.message + }, + ] +} diff --git a/docs/reference/remap/functions/timestamp.cue b/docs/reference/remap/functions/timestamp.cue new file mode 100644 index 0000000000000..1445f52a4e7f9 --- /dev/null +++ b/docs/reference/remap/functions/timestamp.cue @@ -0,0 +1,40 @@ +package metadata + +remap: functions: timestamp: { + category: "Type" + description: """ + Errors if `value` is not a timestamp, if `value` is a timestamp it is returned. + + This allows the type checker to guarantee that the returned value is a timestamp and can be used in any function + that expects this type. + """ + + arguments: [ + { + name: "value" + description: "The value to ensure is a timestamp." + required: true + type: ["any"] + }, + ] + internal_failure_reasons: [ + "`value` is not a timestamp.", + ] + return: { + types: ["string"] + rules: [ + #"If `value` is a timestamp then it is returned."#, + #"Otherwise an error is raised."#, + ] + } + examples: [ + { + title: "Declare a timestamp type" + input: log: timestamp: "2020-10-10T16:00:00Z" + source: #""" + timestamp(.timestamp) + """# + return: input.log.timestamp + }, + ] +} diff --git a/docs/reference/remap/functions/to_string.cue b/docs/reference/remap/functions/to_string.cue index e149b9d883ab8..dabd9b81981d0 100644 --- a/docs/reference/remap/functions/to_string.cue +++ b/docs/reference/remap/functions/to_string.cue @@ -22,7 +22,7 @@ remap: functions: to_string: { #"If `value` is an float then its string representation is returned."#, #"If `value` is an boolean then `"true"` or `"false"` is returned."#, #"If `value` is an timestamp then its RFC3339 representation is returned."#, - #"If `value` is a map then it is encoded into JSON."#, + #"If `value` is an object then it is encoded into JSON."#, #"If `value` is a list then it is encoded into JSON."#, ] } diff --git a/docs/reference/remap/literals/map.cue b/docs/reference/remap/literals/map.cue deleted file mode 100644 index 81eed8f9e185f..0000000000000 --- a/docs/reference/remap/literals/map.cue +++ /dev/null @@ -1,31 +0,0 @@ -package metadata - -remap: literals: map: { - title: "Map" - description: """ - A _map_ literal is a growable key/value structure that is syntactically equivalent to a JSON object. - - A well-formed JSON document is a valid VRL map. - """ - - characteristics: { - ordering: { - title: "Ordering" - description: """ - Maps are ordered alphabetically by the key in ascending order. Therefore, operations, such as encoding - into JSON, will produce a string with keys that are alphabetically ordered in ascending fashion. - """ - } - } - - examples: [ - """ - { - "field1": "value1", - "field2": [ "value2", "value3", "value4" ], - "field3": { "field4": "value5" } - } - """, - - ] -} diff --git a/docs/reference/remap/literals/object.cue b/docs/reference/remap/literals/object.cue new file mode 100644 index 0000000000000..70356e2fcf41d --- /dev/null +++ b/docs/reference/remap/literals/object.cue @@ -0,0 +1,32 @@ +package metadata + +remap: literals: object: { + title: "Object" + description: """ + An _object_ literal is a growable key/value structure that is syntactically equivalent to a JSON object. + + A well-formed JSON document is a valid VRL object. + """ + + characteristics: { + ordering: { + title: "Ordering" + description: """ + Objects are ordered alphabetically by the key in ascending order. Therefore, operations, such as + encoding into JSON, will produce a string with keys that are alphabetically ordered in ascending + fashion. + """ + } + } + + examples: [ + """ + { + "field1": "value1", + "field2": [ "value2", "value3", "value4" ], + "field3": { "field4": "value5" } + } + """, + + ] +}