Služba ScriptForge.Exception

Služba Exception je sada metod napomáhajících ladění kódu ve skriptech Basicu a Pythonu a zpracování chyb ve skriptech Basicu.

Když ve skriptech Basicu nastane běhová chyba, metody a vlastnosti služby Exception pomáhají identifikovat kontext chyby a umožňují chybu zpracovat.

Služba SF_Exception se podobá objektu VBA Err.
Vlastnost Number chybu identifikuje.
Pomocí metody Raise přerušíte zpracování kódu. Metodou RaiseWarning můžete nečekané chování zachytit, aniž by bylo vykonávání makra přerušeno.

Chyby a upozornění vyvolané službou Exception jsou ukládány do paměti a lze je získat pomocí metody Console.

V konzoli služby Exception se ukládají události, hodnoty proměnných a informace o chybách. Její použití je vhodné v případě, že není snadno přístupné IDE Basicu, například v uživatelem definovaných funkcích Calcu nebo během zpracovávání událostí.

Metodou DebugPrint do konzole přidáte libovolnou relevantní informaci. Položky konzole je možné vypsat do textového souboru nebo zobrazit v dialogovém okně.

Jestliže nastane chyba, makro s aplikací může:

Nahlásit chybu do konzole služby Exception.
Informovat o chybě uživatele pomocí standardní nebo vlastní zprávy.
Volitelně zastavit svůj běh.

Ve skriptech Pythonu se služba Exception používá převážně pro ladění. Metody jako DebugPrint, Console nebo DebugDisplay umožňují ze skriptu v Pythonu rychle vypisovat zprávy, ukládat data do protokolu a otevírat okno s konzolí.

Ne všechny metody a vlastnosti jsou pro skripty Pythonu dostupné, protože jazyk Python již obsahuje pokročilý systém pro zpracování chyb.

Volání služby

V Basicu

Následující příklady ukazují tři odlišné způsoby volání metody Raise. Všechny ostatní metody lze spustit obdobně.


    SF_Exception.Raise(...)


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


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

V Pythonu

V níže uvedené části kódu se vytvoří instance služby Exception, zaznamená se zpráva do protokolu a zobrazí se okno Console.


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

Vlastnosti

Následující vlastnosti jsou k dispozici pouze pro skripty v jazyce Basic.

Název	Pouze pro čtení	Popis
Description	ne	Text chybové zprávy. Výchozí hodnotou je "" nebo řetězec obsahující zprávu běhové chyby Basicu.
Number	ne	Kód chyby. Jedná se o číselnou hodnotu nebo text. Výchozí hodnotou je 0 nebo číselná hodnota odpovídající kódu běhové chyby Basicu.
Source	ne	Místo v kódu, kde chyba nastala. Jedná se o číselnou hodnotu nebo text. Výchozí hodnotou je 0 nebo číslo řádku kódu u standardní běhové chyby Basicu.

Název

Pouze pro čtení

Popis

Description

Text chybové zprávy.

Výchozí hodnotou je "" nebo řetězec obsahující zprávu běhové chyby Basicu.

Number

Kód chyby. Jedná se o číselnou hodnotu nebo text.

Výchozí hodnotou je 0 nebo číselná hodnota odpovídající kódu běhové chyby Basicu.

Source

Místo v kódu, kde chyba nastala. Jedná se o číselnou hodnotu nebo text.

Výchozí hodnotou je 0 nebo číslo řádku kódu u standardní běhové chyby Basicu.

Při vyvolání chyby nebo vymazání služby Exception jsou nastaveny její vlastnosti na výchozí.

Rozsah chybových kódů 0–2000 je vyhrazen pro LibreOffice Basic. Aby se zabránilo konfliktu během budoucího vývoje jazyka, mohou mít uživatelem definované chyby pouze větší hodnoty.

Seznam metod služby Exception
Clear Console ConsoleClear ConsoleToFile	DebugDisplay DebugPrint PythonPrint	PythonShell Raise RaiseWarning

Clear

