expression library

The Spring Expression Language (SpEL): small expressions written as strings, parsed once and evaluated against objects at run time.

Applications mostly meet SpEL inside annotations, where the framework parses and evaluates it for them: @Value('#{...}') values, cache keys and conditions (@Cacheable('books', key: '#isbn')), security rules (@PreAuthorize("hasRole('ADMIN')")) and @ConditionalOnExpression. Import this library to evaluate expressions yourself (rules or templates read from configuration, for example) or to extend what expressions can see: property accessors, method resolvers, functions and types.

The syntax is Spring's: literals (42, 3.5, 'text', true, null), inline lists and maps ({1, 2}, {name: 'Ada'}), properties and methods (user.name, name.toUpperCase()), indexing (items[0], map['key']), safe navigation (a?.b), variables and functions (#n, #this, #root, #twice(2)), types and constructors (T(Math).max(1, 2), new int[3]), bean references (@mailer), selection and projection (list.?[#this > 1], users.![name]), all operators (arithmetic, ==, <, and, !, instanceof, matches, between, Elvis ?:, ternary ? :), assignment and ++/--. Templates mix text and #{...} parts ('Total: #{price * 2}').

// Which items of an order pass a rule kept in configuration.
final parser = SpelExpressionParser();
final context = StandardEvaluationContext({'items': [1, 2, 3]});
parser.parseExpression('items.?[#this > 1].size()').getValue(context); // 2

Differences from Java SpEL, all because Dart has no reflection: the properties and methods of your classes are reached through @Introspected metadata or accessors you register, T(...) and new only know registered types, matches uses Dart's RegExp, and String methods are Dart's (plus the common Java names). There is no compiler mode of the interpreter; instead the build compiles the expressions it can to plain Dart: the :#{...} of the data starter's @Query (a typo in #book.titel is a build error), written with SpelOperations, the operators the interpreter runs as well. What it cannot compile stays interpreted.

Spring (Java):

ExpressionParser parser = new SpelExpressionParser();
parser.parseExpression("items.?[#this > 1].size()").getValue(context);

Classes

