Class Expression

Namespace

NCalc

Assembly

NCalc.Core.dll

A reusable parsed expression and its immutable parsing and evaluation options. Runtime parameters, functions, and handlers are supplied through ExpressionContext.

public class Expression

Inheritance

object

Expression

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

Expression(ExpressionConfiguration, ExpressionContext, CultureInfo, IEvaluationVisitorFactory?)

protected Expression(ExpressionConfiguration configuration, ExpressionContext context, CultureInfo cultureInfo, IEvaluationVisitorFactory? evaluationVisitorFactory = null)

Parameters

configuration ExpressionConfiguration

context ExpressionContext

cultureInfo CultureInfo

evaluationVisitorFactory IEvaluationVisitorFactory

Expression(LogicalExpression, ExpressionConfiguration?, ExpressionContext?, CultureInfo?, IEvaluationVisitorFactory?)

public Expression(LogicalExpression logicalExpression, ExpressionConfiguration? configuration = null, ExpressionContext? context = null, CultureInfo? cultureInfo = null, IEvaluationVisitorFactory? evaluationVisitorFactory = null)

Parameters

logicalExpression LogicalExpression

configuration ExpressionConfiguration

context ExpressionContext

cultureInfo CultureInfo

evaluationVisitorFactory IEvaluationVisitorFactory

Expression(LogicalExpression, ExpressionConfiguration, ExpressionContext, CultureInfo, ILogicalExpressionFactory, ILogicalExpressionCache, IEvaluationVisitorFactory?)

protected Expression(LogicalExpression logicalExpression, ExpressionConfiguration configuration, ExpressionContext expressionContext, CultureInfo cultureInfo, ILogicalExpressionFactory logicalExpressionFactory, ILogicalExpressionCache logicalExpressionCache, IEvaluationVisitorFactory? evaluationVisitorFactory = null)

Parameters

logicalExpression LogicalExpression

configuration ExpressionConfiguration

expressionContext ExpressionContext

cultureInfo CultureInfo

logicalExpressionFactory ILogicalExpressionFactory

logicalExpressionCache ILogicalExpressionCache

evaluationVisitorFactory IEvaluationVisitorFactory

Expression(string?, ExpressionConfiguration?, ExpressionContext?, CultureInfo?, IEvaluationVisitorFactory?)

public Expression(string? expression, ExpressionConfiguration? configuration = null, ExpressionContext? context = null, CultureInfo? cultureInfo = null, IEvaluationVisitorFactory? evaluationVisitorFactory = null)

Parameters

expression string

configuration ExpressionConfiguration

context ExpressionContext

cultureInfo CultureInfo

evaluationVisitorFactory IEvaluationVisitorFactory

Expression(string, ExpressionConfiguration, ExpressionContext, CultureInfo, ILogicalExpressionFactory, ILogicalExpressionCache, IEvaluationVisitorFactory?)

protected Expression(string expressionString, ExpressionConfiguration configuration, ExpressionContext expressionContext, CultureInfo cultureInfo, ILogicalExpressionFactory logicalExpressionFactory, ILogicalExpressionCache logicalExpressionCache, IEvaluationVisitorFactory? evaluationVisitorFactory = null)

Parameters

expressionString string

configuration ExpressionConfiguration

expressionContext ExpressionContext

cultureInfo CultureInfo

logicalExpressionFactory ILogicalExpressionFactory

logicalExpressionCache ILogicalExpressionCache

evaluationVisitorFactory IEvaluationVisitorFactory

Expression(string?, ExpressionContext)

public Expression(string? expression, ExpressionContext context)

Parameters

expression string

context ExpressionContext

Expression(string?, CultureInfo)

public Expression(string? expression, CultureInfo cultureInfo)

Parameters

expression string

cultureInfo CultureInfo

Properties

AsyncFunctions

Async custom functions for the expression evaluation.

public IDictionary<string, AsyncExpressionFunction> AsyncFunctions { get; }

Property Value

IDictionary<string, AsyncExpressionFunction>

AsyncParameters

Async dynamic parameters for the expression evaluation.

public IDictionary<string, AsyncExpressionParameter> AsyncParameters { get; }

Property Value

IDictionary<string, AsyncExpressionParameter>

Configuration

Gets or sets parsing, evaluation, and caching configuration.

public ExpressionConfiguration Configuration { get; set; }

Property Value

ExpressionConfiguration

Context

Runtime context that stores parameters, functions, and handlers.

public ExpressionContext Context { get; set; }

Property Value

ExpressionContext

CultureInfo

Culture information for parsing and evaluation.

public CultureInfo CultureInfo { get; set; }

Property Value

CultureInfo

DynamicParameters

Dynamic parameters for the expression evaluation.

public IDictionary<string, ExpressionParameter> DynamicParameters { get; }

Property Value

IDictionary<string, ExpressionParameter>

Error

Gets the last parsing error, if any.

public Exception? Error { get; }

Property Value

Exception

EvaluationOptions

Gets the evaluation options from Configuration.

public ExpressionEvaluationOptions EvaluationOptions { get; }

Property Value

ExpressionEvaluationOptions

EvaluationVisitorFactory

