ExpressionManager

Description of ExpressionManager (1) Does safe evaluation of PHP expressions. Only registered Functions, and known Variables are allowed.

(a) Functions include any math, string processing, conditional, formatting, etc. functions (2) This class replaces LimeSurvey's <= 1.91+ process of resolving strings that contain LimeReplacementFields (a) String is split by expressions (by curly braces, but safely supporting strings and escaped curly braces) (b) Expressions (things surrounded by curly braces) are evaluated - thereby doing LimeReplacementField substitution and/or more complex calculations (c) Non-expressions are left intact (d) The array of stringParts are re-joined to create the desired final string. (3) The core of Expression Manager is a Recursive Descent Parser (RDP), based off of one build via JavaCC by TMSWhite in 1999. (a) Functions that start with RDP_ should not be touched unless you really understand compiler design.

author

LimeSurvey Team (limesurvey.org)

author

Thomas M. White (TMSWhite)

Methods

__construct

__construct() 

Add an error to the error log

RDP_AddError(string $errMsg, array|null $token) : void

Arguments

$errMsg

string

$token

array|null

RDP_GetErrors

RDP_GetErrors() : array

Response

array

Get informatin about type mismatch between arguments.

getMismatchInformation(array $arg1, array $arg2) : array

Arguments

$arg1

array

$arg2

array

Response

array

Like (boolean $bMismatchType, boolean $bBothNumeric, boolean $bBothString)

RDP_EvaluateBinary() computes binary expressions, such as (a or b), (c * d), popping the top two entries off the stack and pushing the result back onto the stack.

RDP_EvaluateBinary(array $token) : boolean

Arguments

$token

array

Response

boolean

  • false if there is any error, else true

Processes operations like +a, -b, !c

RDP_EvaluateUnary(array $token) : boolean

Arguments

$token

array

Response

boolean

  • true if success, false if any error occurred

Main entry function

RDP_Evaluate(string $expr, boolean $onlyparse = false) : boolean

Arguments

$expr

string

$onlyparse

boolean

  • if true, then validate the syntax without computing an answer

Response

boolean

  • true if success, false if any error occurred

Process "a op b" where op in (+,-,concatenate)

RDP_EvaluateAdditiveExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process a Constant (number of string), retrieve the value of a known variable, or process a function, returning result on the stack.

RDP_EvaluateConstantVarOrFunction() : boolean|null

Response

boolean|null

  • true if success, false if any error occurred

Process "a == b", "a eq b", "a != b", "a ne b"

RDP_EvaluateEqualityExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process a single expression (e.g. without commas)

RDP_EvaluateExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process "expression [, expression]*

RDP_EvaluateExpressions() : boolean

Response

boolean

  • true if success, false if any error occurred

Process a function call

RDP_EvaluateFunction() : boolean|null

Response

boolean|null

  • true if success, false if any error occurred

Process "a && b" or "a and b"

RDP_EvaluateLogicalAndExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process "a || b" or "a or b"

RDP_EvaluateLogicalOrExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process "a op b" where op in (*,/)

RDP_EvaluateMultiplicativeExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process expressions including functions and parenthesized blocks

RDP_EvaluatePrimaryExpression() : boolean|null

Response

boolean|null

  • true if success, false if any error occurred

Process "a op b" where op in (lt, gt, le, ge, <, >, <=, >=)

RDP_EvaluateRelationExpression() : boolean

Response

boolean

  • true if success, false if any error occurred

Process "op a" where op in (+,-,!)

RDP_EvaluateUnaryExpression() : boolean|null

Response

boolean|null

  • true if success, false if any error occurred

Returns array of all JavaScript-equivalent variable names used when parsing a string via sProcessStringContainingExpressions

GetAllJsVarsUsed() : array

Response

array

Return the list of all of the JavaScript variables used by the most recent expression - only those that are set on the current page This is used to control static vs dynamic substitution. If an expression is entirely made up of off-page changes, it can be statically replaced.

GetOnPageJsVarsUsed() : array

Response

array

Return the list of all of the JavaScript variables used by the most recent expression

