Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature: Add new Provider Function 'collection_filter' #5

Merged
merged 2 commits into from
Dec 3, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions docs/functions/collection_filter.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
page_title: "collection_filter function - helpers"
subcategory: "Collection Functions"
description: |-
Filter collection of objects.
---

# Function: collection_filter

Filter collection of objects.

The function `collection_filter` can be used, as indicated by the name, to quickly filter a collection of values.
Terraform does not offer out-of-the-box such functionality in a direct way, with the only reasonable solution of loop
through the collection and perform the filtering.

In the current version the function is able to filter collection of primitives (number, bool, string) and objects, with
the last one able to also filter by a nested attribute. The filter right now is only using an "equal" check operation,
however, we might put some effort in the future to support different operators.


## Example Usage

```terraform
locals {
test_object_collection = [
{ key1 = "value1", key2 = true, key3 = 3, key4 = null },
{ key1 = "value2", key2 = false, key3 = 0, key4 = {} },
{ key1 = "value3", key2 = true, key3 = 5, key4 = null },
{ key1 = "value4", key2 = false, key3 = 1, key4 = { key5 = "value5", key6 = true } },
]

test_string_array = ["value1", "value2", "value3", "value1"]

test_number_array = [5, 8, 3, 5]

test_bool_array = [true, false, true]
}

# Expected return:
# [
# { key1 = "value1", key2 = true, key3 = 3, key4 = null },
# ]
output "test_match_object_string_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key1", "value1")
}

# Expected return:
# [
# { key1 = "value1", key2 = true, key3 = 3, key4 = null },
# { key1 = "value3", key2 = true, key3 = 5, key4 = null },
# ]
output "test_match_object_bool_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key2", true)
}

# Expected return:
# [
# { key1 = "value3", key2 = true, key3 = 5, key4 = null },
# ]
output "test_match_object_number_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key3", 5)
}

# Expected return:
# [
# { key1 = "value1", key2 = true, key3 = 3, key4 = null },
# { key1 = "value3", key2 = true, key3 = 5, key4 = null },
# ]
output "test_match_object_null_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key4", null)
}

# Expected return:
# [
# { key1 = "value4", key2 = false, key3 = 1, key4 = { key5 = "value5", key6 = true } },
# ]
output "test_match_object_string_nested_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key4.key5", "value5")
}

# Expected return:
# [ ]
output "test_no_match_object_string_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key1", "new_value")
}

# Expected return:
# ["value1", "value1"]
output "test_match_string_array" {
value = provider::helpers::collection_filter(local.test_string_array, "", "value1")
}

# Expected return:
# [5, 5]
output "test_match_number_array" {
value = provider::helpers::collection_filter(local.test_number_array, "", 5)
}

# Expected return:
# [false]
output "test_match_bool_array" {
value = provider::helpers::collection_filter(local.test_bool_array, "", false)
}
```

## Signature

<!-- signature generated by tfplugindocs -->
```text
collection_filter(collection dynamic, key string, value dynamic) dynamic
```

## Arguments

<!-- arguments generated by tfplugindocs -->
1. `collection` (Dynamic) The collection of objects to filter
1. `key` (String) The key from the object to filter by
1. `value` (Dynamic, Nullable) The value used to compare against


## Return Type

The signature shows a dynamic type of return because in order to support multiple types of collections the return must
be specified in such way. You can always expect a collection of the same type as used in the input.
43 changes: 43 additions & 0 deletions docs/functions/os_get_env.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
page_title: "os_get_env function - helpers"
subcategory: "OS Functions"
description: |-
Get an environment variable
---

# Function: os_get_env

Get an environment variable

The function `os_get_env` retrieves the value of an environment variable and provides a fallback value if the
environment variable is not set.

## Example Usage

```terraform
output "tf_log" {
value = {
test_value_as_is = provider::helpers::os_get_env("TF_LOG")
test_value_with_fallback = provider::helpers::os_get_env("TF_ENV", "test")
}
}
```

## Signature

<!-- signature generated by tfplugindocs -->
```text
os_get_env(name string, fallback string...) string
```

## Arguments

<!-- arguments generated by tfplugindocs -->
1. `name` (String) The name of the environment variable to get
<!-- variadic argument generated by tfplugindocs -->
1. `fallback` (Variadic, String) The fallback value to use if the environment variable is not set

## Return Type

