-
Notifications
You must be signed in to change notification settings - Fork 34
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add more to docs on
prefer-some-in-iteration
(#851)
This is one of the most visited docs pages, so filling in some blanks and adding some links to relevant content. Signed-off-by: Anders Eknert <[email protected]>
- Loading branch information
1 parent
7bf1c93
commit e9a2ab6
Showing
1 changed file
with
26 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -49,6 +49,30 @@ Or is `other_rule` a map-generating rule, and we're checking for the existence o | |
elsewhere in the code. Using `some .. in` removes this ambiguity, and makes the intent clear without having to jump | ||
around in the policy. | ||
|
||
Improved readability is not the only benefit of using `some .. in`. The `some` keyword ensures that the bindings | ||
following the keyword are bound to the local scope, and modifications outside of e.g. a rule body won't affect how the | ||
variables are evaluated. Consider the following simplified example to iterate over the keys of a map: | ||
|
||
```rego | ||
package policy | ||
key_traversal if { | ||
map[key] | ||
This comment has been minimized.
Sorry, something went wrong.
This comment has been minimized.
Sorry, something went wrong.
anderseknert
Author
Member
|
||
# do something with key | ||
} | ||
key_traversal if { | ||
some key in object.keys(map) | ||
# do something with key | ||
} | ||
``` | ||
|
||
The two rules above are equivalent in that they both bind the variable `key` to the keys of `map`. The first | ||
example would however change behavior entirely if a rule named `key` was introduced in the package, as the expression | ||
would then mean "does map have key `key`?". While this isn't common, using `some .. in` means one less thing to worry | ||
about. | ||
|
||
## Exceptions | ||
|
||
Deeply nested iteration is often easier to read using the more compact form. | ||
|
@@ -116,6 +140,8 @@ rules: | |
- Rego Style Guide: [Prefer some .. in for iteration](https://github.com/StyraInc/rego-style-guide#prefer-some--in-for-iteration) | ||
- Regal Docs: [Use `some` to declare output variables](https://docs.styra.com/regal/rules/idiomatic/use-some-for-output-vars) | ||
- OPA Docs: [Membership and Iteration: `in`](https://www.openpolicyagent.org/docs/latest/policy-language/#membership-and-iteration-in) | ||
- OPA Docs: [Some Keyword](https://www.openpolicyagent.org/docs/latest/policy-language/#some-keyword) | ||
|
||
## Community | ||
|
||
|
some key map[key]
would do the same, right? should we mention that?