feat: add custom functions

Co-authored-by: Magnus Holm <[email protected]>

Author: tzhelyazkova

spec/02-syntax.md

@@ -1,9 +1,13 @@
 # Syntax
 
-A GROQ query is a string consisting of Unicode characters. The encoding of the query string is implementation-defined, but UTF-8 is the preferred choice. A query consist of a single {Expression}, with {WhiteSpace} and {Comment} allowed anywhere with no effect on the interpretation.
+A GROQ query is a string consisting of Unicode characters. The encoding of the query string is implementation-defined, but UTF-8 is the preferred choice.
 
 SourceCharacter : "any Unicode character"
 
+A query consist of a single {Expression} optionally preceded by a list of {FuncDecl}, with {WhiteSpace} and {Comment} allowed anywhere with no effect on the interpretation.
+
+Query : FuncDecl\* Expression
+
 ## JSON Superset
 
 GROQ's syntax is a superset of JSON, so any valid JSON value is a valid GROQ expression (that simply returns the given value). Below are a few examples of JSON values:
@@ -112,6 +116,7 @@ SimpleExpression :
 - ThisAttribute
 - Everything
 - Parent
+- Parameter
 - FuncCall
 
 CompoundExpression :

spec/03-execution.md

@@ -42,6 +42,7 @@ A query context consists of:
 - the dataset
 - parameter values (map from {string} to {value})
 - the mode: either "normal" or "delta"
+- custom function definitions (map from {string} to {function})
 
 If the mode is "delta" then the query context also has:
 
@@ -55,6 +56,7 @@ A scope consists of:
 - a this value
 - an optional parent scope
 - a query context
+- a map of parameters
 
 A root scope can be constructed from a query context, and a nested scope can be constructed from an existing scope.
 
@@ -64,6 +66,7 @@ NewNestedScope(value, scope):
 - Set the this value of {newScope} to {value}.
 - Set the parent scope of {newScope} to {scope}.
 - Set the query context of {newScope} to the query context of {scope}.
+- Set the parameters of {newScope} to the parameter of {scope}.
 - Return {newScope}.
 
 NewRootScope(context):
@@ -72,6 +75,7 @@ NewRootScope(context):
 - Set the this value of {newScope} to {null}.
 - Set the parent scope of {newScope} to {null}.
 - Set the query context of {newScope} to {context}.
+- Set the parameters to the parameters given to the query request.
 - Return {newScope}.
 
 ## Expression validation
@@ -83,6 +87,11 @@ Validate(expr):
 - Let {validator} be the validator of {expr}.
 - Execute the {validator}.
 
