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.

tip

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:

  1. Nahlásit chybu do konzole služby Exception.

  2. Informovat o chybě uživatele pomocí standardní nebo vlastní zprávy.

  3. 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í.

note

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.


tip

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


note

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.

note

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
  
tip

Ú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 shellu Pythonu (APSO). Argumenty jsou odděleny znakem tabulátor (napodobeným mezerami).

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

note

Tato metoda je k dispozici pouze pro skripty Basicu.


Syntaxe:


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

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.


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

V Pythonu lze jednoduše použít vestavěný příkaz print().


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.

warning

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.

note

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.

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

note

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.

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

Podpořte nás!