Servizio ScriptForge.Exception (SF_Exception)

Contenuto

# Servizio ScriptForge.Exception

Il servizio Exception è una raccolta di metodi di supporto al debug del codice degli script in Basic e Python e alla gestione degli errori negli script in Basic.

Negli script in Basic, quando si verifica un errore in fase di run-time, i metodi e le proprietà del servizio Exception consentono di identificare l'errore e di gestirlo.

- Il servizio SF_Exception è simile all'oggetto VBA Err.

- La proprietà Number identifica l'errore.

- Usate il metodo Raise per interrompere l'elaborazione. Il metodo RaiseWarning può essere usato per catturare un'anomalia senza interrompere l'esecuzione della macro.

Gli errori e gli avvisi generati col servizio Exception vengono memorizzati e possono essere recuperati usando il metodo Console.

La console del servizio Exception memorizza eventi, valori delle variabili e informazioni relative agli errori. Usate la console quando la IDE di Basic non è facilmente accessibile, per esempio nelle funzioni di Calc definite dall'utente (UDF) o durante l'elaborazione di eventi.

Usate il metodo DebugPrint per aggiungere qualsiasi informazione di rilievo alla console. Le voci registrate nella console possono essere scaricate in un file di testo o visualizzate in una finestra di dialogo.

Quando si verifica un errore, una macro può:

1. Riportare l'errore nella console Exception.

2. Informare l'utente in merito all'errore usando un messaggio standard o personalizzato.

3. Opzionalmente interrompere la propria esecuzione.

Negli script in Python il servizio Exception è usato principalmente a scopo di debug. I metodi come DebugPrint, Console e DebugDisplay sono utili per stampare velocemente messaggi, registrare dati e aprire la finestra della console dall'interno di uno script Python.

Non tutti i metodi e le proprietà sono disponibili per gli script in Python, dato che questo linguaggio ha già un suo sistema completo per la gestione delle eccezioni.

## Invocazione del servizio

Prima di usare il servizio Exception è necessario caricare o importare la libreria ScriptForge:

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService

##### In Basic

Gli esempi seguenti mostrano tre differenti approcci per chiamare il metodo Raise. Tutti gli altri metodi possono essere eseguiti in modo analogo.

        SF_Exception.Raise(...)

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

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

##### In Python

Il frammento di codice sottostante crea un'istanza del servizio Exception, registra un messaggio e visualizza la finestra della Console.

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

## Proprietà

Le proprietà elencate di seguito sono disponibili solo per gli script in Basic.

Nome | Sola lettura | Descrizione
--- | --- | ---
Description | No | Il testo del messaggio di errore. Il valore predefinito è "" o una stringa contenente il messaggio dell'errore del tempo di esecuzione (run-time) di Basic.
Number | No | Il codice dell'errore. Può essere un valore numerico o un testo. Il valore predefinito è 0 o il valore numerico corrispondente al codice dell'errore del tempo di esecuzione (runtime) di Basic.
Source | No | La posizione all'interno del codice nella quale si è verificato l'errore. Può essere un valore numerico o un testo. Il valore predefinito è 0 o il numero della riga di codice per un errore del tempo di esecuzione (runtime) standard di Basic.

Sollevare o rimuovere un'eccezione (Exception) reimposta le sue proprietà.

L'intervallo dei codici di errore da 0 a 2000 è riservato per LibreOffice Basic. Gli errori definiti dall'utente dovrebbero iniziare da valori più alti al fine di prevenire conflitti con futuri sviluppi di LibreOffice Basic.

Elenco dei metodi del servizio Exception
Clear Console ConsoleClear ConsoleToFile | DebugDisplay DebugPrint PythonPrint | PythonShell Raise RaiseWarning

## Clear

Reimposta lo stato dell'errore corrente e rimuove le proprietà SF_Exception.

Questo metodo è disponibile solo per gli script Basic.

### Sintassi:

        SF_Exception.Clear()

### Esempio:

L'esempio seguente mostra come catturare un'eccezione relativa a una divisione per zero, il cui codice di errore è 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 la divisione è per zero, ignora l'errore
        End Sub

Per un elenco completo dei codici di errore del tempo di esecuzione (run-time) di Basic consultate Debug di un programma in Basic.

## Console