Factory used to create evaluation visitors.

protected IEvaluationVisitorFactory? EvaluationVisitorFactory { get; }

Property Value

IEvaluationVisitorFactory

ExpressionString

Textual representation of the expression.

public string? ExpressionString { get; protected init; }

Property Value

string

Functions

Custom functions for the expression evaluation.

public IDictionary<string, ExpressionFunction> Functions { get; }

Property Value

IDictionary<string, ExpressionFunction>

LogicalExpression

Parsed logical expression tree.

public LogicalExpression? LogicalExpression { get; set; }

Property Value

LogicalExpression

Options

Replaces Configuration with a configuration converted from ExpressionOptions flags.

public ExpressionOptions Options { set; }

Property Value

ExpressionOptions

Remarks

Prefer setting Configuration directly.

Parameters

Static parameters for the expression evaluation.

public IDictionary<string, object?> Parameters { get; }

Property Value

IDictionary<string, object>

ParserOptions

Gets the parser options from Configuration.

public LogicalExpressionParserOptions ParserOptions { get; }

Property Value

LogicalExpressionParserOptions

Methods

CreateAsyncEvaluationVisitor(ExpressionContext, CancellationToken)

protected virtual AsyncEvaluationVisitor CreateAsyncEvaluationVisitor(ExpressionContext context, CancellationToken cancellationToken = default)

Parameters

context ExpressionContext

cancellationToken CancellationToken

Returns

AsyncEvaluationVisitor

CreateEvaluationVisitor(ExpressionContext, CancellationToken)

protected virtual EvaluationVisitor CreateEvaluationVisitor(ExpressionContext context, CancellationToken cancellationToken = default)

Parameters

context ExpressionContext

cancellationToken CancellationToken

Returns

EvaluationVisitor

Evaluate(CancellationToken)

Evaluates the logical expression.

public object? Evaluate(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

object

Exceptions

NCalcException

Thrown when there is an error in the expression.

EvaluateAsync(CancellationToken)

Asynchronously evaluates the logical expression.

public ValueTask<object?> EvaluateAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<object>

The result of the evaluation.

Exceptions

NCalcException

Thrown when there is an error in the expression.

EvaluateAsync<T>(CancellationToken)

Asynchronously evaluates the logical expression and converts the result to type T.

public ValueTask<T?> EvaluateAsync<T>(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask<T>

The evaluation result converted to type T, or default if the result is null.

Type Parameters

T

The type to which the evaluation result should be converted.

Exceptions

NCalcCastException

Thrown when the result cannot be cast to type T.

NCalcException

Thrown when there is an error in the expression.

Evaluate<T>(CancellationToken)

Evaluates the logical expression and converts the result to type T.

public T? Evaluate<T>(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

T

The evaluation result converted to type T, or default if the result is null.

Type Parameters

T

The type to which the evaluation result should be converted.

Exceptions

NCalcCastException

Thrown when the result cannot be cast to type T.

NCalcException

Thrown when there is an error in the expression.

GetFunctionNames(CancellationToken)

Returns all function names from the expression.

public List<string> GetFunctionNames(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

List<string>

Function names used by the expression.

GetLogicalExpression(CancellationToken)

Gets the parsed logical expression, using the cache when enabled.

public LogicalExpression? GetLogicalExpression(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

LogicalExpression

The parsed logical expression, or null when parsing fails.

GetParameterNames(CancellationToken)

Returns all parameter names from the expression.

public List<string> GetParameterNames(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

List<string>

Parameter names used by the expression.

HasErrors(CancellationToken)

Creates the logical expression to check for syntax errors.

[MemberNotNullWhen(true, "Error")]
public bool HasErrors(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

bool

true if errors were detected; otherwise, false.

ToExpressionString(bool, CancellationToken)

Returns the normalized expression string.

public string ToExpressionString(bool evaluateParameters = false, CancellationToken cancellationToken = default)

Parameters

evaluateParameters bool

Whether parameter values should be substituted.

cancellationToken CancellationToken

Returns

string

The expression string.

Events

EvaluateAsyncFunction

Event triggered to handle async function evaluation.

public event EvaluateAsyncFunctionHandler EvaluateAsyncFunction

Event Type

EvaluateAsyncFunctionHandler

EvaluateAsyncParameter

Event triggered to handle async parameter evaluation.

public event EvaluateAsyncParameterHandler EvaluateAsyncParameter

Event Type

EvaluateAsyncParameterHandler

EvaluateBinary

Event triggered to handle binary evaluation.

public event EvaluateBinaryHandler EvaluateBinary

Event Type

EvaluateBinaryHandler

EvaluateBinaryAsync

Event triggered to handle async binary evaluation.

public event EvaluateBinaryAsyncHandler EvaluateBinaryAsync

Event Type

EvaluateBinaryAsyncHandler

EvaluateFunction

Event triggered to handle function evaluation.

public event EvaluateFunctionHandler EvaluateFunction

Event Type

EvaluateFunctionHandler

EvaluateParameter

Event triggered to handle parameter evaluation.

public event EvaluateParameterHandler EvaluateParameter

Event Type

EvaluateParameterHandler