DelphiScript Keywords Supported in Altium Designer
This reference covers the DelphiScript keywords used for the Scripting System in Altium Designer. The scripting system supports the DelphiScript language, which is very similar to the Embarcadero Delphi™ programming language. The key difference is that DelphiScript is a typeless scripting language.
In this section, common DelphiScript keywords are outlined with detailed information and examples. For more keyword information, such as Delphi file, math, and string handling routines, see Functions and the Embarcadero Delphi Reference.
And
Declaration
The And
operator performs a logical/bitwise and.
Description
The And
operator performs a logical, and if the operators are of a boolean type or a bitwise And if the operators are integers.
Example of a boolean And evaluation:
Var
I, J : Integer
Begin
I := $F0;
J := $8F;
ShowMessage(IntToStr(I and J));
End;
Example of a logical And evaluation:
Var
S : String;
Begin
S := '';
If (Length(S) > 0) and (S[1\] = 'X') Then Delete(S,1,1);
End;
See also
Or keyword
Xor keyword
Array
Declaration
Array [index range];
Description
DelphiScript language is a type-less language, so the size or range of an array needs to be specified. What type of elements the array can hold can still be defined, but it is not necessary. The Open array
declaration is not supported.
Example:
var x : array [1..2];
Begin
Declaration
Begin
statement
End;
Description
The begin
keyword starts a block in the script. A block is the main body of a script and can enclose any number of statements, and can be used anywhere a single statement is required, such as the body of a conditional or loop statement.
Example:
Var
Test : Integer;
Begin
Test := Test + 4;
ShowMessage(IntToStr(Test));
End;
See also
End keyword
Break
Declaration
Break;
Description
A Break
jumps out of a loop which is similar to a Goto
statement.
Example:
While Condition Do
Begin
DoSomething;
Begin
If AnotherCondition Then
Break;
End;
End;
See also
While keyword
Continue keyword
Do keyword
Repeat keyword
Case
Declaration
Case expression Of
Value range : Expression;
Else Expression;
End;
Description
The Case
statements select one branch out of many possible branches, depending on the value of the expression.
In many situations a complex set of If
statements can be simplified by replacing them with Case
statements. A case
statement in an expression is used to select a value, a list of possible values, or a range of values. Any Types can be used in a case
statement because DelphiScript is an untyped language. Case
statements can have an else
statement that is executed if none of the labels correspond to the value of the selector (within the Case Of
condition).
Example 1:
Case Char Of
'+' : Text := 'Plus sign';
'-' : Text := 'Minus sign';
'*', '/': Text := 'Multiplication or division';
'0'..'9': Text := 'Number';
'a'..'z': Text := 'Lowercase character';
'A'..'Z': Text := 'Uppercase character';
Else
Text := 'Unknown character';
End;
Example 2:
Case UserName Of
Jack', 'Joe' : IsAdministrator := true;
'Fred' : IsAdministrator := false;
Else
Raise('Unknown User');
End;
See also
Of keyword
Continue
Declaration
Continue
Description
The Continue
statement jumps over the body of a loop, similar to the Goto
statement;
Example:
Var
I := 0; s:= 1;
Begin
While True Do
Begin
S := S \* 2;
I := I \\+ 1;
If I <> 4 then continue;
Break;
End;
See also
Break keyword
While keyword
Continue keyword
Do keyword
Repeat keyword
Const
Declaration
Const
Name = Expression;
Description
The Const
keyword specifies any constant valued expression as the value of a constant. If you try to modify the expression that is of a const
type in the script, the scripting system will throw an undeclared identifier error.
Example:
Const
b = 30;
Begin
ShowMessage(IntTtStr(b));
End;
An attempt to change the value of the b const
parameter will generate an error, for example:
Const
b = 30;
Begin
b := 40;
ShowMessage(IntToStr(b));
End;
Div
Declaration
dividend div divisor
Description
The Div
operator performs integer division that discards fractional results without rounding. If the divisor is zero, DelphiScript reports an error.
See also
Mod Operator
Div Operator
Do
Declaration
For variable := expression1 to expression2 do
statementWhile expression do
statementWith expression do
statement.
Description
The Do
keyword is part of DelphiScript's For, While and With
statements.
Example:
For i := 0 To AnIndex - 1 Do
S := S + #13 + AString;
See also
For keyword
To keyword
While keyword
With keyword
DownTo keyword
DownTo
Declaration
For variable := expression1 DownTo expression2 Do statement.
Description
Use DownTo
in a For
loop to count down.
See also
For keyword
To keyword
Do keyword
Else
Declaration
If condition then statement Else statement
Try statement except exception Else statement end
Case expression of Else end;
Description
The Else
keyword introduces the catch all part of several statements. Note that the else
part of an if
statement is followed by a single statement, but the else
part of the try-except
and case
statements can have multiple statements.
See also
If keyword
Then keyword
Try keyword
Case keyword
End
Declaration
Begin statements End;
Try statements Except Exception clauses... else Statements... End;
Try statements Finally statements End;
Case Expression of clauses Else statements... End;
Description
The End
keyword ends a block or a multiple part such as declarations, Case
statements and so on.
See also
Begin keyword
Case keyword
Try keyword
Except
Declaration
Try statements Except statements End;
Description
Use Try-Except
blocks to handle exceptional cases, for example, to catch specific exceptions and do something useful with them, such as add them to an error log or create a friendly dialog box. Since the On
keyword is not supported in DelphiScript, use the Raise
statement inside the Except
block and only report a textual message.
Example:
Try
X := Y/Z;
Except
Raise('A divide by zero error!');
End;
See also
End keyword
Finally keyword
Try keyword
Finally
Declaration
Try statements... Finally statements... End;
Description
The finally
keyword starts the finally part of a try-finally
block. The statements in the finally
block always run, no matter how the control leaves the try
block exception, exit, or break. The use of the try-finally
block is recommended when dealing with the creation/destruction of objects and File IO.
See also
End keyword
Raise keyword
Try keyword
For
Declaration
for variable := expression1 to expression2 do statement
for variable := expression1 downto expression2 do statement
Description
A for
loop evaluates the expressions that specify the limits of this loop, then performs the loop body repeatedly via the loop control variable, which is updated after each iteration.
Example:
For i := 0 to AnIndex - 1 Do
Begin
S := S + #13 + AString;
End;
ShowMessage(S);
See also
Do keyword
DownTo keyword
Repeat keyword
To keyword
While keyword
With keyword
Forward
Declaration
subroutine header; forward;
Description
The Forward
directive allows a function or procedure to be declared before it is called by declaring the header (name, parameters, and return type) with the forward
directive.
Function
Declaration
Function name (parameters) : return type;
Description
A Function
is a subroutine that returns a value. Note that pointers to functions are not permitted in scripts — that is, functional types cannot be defined. Variables declared inside a function are not accessible outside this procedure.
Example
Function TestFunc(Min, Max : integer) : integer;
Begin
Result := Random(Max - Min +1);
End;
Goto
Declaration
goto label
Description
The goto
statement transfer control to the given label. The label can be any identifier or a digit string with up to four digits.
Example
Label StartHere;
// code
StartHere: //do anything;
Goto StartHere;
See also
Label keyword
If
Declaration
if condition then statement;
if condition then statement1 else statement2;
Description
The condition for the If
keyword must be a boolean expression. The Else
keyword is optional.
Example
If A > B Then
ShowMessage('X>Y and A > B');
Else
ShowMessage('X>Y and A <=B');
End;
See also
And keyword
Begin keyword
Or keyword
Then keyword
Else keyword
Interface
Declaration
Interface
// Globally unique identifier string.
Methods
Properties
End;
Description
The interface
keyword enables access to an existing object in memory and invokes the object's methods. An interface can only consist of properties and methods — no data. Since interfaces cannot contain data, their properties must write to and read from methods. Most importantly interfaces have no implementation, as they only define a contract to an existing object in memory.
An interface can be thought of as a contact point to an existing object in the computer's memory, and offers the ability to read/write data through properties of the interface. The interface requests data from its associated object.
DelphiScript is a typeless language, therefore you cannot define new types such as new records, arrays or classes, and associated interfaces as well.
Label
Declaration
label digits, identifier, ...;
Description
The label
keyword declares one or more labels. A label can be a digit string with up to four digits or an identifier. A label can be used in the same block to identify a statement as the target of a goto
statement.
Example:
Label StartHere;
// code
StartHere: //do anything;
Goto StartHere;
See also
Goto keyword
Mod
Declaration
Integer expression mod integer expression
Description
The mod
operator performs an integer modulus or remainder operation. The result of A mod B
is A - (A div B) * B
.
See also
Div function
Nil
Declaration
const nil = pointer(0);
Description
The nil
keyword is a special pointer value that is guaranteed to be distinct and pointing to nothing.
Not
Declaration
not boolean expression
not integer expression
Description
The not
operator performs a negation. If the operand is a boolean type, the negative is logical negation. Not False = True
and not true = false
. If the operand is an integer, the not
operator performs a bitwise negation of each bit in the integer value — that is, a complement operation.
Of
Declaration
case expression of
selector: expression1
...
end
Description
The Of
keyword is used for the case
statement.
See also
Case statement
Or
Declaration
boolean expression or boolean expression
integer expression or integer expression
Description
The or
operator performs a logical Or if the operands are of boolean type, or a bitwise Or if the operators are integers. A logical Or is false only if both operands are false, otherwise, it is true when at least one operand is true.
See also
And keyword
Not keyword
Shl keyword
Shr keyword
Xor keyword
Procedure
Declaration
Procedure name;
Procedure Name (Parameter, ...);
Description
The procedure
keyword declares a subroutine that does not have a return type. Variables declared inside a procedure are not accessible outside this procedure. Note that this keyword can be used but it is ignored by the scripting system.
Example:
Procedure TestRand(Var Rand: Integer; Max : Integer);
Begin
Rand := Random(Max);
End;
See also
Function keyword
Program
Declaration
Program Name;
declarations...
Block
Description
The program
keyword begins a script. The file extension for a script is *.pas
. Note that this keyword can be used but it is ignored by the scripting system.
See also
Function keyword
Raise
Declaration
Raise statement;
Description
The raise
keyword is related to the Try
keyword. The Raise
keyword can be used without parameters to re-raise the last exception. It can also be used with a string parameter to raise an exception using a specific message.
Example:
Raise(Format('Invalid Value Entered : %d', \[Height]));
Note that the On
keyword is not supported in DelphiScript, so the Exception
objects cannot be used in scripts.
Repeat
Declaration
repeat
statements;
until boolean expression
Description
The statements inside a Repeat Until
block are executed repeatedly until the boolean expression is true.
Example:
Repeat
Write('Enter a value (0..9): ');
ShowMessage(IntToStr(I));
Until (I >= 0) and (I <= 9);
See also
Until keyword
Result
Declaration
Var result : Function return type;
Description
Every function in a script must use the Result
keyword to return a resultant value. The variable type is the return type of the function.
See also
Function keyword
Shl
Declaration
value shl bits
Description
The shl
operator performs a left shift of an integer value by Bits
bit positions. The vacated bits are filled on the right with zero bits.
See also
And keyword
Not keyword
Or keyword
Shr keyword
Xor keyword
Shr
Declaration
value shr bits
Description
The shr
operator performs a right shift of an integer value by Bits
bit positions. The vacated bits are filled on the left with zero bits.
See also
And keyword
Not keyword
Or keyword
Shl keyword
Xor keyword
String
Declaration
type string;
type Name = string[Constant]
Description
The string
keyword represents the string type.
Then
Declaration
If expression then statement
Description
The Then
keyword is part of an If
statement.
See also
If keyword
To
Declaration
For variable := expression1 to expression2 do statement
Description
The to
keyword is part of a for
loop that counts up.
Example
For i := 0 to AnIndex - 1 do
S := S + #13 + AString;
See also
Downto keyword
For keyword
Try
Declaration
Try statements finally statements end;
Try statements except statements end;
Description
The try
keyword introduces a try-except
statement or a try-finally
statement. These two statements are related but serve different purposes.
Try Finally
The statements in the finally
block are always executed no matter how control leaves the try block exception, Exit, or Break. Use the try-finally
block to free temporary objects and other resources and to perform clean-up activities. Typically you do not need more than one try-finally
statement in a subroutine.
Example:
Reset(F);
Try
... // process file F
Finally
CloseFile(F);
End;
Try Except
Use try-except
to handle exceptional cases, for example, to catch specific exceptions and do something useful with them, such as add them to an error log or create a friendly dialog box. Since the On
keyword is not supported in DelphiScript, use the Raise
statement inside the Except
block.
Example:
Try
X := Y/Z;
Except
Raise('A divide by zero error!');
End;
See also
Raise keyword
Type
Declaration
Type Name = type declaration ...
Description
The Type
keyword declares the type for a variable. Since DelphiScript is a typeless language, it is not necessary to declare variables of a specific type, but this can be done for the sake of readability in scripts. All variables in a script are always of Variant type. The major limitation in writing scripts is that you cannot declare records or classes.
Typecasting is ignored in scripts so Types in variable declaration are ignored and can be skipped. These declarations are therefore correct:
Example:
var a : integer;
var b : integer;
var c, d;
Types of parameters in procedure/function declaration are ignored and can be skipped. For example, this code is correct:
Function sum(a, b) : integer;
Begin
Result := a + b;
End;
In general, variants can be used to store any data type and perform numerous operations and type conversions. A variant is type-checked and computed at run time. The compiler won't warn of possible errors in the code, which can be caught only with extensive testing. On the whole, the code portions that use variants can be considered to be interpreted code, because many operations cannot be resolved until run time. This can affect the speed of the code.
Example:
Var
V
Begin
// you can assign to it values of several different types:
V := 10;
V := 'Hello, World';
V := 45.55;
End;
See also
Var keyword
Unit
Declaration
Unit Name;
interface
declarations
implementation
declarations
statements
Initialization
statements
finalization
statements
end.
Unit Name;
interface
declarations
implementation
declarations
statements
begin
statements
end.
The unit
keyword introduces a unit, which is the basic module for a script. Note that this keyword can be used but it is ignored by the scripting system.
See also
Function keyword
Program keyword
Until
Declaration
Repeat
Statements;
Until boolean expression
Description
The until
keyword marks the end of the Repeat-Until
block. The statements inside a Repeat-Until
block are executed repeatedly until the boolean expression is true.
Example:
Repeat
Write('Enter a value (0..9): ');
ShowMessage(IntToStr(I));
Until (I >= 0) and (I <= 9);
See also
Repeat keyword
Uses
Declaration
Uses Unit Name, ...;
Description
The uses
keyword lists the names of units that are imported into the surrounding unit. The uses
declaration is optional because the scripting system has supported units that are imported in Altium Designer. You can include the uses declaration for the sake of readability.
All units stored within the same project can access global variables from any of these units. Keep this in mind when declaring variables in units within the same project.
Altium Designer's Client, PCB, Schematic, and WorkSpace Manager APIs and Delphi's SysUtils, Classes, and other units are imported and available for use in scripts - so there is no specific need to declare these units in scripts.
See also
For more detailed information on the Altium Designer API, refer to the Using the Altium Designer API documentation.
Var
Declaration
Name : Type
Name : Type = Expression;
DelphiScript Variables
All variables in a script are always of Variant type. Typecasting is ignored. Types in variables declaration are ignored and can be skipped, so these declarations are correct:
Var a : integer;
Var b : integer;
Var c, d;
Types of parameters in procedure/function declaration are ignored and can be skipped. For example, this code is correct:
Function sum(a, b) : integer;
Begin
Result := a + b;
End;
In general, variants can be used to store any data type and perform numerous operations and type conversions. A variant is type-checked and computed at run time. The compiler won't warn of possible errors in the code, which can be caught only with extensive testing. On the whole, the code portions that use variants can be considered to be interpreted code, because many operations cannot be resolved until run time. This can affect the speed of the code.
Declaring a variant variable:
Var
V;
Begin
// you can assign to it values of several different types:
V := 10;
V := 'Hello, World';
V := 45.55;
End;
Array elements
the Type of array elements is ignored and can be skipped so these declarations are equivalent:
Var x : array [1..2] of double;
Var x : array [1..2];
Illegal array example:
Type
TVertices = Array [1..50] Of TLocation;
Var
NewVertices : TVertices;
Legal array example:
Var
NewVertices : Array [1..50] of TLocation;
While
Declaration
while expression do statement
Description
The while
statement repeatedly executes the statement while the expression is true.
See also
Break keyword
Continue keyword
Do keyword
DownTo keyword
For keyword
Repeat keyword
To keyword
With keyword
With
Declaration
with expression do statement
Description
The With
statement adds a record, object, class, or interface reference to the scope for resolving symbol names.
Normal version example:
Form.Canvas.Pen.Width := 2;
Form.Canvas.Pen.Color := clSilver;
With version example:
With Form.Canvas.Pen do
Begin
Width := 2;
Color := clSilver;
End;
See also
Do keyword
Xor
Declaration
- boolean expression Xor boolean expression
integer expression Xor integer expression
Description
The xor
operator performs an Exclusive Or on its operands. If the operands are of boolean type, it returns a boolean result — true if the operands are different and false if they are the same.
An integer xor
operates on each bit of its operands, setting the result bit to 1
if the corresponding bits in both operands are different, and to 0 if both operands have identical bits. If one operand is smaller than the other, the smaller operand is extended with 0
in the left-most bits.
See also
And keyword
Not keyword
Or keyword
Shl keyword
Shr keyword