ScriptForge.Exception serviço

O serviço Exception é um conjunto de métodos destinados a auxiliar na depuração de código em scripts Basic e Python e no tratamento de erros em scripts Basic.

Nos scripts Basic, quando ocorre um erro em tempo de execução, os métodos e propriedades do serviço Exception ajudam a identificar o contexto do erro e permitem tratá-lo.

• O serviço SF_Exception é semelhante ao objeto VBA Err.

• A propriedade Number identifica o erro.

• Utilize o método Raise para interromper o processamento. O método RaiseWarning pode ser utilizado para detetar uma anomalia sem interromper a execução da macro.

Os erros e avisos gerados pelo serviço Exception são armazenados na memória e podem ser recuperados através do método Console.

A consola de serviço Exception armazena eventos, valores de variáveis e informações sobre erros. Utilize a consola quando não for fácil aceder ao IDE Básico, por exemplo, em funções definidas pelo utilizador (UDF) do Calc ou durante o processamento de eventos.

Utilize o método DebugPrint para adicionar qualquer informação relevante à consola. As entradas da consola podem ser exportadas para um ficheiro de texto ou visualizadas numa janela de diálogo.

Quando ocorre um erro, uma macro de aplicação pode:

1. Comunique o erro na consola Exception

2. Informar o utilizador sobre o erro, utilizando uma mensagem padrão ou uma mensagem personalizada

3. Opcionalmente, interromper a sua execução

Nos scripts Python, o serviço Exception é utilizado principalmente para fins de depuração. Métodos como DebugPrint, Console e DebugDisplay são úteis para apresentar rapidamente mensagens, registar dados e abrir a janela da consola a partir de um script Python.

Nem todos os métodos e propriedades estão disponíveis para os scripts em Python, uma vez que a linguagem Python já dispõe de um sistema abrangente de gestão de exceções.

Chamada de serviço

Antes de utilizar o serviço Exception, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

Os exemplos seguintes mostram três formas diferentes de chamar o método Raise. Todos os outros métodos podem ser executados de forma semelhante.

    SF_Exception.Raise(...)
  

    Dim exc : exc = SF_Exception
    exc.Raise(...)
  

    Dim exc : exc = CreateScriptService("Exception")
    exc.Raise(...)
  

O trecho de código abaixo cria uma instância do serviço Exception, regista uma mensagem e apresenta a janela Console.

    from scriptforge import CreateScriptService
    exc = CreateScriptService("Exception")
    someVar = 100
    exc.DebugPrint("Value of someVar", someVar)
    exc.Console()
  

Propriedades

The properties listed below are only available for Basic scripts.

Lançar ou eliminar uma Exception reinicia as suas propriedades.

O intervalo de códigos de erro 0-2000 está reservado para o LibreOffice Basic. Os erros definidos pelo utilizador podem começar a partir de valores mais elevados, a fim de evitar conflitos com futuros desenvolvimentos do LibreOffice Basic.

Clear

Reinicia o estado de erro atual e limpa as propriedades da SF_Exception.

Este método só está disponível para scripts Basic.

    SF_Exception.Clear()
  

O exemplo seguinte mostra como detetar uma exceção de divisão por zero, cujo código de erro é 11.

    Sub Example_Clear()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            If SF_Exception.Number = 11 Then SF_Exception.Clear()
            «Se houver divisão por zero, ignore o erro»
    End Sub
  

Para obter uma lista completa dos códigos de erro de execução do Basic, consulte Depuração de um programa Basic.

Console

Exibe as mensagens da consola numa caixa de diálogo modal ou não modal. Em ambos os modos, são exibidas todas as mensagens anteriores emitidas pelo método DebugPrint() ou resultantes de uma exceção. No modo não modal, as entradas subsequentes são adicionadas automaticamente.

Se a consola já estiver aberta, quando não estiver em modo modal, é trazida para a frente.

Um console modal só pode ser fechado pelo utilizador. Um console não modal pode ser fechado pelo utilizador ou quando a macro terminar.

exc.Console(modal: bool = True)

