Add ParserBuilderInterface and ParserInterface classes. Add factory for stateful parser object.

PiperOrigin-RevId: 693047557

Author: jnthntatum

parser/BUILD

@@ -32,7 +32,9 @@ cc_library(
         ":macro_expr_factory",
         ":macro_registry",
         ":options",
+        ":parser_interface",
         ":source_factory",
+        "//base/ast_internal:ast_impl",
         "//base/ast_internal:expr",
         "//common:ast",
         "//common:constant",
@@ -51,6 +53,7 @@ cc_library(
         "@com_google_absl//absl/container:btree",
         "@com_google_absl//absl/container:flat_hash_map",
         "@com_google_absl//absl/functional:overload",
+        "@com_google_absl//absl/log:absl_check",
         "@com_google_absl//absl/memory",
         "@com_google_absl//absl/status",
         "@com_google_absl//absl/status:statusor",
@@ -173,12 +176,15 @@ cc_test(
         ":options",
         ":parser",
         ":source_factory",
+        "//base/ast_internal:ast_impl",
         "//common:constant",
         "//common:expr",
+        "//common:source",
         "//internal:benchmark",
         "//internal:testing",
         "//testutil:expr_printer",
         "@com_google_absl//absl/algorithm:container",
+        "@com_google_absl//absl/status",
         "@com_google_absl//absl/status:status_matchers",
         "@com_google_absl//absl/strings",
         "@com_google_absl//absl/strings:str_format",
@@ -199,3 +205,16 @@ cc_library(
         "@com_google_absl//absl/status",
     ],
 )
+
+cc_library(
+    name = "parser_interface",
+    hdrs = ["parser_interface.h"],
+    deps = [
+        ":macro",
+        ":options",
+        "//common:ast",
+        "//common:source",
+        "@com_google_absl//absl/status",
+        "@com_google_absl//absl/status:statusor",
+    ],
+)

parser/parser.cc

@@ -36,6 +36,7 @@
 #include "absl/container/btree_map.h"
 #include "absl/container/flat_hash_map.h"
 #include "absl/functional/overload.h"
+#include "absl/log/absl_check.h"
 #include "absl/memory/memory.h"
 #include "absl/status/status.h"
 #include "absl/status/statusor.h"
@@ -50,6 +51,7 @@
 #include "absl/types/span.h"
 #include "absl/types/variant.h"
 #include "antlr4-runtime.h"
+#include "base/ast_internal/ast_impl.h"
 #include "base/ast_internal/expr.h"
 #include "common/ast.h"
 #include "common/constant.h"
@@ -69,6 +71,7 @@
 #include "parser/macro_expr_factory.h"
 #include "parser/macro_registry.h"
 #include "parser/options.h"
+#include "parser/parser_interface.h"
 #include "parser/source_factory.h"
 
 namespace google::api::expr::parser {
@@ -1659,6 +1662,61 @@ absl::StatusOr<ParseResult> ParseImpl(const cel::Source& source,
   }
 }
 
+class ParserImpl : public cel::Parser {
+ public:
+  explicit ParserImpl(const ParserOptions& options,
+                      cel::MacroRegistry macro_registry)
+      : options_(options), macro_registry_(std::move(macro_registry)) {}
+  absl::StatusOr<std::unique_ptr<cel::Ast>> Parse(
+      const cel::Source& source) const override {
+    CEL_ASSIGN_OR_RETURN(auto parse_result,
+                         ParseImpl(source, macro_registry_, options_));
+    return std::make_unique<cel::ast_internal::AstImpl>(
+        std::move(parse_result.expr), std::move(parse_result.source_info));
+  }
+
+ private:
+  const ParserOptions options_;
+  const cel::MacroRegistry macro_registry_;
+};
+
+class ParserBuilderImpl : public cel::ParserBuilder {
+ public:
+  explicit ParserBuilderImpl(const ParserOptions& options)
+      : options_(options) {}
+
+  ParserOptions& GetOptions() override { return options_; }
+
+  absl::Status AddMacro(const cel::Macro& macro) override {
+    for (const auto& existing_macro : macros_) {
+      if (existing_macro.key() == macro.key()) {
+        return absl::AlreadyExistsError(
+            absl::StrCat("macro already exists: ", macro.key()));
+      }
+    }
+    macros_.push_back(macro);
+    return absl::OkStatus();
+  }
+
+  absl::StatusOr<std::unique_ptr<cel::Parser>> Build() && override {
+    cel::MacroRegistry macro_registry;
+
+    if (!options_.disable_standard_macros) {
+      CEL_RETURN_IF_ERROR(macro_registry.RegisterMacros(Macro::AllMacros()));
+    }
+    if (options_.enable_optional_syntax) {
+      CEL_RETURN_IF_ERROR(macro_registry.RegisterMacro(cel::OptMapMacro()));
+      CEL_RETURN_IF_ERROR(macro_registry.RegisterMacro(cel::OptFlatMapMacro()));
+    }
+    CEL_RETURN_IF_ERROR(macro_registry.RegisterMacros(macros_));
+    return std::make_unique<ParserImpl>(options_, std::move(macro_registry));
+  }
+
+ private:
+  ParserOptions options_;
+  std::vector<cel::Macro> macros_;
+};
+
 }  // namespace
 
 absl::StatusOr<ParsedExpr> Parse(absl::string_view expression,
@@ -1719,3 +1777,16 @@ absl::StatusOr<cel::expr::ParsedExpr> Parse(
 }
 
 }  // namespace google::api::expr::parser
+
+namespace cel {
+
+// Creates a new parser builder.
+//
+// Intended for use with the Compiler class, most users should prefer the free
+// functions above for independent parsing of expressions.
+std::unique_ptr<ParserBuilder> NewParserBuilder(const ParserOptions& options) {
+  return std::make_unique<google::api::expr::parser::ParserBuilderImpl>(
+      options);
+}
+
+}  // namespace cel

parser/parser.h

@@ -21,6 +21,7 @@
 #ifndef THIRD_PARTY_CEL_CPP_PARSER_PARSER_H_
 #define THIRD_PARTY_CEL_CPP_PARSER_PARSER_H_
 
+#include <memory>
 #include <utility>
 #include <vector>
 
@@ -31,6 +32,7 @@
 #include "parser/macro.h"
 #include "parser/macro_registry.h"
 #include "parser/options.h"
+#include "parser/parser_interface.h"
 #include "parser/source_factory.h"
 
 namespace google::api::expr::parser {
@@ -88,4 +90,13 @@ absl::StatusOr<cel::expr::ParsedExpr> Parse(
 
 }  // namespace google::api::expr::parser
 
+namespace cel {
+// Creates a new parser builder.
+//
+// Intended for use with the Compiler class, most users should prefer the free
+// functions above for independent parsing of expressions.
+std::unique_ptr<ParserBuilder> NewParserBuilder(
+    const ParserOptions& options = {});
+}  // namespace cel
+
 #endif  // THIRD_PARTY_CEL_CPP_PARSER_PARSER_H_

parser/parser_interface.h

@@ -0,0 +1,60 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+#ifndef THIRD_PARTY_CEL_CPP_PARSER_PARSER_INTERFACE_H_
+#define THIRD_PARTY_CEL_CPP_PARSER_PARSER_INTERFACE_H_
+
+#include <memory>
+
+#include "absl/status/status.h"
+#include "absl/status/statusor.h"
+#include "common/ast.h"
+#include "common/source.h"
+#include "parser/macro.h"
+#include "parser/options.h"
+
+namespace cel {
+
+class Parser;
+
+// Interface for building a CEL parser, see comments on `Parser` below.
+class ParserBuilder {
+ public:
+  virtual ~ParserBuilder() = default;
+
+  // Returns the (mutable) current parser options.
+  virtual ParserOptions& GetOptions() = 0;
+
+  // Adds a macro to the parser.
+  // Standard macros should be automatically added based on parser options.
+  virtual absl::Status AddMacro(const cel::Macro& macro) = 0;
+
+  // Builds a new parser instance, may error if incompatible macros are added.
+  virtual absl::StatusOr<std::unique_ptr<Parser>> Build() && = 0;
+};
+
+// Interface for stateful CEL parser objects for use with a `Compiler`
+// (bundled parse and type check). This is not needed for most users:
+// prefer using the free functions in `parser.h` for more flexibility.
+class Parser {
+ public:
+  virtual ~Parser() = default;
+
+  // Parses the given source into a CEL AST.
+  virtual absl::StatusOr<std::unique_ptr<cel::Ast>> Parse(
+      const cel::Source& source) const = 0;
+};
+
+}  // namespace cel
+
+#endif  // THIRD_PARTY_CEL_CPP_PARSER_PARSER_INTERFACE_H_

parser/parser_test.cc

@@ -22,15 +22,18 @@
 
 #include "cel/expr/syntax.pb.h"
 #include "absl/algorithm/container.h"
+#include "absl/status/status.h"
 #include "absl/status/status_matchers.h"
 #include "absl/strings/ascii.h"
 #include "absl/strings/str_cat.h"
 #include "absl/strings/str_format.h"
 #include "absl/strings/str_join.h"
 #include "absl/strings/string_view.h"
 #include "absl/types/optional.h"
+#include "base/ast_internal/ast_impl.h"
 #include "common/constant.h"
 #include "common/expr.h"
+#include "common/source.h"
 #include "internal/benchmark.h"
 #include "internal/testing.h"
 #include "parser/macro.h"
@@ -43,6 +46,7 @@ namespace google::api::expr::parser {
 namespace {
 
 using ::absl_testing::IsOk;
+using ::absl_testing::StatusIs;
 using ::cel::ConstantKindCase;
 using ::cel::ExprKindCase;
 using ::cel::test::ExprPrinter;
@@ -1536,6 +1540,57 @@ TEST(ExpressionTest, RecursionDepthIgnoresParentheses) {
   EXPECT_THAT(result, IsOk());
 }
 
+TEST(NewParserBuilderTest, Defaults) {
+  auto builder = cel::NewParserBuilder();
+  ASSERT_OK_AND_ASSIGN(auto parser, std::move(*builder).Build());
+
+  ASSERT_OK_AND_ASSIGN(auto source,
+                       cel::NewSource("has(a.b) && [].exists(x, x > 0)"));
+  ASSERT_OK_AND_ASSIGN(auto ast, parser->Parse(*source));
+
+  EXPECT_FALSE(ast->IsChecked());
+}
+
+TEST(NewParserBuilderTest, CustomMacros) {
+  auto builder = cel::NewParserBuilder();
+  builder->GetOptions().disable_standard_macros = true;
+  ASSERT_THAT(builder->AddMacro(cel::HasMacro()), IsOk());
+  ASSERT_OK_AND_ASSIGN(auto parser, std::move(*builder).Build());
+  builder.reset();
+
+  ASSERT_OK_AND_ASSIGN(auto source, cel::NewSource("has(a.b) && [].map(x, x)"));
+  ASSERT_OK_AND_ASSIGN(auto ast, parser->Parse(*source));
+
+  EXPECT_FALSE(ast->IsChecked());
+  KindAndIdAdorner kind_and_id_adorner;
+  ExprPrinter w(kind_and_id_adorner);
+  const auto& ast_impl = cel::ast_internal::AstImpl::CastFromPublicAst(*ast);
+  EXPECT_EQ(w.Print(ast_impl.root_expr()),
+            "_&&_(\n"
+            "  a^#2:Expr.Ident#.b~test-only~^#4:Expr.Select#,\n"
+            "  []^#5:Expr.CreateList#.map(\n"
+            "    x^#7:Expr.Ident#,\n"
+            "    x^#8:Expr.Ident#\n"
+            "  )^#6:Expr.Call#\n"
+            ")^#9:Expr.Call#");
+}
+
+TEST(NewParserBuilderTest, ForwardsOptions) {
+  auto builder = cel::NewParserBuilder();
+  builder->GetOptions().enable_optional_syntax = true;
+  ASSERT_OK_AND_ASSIGN(auto parser, std::move(*builder).Build());
+  ASSERT_OK_AND_ASSIGN(auto source, cel::NewSource("a.?b"));
+  ASSERT_OK_AND_ASSIGN(auto ast, parser->Parse(*source));
+  EXPECT_FALSE(ast->IsChecked());
+
+  builder = cel::NewParserBuilder();
+  builder->GetOptions().enable_optional_syntax = false;
+  ASSERT_OK_AND_ASSIGN(parser, std::move(*builder).Build());
+  ASSERT_OK_AND_ASSIGN(source, cel::NewSource("a.?b"));
+  EXPECT_THAT(parser->Parse(*source),
+              StatusIs(absl::StatusCode::kInvalidArgument));
+}
+
 std::string TestName(const testing::TestParamInfo<TestInfo>& test_info) {
   std::string name = absl::StrCat(test_info.index, "-", test_info.param.I);
   absl::c_replace_if(name, [](char c) { return !absl::ascii_isalnum(c); }, '_');