The return type of `os_get_env` is a string representing the value of the environment variable or the fallback value.
You can use terraform type conversion functions to convert the string to other types if needed.
80 changes: 80 additions & 0 deletions examples/functions/collection_filter/function.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
locals {
test_object_collection = [
{ key1 = "value1", key2 = true, key3 = 3, key4 = null },
{ key1 = "value2", key2 = false, key3 = 0, key4 = {} },
{ key1 = "value3", key2 = true, key3 = 5, key4 = null },
{ key1 = "value4", key2 = false, key3 = 1, key4 = { key5 = "value5", key6 = true } },
]

test_string_array = ["value1", "value2", "value3", "value1"]

test_number_array = [5, 8, 3, 5]

test_bool_array = [true, false, true]
}

# Expected return:
# [
# { key1 = "value1", key2 = true, key3 = 3, key4 = null },
# ]
output "test_match_object_string_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key1", "value1")
}

# Expected return:
# [
# { key1 = "value1", key2 = true, key3 = 3, key4 = null },
# { key1 = "value3", key2 = true, key3 = 5, key4 = null },
# ]
output "test_match_object_bool_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key2", true)
}

# Expected return:
# [
# { key1 = "value3", key2 = true, key3 = 5, key4 = null },
# ]
output "test_match_object_number_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key3", 5)
}

# Expected return:
# [
# { key1 = "value1", key2 = true, key3 = 3, key4 = null },
# { key1 = "value3", key2 = true, key3 = 5, key4 = null },
# ]
output "test_match_object_null_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key4", null)
}

# Expected return:
# [
# { key1 = "value4", key2 = false, key3 = 1, key4 = { key5 = "value5", key6 = true } },
# ]
output "test_match_object_string_nested_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key4.key5", "value5")
}

# Expected return:
# [ ]
output "test_no_match_object_string_value" {
value = provider::helpers::collection_filter(local.test_object_collection, "key1", "new_value")
}

# Expected return:
# ["value1", "value1"]
output "test_match_string_array" {
value = provider::helpers::collection_filter(local.test_string_array, "", "value1")
}

# Expected return:
# [5, 5]
output "test_match_number_array" {
value = provider::helpers::collection_filter(local.test_number_array, "", 5)
}

# Expected return:
# [false]
output "test_match_bool_array" {
value = provider::helpers::collection_filter(local.test_bool_array, "", false)
}
6 changes: 6 additions & 0 deletions examples/functions/os_get_env/function.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
output "tf_log" {
value = {
test_value_as_is = provider::helpers::os_get_env("TF_LOG")
test_value_with_fallback = provider::helpers::os_get_env("TF_ENV", "test")
}
}
14 changes: 7 additions & 7 deletions go.mod
Original file line number Diff line number Diff line change
@@ -9,6 +9,7 @@ require (
github.com/hashicorp/terraform-plugin-go v0.25.0
github.com/hashicorp/terraform-plugin-log v0.9.0
github.com/hashicorp/terraform-plugin-testing v1.11.0
golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f
)

