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.

tip

Gli errori e gli avvisi sollevati 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.

note

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.


Invocare il servizio

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 (run-time) 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 (run-time) standard di Basic.


tip

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


note

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

PythonShell
Raise
RaiseWarning


Clear

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

note

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
  
tip

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
  

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.

warning

Questo metodo richiede l'installazione dell'estensione APSO (Alternative Script Organizer for Python). Se non è installato si verificherà un errore.


note

Questo metodo è disponibile solo per gli script Python.


Sintassi:

exc.PythonShell(variables: dict)

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.

Esempio:

L'esempio seguente apre la shell APSO di Python passando tutte le variabili globali e locali tenendo conto del contesto nel quale lo script è in esecuzione.


    exc.PythonShell({**globals(), **locals()})
  

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.


    exc.PythonShell()
    print("Ciao mondo!")
  

Raise

Genera un errore del tempo di esecuzione (run-time). 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.

note

Questo metodo è disponibile solo per gli script Basic.


Sintassi:


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

I frammenti di codice presentati di seguito sono equivalenti. Mostrano modi alternativi per sollevare 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 come stringa. Il valore predefinito è quello della funzione Err incorporata in 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 sollevare un'eccezione con i valori standard:


    Catch:
        SF_Exception.Raise()
  

Per sollevare 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 sollevare 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.

note

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 come stringa. Il valore predefinito è quello della funzione Err incorporata in 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:="Something wrong happened !", _
        Number:="MyAppError")
  

Sosteneteci!