Expression Editor

A guide to the window where you write and test expressions in Simplebim. It explains what the buttons, lists and panes do and how to read the feedback the editor gives you while you type.

This guide is about the editor. What you can write in it — property names, functions, operators, dates and so on — is covered in Expression Syntax Guide, and you will want both open the first time.

Contents

• Where you find the Expression Editor
• The editor at a glance
• Writing the expression
• Inserting a property
• Inserting a unit
• Inserting a function
• Checking the expression
• Trying the expression on a real object
• Which properties you can use
• What kind of answer is required
• Keeping or discarding your changes
• Troubleshooting

Where you find the Expression Editor

You do not open the Expression Editor from a menu. It opens from the place where an expression is needed, and there are two such places:

1. An expression setting in a configuration. Tools, dataflow steps and settings dialogs are configured with a list of settings. A setting that takes an expression shows the current expression with syntax colouring and has an fx button next to it. Click fx to open the editor.

2. An Expression rule in the Query Editor. When you build a query, one of the rule types is Expression. The rule shows the expression in a box with an fx button at its right end. Click fx to open the editor.

In both cases the editor opens in place of the list you came from, in the same window. A path at the top tells you where you are, for example

Expression: Add or Modify Groups

and two buttons, Apply Changes and Discard Changes, take you back. See Keeping or discarding your changes.

The editor at a glance

From top to bottom the editor has these parts:

The three lists carry a small colour badge that matches the colour their inserts get in the expression — green for properties, purple for units, blue for functions — so you can see at a glance which part of the expression came from where.

Writing the expression

Click in the expression box and type. Everything you would write in a text editor works: select with the mouse or with Shift and the arrow keys, double-click to select a word, and use the usual keys:

Line breaks are allowed. A long expression is easier to read spread over several lines, and the line breaks do not change what it means:

IF([Length {mm}] > 8000;
   "Long";
   "Short")

The colours

The editor colours the parts of the expression as you type, so a slip shows up immediately:

Two things are worth knowing about the colours:

• A property is only green when its closing ] is there. An opening [ without a closing ] is shown white on red right away, before any other checking happens.
• The colours only tell you what the editor thinks a piece is. A name is blue if it is followed by (, whether or not a function of that name exists. Whether the expression actually works is decided by the validation, not by the colours.

Inserting a property

You can always type a property name by hand, in square brackets. The Select Property list saves you the typing and, more importantly, the guessing: it only lists the properties that the expression is allowed to use, spelled exactly right.

1. Put the cursor where the property should go.
2. Open Select Property and pick a property. You can also type a few letters into the box; the list narrows to the names that contain what you typed, so area finds Gross Floor Area.
3. The property is inserted at the cursor as [Name].

If a property is a measurement, it is inserted with its unit, for example [Height {mm}], and the unit is left selected so you can type a different one straight over it. For any other property the name is left selected instead. Just click or press an arrow key to carry on.

Two details:

• If the cursor is inside a selection, the selection is replaced by the property. This is the quickest way to swap one property for another: select the old one, pick the new one.
• When two properties have the same name but different types — a text Code on one kind of object and a number Code on another — the list shows them as separate entries with the type in brackets, for example Code (Text) and Code (Number). Both insert plain [Code]; the entries are there so you can see what you are getting.

Inserting a unit

A measurement can be asked for in a unit of your choice by writing the unit symbol in curly brackets inside the property: [Length {m}]. The Select Unit list gives you the symbols so you do not have to remember them.

Picking a unit inserts {symbol} at the cursor position, wherever that is. The editor does not move it inside the brackets for you, so put the cursor in the right place first — directly after the property name, before the ]:

[Length|]          cursor here, then pick m  →  [Length {m}]

The list adapts to what you last inserted. After you insert a measurement property from Select Property, the list only offers the units of that property's kind — lengths for a length, areas for an area — with the property's own unit preselected. Until then, and after inserting a property that is not a measurement, it offers every unit Simplebim knows.

A unit symbol that Simplebim does not recognise is silently ignored. Taking the symbol from the list is the way to be sure it is one that works.

Inserting a function

The Select Function list holds the functions you can use, grouped by kind — logical, text, maths, date and time, and so on — under grey group headings. Start typing in the box and the list jumps to matching names.

Picking a function inserts it together with a placeholder for each argument, and the first placeholder is selected so that you can start typing the real value at once:

IF([Logical test], [Value if true], [Value if false])

Replace each placeholder by selecting it and typing over it. A function that takes any number of arguments gets a couple of placeholders followed by ... to show that you can add more; delete what you do not need.

Three things to watch:

• Placeholders are separated with commas. As explained in Writing Expressions in Simplebim, commas can be confused with decimal points, so replace them with semicolons while you fill the arguments in: IF([Height] > 1.5; 5; 6).
• The placeholders are in square brackets, which makes them look like properties. They are not — the editor reports the expression as not complete until every placeholder and every ... is gone.

Checking the expression

The editor checks the expression while you type. It waits until you have paused for a moment, then validates what is in the box and reports the result in the line at the bottom.

"The expression is not complete"

