Small doc updates

Signed-off-by: Jasper Van der Jeugt <[email protected]>

docs/content/policy-language.md

@@ -419,13 +419,16 @@ Both forms are valid, however, the dot-access style is typically more readable.
   3. Variable keys which are described later.
   4. Composite keys which are described later.
 
-References are always prefixed with a variable that identifies the root
-document. In the example above this is `sites`. The root document may be:
+The prefix of a reference identifies the root document for that reference. In
+the example above this is `sites`. The root document may be:
 
   * a local variable inside a rule.
   * a rule inside the same package.
   * a document stored in OPA.
   * a documented temporarily provided to OPA as part of a transaction.
+  * an array, object or set, e.g. `[1, 2, 3][0]`.
+  * a function call, e.g. `split("a.b.c", ".")[1]`.
+  * a [comprehension](#comprehensions).
 
 ### Variable Keys
 

docs/content/policy-reference.md

@@ -616,8 +616,8 @@ query           = literal { ";" | [\r\n] literal }
 literal         = ( some-decl | expr | "not" expr ) { with-modifier }
 with-modifier   = "with" term "as" term
 some-decl       = "some" var { "," var }
-expr            = term | expr-built-in | expr-infix
-expr-built-in   = var [ "." var ] "(" [ term { , term } ] ")"
+expr            = term | expr-call | expr-infix
+expr-call       = var [ "." var ] "(" [ term { , term } ] ")"
 expr-infix      = [ term "=" ] term infix-operator term
 term            = ref | var | scalar | array | object | set | array-compr | object-compr | set-compr
 array-compr     = "[" term "|" rule-body "]"
@@ -627,7 +627,7 @@ infix-operator  = bool-operator | arith-operator | bin-operator
 bool-operator   = "==" | "!=" | "<" | ">" | ">=" | "<="
 arith-operator  = "+" | "-" | "*" | "/"
 bin-operator    = "&" | "|"
-ref             = var { ref-arg }
+ref             = ( var | array | object | set | array-compr | object-compr | set-compr | expr-call ) { ref-arg }
 ref-arg         = ref-arg-dot | ref-arg-brack
 ref-arg-brack   = "[" ( scalar | var | array | object | set | "_" ) "]"
 ref-arg-dot     = "." var