BeanExpressionContext: The root object of @Value('#{...}') expressions, whose properties are the beans of a bean factory.
BeanExpressionContextAccessor: A PropertyAccessor that reads the beans of a BeanExpressionContext as its properties, so that #{mailer} is the bean mailer.
BeanFactoryAccessor: A PropertyAccessor that reads beans as properties of a BeanFactory itself, for expressions whose value is a bean factory (factory.mailer).
BeanFactoryResolver: A BeanResolver that answers @name references with the beans of a BeanFactory.
BeanResolver: Looks up the object an @name (or &name) reference stands for.
BuiltinMethodResolver: A MethodResolver for the common methods of core Dart types, under their Dart names and the Java names Spring expressions use (size(), toUpperCase(), charAt(), equals(), getOrDefault(), putIfAbsent()).
BuiltinPropertyAccessor: A PropertyAccessor for the common read-only properties of core Dart types, which expressions cannot reach otherwise without reflection.
CompositeStringExpression: A template made of several parts, text and #{...} expressions, whose value is the parts joined into one string.
ConstructorResolver: A plug-in that tells expressions how to create an object for new Name(...).
EnvironmentAccessor: A PropertyAccessor that reads configuration properties of an Environment, so that environment['app.name'] in an expression is the value of app.name.
EnvironmentMethodResolver: A MethodResolver that lets expressions call the methods of an Environment (or any PropertyResolver) under their Java names.
EvaluationContext: The world an expression is evaluated in: its root object, its variables, and the plug-ins that decide which properties, methods, types and beans it can reach.
Expression: A parsed expression, ready to be evaluated as often as needed.
ExpressionParser: Turns expression text into an Expression that can be evaluated.
ExpressionState: The working state of one evaluation: which object names currently apply to, what #this is, and how many operations have run.
FunctionMethodResolver<T extends Object>: A MethodResolver for objects of type T, built from one function per method name.
FunctionPropertyAccessor<T extends Object>: A PropertyAccessor for objects of type T, built from one getter (and optionally one setter) function per property name.
IndexAccessor: A plug-in that makes target[index] work for your own indexable types.
IntrospectionMethodResolver: A MethodResolver that calls the methods of @Introspected classes, using the metadata the code generator wrote for them.
IntrospectionPropertyAccessor: A PropertyAccessor that reads and writes the properties of @Introspected classes, using the metadata the code generator wrote for them.
LiteralExpression: An expression whose value is fixed text: a template with no #{...} in it, or a text part of a template.
MapAccessor: A PropertyAccessor that treats the entries of a map as properties, so user.name works when user is a map such as decoded JSON.
MethodResolver: A plug-in that tells expressions which code to run for a method call such as greeter.greet('Ada').
OperatorOverloader: A plug-in that gives arithmetic operators a meaning for your own types, such as + on two money amounts.
ParserContext: Tells the parser whether a text is one expression or a template of literal text with embedded expressions, and which delimiters mark them.
PropertyAccessor: A plug-in that tells expressions how to read and write the properties of some kind of object, so that point.x works.
SimpleEvaluationContext: An evaluation context that only lets an expression read (and, if allowed, write) properties: the one to use for expressions that come from outside, such as a filter typed by a user or a field path sent by a client.
SimpleEvaluationContextBuilder: Sets up a SimpleEvaluationContext: which methods, index accessors, conversions and root object it has.
SpelExpression: One parsed SpEL expression: the syntax tree of the text and the parser options it runs under.
SpelExpressionParser: The parser of the Spring Expression Language: it turns expression text into an Expression you can evaluate.
SpelLimits: The fixed size limits of what one operator may build, which keep a hostile expression from exhausting memory or time.
SpelNode: One node of a parsed expression's syntax tree: a literal, a property reference, an operator, a method call, ...
SpelOperations: The operators of SpEL as plain functions: what an expression computes for /, ==, <, + on text, and and the like, apart from the tree that holds the operands.
SpelParserConfiguration: The options of a SpelExpressionParser: the limits that protect against hostile or runaway expressions, and auto-grow for data binding.
SpelParserConfigurationBuilder: Builds a SpelParserConfiguration, starting from the defaults.
SpelPatterns: The compiler of the regular expressions used by matches (the operator and the String method), with Spring's length limit and a guard against patterns that could hang the program.
SpelType: The description of a type that expressions may name: its name, its static fields and methods, its constructor, and how to test an instance.
SpelTypeConstructorResolver: The default ConstructorResolver: it runs the constructor function registered on a SpelType for new Name(...).
SpelTypeMethodResolver: The MethodResolver for static methods, T(Name).method(...): it runs the functions listed in SpelType.staticMethods.
StandardBeanExpressionResolver: Evaluates the #{...} parts of @Value strings (and of other framework values, such as @ConditionalOnExpression) against the beans of a bean factory.
StandardEvaluationContext: An evaluation context with every feature of the language enabled: the one to use for expressions you or your application wrote.
StandardOperatorOverloader: The default OperatorOverloader: it takes over no operator, so arithmetic on operands without a built-in rule fails with operatorNotSupportedBetweenTypes (EL1030E).
StandardTypeComparator: The default TypeComparator: it orders numbers, strings, dates, durations, booleans, enums and other Comparables, with null before everything.
StandardTypeConverter: The default TypeConverter: it hands every conversion to a ConversionService.
StandardTypeLocator: The usual TypeLocator: a registry of SpelTypes by name, with the core Dart types and the common Java names already in it.
TemplateParserContext: A template ParserContext with delimiters of your choice.
TypeComparator: Decides how two values are ordered for <, <=, >, >= and between.
TypeConverter: Converts a value to another type while an expression is evaluated.
TypeLocator: Finds the type a name stands for in T(Name), new Name(...) and instanceof T(Name).
ValueRef: A handle on the place an assignable expression names (a property, a variable, a list or map element), to read and write it.
VarargsFunction: A wrapper that lets a Dart function accept any number of trailing arguments when an expression calls it, like a Java varargs method (String.join(delimiter, String... elements)).

Enums

Operation: The arithmetic operators an OperatorOverloader can take over.
SpelMessage: The catalogue of SpEL failures: each value is one kind of error with its code (EL1005E) and message text.
SpelMessageKind: The severity of a SpelMessage. Every message defined today is an error; the other kinds exist because Spring defines them.

Typedefs

ConstructorExecutor = Object? Function(EvaluationContext context, List<Object?> arguments): The function a ConstructorResolver returns to run one new Name(...): it gets the evaluated arguments and returns the new object.
MethodExecutor = Object? Function(EvaluationContext context, Object target, List<Object?> arguments): The function a MethodResolver returns to run one method call: it gets the target and the evaluated arguments and returns the result.

Exceptions / Errors

AccessException: The exception a plug-in (property or index accessor, method, constructor or bean resolver, executor) throws to say it could not do its job.
EvaluationException: An expression was valid but could not be evaluated: a missing property, an unknown type, a failed conversion.
ExpressionException: The common supertype of everything that can go wrong with an expression: invalid text (ParseException) or a failed evaluation (EvaluationException).
ParseException: The text of an expression or template is not valid, so it cannot be parsed.
SpelEvaluationException: Evaluating a SpEL expression failed; messageCode says why.
SpelParseException: The text of a SpEL expression is not valid; messageCode says what is wrong.

expression library

Classes

Enums

Typedefs

Exceptions / Errors

spring_core_dart package

expression library