Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 30 additions & 4 deletions core/src/main/java/org/projectnessie/cel/CEL.java
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;
import org.projectnessie.cel.interpreter.Activation;
import org.projectnessie.cel.interpreter.Activation.PartialActivation;
import org.projectnessie.cel.interpreter.AttributePattern;
Expand All @@ -50,10 +51,23 @@
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>If the program cannot be configured the prog will be nil, with a non-nil error response.
* <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.
*
* @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.
Expand Down Expand Up @@ -86,7 +100,12 @@ public static Program newProgram(Env e, Ast ast, ProgramOption... opts) {

Interpreter interp =
newInterpreter(
disp, e.getContainer(), e.getTypeProvider(), e.getTypeAdapter(), p.attrFactory);
disp,
e.getContainer(),
e.getTypeProvider(),
e.getTypeAdapter(),
p.attrFactory,
nativePlanningPermitted(p.evalOpts, p.decorators));
p.interpreter = interp;

// Translate the EvalOption flags into InterpretableDecorator instances.
Expand Down Expand Up @@ -158,6 +177,13 @@ private static Program initInterpretable(
return p;
}

static boolean nativePlanningPermitted(
Set<EvalOption> evalOptions, List<InterpretableDecorator> decorators) {
return decorators.isEmpty()
&& (evalOptions.isEmpty()
|| evalOptions.size() == 1 && evalOptions.contains(EvalOption.OptOptimize));
}