GetJsVarsUsed() : array

Response

array

SetJsVarsUsed

SetJsVarsUsed($vars) : void

Arguments

$vars

Return the JavaScript variable name for a named variable

GetJsVarFor(string $name) : string

Arguments

$name

string

Response

string

Returns array of all variables used when parsing a string via sProcessStringContainingExpressions

GetAllVarsUsed() : array

Response

array

Return the result of evaluating the equation - NULL if error

GetResult() : mixed

Response

mixed

Return an array of errors

GetErrors() : array

Response

array

Converts the most recent expression into a valid JavaScript expression, mapping function and variable names and operators as needed.

GetJavaScriptEquivalentOfExpression() : string

Response

string

the JavaScript expresssion

JavaScript Test function - simply writes the result of the current JavaScriptEquivalentFunction to the output buffer.

GetJavascriptTestforExpression(string $expected, integer $num) : string

Arguments

$expected

string

$num

integer

Response

string

Generate the function needed to dynamically change the value of a <span> section

GetJavaScriptFunctionForReplacement(integer $questionNum, string $name, string $eqn) : string

Arguments

$questionNum

integer

$name

string

  • the ID name for the function

$eqn

string

Response

string

Returns the most recent PrettyPrint string generated by sProcessStringContainingExpressions

GetLastPrettyPrintExpression() 

This is only used when there are no needed substitutions

SetPrettyPrintSource(string $expr) 

Arguments

$expr

string

Color-codes Expressions (using HTML <span> tags), showing variable types and values.

GetPrettyPrintString() : string

Response

string

HTML

Get information about the variable, including JavaScript name, read-write status, and whether set on current page.

GetVarAttribute(string $name, string|null $attr, $default) : string

Arguments

$name

string

$attr

string|null

$default

Response

string

Return array of the list of variables used in the equation

GetVarsUsed() : array

Response

array

Return true if there were syntax or processing errors

HasErrors() : boolean

Response

boolean

Return true if there are syntax errors

HasSyntaxErrors() : boolean

Response

boolean

Return true if the function name is registered

RDP_isValidFunction(string $name) : boolean

Arguments

$name

string

Response

boolean

Return true if the variable name is registered

RDP_isValidVariable(string $name) : boolean

Arguments

$name

string

Response

boolean

Return true if the variable name is writable

RDP_isWritableVariable(string $name) : boolean

Arguments

$name

string

Response

boolean

Process an expression and return its boolean value

ProcessBooleanExpression(string $expr, int $groupSeq = -1, int $questionSeq = -1) : boolean

Arguments

$expr

string

$groupSeq

int

  • needed to determine whether using variables before they are declared

$questionSeq

int

  • needed to determine whether using variables before they are declared

Response

boolean

Start processing a group of substitions - will be incrementally numbered

StartProcessingGroup($sid = NULL, $rooturl = '', $hyperlinkSyntaxHighlighting = true) 

Arguments

$sid

$rooturl

$hyperlinkSyntaxHighlighting

Clear cache of tailoring content.

ClearSubstitutionInfo() 

When re-displaying same page, need to avoid generating double the amount of tailoring content.

Process multiple substitution iterations of a full string, containing multiple expressions delimited by {}, return a consolidated string

sProcessStringContainingExpressions(string $src, int $questionNum, int $numRecursionLevels = 1, int $whichPrettyPrintIteration = 1, int $groupSeq = -1, int $questionSeq = -1, boolean $staticReplacement = false) : string

Arguments

$src

string

$questionNum

int

$numRecursionLevels

int

  • number of levels of recursive substitution to perform

$whichPrettyPrintIteration

int

  • if recursing, specify which pretty-print iteration is desired

$groupSeq

int

  • needed to determine whether using variables before they are declared

$questionSeq

int

  • needed to determine whether using variables before they are declared

$staticReplacement

boolean

Response

string

Process one substitution iteration of a full string, containing multiple expressions delimited by {}, return a consolidated string

sProcessStringContainingExpressionsHelper(string $src, integer $questionNum, boolean $staticReplacement = false) : string

