de.unkrig.commons.text.expression

Class ExpressionEvaluator

java.lang.Object

de.unkrig.commons.text.expression.ExpressionEvaluator

public class ExpressionEvaluator
extends Object

Supports two operation modes:

• Scans, parses and evaluates an expression immediately (see evaluate(String, Mapping))
• Scans and parses an expression (see parse(String)) into an Expression object for repeated evaluation (see Expression.evaluate(Object...)).

Field Summary

Fields

Modifier and Type	Field and Description
static Set<Object>	FALSES All values the are implicitly regarded als false: null "" Boolean.FALSE (byte) 0 (short) 0 (integer) 0 (long) 0

Constructor Summary

Constructors

Constructor and Description
ExpressionEvaluator(Collection<String> variableNames)
ExpressionEvaluator(PredicateWhichThrows<? super String,? extends RuntimeException> isValidVariableName)
ExpressionEvaluator(String... variableNames)

Method Summary

Modifier and Type	Method and Description
protected static Object	binaryNumericPromotion(Object value, Object other) Converts and returns the value to Integer, Long, Float, Double or String as appropriate for comparison with other.
Object	evaluate(String spec, Mapping<String,?> variables) Scans, parses and evaluates an expression.
Object	evaluate(String spec, Object... variableNamesAndValues) Scans, parses and evaluates an expression.
<T> T	evaluateTo(String spec, Class<T> targetType, Mapping<String,?> variables) Scans, parses, evaluates and returns an expression.
<T> T	evaluateTo(String spec, Class<T> targetType, Object... variableNamesAndValues) Scans, parses, evaluates and returns an expression.
boolean	evaluateToBoolean(String spec, Mapping<String,?> variables) Scans, parses and evaluates an expression.
boolean	evaluateToBoolean(String spec, Object... variableNamesAndValues) Scans, parses and evaluates an expression.
Object	evaluateToPrimitive(String spec, Class<?> targetType, Mapping<String,?> variables) Scans, parses and evaluates an expression.
Object	evaluateToPrimitive(String spec, Class<?> targetType, Object... variableNamesAndValues) Scans, parses and evaluates an expression.
ClassLoader	getClassLoader()
String[]	getImports()
Expression	parse(ProducerWhichThrows<? extends AbstractScanner.Token<Scanner.TokenType>,? extends ScanException> tokenProducer) Parses an expression from a tokenProducer.
Expression	parse(String spec) Parses an expression.
Expression	parsePart(CharSequence spec, int[] offset) Parses an expression from the spec, but only as far as it is possible without a parse error.
Parser<Expression,RuntimeException>	parser(ProducerWhichThrows<? extends AbstractScanner.Token<Scanner.TokenType>,? extends ScanException> tokenProducer)
Parser<Expression,RuntimeException>	parser(String spec)
ExpressionEvaluator	setClassLoader(ClassLoader classLoader)
ExpressionEvaluator	setImports(String[] imports)
static <T> T	to(Object subject, Class<T> targetType) Converts the given subject to the given targetType.
static boolean	toBoolean(Object subject)
static <T> T	toPrimitive(Object subject, Class<T> targetType) Converts the given subject to the given primitive target type.
static String	toString(Object subject)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FALSES

public static final Set<Object> FALSES

All values the are implicitly regarded als false:

• null
• ""
• Boolean.FALSE
• (byte) 0
• (short) 0
• (integer) 0
• (long) 0

Constructor Detail

ExpressionEvaluator

public ExpressionEvaluator(PredicateWhichThrows<? super String,? extends RuntimeException> isValidVariableName)

Parameters:

isValidVariableName - Evaluates whether a string is a valid variable name; if not, then the parser will throw a ParseException

ExpressionEvaluator

public ExpressionEvaluator(Collection<String> variableNames)

Parameters:

variableNames - Contains all valid variable names

ExpressionEvaluator

public ExpressionEvaluator(String... variableNames)

Parameters:

variableNames - The names of the variables that can be referred to in an expression

Method Detail

getImports

public String[] getImports()

Returns:

The currently configured imports

setImports

public ExpressionEvaluator setImports(String[] imports)

Parameters:

imports - Names of imported packages

getClassLoader

public ClassLoader getClassLoader()

Returns:

The currently configured ClassLoader

setClassLoader

public ExpressionEvaluator setClassLoader(ClassLoader classLoader)

Parameters:

classLoader - Used to load classes named in the expression; by default the ClassLoader which loaded the ExpressionEvaluator class.

parse

public Expression parse(String spec)
                 throws ParseException

Parses an expression.

Parameters:

spec - The text to be parsed

Returns:

Expression.TRUE iff the expression is constant and evaluates to true; Expression.FALSE iff the expression is constant and evaluates to false; Expression.NULL iff the expression is constant and evaluates to null

Throws:

ParseException

See Also:

The expression syntax

parsePart

public Expression parsePart(CharSequence spec,
                            int[] offset)
                     throws ParseException

Parses an expression from the spec, but only as far as it is possible without a parse error. E.g. "a + b)" is parsed up to and including "b".

Parameters:

spec - The text to be parsed

offset - Returns the position of the first character within the space that could not be parsed

Throws:

ParseException - The expression cannot be parsed, e.g. "a +)" (the second operand of the "+" operator is missing)

See Also:

The expression syntax

parse

