Diferenças entre DelphiScript e Delphi

Diferenças entre DelphiScript e Delphi

Esta secção aborda as diferenças essenciais entre a linguagem de scripting DelphiScript e a linguagem de programação Delphi da Embarcadero, e como isto se aplica à API do Altium Designer.

O sistema de scripting do Altium Designer utiliza a linguagem DelphiScript sem tipos, pelo que não existem tipos de dados nos scripts. Embora possa declarar variáveis e os seus tipos, e especificar os tipos para funções/procedimentos ou parâmetros de métodos para melhorar a legibilidade, o DelphiScript converte variáveis não declaradas quando um script está a ser executado. Assim, por exemplo, não é possível definir registos nem classes.

Variáveis em Delphi Script

Todas as variáveis num script são do tipo Variant, e os tipos numa declaração de variável são ignorados e podem ser omitidos. Assim, estas três declarações estão corretas:

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

Os tipos de parâmetros numa declaração de procedimento/função também são ignorados e podem ser omitidos. Por exemplo, este código está correto:

Function Sum(a, b) : Integer;
Begin
  Result := a + b;
End;

De um modo geral, as variants podem ser usadas para armazenar qualquer tipo de dados e realizar numerosas operações e conversões de tipo. Uma variant é verificada e avaliada em tempo de execução. O compilador não fornecerá um aviso sobre possíveis erros no código, os quais só podem ser detetados com testes exaustivos. No geral, as partes do código que utilizam variants podem ser consideradas código interpretado, porque muitas operações não podem ser resolvidas até ao tempo de execução. Isto pode afetar a velocidade do código.

O resultado disto é que, depois de uma variável variant ter sido declarada e ter obtido um valor variant, pode ser copiada para qualquer tipo de dados compatível ou incompatível :

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

Se um tipo de dados incompatível tiver sido atribuído a uma variável, o interpretador DelphiScript executa uma conversão sempre que possível. Caso contrário, é emitido um erro em tempo de execução. Na prática, uma variant armazena informações de tipo juntamente com os dados, pelo que o DelphiScript é mais lento do que o código compilado equivalente em Delphi da Embarcadero.

Conjuntos em Scripts

O DelphiScript não tem tipos Set e não suporta operadores Set, ao contrário da linguagem Delphi, que tem tipos Set e suporta operadores Set.

Para usar Sets em scripts DelphiScript, utilize as funções incorporadas que manipulam conjuntos num script.

Consulte a entrada Utilizar Sets em DelphiScript para mais informações

Funções ou Procedimentos Internos

Ao considerar a utilização de Funções e Procedimentos inside uma Function ou Procedure, a abordagem recomendada é escrever funções/procedimentos autónomos — embora procedimentos/funções recursivos sejam permitidos.

O seguinte excerto de função não é recomendado:

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

Estrutura de função recomendada:

Function B
Begin
// blah
End;

Function A
Begin
B;
End;

Palavra-chave Result

Utilize a palavra-chave Result para definir o valor de retorno dentro de um bloco de função. Por exemplo:

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

Rotinas Aninhadas

As rotinas aninhadas são suportadas, mas as variáveis da função de nível superior não podem ser utilizadas a partir da função aninhada.

Elementos de Array

O tipo dos elementos do array é ignorado e pode ser omitido, pelo que estas duas declarações são equivalentes:

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

Var
x : array [1..2];

Tenha em atenção que não é possível declarar tipos de array, mas é possível declarar arrays em variáveis.

Illegal example:

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

Legal example:

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

Declaração de Open Array

A declaração Open Array não é suportada.

Palavra-chave Case

A palavra-chave Case pode ser usada para qualquer tipo. Assim, o seguinte é válido:

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

Declarações de Classe

Não é possível definir novas classes em DelphiScript, mas pode utilizar classes DelphiScript existentes e instanciá-las. Por exemplo, as classes TList e TStringList podem ser criadas e utilizadas nos seus scripts.
See also
TList
TStringList

Função CreateObject

A função CreateObject pode ser usada para criar objetos que serão implicitamente libertados quando deixarem de ser utilizados.

Assim, em vez de:

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

