Add help and compile options to the REPL

repl/appengine/app/api_test.go

@@ -85,7 +85,7 @@ func TestAPIEvaluate(t *testing.T) {
 					},
 					{
 						ReplOutput: "",
-						Issue:      "(1:0) no viable alternative at input '}'",
+						Issue:      "invalid command: (1:0) no viable alternative at input '}'",
 						Evaluated:  false,
 					},
 				},

repl/appengine/go.mod

@@ -2,13 +2,16 @@ module github.com/google/cel-go/repl/appengine
 
 go 1.18
 
-require github.com/google/cel-go/repl v0.0.0-20230215224331-739dcddbb53f
+require github.com/google/cel-go/repl v0.0.0-20230406155237-b081aea03865
 
 require (
-	github.com/antlr/antlr4/runtime/Go/antlr v1.4.10 // indirect
-	github.com/google/cel-go v0.13.0 // indirect
-	github.com/stoewer/go-strcase v1.2.0 // indirect
-	golang.org/x/text v0.4.0 // indirect
-	google.golang.org/genproto v0.0.0-20230106154932-a12b697841d9 // indirect
-	google.golang.org/protobuf v1.28.1 // indirect
+	github.com/antlr/antlr4/runtime/Go/antlr/v4 v4.0.0-20230321174746-8dcc6526cfb1 // indirect
+	github.com/google/cel-go v0.14.0 // indirect
+	github.com/stoewer/go-strcase v1.3.0 // indirect
+	golang.org/x/exp v0.0.0-20230321023759-10a507213a29 // indirect
+	golang.org/x/text v0.9.0 // indirect
+	google.golang.org/genproto v0.0.0-20230403163135-c38d8f061ccd // indirect
+	google.golang.org/protobuf v1.30.0 // indirect
 )
+
+replace github.com/google/cel-go/repl => ../.

repl/appengine/go.sum

