Usługa ScriptForge.Exception

Usługa Exception to zbiór metod wspomagających debugowanie kodu w skryptach Basic i Python oraz obsługę błędów w skryptach Basic.

W skryptach Basic, gdy wystąpi błąd wykonania, metody i właściwości usługi Exception pomagają zidentyfikować kontekst błędu i pozwalają go obsłużyć.

Usługa SF_Exception jest podobna do obiektu VBA Err.
Właściwość Number identyfikuje błąd.
Użyj metody Raise, aby przerwać przetwarzanie. Metodę RaiseWarning można wykorzystać do wychwytywania anomalii bez przerywania wykonywania makra.

Błędy i ostrzeżenia zgłaszane przez usługę Exception są przechowywane w pamięci i można je odzyskać za pomocą metody Console.

Konsola usługi Exception przechowuje zdarzenia, wartości zmiennych i informacje o błędach. Korzystaj z konsoli, gdy podstawowe środowisko IDE nie jest łatwo dostępne, na przykład w funkcjach Calc zdefiniowanych przez użytkownika (UDF) lub podczas przetwarzania zdarzeń.

Użyj metody DebugPrint, aby dodać odpowiednie informacje do konsoli. Wpisy konsoli można zrzucić do pliku tekstowego lub wyświetlić w oknie dialogowym.

W przypadku wystąpienia błędu makro aplikacyjne może:

Zgłosić błąd w konsoli Exception
Poinformować użytkownika o błędzie za pomocą komunikatu standardowego lub niestandardowego
Opcjonalnie zatrzymać jego wykonanie

W skryptach Pythona usługa Exception jest używana głównie do celów debugowania. Metody takie jak DebugPrint, Console i DebugDisplay są przydatne do szybkiego drukowania komunikatów, rejestrowania danych i otwierania okna konsoli z poziomu skryptu Pythona.

Nie wszystkie metody i właściwości są dostępne dla skryptów Pythona, ponieważ język Python ma już kompleksowy system obsługi wyjątków.

Wywoływanie usługi

W języku Basic

Poniższe przykłady pokazują trzy różne podejścia do wywoływania metody Raise. Wszystkie inne metody można wykonać w podobny sposób.


    SF_Exception.Raise(...)


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


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

W języku Python

Poniższy fragment kodu tworzy instancję usługi Exception, rejestruje komunikat i wyświetla okno Console.


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

Właściwości

Właściwości wymienione poniżej są dostępne tylko dla skryptów Basic.

Nazwa	Tylko do odczytu	Opis
Description	Nie	Tekst komunikatu o błędzie. Wartość domyślna to "" lub ciąg zawierający komunikat o błędzie wykonania Basic.
Number	Nie	Kod błędu. Może to być wartość liczbowa lub tekst. Wartość domyślna to 0 lub wartość numeryczna odpowiadająca kodowi błędu wykonania Basic.
Source	Nie	Położenie w kodzie, gdzie wystąpił błąd. Może to być wartość liczbowa lub tekst. Wartość domyślna to 0 lub numer wiersza kodu dla standardowego błędu wykonania Basic.

Nazwa

Tylko do odczytu

Opis

Description

Nie

Tekst komunikatu o błędzie.

Wartość domyślna to "" lub ciąg zawierający komunikat o błędzie wykonania Basic.

Number

Nie

Kod błędu. Może to być wartość liczbowa lub tekst.

Wartość domyślna to 0 lub wartość numeryczna odpowiadająca kodowi błędu wykonania Basic.

Source

Nie

Położenie w kodzie, gdzie wystąpił błąd. Może to być wartość liczbowa lub tekst.

Wartość domyślna to 0 lub numer wiersza kodu dla standardowego błędu wykonania Basic.

Zgłoszenie lub wyczyszczenie Exception resetuje jego właściwości.

Zakres kodów błędów 0-2000 jest zarezerwowany dla LibreOffice Basic. Błędy zdefiniowane przez użytkownika mogą zaczynać się od wyższych wartości, aby zapobiec kolizji z przyszłymi zmianami LibreOffice Basic.

Lista metod w usłudze Exception
Clear Console ConsoleClear ConsoleToFile	DebugDisplay DebugPrint PythonPrint	PythonShell Raise RaiseWarning

Clear

