Usługa ScriptForge.Exception (SF_Exception)

Spis treści

# 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:

1. Zgłosić błąd w konsoli Exception

2. Poinformować użytkownika o błędzie za pomocą komunikatu standardowego lub niestandardowego

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

Przed użyciem usługi Exception należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

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

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(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

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

background: kolor tła konsoli określony jako 24-bitowa wartość całkowita RGB. Domyślnym tłem jest APSO.

foreground: kolor pierwszego planu konsoli określony jako 24-bitowa wartość całkowita RGB. Domyślny pierwszy plan to kolor APSO.

### Przykład:

Poniższy przykład otwiera powłokę APSO Python, przekazując wszystkie zmienne globalne i lokalne, biorąc pod uwagę kontekst, w którym skrypt jest uruchomiony. Konsola jest wyświetlana z białymi znakami na czarnym tle.

        exc.PythonShell({**globals(), **locals()}, \
            background = 0x0, foreground = 0xFFFFFF)

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.

        s = CreateScriptService('Basic')
        RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
        exc.PythonShell(background=RED, foreground=BLUE)
        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 := Err, [Source := Erl], [Description := Error$])

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:

Liczba: kod błędu, jako liczba lub ciąg znaków. Wartością domyślną jest Err podstawowa wbudowana funkcja, w którym przypadku Number jest opcjonalny.

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.

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:

Liczba: kod błędu, jako liczba lub ciąg znaków. Wartością domyślną jest Err podstawowa wbudowana funkcja, w którym przypadku Number jest opcjonalny.

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.

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:="Coś złego się stało!", _
            Number:="MyAppError")

Tematy pokrewne

Funkcje obsługi błędów