@@ -1,33 +1,35 @@
-github.com/antlr/antlr4/runtime/Go/antlr v1.4.10 h1:yL7+Jz0jTC6yykIK/Wh74gnTJnrGr5AyrNMXuA0gves=
-github.com/antlr/antlr4/runtime/Go/antlr v1.4.10/go.mod h1:F7bn7fEU90QkQ3tnmaTx3LTKLEDqnwWODIYppRQ5hnY=
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/antlr/antlr4/runtime/Go/antlr/v4 v4.0.0-20230321174746-8dcc6526cfb1 h1:X8MJ0fnN5FPdcGF5Ij2/OW+HgiJrRg3AfHAx1PJtIzM=
+github.com/antlr/antlr4/runtime/Go/antlr/v4 v4.0.0-20230321174746-8dcc6526cfb1/go.mod h1:pSwJ0fSY5KhvocuWSx4fz3BA8OrA1bQn+K1Eli3BRwM=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
-github.com/golang/protobuf v1.5.2 h1:ROPKBNFfQgOUMifHyP+KYbvpjbdoFNs+aK7DXlji0Tw=
-github.com/google/cel-go v0.12.5 h1:DmzaiSgoaqGCjtpPQWl26/gND+yRpim56H1jCVev6d8=
-github.com/google/cel-go v0.12.5/go.mod h1:Jk7ljRzLBhkmiAwBoUxB1sZSCVBAzkqPF25olK/iRDw=
-github.com/google/cel-go v0.13.0 h1:z+8OBOcmh7IeKyqwT/6IlnMvy621fYUqnTVPEdegGlU=
-github.com/google/cel-go v0.13.0/go.mod h1:K2hpQgEjDp18J76a2DKFRlPBPpgRZgi6EbnpDgIhJ8s=
-github.com/google/cel-go/repl v0.0.0-20230215224331-739dcddbb53f h1:dLZBVQxd0lWCFcSe8QrX4AyE4QtbluOajcFG9uM6x9Q=
-github.com/google/cel-go/repl v0.0.0-20230215224331-739dcddbb53f/go.mod h1:LzcdDpGx1CNEvTDxbxThsW0X/Hj9jdylS1/1FJBkQD0=
-github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
+github.com/google/cel-go v0.14.0 h1:LFobwuUDslWUHdQ48SXVXvQgPH2X1XVhsgOGNioAEZ4=
+github.com/google/cel-go v0.14.0/go.mod h1:YzWEoI07MC/a/wj9in8GeVatqfypkldgBlwXh9bCwqY=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stoewer/go-strcase v1.2.0 h1:Z2iHWqGXH00XYgqDmNgQbIBxf3wrNq0F3feEy0ainaU=
-github.com/stoewer/go-strcase v1.2.0/go.mod h1:IBiWB2sKIp3wVVQ3Y035++gc+knqhUQag1KpM8ahLw8=
+github.com/stoewer/go-strcase v1.3.0 h1:g0eASXYtp+yvN9fK8sH94oCIk0fau9uV1/ZdJ0AVEzs=
+github.com/stoewer/go-strcase v1.3.0/go.mod h1:fAH5hQ5pehh+j3nZfvwdk2RgEgQjAoM8wodgtPmh1xo=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.5.1 h1:nOGnQDM7FYENwehXlg/kFVnos3rEvtKTjRvOWSzb6H4=
-github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
-golang.org/x/text v0.4.0 h1:BrVqGRd7+k1DiOgtnFvAkoQEWQvBc25ouMJM6429SFg=
-golang.org/x/text v0.4.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
-golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+golang.org/x/exp v0.0.0-20230321023759-10a507213a29 h1:ooxPy7fPvB4kwsA2h+iBNHkAbp/4JxTSwCmvdjEYmug=
+golang.org/x/exp v0.0.0-20230321023759-10a507213a29/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc=
+golang.org/x/text v0.9.0 h1:2sjJmO8cDvYveuX97RDLsxlyUxLl+GHoLxBiRdHllBE=
+golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/genproto v0.0.0-20230106154932-a12b697841d9 h1:3wPBShTLWQnEkZ9VW/HZZ8zT/9LLtleBtq7l8SKtJIA=
-google.golang.org/genproto v0.0.0-20230106154932-a12b697841d9/go.mod h1:RGgjbofJ8xD9Sq1VVhDM1Vok1vRONV+rg+CjzG4SZKM=
+google.golang.org/genproto v0.0.0-20230403163135-c38d8f061ccd h1:sLpv7bNL1AsX3fdnWh9WVh7ejIzXdOc1RRHGeAmeStU=
+google.golang.org/genproto v0.0.0-20230403163135-c38d8f061ccd/go.mod h1:UUQDJDOlWu4KYeJZffbWgBkS1YFobzKbLVfK69pe0Ak=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
-google.golang.org/protobuf v1.28.1 h1:d0NfwRgPtno5B1Wa6L2DAG+KivqkdutMf1UhdNx175w=
-google.golang.org/protobuf v1.28.1/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
+google.golang.org/protobuf v1.30.0 h1:kPPoIgf3TsEvrm0PFe15JQ+570QVxYzEvvHqChK+cng=
+google.golang.org/protobuf v1.30.0/go.mod h1:HV8QOd/L58Z+nl8r43ehVNZIU/HEI6OcFqwMG9pJV4I=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v2 v2.2.2 h1:ZCJp+EgiOT7lHqUV2J862kp8Qj64Jo6az82+3Td9dZw=
-gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

repl/commands.go

@@ -26,17 +26,34 @@ import (
 	exprpb "google.golang.org/genproto/googleapis/api/expr/v1alpha1"
 )
 
