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

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

Proprietà

Le proprietà elencate di seguito sono disponibili solo per gli script in 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.

Clear

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

Questo metodo è disponibile solo per gli script Basic.

    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.

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.

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)
  

ConsoleClear

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)
  

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.

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")
  

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.

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)
  

DebugPrint

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
  

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.

  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.

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

exc.PythonShell(variables: dict)

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.

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

    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.

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.

    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.

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

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

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.

    SF_Exception.RaiseWarning(Source:="Example_Raise()", _
        Description:="Something wrong happened !", _
        Number:="MyAppError")