Nastaví aktuální stav chyby na výchozí a vymaže vlastnosti služby SF_Exception.

Tato metoda je k dispozici pouze pro skripty Basicu.

Syntaxe:


    SF_Exception.Clear()

Příklad:

Následující příklad ukazuje, jak zachytit výjimku při dělení nulou, jejíž kód je 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()
            ' Při dělení nulou se chyba ignoruje
    End Sub

Úplný seznam kódu běhových chyb Basicu naleznete v části Ladění programu v Basicu.

Console

Zobrazí zprávy konzole v modálním nebo nemodálním dialogovém okně. V obou případech se zobrazí všechny zprávy z minulosti zaznamenané metodou DebugPrint() nebo uložené jako výsledek výjimky. V nemodálním režimu se automaticky budou přidávat následující záznamy.

Je-li již konzole otevřena jako nemodální, přenese se do popředí.

Modální konzoli může zavřít pouze uživatel. Nemodální může být také zavřena uživatelem, navíc se zavře při ukončení makra.

Syntaxe:

exc.Console(modal: bool = True)

Parametry:

modal: Určuje, zda je okno s konzolí modální (True) nebo nemodální (False). Výchozí hodnotou je True.

Příklad:

V Basicu


        SF_Exception.Console(Modal := False)

V Pythonu


    exc.Console(modal = False)

ConsoleClear

Vymaže konzoli, případně v ní ponechat volitelný počet posledních zpráv. Pokud je konzole aktivována v nemodálním režimu, obnoví se.

Syntaxe:

exc.ConsoleClear(keep: int = 0)

Parametry:

keep: Počet posledních zpráv, které se mají ponechat. Výchozí hodnotou je 0.

Příklad:

V následujícím příkladu se konzole vymaže, ponechá se v ní přitom 10 posledních zpráv.

V Basicu


        SF_Exception.ConsoleClear(10)

V Pythonu


    exc.ConsoleClear(10)

ConsoleToFile

Vyexportuje obsah konzole do textového souboru. Pokud soubor již existuje a konzole není prázdná, přepíše bez upozornění jeho obsah. V případě úspěšného exportu vrátí True.

Syntaxe:

exc.ConsoleToFile(filename: str): bool

Parametry:

filename: Název textového souboru, do nějž se má konzole vypsat. Název je zapsán v souladu s aktuální vlastností FileNaming služby SF_FileSystem. Ve výchozím nastavení je povolen jak zápis adresy URL, tak nativní formát operačního systému.

Příklad:

V Basicu


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

V Pythonu


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

DebugDisplay

Spojí všechny argumentu do jediného lidsky čitelného řetězce a zobrazí jej v okně MsgBox spolu s ikonou Informace a tlačítkem OK.

Výsledný řetězec se rovněž přidá do konzole.

Syntaxe:

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

Parametry:

arg0[, arg1, ...]: Jakýkoliv počet argumentů libovolného typu.

Příklad:

V Basicu


    SF_Exception.DebugDisplay("Current Value", someVar)

V Pythonu


    exc.DebugDisplay("Current Value", someVar)

DebugPrint

Spojí všechny zadané argumenty do jediného lidsky čitelného řetězce a přidá jej jako nový záznam do konzole.

Syntaxe:

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

Parametry:

arg0[, arg1, ...]: Jakýkoliv počet argumentů libovolného typu.

Příklad:

V Basicu


    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

V Pythonu


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

PythonPrint

Zobrazí seznam argumentů v čitelné podobě v konzoli systému. Argumenty jsou odděleny znakem tabulátor (napodobeným mezerami).

Stejný řetězec se přidá do ladicí konzole knihovny ScriptForge.

Pokud je aktivní shell Pythonu (APSO), metoda PythonPrint vypíše obsah do konzole APSO místo do konzole systému.

Tato metoda je k dispozici pouze pro skripty Basicu.

Syntaxe:


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

Parametry:

arg0[, arg1, ...]: Jakýkoliv počet argumentů libovolného typu. Maximální délka jednotlivých argumentů činí 1024 znaků.

