Serviço ScriptForge.Exception (SF_Exception)

Conteúdo

# 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

Quando é detetado um erro numa chamada à API do ScriptForge, o comportamento da aplicação é determinado por propriedades específicas:

1. Registe o erro na consola Exception. Isto é feito sempre.

2. Informe o utilizador sobre o erro através de uma mensagem padrão ou localizada.

   Para ativar o modo silencioso, defina:

   exception.ReportScriptErrors = False ' Default = True

3. Para não interromper a execução da macro atual, defina:

   exception.StopWhenError = False ' Default = True

   Faz, então, sentido, antes de prosseguir com o processamento, analisar os valores de:

   exception.ReturnCode ' Short error description

   exception.ReturnCodeDescription ' Long error description

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

##### Em Basic

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(...)

##### Em Python

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

As propriedades abaixo indicadas estão disponíveis apenas para scripts Básicos. Estão relacionadas com erros que ocorrem em qualquer instrução de macro.

Nome | Readonly | Descrição
--- | --- | ---
Description | Não | O texto da mensagem de erro. O valor por predefinição é "" ou uma cadeia de caracteres que contenha a mensagem de erro de tempo de execução do Basic.
Number | Não | O código do erro. Pode ser um valor numérico ou texto. O valor por predefinição é 0 ou o valor numérico correspondente ao código de erro de tempo de execução básico.
Source | Não | A localização no código onde ocorreu o erro. Pode ser um valor numérico ou texto. O valor por predefinição é 0 ou o número da linha de código correspondente a um erro de tempo de execução padrão do Basic.

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.

As propriedades abaixo indicadas estão disponíveis para scripts Basic e Python. Estão relacionadas apenas com erros detetados pela API do ScriptForge.

Nome | Readonly | Tipo de retorno | Descrição
--- | --- | --- | ---
ReportScriptErrors | Não | Booleano | Indica se os erros de script são apresentados numa caixa de mensagem quando ocorrem. O valor por predefinição é False.
ReturnCode | Sim | String | O código devolvido pela última chamada à API do ScriptForge a partir de um script do utilizador. Se tudo tiver decorrido sem erros, trata-se de uma cadeia de caracteres de comprimento zero.
ReturnCodeDescription | Sim | String | A descrição do código devolvido pela última chamada à API do ScriptForge a partir de um script do utilizador. Se tudo tiver decorrido sem erros, trata-se de uma cadeia de caracteres de comprimento zero.
StopWhenError | Não | Booleano | Indica se a macro é interrompida quando o ScriptForge deteta um erro no script do utilizador.

Lista de métodos do Serviço de Exceções
Clear Console ConsoleClear ConsoleToFile | DebugDisplay DebugPrint PythonPrint | PythonShell Raise RaiseWarning

## Clear

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

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

### Sintaxe:

        SF_Exception.Clear()

### Exemplo:

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.

### Sintaxe:

exc.Console(modal: bool = True)

### Parâmetros:

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

### Exemplo:

##### Em Basic

            SF_Exception.Console(Modal := False)

##### Em Python

        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.

### Sintaxe:

exc.ConsoleClear(keep: int = 0)

### Parâmetros:

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

### Exemplo:

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

##### Em Basic

            SF_Exception.ConsoleClear(10)

##### Em Python

        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.

### Sintaxe:

exc.ConsoleToFile(filename: str): bool

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

##### Em Python

        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.

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

##### Em Basic

        SF_Exception.DebugDisplay("Current Value", someVar)

##### Em Python

        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.

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

##### Em Basic

        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

##### Em Python

        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.

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

        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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

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.

### Sintaxe:

        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

### Parâmetros:

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$.

### Exemplo:

        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.

### Sintaxe:

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

### Parâmetros:

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$.

### Exemplo:

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

Tópicos relacionados

Funções de tratamento de erros

Necessitamos da sua ajuda!