Arguments

$src

string

$questionNum

integer

  • used to generate substitution s that indicate to which question they belong

$staticReplacement

boolean

Response

string

If the equation contains refernece to this, expand to comma separated list if needed.

ExpandThisVar(string $src) 

Arguments

$src

string

Get info about all <span> elements needed for dynamic tailoring

GetCurrentSubstitutionInfo() : array

Response

array

Flatten out an array, keeping it in the proper order

flatten_array(array $a) : array

Arguments

$a

array

Response

array

Run a registered function Some PHP functions require specific data types - those can be cast here.

RDP_RunFunction(array $funcNameToken, array $params) : boolean|null

Arguments

$funcNameToken

array

$params

array

Response

boolean|null

Add user functions to array of allowable functions within the equation.

RegisterFunctions(array $functions) 

$functions is an array of key to value mappings like this: See $this->RDP_ValidFunctions for examples of the syntax

Arguments

$functions

array

Set the value of a registered variable

RDP_SetVariableValue(string $op, string $name, string $value) : int

Arguments

$op

string

  • the operator (=,*=,/=,+=,-=)

$name

string

$value

string

Response

int

Split a soure string into STRING vs. EXPRESSION, where the latter is surrounded by unescaped curly braces.

asSplitStringOnExpressions(string $src) : string

This verson properly handles nested curly braces and curly braces within strings within curly braces - both of which are needed to better support JavaScript Users still need to add a space or carriage return after opening braces (and ideally before closing braces too) to avoid having them treated as expressions.

Arguments

$src

string

Response

string

Specify the survey mode for this survey. Options are 'survey', 'group', and 'question'

SetSurveyMode(string $mode) 

Arguments

$mode

string

Pop a value token off of the stack

RDP_StackPop() : \token

Response

\token

Stack only holds values (number, string), not operators

RDP_StackPush(array $token) 

Arguments

$token

array

Public call of RDP_Tokenize

Tokenize(string $sSource, bool $bOnEdit) : array

Arguments

$sSource

string

: the string to tokenize

$bOnEdit

bool

: on edition, actually don't remove space

Response

array

Split the source string into tokens, removing whitespace, and categorizing them by type.

RDP_Tokenize(string $sSource, bool $bOnEdit = false) : array

Arguments

$sSource

string

: the string to tokenize

$bOnEdit

bool

: on edition, actually don't remove space

Response

array

Show a table of allowable Expression Manager functions

ShowAllowableFunctions() : string
static

Response

string

Show a translated string for admin user, always in admin language #12208 public for geterrors_exprmgr_regexMatch function only

gT(string $string) : string
static

Arguments

$string

string

to translate

Response

string

: translated string

Properties

RDP_regex_var_attr

RDP_regex_var_attr : 
static

RDP_ExpressionRegex

RDP_ExpressionRegex : 

RDP_TokenType

RDP_TokenType : 

RDP_TokenizerRegex

RDP_TokenizerRegex : 

RDP_CategorizeTokensRegex

RDP_CategorizeTokensRegex : 

RDP_ValidFunctions

RDP_ValidFunctions : 

RDP_expr

RDP_expr : 

RDP_tokens

RDP_tokens : 

RDP_count

RDP_count : 

RDP_pos

RDP_pos : 

RDP_errs

RDP_errs : 

RDP_onlyparse

RDP_onlyparse : 

RDP_stack

RDP_stack : 

RDP_result

RDP_result : 

RDP_evalStatus

RDP_evalStatus : 

varsUsed

varsUsed : 

allVarsUsed

allVarsUsed : 

prettyPrintSource

prettyPrintSource : 

substitutionNum

substitutionNum : 

substitutionInfo

substitutionInfo : array
var

Type(s)

array

jsExpression

jsExpression : 

questionSeq

questionSeq : 

groupSeq

groupSeq : 

surveyMode

surveyMode : 

sid

sid : 

hyperlinkSyntaxHighlighting

hyperlinkSyntaxHighlighting : 

sgqaNaming

sgqaNaming :