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 dostatementWhile expression dostatementWith expression dostatement.
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 statementTry statement except exception Else statement endCase 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 statementfor 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 expressionnot 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 expressioninteger 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