Delphi - DelphiScript differences

Parent page: DelphiScript

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.

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 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
• Nexus (FPGA) API
• Altium Designer API functions
• Parametric processes

More information