This is the message you see most, because it appears as soon as you type [, ( or " and goes away when you close it. It also means:

• a ( without a ), or more ) than (
• a ] or } without a matching opening bracket before it
• a { outside a property — units only make sense inside [ ]
• the expression ends in an operator or a separator, like [Height] > or IF([Height] > 3;
• a ... placeholder from an inserted function is still there

Nothing else is checked until the expression is complete, so fix this first.

Error messages and the red highlight

When a complete expression is refused, the message comes from the expression engine. Alongside the message, the editor tries to highlight the piece it choked on — white on red, in the expression box — so you can see where the problem is even when the message is not very clear about it.

The highlight follows the message; it is not a separate check. If the engine did not say which piece it stopped at, or the same piece occurs more than once, nothing is highlighted and you have only the message to go on.

Common messages and what they usually mean:

Errors are shown outside the editor too

Back in the configuration, an expression setting shows the same white-on-red highlight on the piece that is wrong, so you can spot a broken expression without opening the editor. The check is repeated when something the expression depends on changes — for example the setting that decides which objects it applies to — so an expression that was fine can become marked, and the other way round.

Trying the expression on a real object

A valid expression is not necessarily the right expression. The pane below the expression box — the one that says Drop an object here — lets you see what the expression does for one actual object of the model.

1. Write the expression and wait until it is reported valid.
2. Drag an object from a palette that lists objects — the Objects palette, for example — and drop it on the pane.

The pane then shows the expression with every property replaced by that object's value, and after an equals sign, the answer:

if(10715 > 8000, "Long", "Short") = Long

The object stays on the pane while you keep editing. Every time the expression becomes valid again it is worked out for the object again, so you can adjust the expression and watch the answer change. The object is forgotten when you open a different expression.

Only one object is used. If you drop a selection of several objects, the first one is taken.

When a property has no value for the object

A property that cannot be resolved for the object stays in the pane as [Name] and is shaded, in one of two ways:

No answer is shown in either case, because the expression cannot be worked out without the value — this is the same rule as in Writing Expressions in Simplebim: an object missing a value drops out of the result. The pane is the easiest way to find out which property is the one dropping objects.

When the answer is an error

If every property has a value but the calculation itself fails — dividing by zero, FIND not finding anything — the answer after the equals sign is the error message, white on red. Wrap the calculation in IFERROR(...; fallback) if that is a case you want to handle.

While the expression is invalid

The pane goes blank as soon as the expression stops being valid, and comes back when it is valid again. If the pane is empty and shows no hint, an object is loaded and the pane is just waiting for a valid expression.

Which properties you can use

The Select Property list is not a list of every property in the model. It lists the properties the expression is allowed to use, and using any other property is an error, even if the property exists.

Which properties are allowed depends on where you opened the editor:

• From the Query Editor, and from most configuration settings: every property of every object currently in the model. This is the usual case.
• From a setting that applies to a selection of objects: only the properties of those objects. A tool that renames the walls you select, say, lets its expression use wall properties and nothing else. The selection is normally another setting of the same configuration, and if you change that setting the list of allowed properties changes with it.

If the list is empty, the selection the expression applies to does not select anything — usually because that setting is not filled in yet, or is not valid. Fix the selection first.

Property names are matched ignoring capitalisation, so [name] is accepted for a property called Name. Spelling and spaces have to be exact.

What kind of answer is required

Some places need an expression that answers true or false — an Expression rule in a query always does, because a query has to decide whether each object is in or out. Other places take any kind of answer: a number, a text, a date.

Where true/false is required, the editor enforces it: an expression that would give a number or a text is reported as invalid, even though it is well formed. The fix is to compare with something:

[Name]                     refused — a text is not a yes/no
[Name] = "Basic Wall"      valid
IF([Height] > 3; 1; 0)     refused — 1 and 0 are numbers
[Height] > 3               valid

Where any answer is fine, nothing is enforced and both of the refused lines above are valid.

Keeping or discarding your changes

The editor opens in place of the list you came from, and the two buttons above it take you back:

Two things to know:

• Apply Changes does not check the expression. It applies whatever is in the box, valid or not. That is deliberate — you may want to save a half-finished expression and come back to it — but it also means the green line at the bottom is your only confirmation that it works. Look at it before you click.
• Applying the expression puts it back into the configuration; it does not save the configuration itself. Saving happens where it always does, when you finish with the tool or dialog.

Troubleshooting

The bottom line stays red with "The expression is not complete" although everything looks closed. Look for a placeholder from an inserted function that is still there, in particular a ... at the end of an argument list, and for a comma or an operator at the very end. Also check that each { is inside a [ ].

The property is in the model but the editor says it does not exist. The expression may only use the properties in the Select Property list. See Which properties you can use. If the list is empty, the setting that selects the objects is not filled in yet.

The property is not in the Select Property list. Same reason as above. If you opened the editor from a query and the property is genuinely missing, the property is probably filtered out of the model view.

The expression is valid but is refused when I open it from a query. Queries need a true/false answer. Compare with something: [Name] = "x", not [Name]. See What kind of answer is required.

Nothing happens when I drop an object on the try-it pane. Either the expression is not valid yet — the pane only works for a valid expression — or what you dragged is not an object. Drag from a palette that lists objects.

The try-it pane shows the expression but no answer. One of the properties is shaded: pink means the object does not have the property, grey italic means it is empty for this object. The answer cannot be worked out without every value.

I picked a unit and it landed in the wrong place. The unit goes wherever the cursor is. Undo with Ctrl+Z, put the cursor directly before the ] of the property, and pick the unit again.

I typed a property name and the whole thing turned white on red. You have a [ without a ]. Type the closing bracket.

I clicked Apply Changes and the setting shows a red highlight. The expression was applied even though it is not valid. Click fx again, read the message at the bottom of the editor, and fix it.