Depuração de Scripts

O sistema de Scripting do Altium Designer oferece um ambiente de depuração completo. O Scripting Debugger ajuda-o a identificar e resolver erros em scripts, disponibilizando um conjunto de ferramentas automatizadas e painéis de informação.

Erros de Script

Os erros mais comuns incluem métodos inválidos, operadores de agrupamento mal colocados, tipos incompatíveis, erros de lógica e erros tipográficos. Quando o sistema de scripting encontra um erro, o depurador interrompe o script e apresenta uma caixa de diálogo de erro a indicar o problema.

O exemplo abaixo mostra um script com um carácter de terminação em falta e a respetiva mensagem na caixa de diálogo de erro.

O depurador interrompe um script em resposta a erros de compilação ou de tempo de execução.

Depois de fechar a caixa de diálogo de erro, o código pode então ser corrigido e o script executado novamente. Se o script precisar de ser interrompido – por exemplo, ao executá-lo passo a passo – utilize o comando Stop (Run » Stop, Ctrl+F3) ou o botão ( na barra de ferramentas Script Debug).

Depuração de Scripts

O sistema de scripting dispõe de um conjunto de ferramentas para ajudar na depuração de scripts. Estas incluem a aplicação de múltiplos breakpoints num script, a utilização do painel Watch List para monitorizar o valor das variáveis, a utilização de marcadores para navegar de forma mais eficiente e o uso das funcionalidades step into e step over para seguir a execução dos scripts.

Por exemplo, as seguintes funcionalidades podem ser utilizadas ao verificar os valores de variáveis e expressões num script:

• Breakpoints
• Tooltips de avaliação de expressões
• Tooltips de informação contextual
• Caixa de diálogo Evaluate
• Watch Expressions

► Consulte Script Editor Tools para obter informação sobre a utilização das ferramentas do editor durante a depuração de scripts.

Tracing

Para ajudar a encontrar e resolver um erro desconhecido num script, pode inserir-se uma série de breakpoints num script para interromper o código em vários pontos, enquanto são verificados os valores das variáveis e expressões.

No entanto, em qualquer ponto em que o script esteja em pausa, também é possível avançá-lo uma linha funcional de cada vez usando as funcionalidades de tracing/step do Debugger. Desta forma, pode usar-se um breakpoint para interromper inicialmente o script na área de interesse e, depois, avançar uma linha de cada vez com a funcionalidade de tracing. O processo de executar um script uma linha de cada vez é designado por tracing ou script stepping.

O Script debugger fornece comandos relacionados com o tracing – stepping into (Run » Step Into) e stepping over (Run » Step Over). Isto permite-lhe seguir o processo do script e analisar o seu comportamento ao depurar o código do script.

Os comandos de depuração estão disponíveis no menu Run .

Comando Step Into

O processo Step Into executa o script uma instrução de cada vez. O comando está disponível no menu Run , no respetivo botão da barra de ferramentas Script Debug () ou através da tecla de atalho F7 .

Se a instrução em execução chamar outro procedimento, ao entrar nessa instrução o controlo é transferido para a primeira linha do procedimento chamado. O realce a verde-claro no editor indica a linha de código em que o script se encontra. O processo de execução passo a passo do script é cancelado com o comando Run » Stop, o atalho Ctrl+F3 ou o botão da barra de ferramentas ().

Comando Step Over

O processo Step Over é semelhante a Step Into, exceto que, se a instrução atual for uma chamada a outro procedimento, todo o procedimento chamado é executado sem interrupção, em vez de seguir a execução dentro dele. O comando está disponível no menu Run , no respetivo botão () ou através da tecla de atalho F8 .

Este comando é útil quando já se determinou que um procedimento called não é a causa do problema no procedimento atual, evitando assim seguir desnecessariamente o procedimento chamado linha a linha – esse procedimento é “saltado”.

Painel Call Stack

O painel Call Stack é usado para ver a cadeia de procedimentos e funções que conduziram ao ponto atual de execução no script que está a ser depurado.

O painel Call Stack 

À medida que depura o script passo a passo, o painel mostra o nome de qualquer função ou procedimento em que entra.

Quando é encontrada uma chamada a outra função ou procedimento, o painel mostra o nome dessa função/procedimento adicional à medida que nela entra. Como a função/procedimento é chamada a partir de outra função/procedimento, a função/procedimento original continua a ser apresentada no painel.

É efetivamente criada uma “call stack”, mostrando a relação entre chamadas descendentes de função/procedimento. A função/procedimento original surge na parte inferior da pilha, com cada função/procedimento chamado subsequentemente por cima, até à função/procedimento atualmente aberta no topo da pilha.

À medida que a execução do script sai de uma subfunção/subprocedimento e regressa à função/procedimento chamador, a anterior é removida da pilha e a função/procedimento chamador passa a ocupar o topo da pilha.

Fazer duplo clique numa entrada do painel leva-o para a linha correspondente do script em que é feita a chamada à função ou procedimento selecionado. A linha será realçada com a cor associada a erros de scripting e apresentará o marcador de erro de scripting na margem direita. Isto é usado apenas para fins de realce. Desaparece quando clica no documento e não interfere de forma alguma com a sessão de depuração.

Exceções e Mensagens

Como tende a acontecer em todos os projetos de programação, o desenvolvimento e a depuração do código do script não terminam necessariamente com um script “funcional”. É provável que, na utilização prática, um script encontre erros imprevistos ou não produza os resultados esperados.

Felizmente, existem várias formas de utilizar o sistema de scripting para tratar exceções de execução e fornecer feedback ao utilizador sobre o funcionamento do script.

