Guida di LibreOffice 25.2
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ò:
Riportare l'errore nella console Exception
Informare l'utente in merito all'errore usando un messaggio standard o personalizzato
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.
Prima di usare il servizio Exception è necessario caricare o importare la libreria ScriptForge:
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(...)
  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()
  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à.
| Elenco dei metodi del servizio Exception | ||
|---|---|---|
Reimposta lo stato dell'errore corrente e rimuove le proprietà SF_Exception.
    SF_Exception.Clear()
  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.
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.
exc.Console(modal: bool = True)
modal: determina se la finestra della console è modale (True) o non modale (False). Il valore predefinito è True.
        SF_Exception.Console(Modal := False)
  
    exc.Console(modal = False)
  Rimuove il contenuto della console mantenendo un numero, facoltativo, di messaggi recenti. Se la console è attivata in modalità non modale viene ricaricata.
exc.ConsoleClear(keep: int = 0)
keep: il numero di messaggi recenti da conservare. Il valore predefinito è 0.
L'esempio seguente cancella il contenuto della console mantenendo i 10 messaggi più recenti.
        SF_Exception.ConsoleClear(10)
  
    exc.ConsoleClear(10)
  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.
exc.ConsoleToFile(filename: str): bool
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.
        SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")
  
    exc.ConsoleToFile(r"C:\Documents\myFile.txt")
  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.
exc.DebugDisplay(arg0: any, [arg1: any, ...])
arg0[, arg1, ...]: qualsiasi numero di argomenti di qualunque tipo.
    SF_Exception.DebugDisplay("Current Value", someVar)
  
    exc.DebugDisplay("Current Value", someVar)
  Assembla tutti gli argomenti specificati in una singola stringa leggibile da una persona e la aggiunge come nuova voce nella console.
exc.DebugPrint(arg0: any, [arg1: any, ...])
arg0[, arg1, ...]: qualsiasi numero di argomenti di qualunque 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
  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.
  exc.PythonPrint(arg0: any, [arg1: any, ...])
  arg0[, arg1, ...]: un numero qualsiasi di argomenti di qualunque tipo. La lunghezza massima di ogni singolo argomento è di 1024 caratteri.
    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.
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.
exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)
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.
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!")
  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.
    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 generare un'eccezione con codice 2100.
    SF_Exception.Raise(2100)
  
    SF_Exception.Number = 2100
    SF_Exception.Raise()
  
    SF_Exception.Raise Number := 2100
  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.
    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!")
  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.
    SF_Exception.RaiseWarning([Number As Variant], [Source As Variant], [Description As String])
  
    SF_Exception.RaiseWarning(Source:="Example_Raise()", _
        Description:="Si è verificato un errore!", _
        Number:="ErroreDellaMiaApp")