-var letUsage = `Let introduces a variable or function defined by a sub-CEL expression.
-%let <identifier> (: <type>)? = <expr>
-%let <identifier> (<param_identifier> : <param_type>, ...) : <result-type> -> <expr>`
+var (
+	compileUsage = `Compile emits a textproto representation of the compiled expression.
+%compile <expr>`
 
-var declareUsage = `Declare introduces a variable or function for type checking, but doesn't define a value for it.
+	declareUsage = `Declare introduces a variable or function for type checking, but
+doesn't define a value for it:
 %declare <identifier> : <type>
-%declare <identifier> (<param_identifier> : <param_type>, ...) : <result-type>
-`
-var deleteUsage = `Delete removes a variable or function declaration from the evaluation context.
+%declare <identifier> (<param_identifier> : <param_type>, ...) : <result-type>`
+
+	deleteUsage = `Delete removes a variable or function declaration from the evaluation context.
 %delete <identifier>`
 
+	letUsage = `Let introduces a variable or function defined by a sub-CEL expression.
+%let <identifier> (: <type>)? = <expr>
+%let <identifier> (<param_identifier> : <param_type>, ...) : <result-type> -> <expr>`
+
+	optionUsage = `Option enables a CEL environment option which enables configuration and
+optional language features.
+%option --container 'google.protobuf'
+%option --extension 'all'`
+
+	exitUsage = `Exit terminates the REPL.
+%exit`
+
+	helpUsage = `Help prints usage information for the commands supported by the REPL.
+%help`
+)
+
 type letVarCmd struct {
 	identifier string
 	typeHint   *exprpb.Type
@@ -59,6 +76,10 @@ type simpleCmd struct {
 	args []string
 }
 
+type compileCmd struct {
+	expr string
+}
+
 type evalCmd struct {
 	expr string
 }
@@ -93,6 +114,10 @@ func (c *simpleCmd) Cmd() string {
 	return c.cmd
 }
 
+func (c *compileCmd) Cmd() string {
+	return "compile"
+}
+
 func (c *evalCmd) Cmd() string {
 	return "eval"
 }
@@ -150,9 +175,19 @@ func Parse(line string) (Cmder, error) {
 		if listener.usage != "" {
 			errFmt = append(errFmt, "", "Usage:", listener.usage)
 		}
-		return nil, errors.New(strings.Join(errFmt, "\n"))
+		return nil, fmt.Errorf("invalid command: %v", strings.Join(errFmt, "\n"))
+	}
+	if listener.cmd.Cmd() == "help" {
+		return nil, errors.New(strings.Join([]string{
+			compileUsage,
+			declareUsage,
+			deleteUsage,
+			letUsage,
+			optionUsage,
+			helpUsage,
+			exitUsage,
+		}, "\n\n"))
 	}
-
 	return listener.cmd, nil
 }
 
@@ -183,6 +218,10 @@ func (c *commandParseListener) EnterSimple(ctx *parser.SimpleContext) {
 	c.cmd = &simpleCmd{cmd: cmd, args: args}
 }
 
+func (c *commandParseListener) EnterHelp(ctx *parser.HelpContext) {
+	c.cmd = &simpleCmd{cmd: "help"}
+}
+
 func (c *commandParseListener) EnterEmpty(ctx *parser.EmptyContext) {
 	c.cmd = &simpleCmd{cmd: "null"}
 }
@@ -231,6 +270,10 @@ func (c *commandParseListener) EnterDelete(ctx *parser.DeleteContext) {
 	c.cmd = &delCmd{}
 }
 
+func (c *commandParseListener) EnterCompile(ctx *parser.CompileContext) {
+	c.cmd = &compileCmd{}
+}
+
 func (c *commandParseListener) EnterExprCmd(ctx *parser.ExprCmdContext) {
 	c.cmd = &evalCmd{}
 }
@@ -314,6 +357,8 @@ func (c *commandParseListener) ExitVarDecl(ctx *parser.VarDeclContext) {
 func (c *commandParseListener) ExitExpr(ctx *parser.ExprContext) {
 	expr := extractSourceText(ctx)
 	switch cmd := c.cmd.(type) {
+	case *compileCmd:
+		cmd.expr = expr
 	case *evalCmd:
 		cmd.expr = expr
 	case *letFnCmd:

repl/commands_test.go

@@ -15,6 +15,7 @@
 package repl
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 	"testing"
@@ -33,6 +34,9 @@ func cmdMatches(t testing.TB, got Cmder, expected Cmder) (result bool) {
 	}()
 
 	switch want := expected.(type) {
+	case *compileCmd:
+		gotCompile := got.(*compileCmd)
+		return gotCompile.expr == want.expr
 	case *evalCmd:
 		gotEval := got.(*evalCmd)
 		return gotEval.expr == want.expr
@@ -111,6 +115,7 @@ func TestParse(t *testing.T) {
 	var testCases = []struct {
 		commandLine string
 		wantCmd     Cmder
+		wantErr     error
 	}{
 		{
 			commandLine: "%let x = 1",
@@ -136,6 +141,10 @@ func TestParse(t *testing.T) {
 				src:        "1",
 			},
 		},
+		{
+			commandLine: `%compile x + 2`,
+			wantCmd:     &compileCmd{expr: "x + 2"},
+		},
 		{
 			commandLine: `%eval x + 2`,
 			wantCmd:     &evalCmd{expr: "x + 2"},
@@ -148,6 +157,34 @@ func TestParse(t *testing.T) {
 			commandLine: `%exit`,
 			wantCmd:     &simpleCmd{cmd: "exit"},
 		},
+		{
+			commandLine: `%help`,
+			wantErr: errors.New(`Compile emits a textproto representation of the compiled expression.
+            %compile <expr>
+
+            Declare introduces a variable or function for type checking, but
+            doesn't define a value for it:
+            %declare <identifier> : <type>
+            %declare <identifier> (<param_identifier> : <param_type>, ...) : <result-type>
+
+            Delete removes a variable or function declaration from the evaluation context.
+            %delete <identifier>
+
+            Let introduces a variable or function defined by a sub-CEL expression.
+            %let <identifier> (: <type>)? = <expr>
+            %let <identifier> (<param_identifier> : <param_type>, ...) : <result-type> -> <expr>
+
+            Option enables a CEL environment option which enables configuration and
+            optional language features.
+            %option --container 'google.protobuf'
+            %option --extension 'all'
+
+            Help prints usage information for the commands supported by the REPL.
+            %help
+
+            Exit terminates the REPL.
+            %exit`),
+		},
 		{
 			commandLine: `%arbitrary --flag -FLAG 'string literal\n'`,
 			wantCmd: &simpleCmd{cmd: "arbitrary",
@@ -237,6 +274,9 @@ func TestParse(t *testing.T) {
 		t.Run(tc.commandLine, func(t *testing.T) {
 			cmd, err := Parse(tc.commandLine)
 			if err != nil {
+				if tc.wantErr != nil && stripWhitespace(tc.wantErr.Error()) == stripWhitespace(err.Error()) {
+					return
+				}
 				t.Errorf("Parse(\"%s\") failed: %s", tc.commandLine, err)
 			}
 			if cmd == nil || !cmdMatches(t, cmd, tc.wantCmd) {

repl/evaluator.go

@@ -431,7 +431,7 @@ type Evaluator struct {
 
 // NewEvaluator returns an inialized evaluator
 func NewEvaluator() (*Evaluator, error) {
-	env, err := cel.NewEnv()
+	env, err := cel.NewEnv(cel.EnableMacroCallTracking())
 	if err != nil {
 		return nil, err
 	}
@@ -847,8 +847,19 @@ func (e *Evaluator) loadDescriptors(args []string) error {
 	return e.AddOption(&typeOption{path: p, fds: fds})
 }
 
+// Process processes the command provided.
 func (e *Evaluator) Process(cmd Cmder) (string, bool, error) {
 	switch cmd := cmd.(type) {
+	case *compileCmd:
+		ast, err := e.Compile(cmd.expr)
+		if err != nil {
+			return "", false, fmt.Errorf("compile failed:\n%v", err)
+		}
+		cAST, err := cel.AstToCheckedExpr(ast)
+		if err != nil {
+			return "", false, fmt.Errorf("compile failed:\n%v", err)
+		}
+		return prototext.Format(cAST), false, nil
 	case *evalCmd:
 		val, resultT, err := e.Evaluate(cmd.expr)
 		if err != nil {
@@ -916,15 +927,15 @@ func (e *Evaluator) Process(cmd Cmder) (string, bool, error) {
 	return "", false, nil
 }
 
-// Evaluate sets up a CEL evaluation using the current evaluation context.
+// Evaluate sets up a CEL evaluation using the current REPL context.
 func (e *Evaluator) Evaluate(expr string) (ref.Val, *exprpb.Type, error) {
 	env, act, err := e.applyContext()
 	if err != nil {
 		return nil, nil, err
 	}
 
 	ast, iss := env.Compile(expr)
-	if iss != nil {
+	if iss.Err() != nil {
 		return nil, nil, iss.Err()
 	}
 
@@ -937,3 +948,16 @@ func (e *Evaluator) Evaluate(expr string) (ref.Val, *exprpb.Type, error) {
 	// expression can be well-formed and result in an error
 	return val, ast.ResultType(), err
 }
+
+// Compile compiles the input expression using the current REPL context.
+func (e *Evaluator) Compile(expr string) (*cel.Ast, error) {
+	env, _, err := e.applyContext()
+	if err != nil {
+		return nil, err
+	}
+	ast, iss := env.Compile(expr)
+	if iss.Err() != nil {
+		return nil, iss.Err()
+	}
+	return ast, nil
+}