Refresh API documentation and guides

Update Javadocs and public documentation to describe the current APIs, evaluation behavior, and supported integrations.

Author: snazy

README.md

@@ -25,8 +25,21 @@
 import org.projectnessie.cel.common.Source;
 
 /**
- * Ast representing the checked or unchecked expression, its source, and related metadata such as
- * source position information.
+ * A parsed or type-checked CEL abstract syntax tree and its source metadata.
+ *
+ * <p>An AST returned by {@link Env#parse(String)} is unchecked. Passing it to {@link
+ * Env#check(Ast)} produces a checked AST with reference and type metadata. Prefer a checked AST
+ * when creating a {@link Program}; unchecked ASTs are supported but provide less planning
+ * information.
+ *
+ * <p>The expression and source-info values are immutable Protobuf messages. The constructors retain
+ * the supplied {@link Source} and, for the full constructor, the supplied reference and type maps.
+ * Callers that construct an AST directly must keep retained mutable state stable while the AST is
+ * in use.
+ *
+ * <p>{@link CEL#astToParsedExpr(Ast)} and {@link CEL#astToCheckedExpr(Ast)} expose the
+ * corresponding Protobuf representations. Exporting those messages does not by itself guarantee
+ * that another CEL runtime recognizes implementation-specific macro expansions.
  */
 public final class Ast {
   private final Expr expr;
@@ -35,10 +48,28 @@ public final class Ast {
   final Map<Long, Reference> refMap;
   final Map<Long, Type> typeMap;
 
+  /**
+   * Creates an unchecked AST.
+   *
+   * @param expr parsed CEL expression
+   * @param info source and position metadata
+   * @param source source used to parse the expression
+   */
   public Ast(Expr expr, SourceInfo info, Source source) {
     this(expr, info, source, new HashMap<>(), new HashMap<>());
   }
 
+  /**
+   * Creates an AST with explicit reference and type metadata.
+   *
+   * <p>The maps are retained rather than copied. A non-empty type map marks the AST as checked.
+   *
+   * @param expr parsed or checked CEL expression
+   * @param info source and position metadata
+   * @param source source used to parse or check the expression
+   * @param refMap checked reference metadata keyed by expression ID
+   * @param typeMap checked type metadata keyed by expression ID
+   */
   public Ast(
       Expr expr,
       SourceInfo info,
@@ -52,30 +83,46 @@ public Ast(
     this.typeMap = typeMap;
   }
 
-  /** Expr returns the proto serializable instance of the parsed/checked expression. */
+  /**
+   * Returns the parsed or checked expression Protobuf message.
+   *
+   * @return expression tree
+   */
   public Expr getExpr() {
     return expr;
   }
 
-  /** IsChecked returns whether the Ast value has been successfully type-checked. */
+  /**
+   * Reports whether this AST contains checked type metadata.
+   *
+   * @return {@code true} when the type map is non-null and non-empty
+   */
   public boolean isChecked() {
     return typeMap != null && !typeMap.isEmpty();
   }
 
+  /**
+   * Returns the source associated with this AST.
+   *
+   * @return retained source
+   */
   public Source getSource() {
     return source;
   }
 
   /**
-   * SourceInfo returns character offset and newling position information about expression elements.
+   * Returns source-location and macro-expansion metadata for expression elements.
+   *
+   * @return source information
    */
   public SourceInfo getSourceInfo() {
     return info;
   }
 
   /**
-   * ResultType returns the output type of the expression if the Ast has been type-checked, else
-   * returns decls.Dyn as the parse step cannot infer the type.
+   * Returns the checked result type of this expression.
+   *
+   * @return the root expression's checked type, or {@link Decls#Dyn} for an unchecked AST
    */
   public Type getResultType() {
     if (!isChecked()) {
@@ -85,8 +132,12 @@ public Type getResultType() {
   }
 
   /**
-   * Source returns a view of the input used to create the Ast. This source may be complete or
-   * constructed from the SourceInfo.
+   * Returns the source text associated with this AST.
+   *
+   * <p>This is the retained source's content, not a newly unparsed representation of the
+   * expression. Use {@link CEL#astToString(Ast)} to obtain a stable unparsed expression.
+   *
+   * @return source content
    */
   @Override
   public String toString() {

core/src/main/java/org/projectnessie/cel/Ast.java

@@ -48,13 +48,34 @@
 import org.projectnessie.cel.interpreter.InterpretableDecorator;
 import org.projectnessie.cel.interpreter.Interpreter;
 
+/**
+ * Low-level factories and conversion utilities for CEL environments, programs, activations, and
+ * ASTs.
+ *
+ * <p>Most applications begin with {@link Env#newEnv(EnvOption...)} and follow the
+ * parse/check/program/evaluate lifecycle. This class supports integrations that need explicit
+ * Protobuf AST conversion, partial activations, attribute patterns, or cost estimates.
+ */
 public final class CEL {
 
   /**
-   * newProgram creates a program instance with an environment, an ast, and an optional list of
-   * ProgramOption values.
+   * Creates an executable program for an AST in an environment.
+   *
+   * <p>Options are applied in argument order. A checked AST provides type and reference metadata
+   * used during planning; an unchecked AST is accepted but may require more runtime dispatch. The
+   * resulting program can be reused for multiple evaluations.
+   *
+   * <p>Native evaluation, when permitted by the selected options, is planner-selected evaluation
+   * over supported Java-native representations. Unsupported shapes fall back to the established
+   * evaluator; this does not generate Java or native machine code.
    *
-   * <p>If the program cannot be configured the prog will be nil, with a non-nil error response.
+   * @param e environment supplying types and name resolution
+   * @param ast parsed or checked expression
+   * @param opts program configuration tokens, normally created by {@link ProgramOption} factories
+   * @return reusable executable program
+   * @throws NullPointerException if {@code e}, {@code ast}, or {@code opts} is {@code null}, or if
+   *     an option is {@code null} or returns {@code null}
+   * @throws RuntimeException if program planning or option application fails
    */
   public static Program newProgram(Env e, Ast ast, ProgramOption... opts) {
     // Build the dispatcher, interpreter, and default program value.
@@ -174,7 +195,16 @@ static boolean nativePlanningPermitted(
             || evalOptions.size() == 1 && evalOptions.contains(EvalOption.OptOptimize));
   }
 
-  /** CheckedExprToAst converts a checked expression proto message to an Ast. */
+  /**
+   * Converts a checked-expression Protobuf message to an AST.
+   *
+   * <p>The returned source is reconstructed from the message's {@link SourceInfo}; it need not
+   * contain the original source text.
+   *
+   * @param checkedExpr checked expression message
+   * @return an AST that is considered checked when the message contains non-empty type metadata
+   * @throws NullPointerException if {@code checkedExpr} is {@code null}
+   */
   public static Ast checkedExprToAst(CheckedExpr checkedExpr) {
     Map<Long, Reference> refMap = checkedExpr.getReferenceMapMap();
     Map<Long, Type> typeMap = checkedExpr.getTypeMapMap();
@@ -187,9 +217,16 @@ public static Ast checkedExprToAst(CheckedExpr checkedExpr) {
   }
 
   /**
-   * AstToCheckedExpr converts an Ast to an protobuf CheckedExpr value.
+   * Converts a checked AST to a checked-expression Protobuf message.
+   *
+   * <p>The conversion preserves CEL-Java's current expression, reference, type, and source-info
+   * shape. It does not establish cross-runtime support for implementation-specific macro
+   * expansions.
    *
-   * <p>If the Ast.IsChecked() returns false, this conversion method will return an error.
+   * @param a checked AST
+   * @return checked-expression message
+   * @throws NullPointerException if {@code a} is {@code null}
+   * @throws IllegalArgumentException if {@code a} is unchecked
    */
   public static CheckedExpr astToCheckedExpr(Ast a) {
     if (!a.isChecked()) {
@@ -203,68 +240,107 @@ public static CheckedExpr astToCheckedExpr(Ast a) {
         .build();
   }
 
-  /** ParsedExprToAst converts a parsed expression proto message to an Ast. */
+  /**
+   * Converts a parsed-expression Protobuf message to an unchecked AST.
+   *
+   * <p>The returned source is reconstructed from the message's {@link SourceInfo}; it need not
+   * contain the original source text.
+   *
+   * @param parsedExpr parsed expression message
+   * @return unchecked AST
+   * @throws NullPointerException if {@code parsedExpr} is {@code null}
+   */
   public static Ast parsedExprToAst(ParsedExpr parsedExpr) {
     SourceInfo si = parsedExpr.getSourceInfo();
     return new Ast(parsedExpr.getExpr(), si, newInfoSource(si));
   }
 
-  /** AstToParsedExpr converts an Ast to an protobuf ParsedExpr value. */
+  /**
+   * Converts an AST to a parsed-expression Protobuf message.
+   *
+   * <p>Checked reference and type maps are not part of {@link ParsedExpr} and are therefore not
+   * included.
+   *
+   * @param a parsed or checked AST
+   * @return parsed-expression message
+   * @throws NullPointerException if {@code a} is {@code null}
+   */
   public static ParsedExpr astToParsedExpr(Ast a) {
     return ParsedExpr.newBuilder().setExpr(a.getExpr()).setSourceInfo(a.getSourceInfo()).build();
   }
 
   /**
-   * AstToString converts an Ast back to a string if possible.
+   * Unparses an AST to stable CEL source text.
    *
    * <p>Note, the conversion may not be an exact replica of the original expression, but will
    * produce a string that is semantically equivalent and whose textual representation is stable.
+   *
+   * @param a AST to unparse
+   * @return stable CEL expression text
+   * @throws NullPointerException if {@code a} is {@code null}
    */
   public static String astToString(Ast a) {
     Expr expr = a.getExpr();
     SourceInfo info = a.getSourceInfo();
     return unparse(expr, info);
   }
 
-  /** NoVars returns an empty Activation. */
+  /**
+   * Returns an activation with no variable bindings.
+   *
+   * @return empty activation
+   */
   public static Activation noVars() {
     return emptyActivation();
   }
 
   /**
-   * PartialVars returns a PartialActivation which contains variables and a set of AttributePattern
-   * values that indicate variables or parts of variables whose value are not yet known.
+   * Creates a partial activation containing bindings and attributes whose values are unknown.
+   *
+   * <p>{@code vars} may be an {@link Activation}, a Java map, a {@link
+   * java.util.function.Function}, or an {@link
+   * org.projectnessie.cel.interpreter.ActivationFunction}. The returned activation copies the
+   * unknown-pattern array but retains its mutable pattern elements.
    *
-   * <p>The `vars` value may either be an interpreter.Activation or any valid input to the
-   * interpreter.NewActivation call.
+   * @param vars bindings accepted by {@link Activation#newActivation(Object)}
+   * @param unknowns attribute patterns that evaluate as unknown
+   * @return partial activation
+   * @throws NullPointerException if {@code vars} or {@code unknowns} is {@code null}
+   * @throws IllegalArgumentException if {@code vars} is not a supported activation input
    */
   public static PartialActivation partialVars(Object vars, AttributePattern... unknowns) {
     return newPartialActivation(vars, unknowns);
   }
 
   /**
-   * AttributePattern returns an AttributePattern that matches a top-level variable. The pattern is
-   * mutable, and its methods support the specification of one or more qualifier patterns.
+   * Creates a mutable attribute pattern matching a top-level variable.
    *
-   * <p>For example, the AttributePattern(`a`).QualString(`b`) represents a variable access `a` with
-   * a string field or index qualification `b`. This pattern will match Attributes `a`, and `a.b`,
-   * but not `a.c`.
+   * <p>For example, {@code attributePattern("a").qualString("b")} represents the access {@code
+   * a.b}. It matches attributes {@code a} and {@code a.b}, but not {@code a.c}.
    *
    * <p>When using a CEL expression within a container, e.g. a package or namespace, the variable
    * name in the pattern must match the qualified name produced during the variable namespace
-   * resolution. For example, when variable `a` is declared within an expression whose container is
-   * `ns.app`, the fully qualified variable name may be `ns.app.a`, `ns.a`, or `a` per the CEL
-   * namespace resolution rules. Pick the fully qualified variable name that makes sense within the
-   * container as the AttributePattern `varName` argument.
+   * resolution. For example, when variable {@code a} is declared within an expression whose
+   * container is {@code ns.app}, the fully qualified variable name may be {@code ns.app.a}, {@code
+   * ns.a}, or {@code a} per the CEL namespace resolution rules. Use the qualified name selected by
+   * resolution as {@code varName}.
    *
-   * <p>See the interpreter.AttributePattern and interpreter.AttributeQualifierPattern for more info
-   * about how to create and manipulate AttributePattern values.
+   * @param varName top-level or resolved qualified variable name
+   * @return mutable attribute pattern
    */
   public static AttributePattern attributePattern(String varName) {
     return newAttributePattern(varName);
   }
 
-  /** EstimateCost returns the heuristic cost interval for the program. */
+  /**
+   * Returns the heuristic cost interval reported by an object that implements {@link Coster}.
+   *
+   * <p>A cost estimate is descriptive only; it does not impose an evaluation budget or runtime
+   * limit.
+   *
+   * @param p program or other cost-reporting object
+   * @return reported cost interval, or {@link Cost#Unknown} when {@code p} is not a {@code Coster}
+   */
   public static Cost estimateCost(Object p) {
     if (p instanceof Coster) {
       return ((Coster) p).cost();