modal: Determina se a janela da consola é modal (True) ou não modal (False). O valor predefinido é True.

        SF_Exception.Console(Modal := False)
  

    exc.Console(modal = False)
  

ConsoleClear

Limpa a consola, mantendo um número opcional de mensagens recentes. Se a consola estiver ativada no modo não modal, é atualizada.

exc.ConsoleClear(keep: int = 0)

manter: O número de mensagens recentes a manter. O valor predefinido é 0.

O exemplo seguinte limpa a consola, mantendo as 10 mensagens mais recentes.

        SF_Exception.ConsoleClear(10)
  

    exc.ConsoleClear(10)
  

ConsoleToFile

Exporta o conteúdo da consola para um ficheiro de texto. Se o ficheiro já existir e a consola não estiver vazia, o ficheiro será substituído sem aviso prévio. Devolve True em caso de sucesso.

exc.ConsoleToFile(filename: str): bool

nome do ficheiro: O nome do ficheiro de texto no qual a saída da consola deve ser gravada. O nome é expresso de acordo com a propriedade atual FileNaming do serviço SF_FileSystem. Por predefinição, são aceites tanto a notação URL como o formato nativo do sistema operativo.

        SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")
  

    exc.ConsoleToFile(r"C:\Documents\myFile.txt")
  

DebugDisplay

Concatena todos os argumentos numa única cadeia de caracteres legível e apresenta-a numa MsgBox com um ícone de Informação e um botão OK.

A string final também é adicionada à consola.

exc.DebugDisplay(arg0: any, [arg1: any, ...])

arg0[, arg1, ...]: Qualquer número de argumentos de qualquer tipo.

    SF_Exception.DebugDisplay("Current Value", someVar)
  

    exc.DebugDisplay("Current Value", someVar)
  

DebugPrint

Reúne todos os argumentos fornecidos numa única cadeia de caracteres legível por humanos e adiciona-a como uma nova entrada na consola.

exc.DebugPrint(arg0: any, [arg1: any, ...])

