Rules of GDL Syntax

This chapter presents the basic elements of GDL syntax, including statements, labels, identifiers, variables and parameters. Typographic rules are also explained in detail.

Rules of GDL Syntax

GDL is not case sensitive; uppercase and lowercase letters are not distinguished, except in strings placed between quotation marks.
The logical end of a GDL script is denoted by an END / EXIT statement or the physical end of the script.


A GDL program consists of statements.
A statement can start with a keyword (defining a GDL shape, coordinate transformations or program control flow), with a macro name, or with a variable name followed by an ‘=’ sign and an expression.


The statements are in lines separated by line-separators (end_of_line characters).

A comma (,) in the last position indicates that the statement continues on the next line.
A colon (:) is used for separating GDL statements in a line. After an exclamation mark (!) you can write any comment in the line.
Blank lines can be inserted into a GDL script with no effect at all. Any number of spaces or tabs can be used between the operands and operators.
The use of a space or tab is obligatory after statement keywords and macro calls.


Any line can start with a label which is used as a reference for a subsequent statement.
A label is an integer number or a constant string between quotation marks, followed by a colon (:). A string label is case sensitive.
Labels are checked for single occurrence. The execution of the program can be continued from any label by using a GOTO or GOSUB statement.


The GDL text is composed of the lower and uppercase letters of the English alphabet, any number and the following characters:

<space> _(underline) ~ ! : , ; . + - * / ^ = < > <= >= # ( ) [ ] { } @ & |(vertical bar) " ' ` ´ “ ” ’ ‘ <end_of_line>


Any string of Unicode characters that is placed between quotation marks (“, ‘, “, ’, `, ´), or any string of characters without quotation marks that does not figure in the script as an identifier with a given value (macro call, attribute name, file name). Strings without quotation marks will be converted to all caps, so using quotation marks is recommended.

The maximum length allowed in a string is 255 characters.

The ‘\’ character has special control values. Its meaning depends on the next character.

\\ ‘\’ char itself
\n new line
\t tabulator
\new line continue string in next line without a new line
\others not correct, results in warning


"This is a string"
`washbasin 1'-6"*1'-2`
'Do not use different delimiters’

Localized strings use special syntax. They start with _( characters and end with ). Compatibility: introduced in ARCHICAD 23.


_("This is a localized string")
_(`This is another localized string`)


Identifiers are special ASCII character strings:
  • they are not longer than 255 characters;
  • they begin with a letter of the alphabet or a ‘_’ or ‘~’
  • they consist of ASCII letters, numbers and ‘_’ or ‘~’
  • upper- and lowercase letters are considered identical.

Identifiers can be GDL keywords, global or local variables or strings (names).
Keywords and global variable names are determined by the program you’re using GDL in; all other identifiers can be used as variable names.


GDL programs can handle numeric and string variables (defined by their identifiers), numbers and character strings.

There are two sets of variables: local and global.

All identifiers that are not keywords, global variables, attribute names, macro names or file names are considered local variables. If left uninitialized (undefined), their value will be 0 (integer). Local variables are stacked with macro calls. When returning from a macro call, the interpreter restores their values.

Global variables have reserved names (for the list of global variables see the section called “Global Variables”). They are not stacked during macro calls, enabling the user to store special values of the modeling and to simulate return codes from macros. The user global variables can be set in any script but they will only be effective in subsequent scripts. If you want to make sure that the desired script is analyzed first, set these variables in the MASTER_GDL library part. All elements will always read these values set by the Master GDL first, unless their own scripts (caller object or called macro) modify those values. There is no user global data exchange between the different interpretation instances. The other global variables can be used in your scripts to communicate with the program. By using the “=” command, you can assign a numeric or string value to local and global variables.


Identifiers listed in a library part’s parameter list are called parameters. Parameter identifiers must not exceed 31 characters in length. And the maximum number of parameters must not exceed 1024. Within a script, the same rules apply to parameters as to local variables.

Parameters of text-only GDL files are identified by letters A to Z.

Simple Types

Variables, parameters and expressions can be of two simple types: numeric or string.

Numeric expressions are constant numbers, numeric variables or parameters, functions that return numeric values, and any combination of these in operations. Numeric expressions can be integer or real. Integer expressions are integer constants, variables or parameters, functions that return integer values, and any combination of these in operations which results in integers. Real expressions are real constants, variables or parameters, functions that return real values, and any combination of these (or integer expressions) in operations which results in reals. A numeric expression being an integer or a real is determined during the compilation process and depends only on the constants, variables, parameters and the operations used to combine them. Real and integer expressions can be used the same way at any place where a numeric expression is required, however, in cases where a combination of these may result in precision problems, a compiler warning appears (comparison of reals or reals and integers using relational operators ‘=’ or ‘<>’, or boolean operators AND, OR, EXOR; IF or GOTO statements with real label expressions).

String expressions are constant strings, string variables or parameters, functions that return strings, and any combination of these in operations which result in strings.

Derived Types

Variables and parameters can also be arrays, and parameters can be value lists of a simple type.

Arrays are one- or two-dimensional tables of numeric and/or string values, which can be accessed directly by indexes.

Value lists are sets of possible numeric or string values. They can be assigned to the parameters in the value list script of the library part or in the MASTER_GDL script, and will appear in the parameter list as a pop-up menu.

Structured Types

Variables and parameters can also be dictionaries. Compatibility: introduced in ARCHICAD 23.

Dictionaries are a hierarchical collection of key and value pairs. Keys can contain other dictionary, array, integer, string or floating-point type values.

Keys are considered identifiers (see the section called “Identifiers”) – same syntax rules apply, except the ‘~’ character is not allowed.

It is not allowed to use dictionary keys (even if they are simple type) in the following places:

Conventions Used in This Book


Square brackets mean that the enclosed elements are optional (if they are bold, they must be entered as shown).


command version number

Previous element may be repeated


Exclusive or relation between parameters of a command


Any GDL variable name


Any character string (must not contain quote character)



special characters

Must be entered as shown


Any GDL expression