From 82bf43956f86f2acca7e5ffff133b17e34fb75b1 Mon Sep 17 00:00:00 2001 From: Anders Eknert Date: Tue, 18 Jun 2024 20:43:59 +0200 Subject: [PATCH] Add more to docs on `prefer-some-in-iteration` 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 --- docs/rules/style/prefer-some-in-iteration.md | 26 ++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/rules/style/prefer-some-in-iteration.md b/docs/rules/style/prefer-some-in-iteration.md index 79dbc374..9c8f75e4 100644 --- a/docs/rules/style/prefer-some-in-iteration.md +++ b/docs/rules/style/prefer-some-in-iteration.md @@ -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] + # 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