arg0[, arg1, ...]: Qualquer número de argumentos de qualquer tipo.

    SF_Exception.DebugPrint(Null, Array(1, 2, 3), "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))
    ' [NULL]   [ARRAY] (0:2) (1, 2, 3)  line1\nLine2  2020-04-09
  

    exc.DebugPrint(None, [1, 2, 3], "line1\nline2")
    # None  [1, 2, 3]  line1\nline2
  

PythonPrint

Apresenta a lista de argumentos de forma legível na consola da plataforma. Os argumentos são separados por um carácter TAB (simulado por espaços).ss

A mesma cadeia de caracteres é adicionada à consola de depuração do ScriptForge.

Se o shell Python (APSO) estiver ativo, o conteúdo PythonPrint é escrito na consola do APSO, em vez de na consola da plataforma.

Este método só está disponível para scripts Basic.

  exc.PythonPrint(arg0: any, [arg1: any, ...])
  

arg0[, arg1, ...]: Qualquer número de argumentos de qualquer tipo. O comprimento máximo de cada argumento individual é de 1024 caracteres.

    exc.PythonPrint(a, Array(1, 2, 3), , "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))
  

Em Python, utilize uma instrução print para apresentar resultados na consola do APSO ou utilize o método DebugPrint para apresentar resultados na consola do ScriptForge.

PythonShell

Abre um shell Python do APSO numa janela não modal. O script Python continua a ser executado após a abertura do shell. A saída das instruções print contidas no script é apresentada no shell.

Só é possível ter uma única instância do shell Python do APSO aberta de cada vez. Por conseguinte, se já houver um shell Python aberto, a chamada a este método não terá qualquer efeito.

Este método requer a instalação da extensão APSO (Alternative Script Organizer for Python). Por sua vez, o APSO requer a presença do ambiente de scripts Python LibreOffice. Se o APSO ou o Python não estiverem instalados, ocorre um erro.

exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

variáveis: um dicionário Python com nomes e valores de variáveis que serão passados para o shell Python do APSO. Por predefinição, todas as variáveis locais são passadas utilizando a função incorporada do Python locals().

fundo: Cor de fundo da consola, especificada como valor inteiro RGB de 24 bits. O fundo predefinido é o da APSO.

primeiro plano: Cor de primeiro plano da consola, especificada como valor inteiro RGB de 24 bits. A cor de primeiro plano predefinida é a do APSO.

O exemplo abaixo abre o shell Python do APSO, passando todas as variáveis globais e locais, tendo em conta o contexto em que o script está a ser executado. A consola é apresentada com caracteres brancos sobre fundo preto.

    exc.PythonShell({**globals(), **locals()}, \
        background = 0x0, foreground = 0xFFFFFF)
  

Quando o shell Python do APSO estiver aberto, qualquer saída subsequente gerada pelo script será apresentada nesse shell. Por conseguinte, a cadeia de caracteres apresentada no exemplo abaixo será exibida no shell Python.

    s = CreateScriptService('Basic')
    RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
    exc.PythonShell(background=RED, foreground=BLUE)
    print("Olá, mundo!")
  

Raise

Gera um erro de execução. É apresentada uma mensagem de erro ao utilizador e esta é registada na consola. A execução é interrompida. O método Raise() pode ser inserido no fluxo normal do script ou numa rotina dedicada ao tratamento de erros.

Este método só está disponível para scripts Basic.

    SF_Exception.Raise(Number := Err, [Source := Erl], [Description := Error$])
  

Os trechos de código apresentados a seguir são equivalentes. Mostram formas alternativas de lançar uma exceção com o código 2100.

    SF_Exception.Raise(2100)
  

    SF_Exception.Number = 2100
    SF_Exception.Raise()
  

    SF_Exception.Raise Number := 2100
  

Número: O código de erro, sob a forma de um número ou de uma cadeia de caracteres. O valor por predefinição é o da função incorporada Err do Basic; nesse caso, Número é opcional.

O intervalo de códigos de erro 0-2000 está reservado para o LibreOffice Basic. Os erros definidos pelo utilizador podem começar a partir de valores mais elevados, a fim de evitar conflitos com futuros desenvolvimentos do LibreOffice Basic.

Fonte: A localização do erro, sob a forma de um número ou de uma cadeia de caracteres. O valor por predefinição é o da função incorporada do Erl Basic.

Descrição: A mensagem a apresentar ao utilizador e a registar na consola. O valor predefinido é o da função incorporada básica Error$.

    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            «Ver variantes abaixo...»
    End Sub
  

Para provocar uma exceção com os valores padrão:

    Catch:
        SF_Exception.Raise()
  

Para lançar uma exceção com um código específico:

    Catch:
        SF_Exception.Raise(11)
  

Para substituir a mensagem habitual:

    Catch:
        SF_Exception.Raise(, , "Não é boa ideia dividir por zero.")
  

Para gerar um erro de aplicação:

    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Aconteceu algo de errado!")
  

RaiseWarning

Este método tem exatamente a mesma sintaxe, os mesmos argumentos e o mesmo comportamento que o método Raise().

No entanto, quando é emitida uma advertência, a execução da macro não é interrompida.

Este método só está disponível para scripts Basic.

    SF_Exception.RaiseWarning([Number As Variant], [Source As Variant], [Description As String])
  

Número: O código de erro, sob a forma de um número ou de uma cadeia de caracteres. O valor por predefinição é o da função incorporada Err do Basic; nesse caso, Número é opcional.

O intervalo de códigos de erro 0-2000 está reservado para o LibreOffice Basic. Os erros definidos pelo utilizador podem começar a partir de valores mais elevados, a fim de evitar conflitos com futuros desenvolvimentos do LibreOffice Basic.

Fonte: A localização do erro, sob a forma de um número ou de uma cadeia de caracteres. O valor por predefinição é o da função incorporada do Erl Basic.

Descrição: A mensagem a apresentar ao utilizador e a registar na consola. O valor predefinido é o da função incorporada básica Error$.

    SF_Exception.RaiseWarning(Source:="Example_Raise()", _
        Description:="Aconteceu algo de errado!", _
        Number:="MyAppError")