Array Functions
The section describes the following array functions.
| • | first |
| • | last |
| • | get |
| • | contains |
| • | select |
| • | size |
| • | jmes_path |
| • | jq |
| • | xpath |
first(<array>)
first returns the first value of an array. The return value type is value of the element. first may appear when defining datasource fields or in validations
Examples:
first(@instances) # returns the first instance from an array of instances
first(split("x,y,z", ",")) # returns the value "x"
In this example we get the first IP address from a list of IP addresses.
first(val(iter_item, "private_ip_addresses"))
last(<array>)
last returns the last value of an array. The return value type is value of the element. last may appear when defining datasource fields or in validations.
Examples:
last(@volume) # returns the last volume from an array of volumes
last(split("/api/volumes/1234", "/")) # returns "1234"
get(index, <array>)
get returns value of an array at index. Index starts at 0. The return value type is value of the element. get may appear when defining datasource fields or in validations.
Examples:
get(2, @instances) # return the third element (index 2) of an array
get(1, split("x,y,z", ",")) # returns the second element of the split array, which is "y"
contains(<array>, <select expression>)
contains returns true if the array contains any elements which match the select expression. The select expression will differ based on the type of the array:
| • | For an array of numbers, select expression much be a number |
| • | For an array of strings, select expression can be a string or regexp. |
| • | For an array of objects, select expression must be a object denoting which fields to match. Deeper matches can be done by specifying sub objects. |
The return type of contains is a boolean. contains may appear when defining datasource fields or in validations.
This example selects fields out of a basic array using a regular expression.
contains(["John Smith", "John Adams", "Tom Jackson"], /John/) # returns true
contains(["John Smith", "John Adams", "Tom Jackson"], "Tom Jackson") # returns true
contains([10,100,500], 100) # returns true
contains([10,100,500], "100") # returns false. The type matters! "100" is a string and the array is an array of numbers.
For the next examples @instances is an array of Instance Resources returned by the Flexera API with the following structure:
{
"id": <string>
"name": <string>
"cloud_specific_attributes": {
"ebs_optimized": <boolean>,
}
}
This will get instances where the ebs optimized flag is set to true:
contains(@instances, {"cloud_specific_attributes": {"ebs_optimized": true})
select(<array>, <select expression>)
select returns a new array with zero or more elements matching the select expression. The select expression will differ based on the type of the array:
| • | For an array of numbers, select expression must be a number |
| • | For an array of strings, select expression can be a string or regexp. |
| • | For an array of objects, select expression must be an object denoting which fields to match. Deeper matches can be done by specifying sub objects. |
The return type of select is a boolean. select may appear when defining datasource fields or in validations.
This example selects fields out of a basic array:
select(["John Smith", "John Adams", "Tom Jackson"], /John/) # returns ["John Smith", "John Adams"]
For the next examples @instances is an array of Instance objects returned by the RightScale API with the following structure:
{
"id": <string>
"name": <string>
"ip_addresses": [<string>, <string>, ...]
}
This example creates a new datasource with public IP addresses selected out:
datasource "test_instances" do
iterate @instances
field "private_ips" select(val(iter_item, "ip_addresses"), /(^192\.168)|(^10\.)|(^172\.1[6-9])|(^172\.2[0-9])|(^172\.3[0-1])/)
end
size(<array>)
size returns the size of an array. The return value type is number. size may appear when defining datasource fields or in validations.
Examples:
size(@volumes) # returns the number of volumes
size(["a","b","c"]) # returns 3
jmes_path(<array of objects>|<object>, expression <string>)
jmes_path will run a JMESPath expression against an array of objects or object. The return type is varied. jmes_path should mostly be used in defining custom datasources (see API Data With Datasources) and Pagination, but can also be used for writing validations (See Describing the Policy Conditions). For more complicated validations, it's highly recommended to use a JavaScript datasource (see Processing Datasources With JavaScript).
For example, given a resource named @clouds:
[
{
"cloud_type": "amazon",
"description": "Amazon's US Cloud on the East Coast",
"display_name": "AWS US-East",
"name": "EC2 us-east-1"
},
{
"cloud_type": "google",
"description": "Google Cloud, including Google Compute Engine, Google Cloud Storage, etc.",
"display_name": "Google",
"name": "Google"
}
]
jmes_path(@clouds, "[].name") # returns ["EC2 us-east-1", "Google"]
jq(<array of objects>|<object>, expression <string>[, type "simple_element"|"array"])
jq will run a jq expression against an array of objects or object. The return type is varied. The optional third argument specifies whether the expression is expected to return a single element ("simple_element") or multiple ("array"); if unspecified, the default is "simple_element" except when used as the expression of a collect where it is "array". jq should mostly be used in defining custom datasources (see API Data With Datasources) and Pagination, but can also be used for writing validations (See Describing the Policy Conditions). For more complicated validations, it's highly recommended to use a JavaScript datasource (see Processing Datasources With JavaScript).
For example, given a resource named @clouds:
[
{
"cloud_type": "amazon",
"description": "Amazon's US Cloud on the East Coast",
"display_name": "AWS US-East",
"name": "EC2 us-east-1"
},
{
"cloud_type": "google",
"description": "Google Cloud, including Google Compute Engine, Google Cloud Storage, etc.",
"display_name": "Google",
"name": "Google"
}
]
jq(@clouds, ".[].name", "array") # returns ["EC2 us-east-1", "Google"]
xpath(<array of xml node objects>|<xml node object>, expression <string>[, type "simple_element"|"array"])
xpath will run an XPath expression against an array of XML node objects or object. The return type is varied. The optional third argument specifies whether the expression is expected to return a single element ("simple_element") or multiple ("array"); if unspecified, the default is "simple_element" except when used as the expression of a collect where it is "array". xpath should be used in defining custom datasources (see API Data With Datasources) and Pagination.
For example, given the response in a datasource:
<clouds>
<cloud>
<type>amazon</type>
<description>Amazon's US Cloud on the East Coast</description>
<display-name>AWS US-East</display-name>
<name>EC2 us-east-1</name>
</cloud>
<cloud>
<type>google</type>
<description>Google Cloud, including Google Compute Engine, Google Cloud Storage, etc.</description>
<display-name>Google</display-name>
<name>Google</name>
</cloud>
</clouds>
xpath(response, "//clouds/cloud/name", "array") # returns ["EC2 us-east-1", "Google"]