Pipeline captures (#224)

Author: cesarParra

docs/src/app/docs/piping/page.md

@@ -15,14 +15,14 @@ Why would you use it?
 
 Consider a chain of operations like this:
 
-```apex
+```
 WHERE(WHERE([1, 2, 3, 4, 5, 6], $current > 2), $current < 5)
 ```
 
 This is slightly hard to read, and it's easy to get lost in the parenthesis. With piping, you can
 write it like this:
 
-```apex
+```
 [1, 2, 3, 4, 5, 6]
     -> WHERE($current > 2)
     -> WHERE($current < 5) 
@@ -35,8 +35,29 @@ Evaluator.run('MAP(WHERE(WHERE(ChildAccounts, NumberOfEmployees > 10), AnnualRev
 
 Evaluator.run(
     'ChildAccounts ' +
-    '-> WHERE(AnnualRevenue > 200) ' +
-    '-> WHERE(NumberOfEmployees > 10) ' +
-    '-> MAP(Name)', 
+        '-> WHERE(AnnualRevenue > 200) ' +
+        '-> WHERE(NumberOfEmployees > 10) ' +
+        '-> MAP(Name)',
     recordId);
 ```
+
+## Capturing Piped Values
+
+By default, piped values are passed as the first argument to the next encountered function. However, you can explicitly
+"capture" the piped value, allowing you to use it in any position within the expression to the right-hand
+side of the pipe operator.
+
+To capture the piped value, use the `_` keyword. For example:
+
+```
+[1, 2, 3, 4, 5, 6]
+    -> WHERE(_, $current > 2)  # Here, _ represents the piped value
+```
+
+Explicitly capturing the value also allows you to use the same value multiple times:
+
+```
+RANGE(1, 10)
+    -> WHERE(_, $current > 1)
+    -> SUM(_) + SIZE(_)
+```

expression-src/main/api/tests/EvaluatorRetrieveRecordTest.cls-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>60.0</apiVersion>
+    <apiVersion>65.0</apiVersion>
     <status>Active</status>
-</ApexClass>
+</ApexClass>

expression-src/main/src/interpreter/ContextResolver.cls

@@ -437,6 +437,16 @@ public with sharing class ContextResolver implements Visitor {
         return null;
     }
 
+    public Object visit(Expr.PipelineFunction pipelineFunction) {
+        resolve(pipelineFunction.left);
+        resolve(pipelineFunction.body);
+        return null;
+    }
+
+    public Object visit(Expr.Capture capture) {
+        return null;
+    }
+
     private final Map<SObjectType, Fields> cachedFieldsBySObjectType = new Map<SObjectType, Fields>();
     private Fields getFields() {
         if (cachedFieldsBySObjectType.containsKey(this.queryContext.objectType)) {

expression-src/main/src/interpreter/Exceptions.cls

@@ -54,4 +54,18 @@ public with sharing class Exceptions {
             return 'Runtime';
         }
     }
+
+    public class UnknownException extends PositionAwareException {
+        public UnknownException(SourcePosition position, String message) {
+            super(position, message);
+        }
+
+        public override String toString() {
+            return super.toString();
+        }
+
+        public override String getType() {
+            return 'Unknown';
+        }
+    }
 }

expression-src/main/src/interpreter/Exceptions.cls-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>60.0</apiVersion>
+    <apiVersion>65.0</apiVersion>
     <status>Active</status>
 </ApexClass>

expression-src/main/src/interpreter/Expr.cls

@@ -545,4 +545,69 @@ public abstract class Expr {
             return result;
         }
     }
+
+    public class PipelineFunction extends Expr {
+        public final Token pipeToken;
+        public final Expr left;
+        public final Expr body;
+        public Boolean hasExplicitCapture = false;
+
+        public PipelineFunction(Token pipeToken, Expr left, Expr body) {
+            this.pipeToken = pipeToken;
+            this.left = left;
+            this.body = body;
+        }
+
+        public override Object accept(Visitor v) {
+            return v.visit(this);
+        }
+
+        public PipelineFunction withInnerCapture(Boolean hasInnerCapture) {
+            this.hasExplicitCapture = hasInnerCapture;
+            return this;
+        }
+
+        public Boolean equals(Object other) {
+            if (other instanceof PipelineFunction) {
+                PipelineFunction otherPipelineFunction = (PipelineFunction)other;
+                return this.pipeToken == otherPipelineFunction.pipeToken
+                    && this.left == otherPipelineFunction.left
+                    && this.body == otherPipelineFunction.body
+                    && this.hasExplicitCapture == otherPipelineFunction.hasExplicitCapture;
+            }
+            return false;
+        }
+
+        public override Integer hashCode() {
+            Integer result = System.hashCode(pipeToken);
+            result = (31 * result) + System.hashCode(left);
+            result = (31 * result) + System.hashCode(body);
+            result = (31 * result) + System.hashCode(hasExplicitCapture);
+            return result;
+        }
+    }
+
+    public class Capture extends Expr {
+        public final Token captureToken;
+
+        public Capture(Token captureToken) {
+            this.captureToken = captureToken;
+        }
+
+        public override Object accept(Visitor v) {
+            return v.visit(this);
+        }
+
+        public Boolean equals(Object other) {
+            if (other instanceof Capture) {
+                Capture otherCapture = (Capture)other;
+                return this.captureToken == otherCapture.captureToken;
+            }
+            return false;
+        }
+
+        public override Integer hashCode() {
+            return System.hashCode(captureToken);
+        }
+    }
 }