Visualizza i messaggi della console in una finestra di dialogo modale o non modale. In entrambe le modalità vengono visualizzati tutti i messaggi pregressi sollevati da un metodo DebugPrint() o risultanti da un'eccezione. In modalità non modale, le voci successive vengono aggiunte automaticamente.

Se la console è già aperta, e non è modale, viene portata in primo piano.

Una console modale può essere chiusa solo dall'utente. Una console non modale può essere chiusa sia dall'utente, sia dalla macro.

### Sintassi:

exc.Console(modal: bool = True)

### Parametri:

modal: determina se la finestra della console è modale (True) o non modale (False). Il valore predefinito è True.

### Esempio:

##### In Basic

            SF_Exception.Console(Modal := False)

##### In Python

        exc.Console(modal = False)

## ConsoleClear

Rimuove il contenuto della console mantenendo un numero, facoltativo, di messaggi recenti. Se la console è attivata in modalità non modale viene ricaricata.

### Sintassi:

exc.ConsoleClear(keep: int = 0)

### Parametri:

keep: il numero di messaggi recenti da conservare. Il valore predefinito è 0.

### Esempio:

L'esempio seguente cancella il contenuto della console mantenendo i 10 messaggi più recenti.

##### In Basic

            SF_Exception.ConsoleClear(10)

##### In Python

        exc.ConsoleClear(10)

## ConsoleToFile

Esporta i contenuti della console in un file di testo. Se il file esiste già e la console non è vuota, il file sarà sovrascritto senza alcun avvertimento. Restituisce True se l'esportazione viene eseguita correttamente.

### Sintassi:

exc.ConsoleToFile(filename: str): bool

### Parametri:

filename: il nome del file di testo nel quale scaricare il contenuto della console. Il nome è espresso in conformità alla proprietà FileNaming corrente del servizio SF_FileSystem. Per impostazione predefinita sono ammesse sia la notazione URL sia il formato nativo del sistema operativo.

### Esempio:

##### In Basic

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

##### In Python

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

## DebugDisplay

Concatena tutti gli argomenti in una stringa leggibile da una persona e la visualizza in una finestra di dialogo MsgBox con un'icona Informazione e un pulsante OK.

La stringa risultante viene aggiunta anche alla console.

### Sintassi:

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

### Parametri:

arg0[, arg1, ...]: qualsiasi numero di argomenti di qualunque tipo.

### Esempio:

##### In Basic

        SF_Exception.DebugDisplay("Current Value", someVar)

##### In Python

        exc.DebugDisplay("Current Value", someVar)

## DebugPrint

Assembla tutti gli argomenti specificati in una singola stringa leggibile da una persona e la aggiunge come nuova voce nella console.

### Sintassi:

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

### Parametri:

arg0[, arg1, ...]: qualsiasi numero di argomenti di qualunque tipo.

### Esempio:

##### In 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

##### In Python

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

## PythonPrint

Visualizza l'elenco degli argomenti in formato leggibile all'interno di una console della piattaforma. Gli argomenti sono separati da un carattere di tabulazione (TAB, simulato da spazi).

La stessa stringa viene aggiunta alla console di debug di ScriptForge.

Se la shell Python (APSO) è attiva, il contenuto di PythonPrint viene scritto nella console di APSO al posto della console della piattaforma.

Questo metodo è disponibile solo per gli script Basic.

### Sintassi:

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

### Parametri:

arg0[, arg1, ...]: un numero qualsiasi di argomenti di qualunque tipo. La lunghezza massima di ogni singolo argomento è di 1024 caratteri.

### Esempio:

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

In Python usare un'istruzione print per stampare nella console di APSO o usare il metodo DebugPrint per stampare nella console di ScriptForge.

## PythonShell

Apre una shell APSO di Python in una finestra non modale. Lo script di Python continua la sua esecuzione dopo l'apertura della shell. Il risultato delle istruzioni print presenti all'interno dello script viene visualizzato nella shell.

Può essere aperta solo una singola istanza della shell APSO di Python in un determinato momento. Perciò, se una shell Python è già aperta, la chiamata a questo metodo non avrà effetto.

Questo metodo richiede l'installazione dell'estensione APSO (Alternative Script Organizer for Python). A sua volta APSO richiede la presenza del framework di LibreOffice per gli script in Python. Se APSO o Python mancano, si genera un errore.