...pode escrever:

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

See also
Função CreateObject.

Gerar Exceções

A palavra-chave Raise pode ser usada sem parâmetros para voltar a gerar a última exceção. Raise também pode ser usada com um parâmetro string para gerar a exceção com a mensagem especificada. Os objetos Exception não são suportados em DelphiScript, porque a palavra-chave On não é suportada.

Example:

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

See also
Palavras-chave Try, Finally e Raise.

ThreadVar

Em Delphiscript, a palavra-chave Threadvar é tratada como Var. Tenha em atenção que, em Delphi da Embarcadero, as variáveis declaradas com a palavra-chave Threadvar têm valores distintos em cada thread.

Operadores Set

O operador Set In não é suportado. O operador InSet pode ser usado para verificar se um valor é membro de um conjunto. Por exemplo:

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

Tenha em atenção que os operadores set do Delphi +, -, *, <=, >= não funcionam corretamente. Em vez disso, são utilizadas as funções incorporadas do Delphiscript MkSet, MkSetRange, SetUnion, SetDifference, SetIntersection, SubSet and InSet:

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

Os construtores set [...] não são suportados — utilize a função MkSet para criar um Set:

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

See also
MkSet palavra-chave
MkSetRange palavra-chave
InSet palavra-chave
SetDifference palavra-chave
SetIntersection palavra-chave
SetUnion palavra-chave
SubSet palavra-chave
InSet palavra-chave

Operadores

Os operadores ^ e @ não são suportados.

Diretivas

As seguintes diretivas não são suportadas (tenha em atenção que algumas estão obsoletas e também não são suportadas pelo Delphi da Embarcadero): 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.

Além disso, tenha em atenção que a diretiva in na cláusula Uses é ignorada.

Palavras-chave Ignoradas

As palavras-chave interface, implementation, program e unit são ignoradas em DelphiScript. Os scripts podem contê-las, mas não têm qualquer efeito — no entanto, estas palavras-chave podem melhorar a legibilidade dos scripts.

Palavras-chave Não Suportadas

As seguintes palavras-chave não são suportadas em DelphiScript:

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

As seguintes funções RTL do Delphi não são suportadas em DelphiScript:

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

As funções da unit Windows do Delphi (o ficheiro windows.pas) não são suportadas (por exemplo, a função RGB não é suportada).

Utilizar a API do Altium Designer em scripts

Não pode criar os seus próprios tipos de registos ou classes utilizando DelphiScript e instanciá-los num script; no entanto, pode utilizar determinadas classes da API do Altium Designer. Por exemplo, as classes TStringList e TList podem ser instanciadas e usadas como contentores de armazenamento de dados (normalmente do mesmo tipo) para satisfazer as necessidades de um script.

As interfaces de objeto da API que representam objetos do Altium Designer estão disponíveis para utilização em scripts. Por exemplo, tem a possibilidade de atualizar objetos de projeto em documentos Schematic e PCB através da utilização de interfaces de objeto Schematic e interfaces de objeto PCB.

Por convenção, os nomes das interfaces têm um 'I' adicionado no início do nome. Por exemplo, IPCB_Board representa uma interface para um documento PCB existente.

Exemplo de interfaces PCB num script:

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;

As seguintes APIs podem ser utilizadas em Scripts:

• Determinadas funções e classes do Delphi™ da Embarcadero, e extensões DelphiScript
• API Client
• API PCB Server
• API Schematic Server
• API Workspace Manager Server
• API Integrated Library
• Funções da API do Altium Designer
• Processos paramétricos

Mais Informações

Consulte os scripts na coleção de scripts descarregável para ver interfaces de objeto e funções do Altium Designer, bem como objetos e funções Delphi utilizados em scripts.

Consulte a documentação principal de Scripting para obter informações sobre como escrever scripts para o Altium Designer.

Consulte o guia Utilizar a API do Altium Designer para obter detalhes sobre como usar objetos de projeto e as respetivas interfaces nos seus scripts.

Consulte a Referência da API do Altium Designer para obter informações sobre a gama de APIs do Altium Designer e os seus Objetos de Interface para scripts.