On Land

Environment Information
At Rill Architects we run ArchiCAD on macOS. If you work at Rill, this is your stuff. If you don't, but you work in ArchiCAD, you may find something interesting. Anybody else, I don't know.

This is somewhat redundant with the GDL Syntax section of the reference guide. I'm trying to make it a little clearer.

Variables: A variable is piece of text that can hold a value. You can then use the variable in any situation where you would use the value. Parameters are variables, but not all variables are parameters. A BLOCK built from three variables:

BLOCK len, wid, hgt

Variables are one of the fundamentals of all programming. They enable you to use a value over and over in a program, with the ability to change the value in one place and have the change reflected everywhere.

In GDL, variable names can contain numbers but must begin with a letter, "_", or "~". They cannot have spaces. Variable and parameter names are technically not case-sensitive, but treat them like they are, I'll tell you why later.

Variable and parameter naming is a big component of style, and reasonable people can disagree on what is best. It is most important to be consistent, and not too cryptic. I have a "glossary" of terms that I try to stick to when naming variables. Length is len, quantity is qty, angle is ng, etc. So the variable representing the width of the bottom rail of a door leaf is botRailWid. The capitalization of each segment helps readability.

Keywords: These are the words you can't use for your variables and parameter names. Most of these words do things, and so we typically refer to them as "Commands", although you won't find this category in the reference guide. Kinds of commands include Shapes, Transformations, Directives, and Control Statements. More on these below.

Statements: There are two main kinds of statements. Commands do things using the tools in GDL, such as making things, moving around, and repeating actions. Assignments (my term) set values for variables, and have the form variable=value. (The ref guide describes a third type, the plain macro call, but it's too early for that and I don't write macro calls that way myself.) Examples of statements:

ADDx 1' !!!A transformation command
BLOCK 1', 2', 3' !! A shape command
thk=4" !! assignment
halfThk=thk*0.5 !! assignment

Shapes: These commands make things, placing elements in 2D or 3D. There are many shapes, and they vary in complexity. All the 2D shapes (and transformations) have a "2". (Examples: ADD2, LINE2, POLY2_B)

All shapes have arguments, which are values following the shape keyword. ("Arguments" is what they should be called. The error warnings in the editing environment call them "parameters", even though they are completely different from the parameters in the master window. Very confusing.) The arguments describe the details of that instance of the shape, primarily its dimensions and coordinates, but often including instructions on how to draw and model the shape. For example, the BLOCK statement above has three arguments, which represent the x, y, and z dimensions of the shape. Arguments can be variables or constants. A lot of the errors you will get, especially early on, will come from problems with arguments (they'll call them "parameters"): wrong number, wrong kind, missing commas, etc.

Transformations: Each shape is built on its own local origin. Transformations move and rotate the origin, so shapes can be placed where you want them. They can also change the proportions of the entire coordinate system. GDL is more like a conventional CAD program, where you would move the origin before giving a command, and less like Archicad, where the user can choose to ignore the origin while placing elements. The three transformation types are:

ADD (ADDx, ADDy, ADDz, ADD2) moves the origin along a given axis.

ROT (ROTx, ROTy, ROTz, ROT2) rotates the coordinate system around a given axis or vector.

MUL (MULx, MULy, MULz, MUL2) Changes the proportion and/or direction of the coordinate system along a given axis. MULs can be used to shrink the "world" by 10% (MULx 0.9), and they can be used to mirror (MULx -1).

DEL is not technically a transformation, but is part of the whole transformation scene. It "undoes" a given number of previous transformation commands. This is the "come back" part. DEL 1 steps back one step, DEL 5 undoes 5 steps.

With these two types of commands, you can use GDL at a very basic level. They embody my description of GDL as saying, "Go over there (transformation) and do something (shape)."

Directives: Issuing a directive is like changing the attribute settings in the info box. Examples: PEN, MATERIAL, FILL, LINE_TYPE, etc. Everything after the directive will be drawn/modeled with that attribute. This script:

PEN 10 ! red
BLOCK 1', 2', 3'
ADDx 2'
PEN 7 ! blue
BLOCK 1', 2', 3'

...will build two blocks, one with red edges, one with blue.

If there are no directives, the elements will built with the current settings of the tool.

Control Statements: These control the flow of the program, and manipulate the parameter buffer. Buffer manipulation (PUT, GET, USE) is stupendously powerful, and we'll get to it later. Flow control you need right away.

You will very, very frequently use the FOR/NEXT loop. This is how you repeat things in an orderly way for a given quantity. Example: balusters. You will almost always use the IF/THEN conditional statement, which says, "if the situation is this, do that, otherwise do the other." (IF/THEN is arguably the foundation concept in all information processing.) Every so often, you will need a DO/WHILE loop, which is a sort of open-ended FOR/NEXT, repeating an action until a condition is met.

Once your script reaches a certain level of complexity, you will be glad there's GOSUB, which allows you to break out sections of script, and refer to them by label. Instead of:

IF shp='ThisShape' THEN
    [dozens of lines]

IF shp='ThatShape' THEN
    [dozens of other lines]

You use:

IF shp='ThisShape' GOSUB 100
IF shp='ThatShape' GOSUB 200

    [dozens of lines]

    [dozens of other lines]

...which makes the structure of the script much clearer. The broken out parts are called subroutines.

Comments: Any line that starts with "!" will not be executed. If there's a "!" in the middle of the line, the rest of that line (until the return) is not executed. Text treated this way is called a comment. Why put the text in there if it's not going to do anything?

Primarily, as a note to yourself, and whoever else might be interested, about what you actually want the code to do. Comments should describe intent in plain english rather than script. While you're working on something, you wind up understanding it very well, even if it's complex. Six months later, when you go to revise it, it will be baffling, especially if it's complex. Comments help you remember what was going on and get back up to speed quickly.

Their other big function is to temporarily turn code off without deleting it. This is known as "commenting out". It is crucial in hunting down errors.

That's enough for now.