public Expression parse(ProducerWhichThrows<? extends AbstractScanner.Token<Scanner.TokenType>,? extends ScanException> tokenProducer)
                 throws ParseException

Parses an expression from a tokenProducer.

Throws:

ParseException

See Also:

The expression syntax

parser

public Parser<Expression,RuntimeException> parser(String spec)

Parameters:

spec - The text to be parsed

Returns:

A Parser for expression parsing

See Also:

The expression syntax

parser

public Parser<Expression,RuntimeException> parser(ProducerWhichThrows<? extends AbstractScanner.Token<Scanner.TokenType>,? extends ScanException> tokenProducer)

Parameters:

tokenProducer - The source of tokens to be parsed, e.g. Scanner.stringScanner()

Returns:

A Parser for expression parsing

See Also:

The expression syntax

evaluate

@Nullable
public Object evaluate(String spec,
                                  Object... variableNamesAndValues)
                           throws ParseException,
                                  EvaluationException

Scans, parses and evaluates an expression.

Throws:

ParseException - spec refers to a variable which is not contained in variables

ParseException - Any other parse error

EvaluationException

See Also:

The expression syntax

evaluate

@Nullable
public Object evaluate(String spec,
                                  Mapping<String,?> variables)
                           throws ParseException,
                                  EvaluationException

Scans, parses and evaluates an expression.

Throws:

ParseException - spec refers to a variable which is not contained in variables

ParseException - Any other parse error

EvaluationException

See Also:

The expression syntax

toString

public static String toString(@Nullable
                              Object subject)

Returns:

subject.toString() or null iff subject == null

binaryNumericPromotion

@Nullable
protected static Object binaryNumericPromotion(@Nullable
                                                          Object value,
                                                          @Nullable
                                                          Object other)

Converts and returns the value to Integer, Long, Float, Double or String as appropriate for comparison with other.

Returns the original value iff the value is incomparable with other.

Examples:

value	other	Result
null	any	null
any	null	value
non-primitive	any	value
any	non-primitive	value
Byte	Short	Integer
Long	Short	Long
Byte	String	String

evaluateTo

@Nullable
public <T> T evaluateTo(String spec,
                                   Class<T> targetType,
                                   Object... variableNamesAndValues)
                            throws ParseException,
                                   EvaluationException

Scans, parses, evaluates and returns an expression.

Returns:

An object of type T, or null

Throws:

EvaluationException - The value is not assignable to T

ParseException

See Also:

The expression syntax

evaluateTo

@Nullable
public <T> T evaluateTo(String spec,
                                   Class<T> targetType,
                                   Mapping<String,?> variables)
                            throws ParseException,
                                   EvaluationException

Scans, parses, evaluates and returns an expression.

Returns:

An object of type T, or null

Throws:

EvaluationException - The value is not assignable to T

ParseException

See Also:

The expression syntax

evaluateToPrimitive

public Object evaluateToPrimitive(String spec,
                                  Class<?> targetType,
                                  Object... variableNamesAndValues)
                           throws ParseException,
                                  EvaluationException

Scans, parses and evaluates an expression.

Returns:

The (wrapped) expression value

Throws:

EvaluationException - The expression evaluates to null (and the targetType is not boolean.class)

EvaluationException - The expression value cannot be converted to the given targetType

ParseException

See Also:

The expression syntax

evaluateToPrimitive

public Object evaluateToPrimitive(String spec,
                                  Class<?> targetType,
                                  Mapping<String,?> variables)
                           throws ParseException,
                                  EvaluationException

Scans, parses and evaluates an expression.

Returns:

The (wrapped) expression value

Throws:

EvaluationException - The expression evaluates to null (and the targetType is not boolean.class)

EvaluationException - The expression value cannot be converted to the given targetType

ParseException

See Also:

The expression syntax

evaluateToBoolean

public boolean evaluateToBoolean(@Nullable
                                 String spec,
                                 Object... variableNamesAndValues)
                          throws ParseException,
                                 EvaluationException

Scans, parses and evaluates an expression.

Returns:

null iff the spec is null; otherwise the expresasion value

Throws:

ParseException

EvaluationException

See Also:

The expression syntax

evaluateToBoolean

public boolean evaluateToBoolean(@Nullable
                                 String spec,
                                 Mapping<String,?> variables)
                          throws ParseException,
                                 EvaluationException

Scans, parses and evaluates an expression.

Returns:

null iff the spec is null; otherwise the expresasion value

Throws:

ParseException

EvaluationException

See Also:

The expression syntax

to

@Nullable
public static <T> T to(@Nullable
                                  Object subject,
                                  Class<T> targetType)
                           throws EvaluationException

Converts the given subject to the given targetType. Special processing applies for target types String and Boolean.

Throws:

EvaluationException

See Also:

toBoolean(Object), toString(Object)

toPrimitive

public static <T> T toPrimitive(@Nullable
                                Object subject,
                                Class<T> targetType)
                         throws EvaluationException

Converts the given subject to the given primitive target type. Special processing applies for target type boolean.class, see toBoolean(Object).

Throws:

EvaluationException - The subject is null (and the targetType is not boolean.class)

EvaluationException - The subject cannot be converted to the given targetType

toBoolean

public static boolean toBoolean(@Nullable
                                Object subject)

Returns:

Whether the subject equals on of the FALSES