### Sintassi:

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

### Parametri:

variables: un dizionario di Python con i nomi delle variabili e i valori da passare alla shell APSO di Python. Per impostazione predefinita vengono passate tutte le variabili locali usando la funzione locals() incorporata in Python.

background: colore di sfondo della console specificato come valore intero RGB a 24 bit. Il colore di sfondo predefinito è quello di APSO.

foreground: colore di primo piano della console specificato come valore intero RGB a 24 bit. Il colore di primo piano predefinito è quello di APSO.

### Esempio:

L'esempio seguente apre la shell Python di APSO passandole tutte le variabili globali e locali, tenendo conto del contesto nel quale lo script viene eseguito. La console viene visualizzata con caratteri bianchi su sfondo nero.

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

Quando è aperta una shell APSO di Python, ogni successivo output emesso dallo script sarà mostrato nella shell. Perciò, la stringa stampata nell'esempio sottostante sarà visualizzata nella shell di Python.

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

## Raise

Genera un errore del tempo di esecuzione (runtime). Viene visualizzato un messaggio di errore e registrato nella console. L'esecuzione viene fermata. Il metodo Raise() può essere posizionato all'interno del normale flusso dello script o in una routine dedicata alla gestione dell'errore.

Questo metodo è disponibile solo per gli script Basic.

### Sintassi:

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

I frammenti di codice presentati di seguito sono equivalenti. Mostrano modi alternativi per generare un'eccezione con codice 2100.

        SF_Exception.Raise(2100)

        SF_Exception.Number = 2100
        SF_Exception.Raise()

        SF_Exception.Raise Number := 2100

### Parametri:

Number: il codice di errore, in formato numerico o stringa. Il valore predefinito è quello della funzione Basic incorporata Err, in questo caso Number è opzionale.

L'intervallo dei codici di errore da 0 a 2000 è riservato per LibreOffice Basic. Gli errori definiti dall'utente dovrebbero iniziare da valori più alti al fine di prevenire conflitti con futuri sviluppi di LibreOffice Basic.

Source: la posizione dell'errore, in formato numerico o come stringa. Il valore predefinito è quello della funzione Erl incorporata in Basic.

Description: il messaggio da mostrare all'utente e registrare nella console. Il valore predefinito è quello della funzione Error$ incorporata in Basic.

### Esempio:

        Sub Example_Raise()
            Dim a, b, c
            On Local Error GoTo Catch
            Try:
                a = 10 : b = 0
                c = a / b
                '...
                Exit Sub
            Catch:
                'Vedere le seguenti varianti...
        End Sub

Per generare un'eccezione con i valori standard:

        Catch:
            SF_Exception.Raise()

Per generare un'eccezione con un codice specifico:

        Catch:
            SF_Exception.Raise(11)

Per sostituire il messaggio predefinito:

        Catch:
            SF_Exception.Raise(, , "Non è una buona idea dividere per zero.")

Per generare un errore dell'applicazione:

        Catch:
            SF_Exception.Raise("MyAppError", "Example_Raise()", "Qualcosa è andato storto!")

## RaiseWarning

Questo metodo ha esattamente la stessa sintassi, gli argomenti e il comportamento del metodo Raise().

Tuttavia, quando viene generato un avvertimento, l'esecuzione della macro non viene interrotta.

Questo metodo è disponibile solo per gli script Basic.

### Sintassi:

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

### Parametri:

Number: il codice di errore, in formato numerico o stringa. Il valore predefinito è quello della funzione Basic incorporata Err, in questo caso Number è opzionale.

L'intervallo dei codici di errore da 0 a 2000 è riservato per LibreOffice Basic. Gli errori definiti dall'utente dovrebbero iniziare da valori più alti al fine di prevenire conflitti con futuri sviluppi di LibreOffice Basic.

Source: la posizione dell'errore, in formato numerico o come stringa. Il valore predefinito è quello della funzione Erl incorporata in Basic.

Description: il messaggio da mostrare all'utente e registrare nella console. Il valore predefinito è quello della funzione Error$ incorporata in Basic.

### Esempio:

        SF_Exception.RaiseWarning(Source:="Example_Raise()", _
            Description:="Si è verificato un errore!", _
            Number:="ErroreDellaMiaApp")

Argomenti correlati

Funzioni di gestione degli errori

Sostienici!