Resetuje bieżący stan błędu i czyści właściwości SF_Exception.

Ta metoda jest dostępna tylko dla skryptów w języku Basic.

Składnia:


    SF_Exception.Clear()

Przykład:

Poniższy przykład pokazuje, jak przechwycić wyjątek polegający na dzieleniu przez zero, którego kod błędu to 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()
            ' Jeśli dzielisz przez zero, zignoruj błąd
    End Sub

Pełną listę kodów błędów wykonania Basic znajdziesz w artykule Debugowanie programu Basic.

Console

Wyświetla komunikaty konsoli w modalnym lub niemodalnym oknie dialogowym. W obu trybach wyświetlane są wszystkie poprzednie komunikaty wydane przez metodę DebugPrint() lub powstałe w wyniku wyjątku. W trybie niemodalnym kolejne wpisy dodawane są automatycznie.

Jeśli konsola jest już otwarta, gdy nie jest modalna, jest przenoszona na przód.

Konsolę modalną może zamknąć wyłącznie użytkownik. Konsola niemodalna może zostać zamknięta przez użytkownika lub po zakończeniu makra.

Składnia:

exc.Console(modal: bool = True)

Parametry:

modal: określ, czy okno konsoli jest modalne (True), czy niemodalne (False). Wartość domyślna to True.

Przykład:

W języku Basic


        SF_Exception.Console(Modal := False)

W języku Python


    exc.Console(modal = False)

ConsoleClear

Czyści konsolę, zachowując opcjonalną liczbę ostatnich komunikatów. Jeśli konsola zostanie aktywowana w trybie niemodalnym, zostanie odświeżona.

Składnia:

exc.ConsoleClear(keep: int = 0)

Parametry:

keep: liczba ostatnich komunikatów, które mają zostać zachowane. Wartość domyślna to 0.

Przykład:

Poniższy przykład czyści konsolę, zachowując 10 najnowszych komunikatów.

W języku Basic


        SF_Exception.ConsoleClear(10)

W języku Python


    exc.ConsoleClear(10)

ConsoleToFile

Eksportuje zawartość konsoli do pliku tekstowego. Jeśli plik już istnieje, a konsola nie jest pusta, zostanie nadpisany bez ostrzeżenia. Zwraca wartość True, jeśli operacja się powiedzie.

Składnia:

exc.ConsoleToFile(filename: str): bool

Parametry:

filename: nazwa pliku tekstowego, do którego powinna zostać zrzucona konsola. Nazwa jest wyrażana zgodnie z bieżącą właściwością FileNaming usługi SF_FileSystem. Domyślnie akceptowany jest zarówno notacja adresu URL, jak i format natywnego systemu operacyjnego.

Przykład:

W języku Basic


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

W języku Python


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

DebugDisplay

Łączy wszystkie argumenty w jeden ciąg czytelny dla człowieka i wyświetla go w MsgBox z ikoną Informacje i przyciskiem OK.

Ostatni ciąg znaków jest również dodawany do konsoli.

Składnia:

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

Parametry:

arg0[, arg1, ...]: dowolna liczba argumentów dowolnego typu.

Przykład:

W języku Basic


    SF_Exception.DebugDisplay("Current Value", someVar)

W języku Python


    exc.DebugDisplay("Current Value", someVar)

DebugPrint

Składa wszystkie podane argumenty w jeden ciąg czytelny dla człowieka i dodaje go jako nowy wpis w konsoli.

Składnia:

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

Parametry:

arg0[, arg1, ...]: dowolna liczba argumentów dowolnego typu.

Przykład:

W języku 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

W języku Python


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

PythonPrint

Wyświetla listę argumentów w czytelnej formie w konsoli platformy. Argumenty oddzielane są znakiem TAB (symulowanym spacjami).

Ten sam ciąg zostanie dodany do konsoli debugowania ScriptForge.

Jeśli powłoka Pythona (APSO) jest aktywna, treść PythonPrint jest zapisywana w konsoli APSO zamiast konsoli platformy.

Ta metoda jest dostępna tylko dla skryptów w języku Basic.

Składnia:


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

Parametry:

arg0[, arg1, ...]: dowolna liczba argumentów dowolnego typu. Maksymalna długość każdego pojedynczego argumentu wynosi 1024 znaki.