expression-src/main/src/interpreter/Interpreter.cls

@@ -357,9 +357,28 @@ public virtual with sharing class Interpreter implements Visitor {
     }
 
     public virtual Object visit(Expr.FunctionCall function) {
+        attemptCapture(function);
         return FunctionCaller.exec(this, function);
     }
 
+    protected void attemptCapture(Expr.FunctionCall function) {
+        if (pendingCapture == null || pendingCapture.isExplicit == true) {
+            return;
+        }
+
+        // If there is a pipeline capture pending, then the first function
+        // call we encounter should use that as its first argument.
+        if (function.arguments.isEmpty()) {
+            function.arguments.add(pendingCapture.expression);
+        } else {
+            function.arguments.add(0, pendingCapture.expression);
+        }
+
+        // Once captured, we clear the pending capture to avoid any additional
+        // functions to the right-hand side of the pipeline to try and use it.
+        pendingCapture = null;
+    }
+
     public Object visit(Expr.ListLiteral listLiteral) {
         inListLiteralCounter++;
         List<Object> resultList = new List<Object>();
@@ -567,4 +586,66 @@ public virtual with sharing class Interpreter implements Visitor {
 
         return new ShouldNotAdd();
     }
+
+    private PendingCapture pendingCapture;
+    public Object visit(Expr.PipelineFunction pipelineFunction) {
+        if (pipelineFunction.hasExplicitCapture) {
+            // When dealing with an explicit capture, we immediately evaluate
+            // the left-hand side of the pipeline, and store it for it to be used
+            // whenever a capture ("_") expression is encountered within the right-hand side (body).
+            this.pendingCapture = explicit(evaluate(pipelineFunction.left));
+        } else {
+            // If there is no capture on the right-hand side of the pipeline,
+            // then it acts as syntactic sugar for passing the left-hand side
+            // as the first argument to the function call on the right-hand side.
+            // Thus, it does not get evaluated, but rather stored as an expression
+            // for it to be evaluated during function call argument resolution.
+            this.pendingCapture = implicit(pipelineFunction.left);
+        }
+
+        Object toReturn = evaluate(pipelineFunction.body);
+        return toReturn;
+    }
+
+    public Object visit(Expr.Capture capture) {
+        if (this.pendingCapture == null) {
+            throw new Exceptions.RuntimeException(
+                capture.captureToken,
+                'Capture expressions can only be used inside pipeline functions.'
+            );
+        }
+
+        if (pendingCapture.isExplicit == false) {
+            // This should be unreachable, since the PipelineFunction visitor
+            // should have populated the pending capture as explicit.
+            throw new Exceptions.UnknownException(
+                capture.captureToken.position,
+                'Internal error: expected an explicit pending capture.'
+            );
+        }
+
+        return this.pendingCapture.result;
+    }
+
+    private class PendingCapture {
+        private Boolean isExplicit;
+        // Populated when isExplicit is false
+        private Expr expression;
+        // Populated when isExplicit is true
+        private Object result;
+    }
+
+    private static PendingCapture explicit(Object result) {
+        PendingCapture capture = new PendingCapture();
+        capture.isExplicit = true;
+        capture.result = result;
+        return capture;
+    }
+
+    private static PendingCapture implicit(Expr expression) {
+        PendingCapture capture = new PendingCapture();
+        capture.isExplicit = false;
+        capture.expression = expression;
+        return capture;
+    }
 }

expression-src/main/src/interpreter/Parser.cls

@@ -70,7 +70,21 @@ public with sharing class Parser {
             consume(TokenType.SEMICOLON, 'Expect \';\' after function body.');
             return new Expr.FunctionDeclaration(name, parameters, body, skipCache);
         }
-        return orCheck();
+        return pipe();
+    }
+
+    private Expr pipe() {
+        Expr expr = orCheck();
+
+        while (match(new List<TokenType> {
+            TokenType.ARROW
+        })) {
+            Token operator = previous();
+            Expr right = orCheck();
+            expr = new Expr.Binary(expr, operator, right);
+        }
+
+        return expr;
     }
 
     private Expr orCheck() {
@@ -205,7 +219,7 @@ public with sharing class Parser {
     }
 
     private Expr getExpr() {
-        Expr expr = pipe();
+        Expr expr = primary();
 
         while (true) {
             if (match(TokenType.DOT)) {
@@ -224,20 +238,6 @@ public with sharing class Parser {
         return expr;
     }
 
-    private Expr pipe() {
-        Expr expr = primary();
-
-        while (match(new List<TokenType> {
-            TokenType.ARROW
-        })) {
-            Token operator = previous();
-            Expr right = primary();
-            expr = new Expr.Binary(expr, operator, right);
-        }
-
-        return expr;
-    }
-
     private Expr primary() {
         if (match(TokenType.FALSE_KEYWORD)) {
             return new Expr.Literal(false);
@@ -255,6 +255,10 @@ public with sharing class Parser {
             return parseQuery();
         }
 
+        if (match(TokenType.CAPTURE)) {
+            return new Expr.Capture(previous());
+        }
+
         if (match(TokenType.STRING_LITERAL_START)) {
             // Grab all characters until we reach the STRING_LITERAL_END
             List<Object> strings = new List<Object>();

expression-src/main/src/interpreter/Parser.cls-meta.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>60.0</apiVersion>
+    <apiVersion>65.0</apiVersion>
     <status>Active</status>
 </ApexClass>