Expressions

A hope expression is a string that is used to express predicate logic. It is parsed into an object tree of type Evaluatable using the HopeLangEngine.parse() method. Once parsed, this evaluatable can be evaluated against provided json as many times as needed using the HopeLangEngine.evaluate() method.

Components

A trivial expression looks like the following:

<lhs> <comparison_operator> <rhs>

Where

• lhs - An expression that uses functions, json pointers, json paths and operators to provide a value of any of the supported data types.
• rhs - An expression that uses functions, json pointers, json paths and operators to provide a value of any of the supported data types.
• comparison_operator - Supported comparison operator that can compare between lhs and rhs

Type safety

• If types of both lhs and rhs can be determined during runtine, Hope will fail to parse the exception and throw a 'HopeExpressionParserError'. therefore something like 'true' == true will never parse successfully.
• However, hope values that make up the LHS or RHS might be dynamic (for example a json-pointer, json-path or function) making ti impossible for Hope to deduce the type during parsing. In this case Hope assumes in an expression both the LHS and RHS in a comparison evaluate to the same type during evaluation.
• During evaluation, in case of mismatch of types between LHS and RHS or incompatibility of LHS and/or RHS with the comparison operator used, an exception of type HopeTypeMismatchError will be raised.
• Important NOTE - In case equals(==) and/or not-equals(!=) operators are used, hope will try to evaluate both to objects and match. This means that an expression like true == 'true' will always evaluate to false.
• Most stdlib functions expect values or json pointers or json path or functions that evaluate to specific types as parameters. For example, maths.add() expects parameters that are or evaluate to numbers. If the types do not match exception of Type HopeTypeMismatchError will be raised. Important NOTE: Parameter type checking is always at evaluation time. This helps clients easily plug in custom functions and get eval-time type checking for free.
• In case a value provided by a json pointer or a json path is missing in the provided json or is null, an exception of type HopeMissingValueError will be raised.

Suppressing evaluation time exceptions and using default values

Hope uses a strategy ErrorHandlingStrategy to handle the behaviour during evaluation time. The derived strategy DefaultErrorHandlingStrategy is used to implement the eval time exception throwing behaviour as mentioned above. However, the client can change this behaviour by passing InjectValueErrorHandlingStrategy to use default values in case of type mismatch or missing values. Clients can also derive the ErrorHandlingStrategy class and override it to implement custom behaviour.

In order to override the custom error handling in Hope, the following code can be used.

    final HopeLangEngine hope 
        = HopeLangEngine.builder()
            .errorHandlingStrategy(new InjectValueErrorHandlingStrategy())
            .build();

errorHandlingStrategy() can also be used to provide any other custom implementation of ErrorHandlingStrategy.

Combining expressions

Hope expressions can be combined together using combiners.

• And combiner (&&) - Evaluates to true if all combined expressions evaluate to true.

    2 < 4 && (3 < 5) && 5 > 1

• Or combiner (||) - Evaluates to true if all combined expressions evaluate to true.

    2 > 4 || (3 > 5) || 5 > 1

(...) can be used to separate out components in both LHS, RHS or in combiners