+## Query validation
+
+A query is validated by first validating the custom functions and then [validating the expression](#sec-Expression-validation).
+Custom functions are validated by validating the function bodies.
+
 ## Expression evaluation
 
 An expression is evaluated in a scope. You must successfully validate an expression before you attempt to evaluate it. Every expression type has their own evaluator function in their respective section in this specification (e.g. the evaluator of {ParenthesisExpression} is {EvaluateParenthesis()}).

spec/06-simple-expressions.md

@@ -75,10 +75,34 @@ EvaluateParent(scope):
   - Decrease {level} by one.
 - Return the this value of {currentScope}.
 
+## Parameter expression
+
+A parameter expression returns the value of a parameter
+
+```example
+*[_type == $type]
+           ~~~~~
+```
+
+Parameter : `$` Identifier
+
+EvaluateParameter(scope):
+
+- Let {name} be the string value of the {Identifier}.
+- Return the value of the parameter in {scope}.
+
+ValidateParameter():
+
+- Let {name} be the string value of the {Identifier}.
+- If the parameter doesn't exist in the current validation context:
+  - Report an error.
+
 ## Function call expression
 
 GROQ comes with a set of built-in functions which provides additional features. See the ["Functions"](#sec-Functions) for available functions and their namespaces.
 
+Custom GROQ functions can be defined to extend or override the built-in function set. See [Custom functions](12-custom-functions.md) for details.
+
 ```example
 *{"score": round(score, 2)}
            ~~~~~~~~~~~~~~~
@@ -106,17 +130,31 @@ EvaluateFuncCall(scope):
 - For each {Expression} in {FuncCallArgs}:
   - Let {argumentNode} be the {Expression}.
   - Append {argumentNode} to {args}.
-- Let {func} be the function defined under the name {name} in either {namespace} namespace if provided, or the `global` namespace.
-- Return the result of {func(args, scope)}.
+- If the query context of {scope} has a function defined with the given {name} and {namespace}:
+  - Let {funcBody} be body of the custom function.
+  - Let {context} be the query context of {scope}.
+  - Let {newScope} be the result of {NewRootScope(context)}.
+  - For each {param} in the parameter list of the custom function:
+    - Let {argNode} be next {Expression} in {FuncCallArgs}.
+    - Let {arg} be the result of {Evaluate(argNode, scope)}.
+    - Set the parameter named {param} in {newScope} to {arg}.
+  - Return the result of {Evaluate(funcBody, newScope)}
+- Otherwise:
+  - Let {func} be the function defined under the name {name} in either {namespace} namespace if provided, or the `global` namespace.
+  - Return the result of {func(args, scope)}.
 
 ValidateFuncCall():
 
+- Let {name} be the string value of the {FuncIdentifier}.
 - Let {namespace} be the string value of the {FuncNamespace}.
+- Let {args} be an array of the {Expression}s in {FuncCallArgs}.
+- If there's a custom function defined with the given {name} and {namespace}:
+  - For each {arg} in {args}:
+    - Execute {Validate(arg)}.
+  - Stop.
 - If there is no namespace named {namespace}:
   - Stop and report an error.
-- Let {name} be the string value of the {FuncIdentifier}.
 - If there is no function named {name} defined in either {namespace} namespace if provided, or the `global` namespace:
   - Stop and report an error.
-- Let {args} be an array of the {Expression}s in {FuncCallArgs}.
 - Let {validator} be the validator for the function under the name {name}.
 - Execute {validator(args)}.

spec/12-custom-functions.md

@@ -0,0 +1,15 @@
+# Custom Functions
+
+Custom functions are reusable sets of query substructures that allow for the modular composition of GROQ queries.
+
+## Function Definition
+
+Functions MUST be defined in the beginning of a query using the delimiter `;`.
+A function definition MUST start with the keyword `fn`.
+All custom defined functions MUST live in a namespace.
+
+FuncDecl : `fn` FuncNamespace FuncIdentifier FuncParams `=` FuncBody `;`
+
+## Function invocation
+
+FuncParams : `(` Param `)`

spec/GROQ.md

@@ -5,7 +5,7 @@ _Current Working Draft_
 This is the specification for GROQ (**G**raph-**R**elational **O**bject **Q**ueries), a query language and execution engine made at Sanity, Inc, for filtering and projecting JSON documents. The work started in 2015. The development of this open standard started in 2019.
 
 GROQ is authored by [Alexander Staubo](https://twitter.com/purefiction) and [Simen Svale Skogsrud](https://twitter.com/svale).
-Additional follow up work by [Erik Grinaker](https://twitter.com/erikgrinaker), [Magnus Holm](https://twitter.com/judofyr), [Radhe](https://github.com/j33ty), [Israel Roldan](https://github.com/israelroldan), [Sindre Gulseth](https://github.com/sgulseth), [Matt Craig](https://github.com/codebymatt), [Espen Hovlandsdal](https://github.com/rexxars).
+Additional follow up work by [Erik Grinaker](https://twitter.com/erikgrinaker), [Magnus Holm](https://twitter.com/judofyr), [Radhe](https://github.com/j33ty), [Israel Roldan](https://github.com/israelroldan), [Sindre Gulseth](https://github.com/sgulseth), [Matt Craig](https://github.com/codebymatt), [Espen Hovlandsdal](https://github.com/rexxars), [Tonina Zhelyazkova](https://github.com/tzhelyazkova).
 
 This specification should be considered _work in progress_ until the first release.
 
@@ -62,3 +62,5 @@ Conformance requirements expressed as algorithms can be fulfilled by an implemen
 # [Vendor functions](13-vendor-functions.md)
 
 # [Extensions](14-extensions.md)
+
+# [Custom functions](12-custom-functions.md)