Przykład:


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

W Pythonie użyj instrukcji print, aby wydrukować do konsoli APSO lub użyj metody DebugPrint, aby wydrukować do konsoli ScriptForge.

PythonShell

Otwiera powłokę Pythona APSO jako okno niemodalne. Skrypt Pythona działa nadal po otwarciu powłoki. Dane wyjściowe instrukcji print znajdujących się w skrypcie są wyświetlane w powłoce.

W dowolnym momencie można otworzyć tylko jedną instancję powłoki Pythona APSO. Dlatego też, jeśli powłoka Pythona jest już otwarta, wywołanie tej metody nie będzie miało żadnego efektu.

Ta metoda wymaga instalacji rozszerzenia APSO (Alternative Script Organizer for Python). Z kolei APSO wymaga obecności frameworka skryptowego LibreOffice Python. Jeśli brakuje APSO lub Pythona, wystąpi błąd.

Składnia:

exc.PythonShell(variables: dict)

Parametry:

variables: słownik Pythona z nazwami zmiennych i wartościami, które zostaną przekazane do powłoki Pythona APSO. Domyślnie wszystkie zmienne lokalne są przekazywane za pomocą wbudowanej funkcji Pythona locals().

Przykład:

Poniższy przykład otwiera powłokę Pythona APSO, przekazując wszystkie zmienne globalne i lokalne, biorąc pod uwagę kontekst, w którym działa skrypt.


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

Kiedy powłoka Pythona APSO jest otwarta, wszelkie kolejne dane wyjściowe wydrukowane przez skrypt będą wyświetlane w powłoce. Dlatego ciąg znaków wydrukowany w poniższym przykładzie zostanie wyświetlony w powłoce Pythona.


    exc.PythonShell()
    print("Witaj, świecie!")

Raise

Generuje błąd wykonania. Użytkownikowi zostanie wyświetlony komunikat o błędzie, który zostanie zgłoszony w konsoli. Egzekucja zostaje zatrzymana. Metodę Raise() można umieścić w normalnym przebiegu skryptu lub w dedykowanej procedurze obsługi błędów.

Ta metoda jest dostępna tylko dla skryptów w języku Basic.

Składnia:


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

Przedstawione poniżej fragmenty kodu są równoważne. Pokazują alternatywne sposoby zgłaszania wyjątku za pomocą kodu 2100.


    SF_Exception.Raise(2100)


    SF_Exception.Number = 2100
    SF_Exception.Raise()


    SF_Exception.Raise Number := 2100

Parametry:

Number: kod błędu w postaci liczby lub ciągu znaków. Wartość domyślna to funkcja wbudowana Err języka Basic.

Source: lokalizacja błędu jako liczba lub ciąg. Wartość domyślna to funkcja wbudowana Err języka Basic.

Description: komunikat wyświetlany użytkownikowi i raportowany w konsoli. Wartość domyślna to funkcja wbudowana Error$ języka Basic.

Przykład:


    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            ' Zobacz warianty poniżej...
    End Sub

Aby zgłosić wyjątek ze standardowymi wartościami:


    Catch:
        SF_Exception.Raise()

Aby zgłosić wyjątek z określonym kodem:


    Catch:
        SF_Exception.Raise(11)

Aby zastąpić zwykły komunikat:


    Catch:
        SF_Exception.Raise(, , "Dzielenie przez zero nie jest dobrym pomysłem.")

Aby zgłosić błąd aplikacji:


    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Stało się coś złego!")

RaiseWarning

Ta metoda ma dokładnie taką samą składnię, argumenty i zachowanie jak metoda Raise().

Jednakże, gdy zostanie zgłoszone ostrzeżenie, wykonanie makra nie zostanie zatrzymane.

Ta metoda jest dostępna tylko dla skryptów w języku Basic.

Składnia:


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

Parametry:

Number: kod błędu w postaci liczby lub ciągu znaków. Wartość domyślna to funkcja wbudowana Err języka Basic.

Source: lokalizacja błędu jako liczba lub ciąg. Wartość domyślna to funkcja wbudowana Err języka Basic.

Description: komunikat wyświetlany użytkownikowi i raportowany w konsoli. Wartość domyślna to funkcja wbudowana Error$ języka Basic.

Przykład:


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

Funkcje obsługi błędów