require (
@@ -70,17 +71,16 @@ require (
github.com/zclconf/go-cty v1.15.0 // indirect
go.abhg.dev/goldmark/frontmatter v0.2.0 // indirect
golang.org/x/crypto v0.29.0 // indirect
golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df // indirect
golang.org/x/mod v0.21.0 // indirect
golang.org/x/net v0.30.0 // indirect
golang.org/x/mod v0.22.0 // indirect
golang.org/x/net v0.31.0 // indirect
golang.org/x/sync v0.9.0 // indirect
golang.org/x/sys v0.27.0 // indirect
golang.org/x/text v0.20.0 // indirect
golang.org/x/tools v0.22.0 // indirect
golang.org/x/tools v0.27.0 // indirect
google.golang.org/appengine v1.6.8 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20241021214115-324edc3d5d38 // indirect
google.golang.org/grpc v1.67.1 // indirect
google.golang.org/protobuf v1.35.1 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20241202173237-19429a94021a // indirect
google.golang.org/grpc v1.68.0 // indirect
google.golang.org/protobuf v1.35.2 // indirect
gopkg.in/yaml.v2 v2.3.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)
13 changes: 13 additions & 0 deletions go.sum
Original file line number Diff line number Diff line change
@@ -214,16 +214,22 @@ golang.org/x/crypto v0.29.0 h1:L5SG1JTTXupVV3n6sUqMTeWbjAyfPwoda2DLX8J8FrQ=
golang.org/x/crypto v0.29.0/go.mod h1:+F4F4N5hv6v38hfeYwTdx20oUvLLc+QfrE9Ax9HtgRg=
golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df h1:UA2aFVmmsIlefxMk29Dp2juaUSth8Pyn3Tq5Y5mJGME=
golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc=
golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f h1:XdNn9LlyWAhLVp6P/i8QYBW+hlyhrhei9uErw2B5GJo=
golang.org/x/exp v0.0.0-20241108190413-2d47ceb2692f/go.mod h1:D5SMRVC3C2/4+F/DB1wZsLRnSNimn2Sp/NPsCrsv8ak=
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
golang.org/x/mod v0.21.0 h1:vvrHzRwRfVKSiLrG+d4FMl/Qi4ukBCE6kZlTUkDYRT0=
golang.org/x/mod v0.21.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY=
golang.org/x/mod v0.22.0 h1:D4nJWe9zXqHOmWqj4VMOJhvzj7bEZg4wEYa759z1pH4=
golang.org/x/mod v0.22.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY=
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
golang.org/x/net v0.2.0/go.mod h1:KqCZLdyyvdV855qA2rE3GC2aiw5xGR5TEjj8smXukLY=
golang.org/x/net v0.30.0 h1:AcW1SDZMkb8IpzCdQUaIq2sP4sZ4zw+55h6ynffypl4=
golang.org/x/net v0.30.0/go.mod h1:2wGyMJ5iFasEhkwi13ChkO/t1ECNC4X4eBKkVFyYFlU=
golang.org/x/net v0.31.0 h1:68CPQngjLL0r2AlUKiSxtQFKvzRVbnzLwMUn5SzcLHo=
golang.org/x/net v0.31.0/go.mod h1:P4fl1q7dY2hnZFxEk4pPSkDHF+QqjitcnDjUQyMM+pM=
golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -260,19 +266,26 @@ golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtn
golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
golang.org/x/tools v0.22.0 h1:gqSGLZqv+AI9lIQzniJ0nZDRG5GBPsSi+DRNHWNz6yA=
golang.org/x/tools v0.22.0/go.mod h1:aCwcsjqvq7Yqt6TNyX7QMU2enbQ/Gt0bo6krSeEri+c=
golang.org/x/tools v0.27.0/go.mod h1:sUi0ZgbwW9ZPAq26Ekut+weQPR5eIM6GQLQ1Yjm1H0Q=
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
google.golang.org/appengine v1.6.8 h1:IhEN5q69dyKagZPYMSdIjS2HqprW324FRQZJcGqPAsM=
google.golang.org/appengine v1.6.8/go.mod h1:1jJ3jBArFh5pcgW8gCtRJnepW8FzD1V44FJffLiz/Ds=
google.golang.org/genproto/googleapis/rpc v0.0.0-20241021214115-324edc3d5d38 h1:zciRKQ4kBpFgpfC5QQCVtnnNAcLIqweL7plyZRQHVpI=
google.golang.org/genproto/googleapis/rpc v0.0.0-20241021214115-324edc3d5d38/go.mod h1:GX3210XPVPUjJbTUbvwI8f2IpZDMZuPJWDzDuebbviI=
google.golang.org/genproto/googleapis/rpc v0.0.0-20241202173237-19429a94021a h1:hgh8P4EuoxpsuKMXX/To36nOFD7vixReXgn8lPGnt+o=
google.golang.org/genproto/googleapis/rpc v0.0.0-20241202173237-19429a94021a/go.mod h1:5uTbfoYQed2U9p3KIj2/Zzm02PYhndfdmML0qC3q3FU=
google.golang.org/grpc v1.67.1 h1:zWnc1Vrcno+lHZCOofnIMvycFcc0QRGIzm9dhnDX68E=
google.golang.org/grpc v1.67.1/go.mod h1:1gLDyUQU7CTLJI90u3nXZ9ekeghjeM7pTDZlqFNg2AA=
google.golang.org/grpc v1.68.0 h1:aHQeeJbo8zAkAa3pRzrVjZlbz6uSfeOXlJNQM0RAbz0=
google.golang.org/grpc v1.68.0/go.mod h1:fmSPC5AsjSBCK54MyHRx48kpOti1/jRfOlwEWywNjWA=
google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
google.golang.org/protobuf v1.35.1 h1:m3LfL6/Ca+fqnjnlqQXNpFPABW1UD7mjh8KO2mKFytA=
google.golang.org/protobuf v1.35.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
google.golang.org/protobuf v1.35.2 h1:8Ar7bF+apOIoThw1EdZl0p1oWvMqTHmpA2fRTyZO8io=
google.golang.org/protobuf v1.35.2/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33q108Sa+fhmuc+sWQYwY=
gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
Loading