# The BooleanEval Component

The BooleanEval component provides a convenience API for evaluating boolean expressions in xADL documents. The BooleanEval component provides 2 functions specified by IBooleanEval:

The `eval`

method is responsible for evaluating a boolean
expression based on the symbol table passed in. For more information on
the symbol table, go here. If a variable in
the expression is not defined (no value in the symbol table), it will evaluate the
expression as much as possible (taking advantage of short-circuiting). Its Javadoc
is shown here:

### eval

public ObjRefeval( ObjRef exp, SymbolTable symTable) throws MissingElementException, NoSuchTypeException, TypeMismatchException;

This function will evaluate the boolean expression passed in and will attempt to evaluate based on the symbol table passed in. The expression is also cloned so the original expression passed in is left unchanged. The boolean expression must be part of an xArch document and must have a parent with the expression as "BooleanExp"

Note: It will ignore case when evaluating strings.

**Parameters:**

`exp`

- The ObjRef pointing to the boolean expression that needs to be evaluated.`symTable`

- This is the table that contains all the variables and their values.

**Returns:** ObjRef pointing to a modified version of the cloned expression.
This boolean expression can only be TRUE, FALSE, or a pruned version of the
cloned expression if the not all variables can be resolved.

**Exceptions:**

`MissingElementException`

- This exception is thrown when the evaluator cannot find a required element in the expression.`NoSuchTypeException`

- This exception is thrown when it encounters an unknown/invalid type when evaluating.`TypeMismatchException`

- This exception is thrown when the type of the operands do not match during an evaluation.

A call to this function looks like this:

/* Obtain a reference to the boolean eval component... */ IBooleanEval boolEval = /* get reference here */ ; ObjRef result = boolEval.eval( boolExp, symTab );

For example, if the symbol table contained:

a = 1

b = 2

The the following expressions would return expressions containing:

b >= a --> TRUE

a == 1 && z > 0 --> z > 0

a != 1 && z > 0 --> FALSE

a == 1 || z > 0 --> TRUE

a != 1 || z > 0 --> z > 0

The `boolValue`

method provides a simple way to extract the
boolean value of a boolean value represented by an ObjRef (ie. ObjRef to an
IBool). Its Javadoc is shown here:

### boolValue

public booleanboolValue( ObjRef bool ) throws MissingElementException, TypeMismatchException;

This function takes in a bool reference and returns true or false.

**Parameters:**

`bool`

- The Bool INSIDE a boolean expression

**Returns:** Boolean containing the value of the bool
(true/false)

**Exceptions:**

`MissingElementException`

- This exception is thrown if the element pointed by the bool does not have a "value" field or is null`TypeMismatchException`

- This exception is thrown if the element pointed by the bool is not a boolean expression

This function is can be used to determine the results of the evaluation:

IBooleanEval boolEval = /* get reference here */ ; ObjRef result = boolEval.eval( boolExp, symTab ); ObjRef bool = ( ObjRef )xArch.get( result, "Bool" ); // check to see if it could be evaluated if (bool != null) { if (boolEval.boolValue(bool) { ... } else { ... } } // partial eval else { ... }

Additional questions about the BooleanEval should be sent to Ping H. Chen.