Příklad:


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

V Pythonu vypíšete obsah do konzole APSO pomocí příkazu print, do konzole knihovny ScriptForge pak pomocí metody DebugPrint.

PythonShell

Otevře shell Pythonu APSO jako nemodální okno. Skript Pythonu pokračuje po otevření shellu v běhu. V shellu se bude zobrazovat výstup ve skriptu spuštěných příkazů print.

Najednou může být otevřena pouze jediná instance shellu APSO. Je-li proto shell již otevřen, volání této metody nic neprovede.

Tato metoda vyžaduje nainstalované rozšíření APSO (Alternative Script Organizer for Python). Toto rozšíření vyžaduje v LibreOffice přítomnost skriptovacího prostředí pro Python. Pokud APSO či Python chybí, nastane chyba.

Syntaxe:

exc.PythonShell(variables: dict)

Parametry:

variables: Slovník Pythonu s názvy a hodnotami proměnných, které se shellu APSO předají. Ve výchozím nastavení jsou předány všechny lokální proměnné pomocí vestavěné funkce Pythonu locals().

Příklad:

V níže uvedeném příkladu se otevře shell Pythonu APSO a předají se do něj všechny globální a lokální proměnné vzhledem ke kontextu, v němž je skript spuštěn.


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

Jakmile je shell APSO otevřen, zobrazí se v něm jakýkoliv následující skriptem vypsaný výstup. Zobrazí se v něm tedy i řetězec vypsaný v následujícím příkladu.


    exc.PythonShell()
    print("Ahoj světe!")

Raise

Vyvolá běhovou chybu. Chybová zpráva se zobrazí uživateli a zaznamená se do konzole. Vykonávání programu se zastaví. Metodu Raise() je možné umístit do běžného skriptu i do specializované procedury na zpracování chyb.

Tato metoda je k dispozici pouze pro skripty Basicu.

Syntaxe:


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

Uvedené části kódy mají stejný význam, ukazují alternativní způsoby, jak vyvolat výjimku s kódem 2100.


    SF_Exception.Raise(2100)


    SF_Exception.Number = 2100
    SF_Exception.Raise()


    SF_Exception.Raise Number := 2100

Parametry:

Number: Chybový kód jako číslo nebo řetězec. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Err.

Rozsah chybových kódů 0–2000 je vyhrazen pro LibreOffice Basic. Aby se zabránilo konfliktu během budoucího vývoje jazyka, mohou mít uživatelem definované chyby pouze větší hodnoty.

Source: Místo vzniku chyby jako číslo nebo řetězec. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Err.

Description: Zpráva zobrazená uživateli a zaznamenaná do konzole. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Error$.

Příklad:


    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            ' Viz možnosti níže...
    End Sub

Vyvolání výjimky se standardními hodnotami:


    Catch:
        SF_Exception.Raise()

Vyvolání výjimky se specifickým kódem:


    Catch:
        SF_Exception.Raise(11)

Nahrazení běžné zprávy:


    Catch:
        SF_Exception.Raise(, , "Dělit nulou není dobrý nápad.")

Vyvolání chyby aplikace:


    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Něco se pokazilo!")

RaiseWarning

Tato metoda má naprosto stejnou syntaxi, argumenty a chování jako metoda Raise().

Rozdílem je, že při vyvolání upozornění se vykonávání makra nezastaví.

Tato metoda je k dispozici pouze pro skripty Basicu.

Syntaxe:


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

Parametry:

Number: Chybový kód jako číslo nebo řetězec. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Err.

Rozsah chybových kódů 0–2000 je vyhrazen pro LibreOffice Basic. Aby se zabránilo konfliktu během budoucího vývoje jazyka, mohou mít uživatelem definované chyby pouze větší hodnoty.

Source: Místo vzniku chyby jako číslo nebo řetězec. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Err.

Description: Zpráva zobrazená uživateli a zaznamenaná do konzole. Výchozí hodnotou je hodnota z vestavěné funkce Basicu Error$.

Příklad:


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

Funkce pro zpracování chyb