The Abacus Expression Language (abbreviated: AEL) is a textual language that you can use to read, write, and modify an abacus. AEL is pure text, providing a radically new method of working with an abacus. AEL shows you, for the first time ever, the contents of any abacus — including the underlying abacus that is built for a form query or power query — using plain text.

In the Inspector, the Abacus Expression Language is shown in the ‘Expression’ property of an abacus, form query, or power query, where it can be edited as plain text, making it possible to swap out a single tile or icon, create an entire abacus ‘all at once,’ or anything in between. The AEL is also seen in the ‘Combined query’ property of a view, which is a read-only property showing the current query in effect, including the Quick Query if one exists.

In AppleScript, the Abacus Expression Language can be used to can be used to examine (read) and modify (write) the contents of an abacus, form query, or power query. A complete abacus can be created in a single line of AppleScript code. The ‘Combined query’ property of a view can also be examined (read).

This document defines the syntactical rules governing the Abacus Expression Language.

Tiles are the basic building block of an abacus expression in the Helix GUI.

Each tile is demarcated by a pair of square brackets [ ]

Tiles can contain four types of objects:
    { Keywords, Icons, Constants, Tiles }

Multi-socket tiles follow the same order in AEL as they do in the GUI.
    In some cases, a socket may be left undefined.
    An undefined socket (aka: black hole) is represented by a capital X.

When defining a tile, Keywords and Icons are interspersed between sockets, matching the GUI representation of the tile.

Keywords are textual representation of tiles seen in the Helix GUI

Keywords are defined in the scripting implementation and match nomenclature seen in the GUI tiles as closely as possible.

See the 'abacus operators' section of the AppleScript dictionary or this table for the specific format of each tile.
         
Keywords that are outside the standard ASCII range may have textual equivalents
    (e.g: delta for the ∆ tile)

Icons are the icons seen in the Helix GUI (fields, abaci, etc.)

An icon is written as a composition of two entities: Type & Value (plus an optional divider)

Type: The icon type about to be declared. Current legal icon types are:
    { F, Field, A, Abacus, T, Template, R, Relation }

Value: The icon identifier. Can be either ID or name:
    ID: the icon's internal ID (in AppleScript integer form)
         IDs require no demarcation
    Name: a demarcated string equal to the name as seen in the GUI
         Names require demarcation is by being enclosed with single quotes (')
         Use of the quote character within an icon name is handled by escaping
            it with a duplicate quote mark (Example: "it's" -> "it''s")

Divider: An optional divider can be used to demarcate the Type & Value.
    Legal divider characters are colon (:) or whitespace {space, tab, linefeed} 

Examples: Relation:'Customers'
          Relation 'Customers'
          Relation'Customers'
          R:'Customers'
          R 'Customers'
          R'Customers'
          Relation:8
          Relation 8
          Relation8
          R:8
          R 8
These all produce identical results, assuming the relation 'Customers' has an internal ID of 8.

Reply (output) format: <type (full name)>:'<value>'

Constants are values typed directly into sockets in a tile in the Helix GUI.

A constant is comprised of three parts: Signal, Type, & Quoted Value

Signal: The letter C (short for 'Constant')

Type: A single letter representing the data type about to be declared.
   Current legal data types are:
    T: Text
    S: Styled Text
    N: Number
    I: Fixed Point (Integer)
    D: Date
    F: Flag

Quoted Value: Text string to be cast into the designated Type.
    The rules for quoted text are the same as for designating an icon by name.

Examples: CN'3.14159'
          CT'These are quotes that try men''s patience.'
          CF'True'

Reply (output) format: C<type (single letter)>'<quoted value>'

Notes:

1. There are no expanded forms for the Signal and Type, and there is no divider.
2. A constant by itself is meaningless; it must be placed within the context of a tile. To create an abacus to represent a constant, surround the constant with brackets [], which is the designation of the display tile.

The following general rules should be observed:

• Whitespace {space, tab, linefeed} outside of keywords and quoted values is ignored.
• Whitespace is optional around socket contents.
• All text is case insensitive.
• A form query with no defined criteria appears as "[ CF'1' ]" (Constant Flag of text '1') because that is the content of the underlying query abacus.
• A power query with no defined criteria appears as "[ CF'Yes' ]" (Constant Flag of text 'Yes') because that is the content of the underlying query abacus.

The following are exceptions to the general rules:

• When creating a Use/From tile that references a template, you must specify the template by Object ID, as it is impossible to know which relation to search to find the named template. See R7392 in techdb for discussion on this issue.
• It is not possible to create an invalid abacus construction via AEL. Helix RADE allows you to close in invalidly constructed abacus, on the assumption that you will return and complete it at some point. That is not possible via AEL. See R7393 in techdb for discussion on this issue.

These are examples of abaci as seen in AEL:

[ CN'3.14159' ]
                                
[ If Abacus:'Undefined Color' Then CT'unknown' Else Field:'Color' ]

[ If A:324 Then X Else F:721 ]

[ Lookup A'Full Name' for F'CustNum' = F'Cust#' in R'Customers' ]

[ Lookup  Field:'Age'
        for   A'Full Name'
         =  [ F'First Name' followed by [ CT' ' followed by F'Last Name' ] ]
        in    R'Customers'
]

The complete list of keywords is found in the AEL Operators Table and in the ‘abacus operators’ section of the AppleScript dictionary.

The Abacus Expression Language Exporter is an AppleScript that can be used to create a reference document for your existing abaci, or for study to learn how you can create a complete abacus via this text-based language. Open your collection, then run the script: it creates a text file containing every abacus (including form query and power query statements) in Abacus Expression Language (AEL) format. This script, along with many others, is available on our free AppleScripts page. Subscribers to the Learning AppleScript with Helix self-paced tutorial have access to a wider range of scripting resources.