From b35469a185f2c2f50c985412e3310f02755dfde0 Mon Sep 17 00:00:00 2001 From: Bruce Guenter Date: Thu, 5 Dec 2024 12:12:04 -0600 Subject: [PATCH 1/3] docs(vrl): Add documentation for new `object_from_array` function --- .../remap/functions/object_from_array.cue | 54 +++++++++++++++++++ website/cue/reference/remap/functions/zip.cue | 2 +- 2 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 website/cue/reference/remap/functions/object_from_array.cue diff --git a/website/cue/reference/remap/functions/object_from_array.cue b/website/cue/reference/remap/functions/object_from_array.cue new file mode 100644 index 0000000000000..8831a7c50cd92 --- /dev/null +++ b/website/cue/reference/remap/functions/object_from_array.cue @@ -0,0 +1,54 @@ +package metadata + +remap: functions: object_from_array: { + category: "Object" + description: """ + Iterate over either one or a pair of arrays and create an object out of all the key, value pairs contained in them. + Any entries that are missing the value will use `null` instead. + Any keys that are `null` will skip the corresponding value. + + If a single parameter is given, it must contain an array of all the input arrays. + """ + + arguments: [ + { + name: "values" + description: "The first array of elements, or the array of input arrays if no other parameter is present." + required: true + type: ["array"] + }, + { + name: "keys" + description: "The second array of elements. If not present, the first parameter contains all the arrays." + required: false + type: ["array"] + }, + ] + internal_failure_reasons: [ + "`values` and `keys` must be arrays.", + "If `keys` is not present, `values` must contain only arrays.", + ] + return: { + types: ["object"] + rules: [ + "`object_from_array` is considered fallible if either of the parameters is not an array, or if only the `value` parameter is present and it is not an array of arrays, or if any of the keys are not either a string or `null`.", + ] + } + + examples: [ + { + title: "Create an object from one array" + source: #""" + object_from_array([["one", 1], [null, 2], ["two", 3]]) + """# + return: {"one": 1, "two": 3} + }, + { + title: "Create an object from separate key and value arrays" + source: #""" + object_from_array([1, 2, 3], keys: ["one", null, "two"]) + """# + return: {"one": 1, "two": 3} + }, + ] +} diff --git a/website/cue/reference/remap/functions/zip.cue b/website/cue/reference/remap/functions/zip.cue index 90f5e7927596f..0b8415e31c225 100644 --- a/website/cue/reference/remap/functions/zip.cue +++ b/website/cue/reference/remap/functions/zip.cue @@ -32,7 +32,7 @@ remap: functions: zip: { return: { types: ["array"] rules: [ - "`zip` is considered fallible if any of the parameters is not an array, or if only the first parameter is present and it is not an array of arrays.", + "`zip` is considered fallible if either of the parameters is not an array, or if only the first parameter is present and it is not an array of arrays.", ] } From 10380c0b0a7af7b8e6af86945a1c792d8db3fa3f Mon Sep 17 00:00:00 2001 From: Bruce Guenter Date: Mon, 9 Dec 2024 13:39:08 -0600 Subject: [PATCH 2/3] Address wording feedback --- .../reference/remap/functions/object_from_array.cue | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/cue/reference/remap/functions/object_from_array.cue b/website/cue/reference/remap/functions/object_from_array.cue index 8831a7c50cd92..803563ea8e95d 100644 --- a/website/cue/reference/remap/functions/object_from_array.cue +++ b/website/cue/reference/remap/functions/object_from_array.cue @@ -3,9 +3,9 @@ package metadata remap: functions: object_from_array: { category: "Object" description: """ - Iterate over either one or a pair of arrays and create an object out of all the key, value pairs contained in them. - Any entries that are missing the value will use `null` instead. - Any keys that are `null` will skip the corresponding value. + Iterate over either one or a pair of arrays and create an object out of all the key-value pairs contained in them. + Any entries that are missing the 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. """ @@ -19,7 +19,7 @@ remap: functions: object_from_array: { }, { name: "keys" - description: "The second array of elements. If not present, the first parameter contains all the arrays." + description: "The second array of elements. If not present, the first parameter must contain all the arrays." required: false type: ["array"] }, @@ -31,7 +31,7 @@ remap: functions: object_from_array: { return: { types: ["object"] rules: [ - "`object_from_array` is considered fallible if either of the parameters is not an array, or if only the `value` parameter is present and it is not an array of arrays, or if any of the keys are not either a string or `null`.", + "`object_from_array` is considered fallible in the following cases: if either of the parameters is not an array; if only the `value` parameter is present and it is not an array of arrays; or if any of the keys are not either a string or `null`.", ] } From bdb112358fb966af4658110ebbf9f560ff4000e1 Mon Sep 17 00:00:00 2001 From: Bruce Guenter Date: Sun, 15 Dec 2024 19:33:49 -0600 Subject: [PATCH 3/3] Address wording feedback --- website/cue/reference/remap/functions/object_from_array.cue | 6 +++--- website/cue/reference/remap/functions/zip.cue | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/cue/reference/remap/functions/object_from_array.cue b/website/cue/reference/remap/functions/object_from_array.cue index 803563ea8e95d..1bb29246375ab 100644 --- a/website/cue/reference/remap/functions/object_from_array.cue +++ b/website/cue/reference/remap/functions/object_from_array.cue @@ -3,8 +3,8 @@ package metadata remap: functions: object_from_array: { category: "Object" description: """ - Iterate over either one or a pair of arrays and create an object out of all the key-value pairs contained in them. - Any entries that are missing the value use `null` instead. + 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. @@ -31,7 +31,7 @@ remap: functions: object_from_array: { return: { types: ["object"] rules: [ - "`object_from_array` is considered fallible in the following cases: if either of the parameters is not an array; if only the `value` parameter is present and it is not an array of arrays; or if any of the keys are not either a string or `null`.", + "`object_from_array` is considered fallible in the following cases: if any of the parameters is not an array; if only the `value` parameter is present and it is not an array of arrays; or if any of the keys are not either a string or `null`.", ] } diff --git a/website/cue/reference/remap/functions/zip.cue b/website/cue/reference/remap/functions/zip.cue index 0b8415e31c225..90f5e7927596f 100644 --- a/website/cue/reference/remap/functions/zip.cue +++ b/website/cue/reference/remap/functions/zip.cue @@ -32,7 +32,7 @@ remap: functions: zip: { return: { types: ["array"] rules: [ - "`zip` is considered fallible if either of the parameters is not an array, or if only the first parameter is present and it is not an array of arrays.", + "`zip` is considered fallible if any of the parameters is not an array, or if only the first parameter is present and it is not an array of arrays.", ] }