Statements

Gliimly statements generally have three components separated by space(s):

a name,
an object,
clauses.

A statement starts with a name, which designates its main purpose.

An object denotes what is referenced by a statement.

Each clause that follows consist of a clause name followed either with no arguments, or with one or more arguments. A clause may have subclauses immediately afterwards, which follow the same structure. Most clauses are separated by space(s), however some (like "=" or "@") may not need space(s) before any data; the statement's documentation would clearly specify this.

An object must immediately follow the statement's name, while clauses may be specified in any order.

For example, in the following Gliimly code:

 encrypt-data orig_data input-length 6 password "mypass" salt newsalt to res binary

Copied!

encrypt-data is the statement's name, and "orig_data" is its object. The clauses are:

input-length 6
password "mypass"
salt newsalt
to res
binary

The clauses can be in any order, so the above can be restated as:

 encrypt-data orig_data to res password "mypass" salt newsalt binary input-length 6

Copied!

Gliimly documentation provides a concise BNF-like notation of how each statement works, which in case of encrypt-data is (backslash simply allows continuing to multiple lines, while two backslashes add a new line in between):

 encrypt-data <data> to <result> \
     [ input-length <input length> ] \
     [ binary [ <binary> ] ] \
     ( password <password> \
         [ salt <salt> [ salt-length <salt length> ] ] \
         [ iterations <iterations> ] \
         [ cipher <cipher algorithm> ] \
         [ digest <digest algorithm> ]
         [ cache ]
         [ clear-cache <clear cache> ) \
     [ init-vector <init vector> ]

Copied!

Note the color scheme: clauses with input data are in blue, and with output data in green.

Optional clauses are enclosed with angle brackets (i.e between "[" and "]").

Arguments (in general variables and constants) are stated between "<" and ">".

If only one of a number of clauses may appear, such clauses are separated by "|".

A group of clauses that cannot be separated, or to remove ambiguity, are enclosed with "(" and ")".

Keywords (other than statement names such as encrypt-data above) are generally specific to each statement. So, keyword "salt", for example, has meaning only within encrypt-data and a few other related statements. In order to have the freedom to choose your variable names, you can simply surround them in parenthesis (i.e. "(" and ")") and use any names you want, even keywords, for example:

 set-string password = "some password"
 set-string salt = "0123456789012345"
 encrypt-data "some data" password (password) salt (salt) to enc_data
 p-out enc_data

Copied!

In this example, keywords "password" and "salt" are used as variable names as well.

Note that while you can use tab characters at the beginning of the line (such as for indentation), as well as in string literals, do not use tabs in Gliimly statements otherwise as they are not supported for lack of readability - use plain spaces.

Splitting statement into multiple lines, space trimming

To split a statement into multiple lines (including string continuations), use a backslash (\), for instance:

 encrypt-data orig_data input-length 6 \
     password "my\
     pass" salt \
     newsalt to res binary

Copied!

Note that all statements are always left-trimmed for whitespace. Thus the resulting string literal in the above example is "mypass", and not "my pass", as the whitespaces prior to line starting with "pass" are trimmed first. Also, all statements are right-trimmed for white space, except if backslash is used at the end, in which case any spaces prior to backslash are conserved. For that reason, in the above example there is a space prior to a backslash where clauses need to be separated.

Note that begin-handler statement cannot be split with backsplash, i.e. it must always be on a single line for readability.

Comments

You can use both C style (i.e. /* ... */) and C++ style (i.e. //) comments with Gliimly statements, including within statements (with the exception of /*..*/ before statement name for readability), for example:

 run-query @db = \
     "select firstName, lastName from employee where yearOfHire>='%s'" \
     output /* comment within */ firstName, lastName : "2015" // other comment

Copied!

Error handling

A statement that fails for reasons that are generally irrecoverable will error out, for example out of memory or disk space, bad input parameters etc.

Gliimly philosophy is to minimize the need to check for such conditions by preventing the program from continuing. This is preferable, as forgetting to check usually results in unforeseen bugs and safety issues, and the program should have stopped anyway.

Errors that are correctable programmatically are reported and you can check them, for example when opening a file that may or may not exist.

Overall, the goal is to stop execution when necessary and to offer the ability to handle an issue when warranted, in order to increase run-time safety and provide instant clues about conditions that must be corrected.