Differences between DelphiScript and Delphi

Differences between DelphiScript and Delphi

This section covers the essential differences between the DelphiScript scripting language and Embarcadero's Delphi programming language, and how this applies to the Altium Designer API.

The Altium Designer scripting system uses untyped DelphiScript language so there are no data types in scripts. Although you can declare variables and their types, and specify the types for functions/procedures or method parameters for readability, DelphiScript will convert undeclared variables when a script is being executed. So for example, you cannot define records or classes.

Delphi Script Variables

All variables in a script are of Variant type, and Types in a variable declaration are ignored and can be skipped. So these three declarations are correct:

Var
a : Integer;
 
Var
b : Integer;
 
Var
  c, d;

Types of parameters in a procedure/function declaration are also 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 provide a warning 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.

The result of this is that once a variant variable has been declared and has obtained a variant value, it can be copied to any compatible or incompatible data type:

Var
V;
Begin
  // variable V can be assigned values of several different types:
  V := 10;
  V := 'Hello, World';
  V := 45.55;
End;

If an incompatible data type has been assigned to a variable the DelphiScript interpreter performs a conversion where possible. Otherwise, a run-time error is issued. In practice, a variant stores type information along with the data so DelphiScript is slower than the equivalent Embarcadero Delphi compiled code.

Sets in Scripts

DelphiScript does not have Set types and does not support Set operators, unlike the Delphi language which does have Set types and supports Set operators.

To use Sets in DelphiScript scripts, use the built-in functions that manipulate sets in a script.

See the Using Sets in DelphiScript entry for more information

Internal Functions or Procedures

When considering using Functions and Procedures inside a Function or Procedure, the recommended approach is to write standalone functions/procedures — although recursive procedures/functions are permitted.

The following function snippet is not recommended:

Function A
Function B
Begin
// blah
End;
Begin
B;
End;

Recommended function structure:

Function B
Begin
// blah
End;

Function A
Begin
B;
End;

Result Keyword

Use the Result keyword to set the return value within a function block. For example:

Function Foo : String;
Begin
Result := 'Foo Foo';
End;

Nested Routines

Nested routines are supported, but variables of the top-level function can't be used from the nested one.

Array Elements

The Type of array elements is ignored and can be skipped, so these two declarations are equal:

Var
x : array [1..2] of double;

Var
x : array [1..2];

Note that you cannot declare array types, but you can declare arrays to variables.

Illegal example:

Type
TVertices = Array [1..50] Of TLocation;
Var
NewVertices : TVertices;

Legal example:

Var
NewVertices : Array [1..50] of TLocation;

Open Array Declaration

The Open Array declaration is not supported.

Case Keyword

The Case keyword can be used for any type. So the following is valid:

Case UserName of
'Alex', 'John' : IsAdministrator := true;
'Peter' : IsAdministrator := false;
Else
Raise('Unknown user');
End;

Class Declarations

New classes cannot be defined in DelphiScript, but you can use existing DelphiScript classes and instantiate them. For example the TList and TStringList classes can be created and used in your scripts.
See also
TList
TStringList

CreateObject Function

The CreateObject function can be used to create objects that will be implicitly freed when no longer used.

So instead of:

Procedure Proc;
Var
  l;
Begin
    l := TList.Create;
  Try
    // do something with l
  Finally
  L.Free;
End;

...you can write:

Procedure Proc;
Var
  l;
Begin
  l := CreateObject(TList);
  // Do something with l
End;

See also
CreateObject function.

Raise Exceptions

The Raise keyword can be used without parameters to re-raise the last exception. Raise can also be used with a string parameter to raise the exception with the specified message string. The Exception objects are not supported in DelphiScript, because the On keyword is not supported.

Example:

Raise(Format('Invalid value : %d', [Height]));

See also
Try, Finally and Raise keywords.

ThreadVar

In Delphiscript, the Threadvar keyword is treated as Var. Note that in Embarcadero Delphi, the variables declared using the Threadvar keyword have distinct values in each thread.

Set Operators

The Set operator In is not supported. The InSet operator can be used to check whether a value is a member of a set. For example:

If InSet(fsBold, Font.Style) then
ShowMessage('Bold');

Note that Delphi set operators +, -, *, <=, >= do not work correctly. The built-in Delphiscript functions MkSet, MkSetRange, SetUnion, SetDifference, SetIntersection, SubSet and InSet are used instead:

ASet := BSet + CSet; \\ should be changed to
ASet := SetUnion(BSet, CSet);

The [...] set constructors are not supported — use the MkSet function to create a Set:

Font.Style := MkSet(fsBold, fsItalic); 

See also
MkSet keyword
MkSetRange keyword
InSet keyword
SetDifference keyword
SetIntersection keyword
SetUnion keyword
SubSet keyword
InSet keyword

Operators

The ^ and @ operators are not supported.

Directives

The following directives are not supported (note that some are obsolete, and are also not supported by Embarcadero Delphi): absolute, abstract, assembler, automated, cdecl, contains, default, dispid, dynamic, export, external, far, implements, index, message, name, near, nodefault, overload, override, package, pascal, private protected, public, published, read, readonly, register, reintroduce, requires, resident, safecall, stdcall, stored, virtual, write, writeonly.

Also, note that the in directive in the Uses clause is ignored.

Ignored Keywords

The interface, implementation, program and unit keywords are ignored in DelphiScript. The scripts can contain them but they have no effect — however, these keywords can enhance the readability of scripts.

Unsupported Keywords

The following keywords are not supported in DelphiScript:

• as, asm, class, dispinterface, exports, finalization, inherited, initialization, inline, interface, is, library, object, out, property, record, resourcestring, set, supports, type.

The following Delphi RTL functions aren't supported in DelphiScript:

• Abort, Addr, Assert, Dec, FillChar, Finalize, Hi, High, Inc, Initialize, Lo, Low, New, Ptr, SetString, SizeOf, Str, UniqueString, VarArrayRedim, VarArrayRef, VarCast, VarClear, VarCopy.

The functions from the Delphi's Windows unit (the windows.pas file) are not supported (for example the RGB function is not supported).

Using the Altium Designer API in scripts

You cannot create your own records or classes types using DelphiScript and instantiate them in a script, however, you can use certain classes from the Altium Designer API. For example, the TStringList and TList classes can be instantiated and used as containers of data storage (usually of the same type) to meet the needs of a script.

The API's Object Interfaces that represent Altium Designer objects are available to use in scripts. For example, you have the ability to update design objects on Schematic and PCB documents through the use of Schematic object interfaces and PCB objects interfaces.

As a convention, interface names have an 'I' added in front of the name. For example IPCB_Board represents an interface for an existing PCB document.

PCB Interfaces in a script example:

Procedure ViaCreation;
Var
  Board : IPCB_Board;
  Via : IPCB_Via;
Begin
  Board := PCBServer.GetCurrentPCBBoard;
  If Board = Nil Then Exit;
 
  (\* Create a Via object\* )
  Via           := PCBServer.PCBObjectFactory(eViaObject, eNoDimension, eCreate_Default);
  Via.X         := MilsToCoord(7500);
  Via.Y         := MilsToCoord(7500);
  Via.Size      := MilsToCoord(50);
  Via.HoleSize  := MilsToCoord(20);
  Via.LowLayer  := eTopLayer;
  Via.HighLayer := eBottomLayer;
 
  (* Put this via in the Board object*)
  Board.AddPCBObject(Via);
End;

The following APIs can be used in Scripts:

• Certain Embarcadero Delphi™ functions and classes, and DelphiScript extensions
• Client API
• PCB Server API
• Schematic Server API
• Workspace Manager Server API
• Integrated Library API
• Altium Designer API functions
• Parametric processes

More Information

Check the scripts in the downloadable scripts collection to see Altium Designer Object Interfaces and functions, plus Delphi objects and functions being used in scripts.

Refer to the main Scripting documentation for information on writing scripts for Altium Designer.

Refer to the Using the Altium Designer API guide for details on how to use design objects and their interfaces in your scripts.

Refer to the Altium Designer API Reference for information on the range of Altium Designer APIs and their Interface Objects for scripts.