AssessLang

Introduction

The AssessLang is a language, along with parser that creates an AST JSON, which can be easily interpreted, along with data on an Observation Data, Observation Definition and Treatments, to supply information on the compliance of an overall observation, and each of it's fields, along with a list of treatments.

An example of the code looks like this:

IF motorizedLiftUnitPresent IS false
  ADD T1 TO BETTER AND BEST
  SET COMPLIANT FOR motorizedLiftUnitPresent TO false
#IF motorizedLiftUnitPresent IS true
IF liftUnitBatteryBackupPresent IS false
  ADD T2 TO GOOD
  ADD T1 TO BETTER AND BEST
  SET COMPLIANT FOR liftUnitBatteryBackupPresent TO false

IF perimeterGapsPresent IS true
  ADD T3 TO GOOD AND BETTER
  SET COMPLIANT FOR perimeterGapsPresent TO false
#Assume that BEST option requires a door replacement, so weather stripping would be part of that installation.ADD

The code is somewhat similar to Python. Some basics concepts:

• Code must be indented by 2 spaces to define a scope under an IF statement.
• All code is case-sensitive.
• The program can only add treatments ie T1 to "buckets" ie GOOD, BETTER and BEST, or set overall compliance, or compliance per field.
• The program cannot set general variables, but can read and set preset variables such as COMPLIANT, ZONE, and PRIORITY as well as the value of any field.

And some caveats to keep in mind:

• Currently there is no ELSE keyword - but it may be added later.
• Currently there is no conditional precedence ie IF (X AND Y) OR (Y AND A).

Default Variables

When a program starts the following variables are set:

• COMPLIANT - defaults to null / not set
• PRIORITY - set to the "Default Report Priority" for the observation type ie P1
• ZONE - set to the "Default Zone" for the observation type

Treatment Buckets

There are three buckets (like arrays) which are set as empty lists to take treatments. They are called GOOD BETTER and BEST .

Treatments

Treatments set in the observation are available as T<n> ie T1, T7 etc

Priorities

Priorities set in the assessment type are available as P<n> ie P1, P2 etc

Zones

The following are possible variables available when referring to zones:

• structure
• zone0 through zone5
• access
• fire_defense

Comments

Comments can be added to code by prefixes with a hash # - examples:

# the following line checks for valid material
IF materialType IS wood

# you can also add comments at the end of a line
SET COMPLIANT TO true # we want to make sure every thing is good

Operations

IF statement

IF statements control the flow of the program. Any code indented (by 2 spaces) after an IF statement will only run if the IF statement is true.

Basic structure is as follows:

IF [variable] [operator] [value]

Where:

• variable is one of COMPLIANT, PRIORITY, ZONE or the key of any field.
• operator is one of IS, NOT, GT, LT, GTE or LTE
• value is either a number, the key from a list ie wood, a string ie "a value" or true or false - it may also refer to a treatment T1 or priority P1 or zone zone0 .

Values you also be one of a list by separating them by OR for example:

IF [variable] [operator] [value] OR [value2] OR [value3]

You can use this with IS and NOT - the following example is true if the materialType is neither wood nor plastic:

IF materialType NOT wood OR plastic

WARNING

IF statements may work differently than in other languages. In most languages you would have to specify that a variable is operating on a list.

Some more examples:

IF ZONE IS zone0
IF COMPLIANT IS false
IF PRIORITY NOT P2
IF dimension_width GTE 10

ADD statement

Used for adding a treatment to a treatment bucket.

ADD [treatment] TO [treatment_bucket]

An example:

ADD T3 TO GOOD

You can also add a treatment to more than one bucket at a time:

ADD [treatment] TO [treatment_bucket] AND [treatment_bucket]

SET statement

The set statement works on either PRIORITY or COMPLIANT

SET PRIORITY statement

Overrides the default priority for the observation type ie:

SET PRIORITY TO P3

SET COMPLIANT statement

Must be set to either true or false.

Can either set compliance for the whole observation ie:

SET COMPLIANT TO false

Or it can be used to set compliance for a specific field, or zone.

SET COMPLIANT FOR material TO false # field
SET COMPLIANT FOR ZONE TO false # zone

WARNING

If any field has compliance set to false the overall observation's compliance will also be set to false - this means when testing for compliance using IF it may be set to false this way.

EXIT statement

Simple exits the current program. Any variables that have already been set are returns as they are.

SET COMPLAINT TO true
IF material IS wood
  EXIT
# this will only run if the material is not wood
SET COMPLIANT TO false

Operators

The following operators may work differently depending on the value it is working on

• IS - checks that a value is equal to something. Can be used with OR
• NOT - checks that a value is not equal to something. Can be used with OR
• GT GTE - checks that a value is greater than (or greater than or equal to) something. Can be used with numbers or zones.
• LT LTE - checks that a value is less than (or less than or equal to) something. Can be used with numbers or zones.

WARNING

When testing "greater than" etc against zones, the lowest value is structure up through fire_access as the highest as listed above.

Abstract Syntax Tree (AST)

The AST is the easily machine readable version of the program, representing the same actions as the code but in a normalized JSON format.

The AST is an array of objects, each with at least a type property, and optionally a line property:

[
  { "type": "if", "line": 2 ... },
  { "type": "exit", "line": 4 }
]

The line property is only used for debugging so we know which line in the code this action was generated from.

"if" Action

The most complex action is an if action. It needs to check if a condition is met, and if so then run the actions in the then property.

{
  "type": "if",
  "left": "material",
  "op": "IS",
  "right": "wood",
  "then": [
    { "type": "set", ... },
    ...
  ]
}

In this example, we must only process the actions in the then property if our condition is met.

WARNING

Currently an ELSE branch is not supported, although it will be added at a later date under the else property.

Complex IF statements are also not yet supported. These will be added at a later date under the condition property.

"push" Action

The push action is used to add a treatment to a treatment bucket.

{
  type: 'push',
  target: 'BEST', // the BEST bucket
  value: 'T1' // add the T1 treatment
}

WARNING

In the program, if we add a treatment to two treatment buckets, two separate push actions will be generated.

"set" Action

The set action is used to override the default priority, or set the compliance on an observation level.

This example sets compliance:

{
  "type": "set",
  "target": "COMPLIANT",
  "value" false
}

And this example sets priority. Note that the value here is set to "1", rather than "P1" as may be expected.

{
  "type": "set",
  "target": "PRIORITY",
  "value": "1"
}

"set-compliant-for" Action

The set-compliant-for action is used to set a compliance for a specific observation field.

{
  "type": "set-compliant-for",
  "target": "material",
  "value": false
}

WARNING

At the current time the value can only be set to false . Setting the value to true will not reset the compliance. This may change in the future.