This directory contains files that are necessary to make expressions work.

Expressions can be evaluated at runtime (i.e. when playing an Oppia exploration)

and can reference parameters and system variables to produce textual output

(e.g. used in a message presented to users) as well as boolean results which

may be used to control state transitions.

Example string expressions:

- "Hello " + userName + "!"

- "The answer is " + (x + y * z) + "."

Example boolean expressions:

- answer == "yes"

- loopCounter > 100

See comments in parser.pegjs for the description of input expression grammar.

Also see parser.pegjs for the parser output (i.e. parse tree) data format.

See ExpressionEvaluatorService.js for the operator contracts.

Files:

parser.pegjs

This is the parser definition which is used to generate the expression-parser.service.js file

that will be used at runtime to parse user-entered expressions.

expression-parser.service.js

This is the JavaScript parser file produced by PEGJS and the input file

parser.pegjs.

ExpressionEvaluatorService.js

Implementation of the expression evaluator. Includes the evaluation engine

as well as the system operators.

ExpressionParserServiceSpec.js

Tests for the parser.

ExpressionEvaluatorServiceSpec.js

Tests for the evaluator.

How to update the parser:

1. Modify parser.pegjs.

2. Add tests in test.js for the new or modified grammar.

3. Run

python -m scripts.create_expression_parser

which updates expression-parser.service.js. Then run the frontend unit tests using

python -m scripts.run_frontend_tests

to ensure that the new grammar passes the tests in ExpressionParserServiceSpec.js and

ExpressionEvaluatorServiceSpec.js.

4. Repeat 1-3 until the desired grammar is written and tested.

5. Check the changes. You need to check in parser.pegjs as well as expression-parser.service.js

(and probably ExpressionParserServiceSpec.js and ExpressionEvaluatorServiceSpec.js).