Gestores de Exceções

Em DelphiScript, a palavra-chave try introduz uma instrução try-except ou uma instrução try-finally. Estas duas instruções estão relacionadas, mas servem finalidades diferentes.

Try Finally

Num gestor Try-Finally, as instruções no bloco finally são sempre executadas – independentemente de ter ocorrido ou não um erro de exceção no bloco try. Utilize o bloco try-finally para libertar objetos temporários ou outros recursos, e para realizar tarefas de limpeza.

Reset(F);
Try
  // process file F
Finally
  CloseFile(F);
End;

Try Except

Utilize a instrução Try-Except para capturar exceções geradas e executar o código de tratamento de erros relacionado. Por exemplo, pode capturar-se uma exceção específica e atualizar um registo ou abrir uma caixa de diálogo de erro descritiva. Uma exceção de código no bloco try faz com que o bloco except seja executado.

No exemplo abaixo, o procedimento ApplyOffset é chamado, com parâmetros adequados, a partir do procedimento DefineOffset. O procedimento faz um cálculo simples de divisão (sobre as variáveis Ydim e Zdim ) e apresenta o resultado (Offset) numa caixa de diálogo padrão.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   Try
      Offset := Ydim div Zdim;
      ShowInfo('Calculated Offset = ' + IntToStr(Offset));
   Except
      ShowWarning('Entered Z dimension must be greater than zero.');
   End;
End;

Procedure DefineOffset;
Begin;
   ApplyOffset(32, 4);
End;

Para os parâmetros ApplyOffset apresentados acima (32,4), o script executado mostrará o resultado calculado utilizando o procedimento ShowMessage, conforme apresentado abaixo.

Em alternativa, alterar os parâmetros passados para 32,0 (ApplyOffset(32, 0);) provoca uma exceção de divisão por zero no cálculo Offset, acionando o bloco de tratamento Except. Este utiliza o procedimento ShowWarning para apresentar uma caixa de diálogo Warning relevante.

Raise

O pressuposto no procedimento simples de tratamento de erros acima é que a exceção é gerada em resposta a um erro de divisão por zero, mas isso significa que outros tipos de exceções não serão comunicados com precisão pelo texto da caixa de diálogo de aviso. No entanto, neste exemplo, esse é o erro de exceção mais provável de ocorrer.

Ainda assim, do ponto de vista do utilizador, é desejável algum tipo de deteção específica de erros. Em DelphiScript, a palavra-chave Delphi On (para capturar um tipo de exceção especificado) não é suportada, mas a instrução Raise pode ser usada dentro de um bloco Except para gerar novamente a exceção mais recente (qualquer que tenha sido o seu tipo).

Try
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
Except
   Raise;
End;

Desta forma, quando a maior parte do código de um procedimento existe dentro do bloco try de uma instrução try-except, todas as exceções podem ser comunicadas pela instrução Raise . Note que a caixa de diálogo de exceção apenas apresenta mensagens de erro genéricas, em vez de informação específica do script.

Raise Também pode ser usado para induzir uma exceção em resposta a testes específicos, por exemplo aplicando instruções simples if-then ou case.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   if Zdim > Ydim then
      Begin;
         Raise('Z dimension must be smaller than Y dimension.');
      End;
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
End;

Aqui, se o parâmetro Zdim do exemplo acima for maior do que o parâmetro Ydim, é gerada uma exceção (com mensagem).

Erros em Scripts VB

A implementação de VBScript no motor de scripting do Altium Designer tem funções incorporadas que podem ser usadas em projetos de scripts VBScript, como a função MsgBox .

A instrução On Error pode ser utilizada ao capturar erros em scripts VB. Consulte a documentação do Microsoft VBScript para mais informações sobre a captura de erros.

Mensagens

De uma forma geral, as mensagens são o principal meio de melhorar o funcionamento do script na perspetiva do utilizador.

As mensagens podem fornecer alertas para exceções ou indicar informações de execução e avisos, e podem ser inseridas em rotinas de script que tratam dados de entrada, cálculos, operações com ficheiros ou qualquer procedimento em que uma perceção do processo seja benéfica.

Caixas de Diálogo de Mensagens

Para além da caixa de diálogo de mensagem básica disponível no sistema de scripting (ShowMessage), está disponível um conjunto de caixas de diálogo específicas para fornecer feedback adaptado ao utilizador.

Estas incluem procedimentos de mensagem como:

• ShowError
• ShowException
• ShowInfo
• ShowWarning
• e mais..

Painel Messages

O painel Messages do Altium Designer pode ser uma ferramenta útil de depuração para scripting, mas também pode ser utilizado para fornecer ao utilizador um fluxo contínuo de informações de mensagem úteis.

O painel Messages é um objeto do Workspace Manager, acedido a partir da interface Message Manager. O painel Messages pode ser utilizado num script para mostrar os estados de variáveis e propriedades (ou, na verdade, quaisquer outros dados), tanto para depuração como para feedback ao utilizador, conforme exemplificado abaixo.

Procedure CreateMessages;
var
   WS : IWorkSpace;
   MM : IMessagesManager;
Begin
   WS := GetWorkSpace;           // obtain Workspace Manager interface
   MM := WS.DM_MessagesManager;  // obtain Message Manager interface
   
   MM.ClearMessages;             // initialize

   MM.BeginUpdate;
   // add relevant messages here using MM.AddMesssage procedures
   MM.EndUpdate;

   WS.DM_ShowMessageView;         // display messages
End;