/** CheckedExprToAst converts a checked expression proto message to an Ast. */
public static Ast checkedExprToAst(CheckedExpr checkedExpr) {
Map<Long, Reference> refMap = checkedExpr.getReferenceMapMap();
Expand Down
40 changes: 29 additions & 11 deletions core/src/main/java/org/projectnessie/cel/EvalOption.java
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,12 @@
package org.projectnessie.cel;

/**
* EvalOption indicates an evaluation option that may affect the evaluation behavior or information
* in the output result.
* Built-in evaluation modes selected through {@link ProgramOption#evalOptions(EvalOption...)}.
*
* <p>Options are additive. Every built-in option except {@link #OptOptimize} selects the
* established interpreter planning path; custom decorators do so as well. With no such option, the
* planner may select native evaluation for eligible checked expression shapes and falls back to the
* established evaluator elsewhere.
*/
public enum EvalOption {

Expand All @@ -28,21 +32,35 @@ public enum EvalOption {
OptExhaustiveEval(2 | OptTrackState.mask),

/**
* OptOptimize precomputes functions and operators with constants as arguments at program creation
* time. This flag is useful when the expression will be evaluated repeatedly against a series of
* different inputs.
* Enables program-creation-time optimization of functions and operators whose arguments are
* constant.
*
* <p>This is useful for programs evaluated repeatedly. It does not guarantee that a particular
* expression is folded, and it is independent of whether eligible nodes use native evaluation.
*/
OptOptimize(4),

/**
* OptPartialEval enables the evaluation of a partial state where the input data that may be known
* to be missing, either as top-level variables, or somewhere within a variable's object member
* graph.
* Enables partial evaluation for variables or qualified attributes whose values are marked
* unknown.
*
* <p>By itself this does not change a result. Supply a {@link
* org.projectnessie.cel.interpreter.Activation.PartialActivation}, for example from {@link
* CEL#partialVars(Object, org.projectnessie.cel.interpreter.AttributePattern...)}, to mark
* unknown input. Combine with {@link #OptTrackState} when creating a residual AST through {@link
* Env#residualAst(Ast, EvalDetails)}. Partial evaluation selects established interpreter
* planning.
*/
OptPartialEval(8),

/**
* Forces checked expressions to use established interpreter planning.
*
* <p>By itself, OptPartialEval does not change evaluation behavior unless the input to the
* Program Eval is an PartialVars.
* <p>Without this option, the planner may evaluate eligible expression nodes directly over
* supported Java-native representations and falls back when a shape is not eligible. Native
* evaluation does not mean generated Java, bytecode, JNI, or machine code.
*/
OptPartialEval(8);
OptDisableNativeEval(16);

private final int mask;

Expand Down
9 changes: 7 additions & 2 deletions core/src/main/java/org/projectnessie/cel/Library.java
Original file line number Diff line number Diff line change
Expand Up @@ -17,12 +17,12 @@

import static org.projectnessie.cel.EnvOption.declarations;
import static org.projectnessie.cel.EnvOption.macros;
import static org.projectnessie.cel.ProgramOption.functions;
import static org.projectnessie.cel.checker.Checker.StandardDeclarations;
import static org.projectnessie.cel.interpreter.functions.Overload.standardOverloads;
import static org.projectnessie.cel.parser.Macro.AllMacros;

import java.util.List;
import org.projectnessie.cel.interpreter.functions.Overload;

/**
* Library provides a collection of EnvOption and ProgramOption values used to confiugre a CEL
Expand Down Expand Up @@ -83,7 +83,12 @@ public List<EnvOption> getCompileOptions() {
/** ProgramOptions returns function implementations for the standard CEL functions. */
@Override
public List<ProgramOption> getProgramOptions() {
return List.of(functions(standardOverloads()));
Overload[] overloads = standardOverloads();
return List.of(
p -> {
p.dispatcher.add(overloads);
return p;
});
}
}
}
9 changes: 7 additions & 2 deletions core/src/main/java/org/projectnessie/cel/ProgramOption.java
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,14 @@ public interface ProgramOption {
Prog apply(Prog prog);

/**
* CustomDecorator appends an InterpreterDecorator to the program.
* Appends a low-level interpreter-plan decorator.
*
* <p>InterpretableDecorators can be used to inspect, alter, or replace the Program plan.
* <p>Decorators can inspect, alter, or replace the established interpreter plan. Custom
* decorators are applied in insertion order; built-in optimization and state decorators may have
* fixed later placement. Supplying a custom decorator disables native planning for the program.
*
* @param dec decorator to append
* @return program configuration token
*/
static ProgramOption customDecorator(InterpretableDecorator dec) {
return p -> {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,14 @@
import org.projectnessie.cel.common.ULong;
import org.projectnessie.cel.common.types.Err;
import org.projectnessie.cel.common.types.Types;
import org.projectnessie.cel.common.types.ref.StandardScalarTypeAdapter;
import org.projectnessie.cel.common.types.ref.Type;
import org.projectnessie.cel.common.types.ref.TypeAdapter;
import org.projectnessie.cel.common.types.ref.TypeAdapterSupport;
import org.projectnessie.cel.common.types.ref.Val;

/** defaultTypeAdapter converts go native types to CEL values. */
public final class DefaultTypeAdapter implements TypeAdapter {
public final class DefaultTypeAdapter implements StandardScalarTypeAdapter {
/** DefaultTypeAdapter adapts canonical CEL types from their equivalent Go values. */
public static final DefaultTypeAdapter Instance = new DefaultTypeAdapter(Db.defaultDb);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,12 +98,15 @@
import org.projectnessie.cel.common.types.ref.FieldGetter;
import org.projectnessie.cel.common.types.ref.FieldTester;
import org.projectnessie.cel.common.types.ref.FieldType;
import org.projectnessie.cel.common.types.ref.StandardScalarFieldProvider;
import org.projectnessie.cel.common.types.ref.StandardScalarTypeAdapter;
import org.projectnessie.cel.common.types.ref.TypeAdapterSupport;
import org.projectnessie.cel.common.types.ref.TypeRegistry;
import org.projectnessie.cel.common.types.ref.Val;
import org.projectnessie.cel.common.types.traits.Lister;

public final class ProtoTypeRegistry implements TypeRegistry {
public final class ProtoTypeRegistry
implements TypeRegistry, StandardScalarTypeAdapter, StandardScalarFieldProvider {
private static final ProtoTypeRegistry DEFAULT_REGISTRY = newDefaultRegistry();

private final Map<String, org.projectnessie.cel.common.types.ref.Type> revTypeMap;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
/*
* Copyright (C) 2021 The Authors of CEL-Java
*
* 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
*
* http://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.
*/
package org.projectnessie.cel.common.types.ref;

/**
* Type provider whose scalar field accessors return canonical Java scalar representations.
*
* <p>For fields described as CEL boolean, signed integer, double, string, or null, the associated
* {@link FieldType#getFrom} accessor returns the corresponding Java scalar, Java {@code null}, or
* an existing terminal {@link Val}. Access must not depend on mutable evaluation context.
*
* <p>This semantic marker permits evaluators to consume supported scalar fields before adapting a
* final result. Implementations should only declare it when those guarantees apply to every
* instance.
*/
public interface StandardScalarFieldProvider extends TypeProvider {}
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/*
* Copyright (C) 2021 The Authors of CEL-Java
*
* 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
*
* http://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.
*/
package org.projectnessie.cel.common.types.ref;

/**
* Type adapter whose Java scalar conversions have the standard CEL semantics.
*
* <p>Implementations preserve existing {@link Val} values and convert Java {@code null}, boolean,
* signed integral, floating-point, and string values exactly as {@link TypeAdapterSupport}. The
* primitive overloads must agree with {@link #nativeToValue(Object)}, and these conversions must
* not depend on mutable evaluation context.
*
* <p>This semantic marker permits evaluators to carry the corresponding Java scalars internally
* before adapting the final result. Implementations should only declare it when those guarantees
* apply to every instance.
*/
public interface StandardScalarTypeAdapter extends TypeAdapter {}
Loading
Loading