ScriptForge.Exception service (SF_Exception)

Contenu
Index 🔎︎

# ScriptForge.Exception service

Le service Exception est un ensemble de méthodes pour aider au débogage du code dans les scripts Basic et Python et à la gestion des erreurs dans les scripts Basic.

Dans les scripts de base, lorsqu'une erreur d'exécution se produit, les méthodes et propriétés du service Exception aident à identifier le contexte de l'erreur et permettent de le gérer.

- The SF_Exception service is similar to the VBA Err object.

- La propriété Number identifie l'erreur.

- Utilisez la méthode Raise pour interrompre le traitement. La méthode RaiseWarning peut être utilisée pour intercepter une anomalie sans interrompre l'exécution de la macro.

Les erreurs et les avertissements générés avec le service Exception sont stockés en mémoire et peuvent être récupérés à l'aide de la méthode Console.

The Exception service console stores events, variable values and information about errors. Use the console when the Basic IDE is not easily accessible, for example in Calc user defined functions (UDF) or during events processing.

Utilisez la méthode DebugPrint pour ajouter toute information pertinente à la console. Les entrées de la console peuvent être copiées dans un fichier texte ou visualisées dans une fenêtre de dialogue.

Lorsqu'une erreur se produit, une macro d'application peut :

1. Signaler l'erreur dans la console Exception

2. Informer l'utilisateur de l'erreur à l'aide d'un message standard ou d'un message personnalisé

3. Arrêter éventuellement son exécution

Dans les scripts Python, le service Exception est principalement utilisé à des fins de débogage. Des méthodes telles que DebugPrint, Console et DebugDisplay sont utiles pour imprimer rapidement des messages, enregistrer des données et ouvrir la fenêtre de la console à partir d'un script Python.

Toutes les méthodes et propriétés ne sont pas disponibles pour les scripts Python car le langage Python dispose déjà d'un système complet de gestion des exceptions.

## Invocation du service

##### En Basic :

Les exemples suivants montrent trois approches différentes pour appeler la méthode Raise. Toutes les autres méthodes peuvent être exécutées de la même manière.

        SF_Exception.Raise(...)

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

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

##### En Python

L'extrait de code ci-dessous crée une instance du service Exception, consigne un message et affiche la fenêtre Console.

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

## Propriétés

Les propriétés listées ci-dessous ne sont disponibles que pour les scripts Basic.

Nom | En lecture seule | Description
--- | --- | ---
Description | Non | Le texte du message d'erreur. La valeur par défaut est "" ou une chaîne contenant le message d'erreur d'exécution Basic.
Number | Non | Le code de l'erreur. Il peut s'agir d'une valeur numérique ou de texte. La valeur par défaut est 0 ou la valeur numérique correspondant au code d'erreur d'exécution Basic.
Source | Non | L'emplacement dans le code où l'erreur s'est produite. Il peut s'agir d'une valeur numérique ou de texte. La valeur par défaut est 0 ou le numéro de ligne de code pour une erreur d'exécution Basic

Lever ou effacer une Exception réinitialise ses propriétés.

La plage de codes d'erreur 0-2000 est réservée à LibreOffice Basic. Les erreurs définies par l'utilisateur peuvent commencer à partir de valeurs plus élevées afin d'éviter une collision avec les développements futurs de LibreOffice Basic.

Liste des méthodes dans le service Exception
Clear Console ConsoleClear | ConsoleToFile DebugDisplay DebugPrint | PythonPrint PythonShell Raise RaiseWarning

## Clear

Réinitialise l'état d'erreur actuel et efface les propriétés SF_Exception.

Cette méthode n'est disponible que pour les scripts Basic.

### Syntaxe :

        SF_Exception.Clear()

### Exemple :

L'exemple suivant montre comment intercepter une exception de division par zéro, dont le code d'erreur est 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()
                'Si division par zéro, ignorer l'erreur
        End Sub

For a complete list of Basic run-time error codes, refer to Debugging a Basic Program.

## Console

Affiche les messages de la console dans une boîte de dialogue modale ou non modale. Dans les deux modes, tous les messages passés émis par une méthode DebugPrint() ou résultant d'une exception sont affichés. En mode non modal, les entrées suivantes sont ajoutées automatiquement.

Si la console est déjà ouverte, lorsqu'elle est non modale, elle est amenée au premier plan.

Une console modale ne peut être fermée que par l'utilisateur. Une console non modale peut être fermée par l'utilisateur ou lors de l'arrêt de la macro.

### Syntaxe :

exc.Console(modal: bool = True)

### Paramètres :

modal : détermine si la fenêtre de la console est modale (True) ou non modale (False). La valeur par défaut est True.

### Exemple :

##### En Basic :

            SF_Exception.Console(Modal := False)

##### En Python

        exc.Console(modal = False)

## ConsoleClear

Efface la console en conservant un nombre facultatif de messages récents. Si la console est activée en mode non modal, elle est rafraîchie.

### Syntaxe :

exc.ConsoleClear(keep: int = 0)

### Paramètres :

keep : le nombre de messages récents à conserver. La valeur par défaut est 0.

### Exemple :

L'exemple suivant efface la console en conservant les 10 messages les plus récents.

##### En Basic :

            SF_Exception.ConsoleClear(10)

##### En Python

        exc.ConsoleClear(10)

## ConsoleToFile

Exporte le contenu de la console dans un fichier texte. Si le fichier existe déjà et que la console n'est pas vide, il sera écrasé sans avertissement. Renvoie True en cas de succès.

### Syntaxe :

exc.ConsoleToFile(filename: str): bool

### Paramètres :

filename: The name of the text file the console should be dumped into. The name is expressed according to the current FileNaming property of the SF_FileSystem service. By default, URL notation and the native operating system's format are both admitted.

### Exemple :

##### En Basic :

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

##### En Python

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

## DebugDisplay

Concatène tous les arguments en une seule chaîne lisible par l'homme et l'affiche dans une MsgBox avec une icône d'information et un bouton OK.

La chaîne finale est également ajoutée à la console.

### Syntaxe :

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

### Paramètres :

arg0[, arg1, ...] : n'importe quel nombre d'arguments de n'importe quel type.

### Exemple :

##### En Basic :

        SF_Exception.DebugDisplay("Current Value", someVar)

##### En Python

        exc.DebugDisplay("Current Value", someVar)

## DebugPrint

Assemble tous les arguments donnés en une seule chaîne lisible par l'homme et l'ajoute en tant que nouvelle entrée dans la console.

### Syntaxe :

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

### Paramètres :

arg0[, arg1, ...] : n'importe quel nombre d'arguments de n'importe quel type.

### Exemple :

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

##### En Python

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

## PythonPrint

Displays the list of arguments in a readable form in the Python shell (APSO) console. Arguments are separated by a TAB character (simulated by spaces).

The same string is added to the ScriptForge debug console.

Cette méthode n'est disponible que pour les scripts Basic.

### Syntaxe :

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

Cette méthode nécessite l'installation de l'extension APSO (Alternative Script Organizer pour Python). À son tour, APSO requiert la présence de l'environnement de script LibreOffice Python. Si APSO ou Python sont manquants, une erreur se produit.

### Paramètres :

arg0[, arg1, ...]: Any number of arguments of any type. The maximum length of each individual argument is 1024 characters.

### Exemple :

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

In python use simply the builtin print() statement.

## PythonShell

Opens an APSO Python shell as a non-modal window. The Python script keeps running after the shell is opened. The output from print statements inside the script are shown in the shell.

Only a single instance of the APSO Python shell can be opened at any time. Hence, if a Python shell is already open, then calling this method will have no effect.

Cette méthode nécessite l'installation de l'extension APSO (Alternative Script Organizer pour Python). À son tour, APSO requiert la présence de l'environnement de script LibreOffice Python. Si APSO ou Python sont manquants, une erreur se produit.

### Syntaxe :

exc.PythonShell(variables: dict)

### Paramètres :

variables: a Python dictionary with variable names and values that will be passed on to the APSO Python shell. By default all local variables are passed using Python's builtin locals() function.

### Exemple :

The example below opens the APSO Python shell passing all global and local variables considering the context where the script is running.

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

When the APSO Python shell is open, any subsequent output printed by the script will be shown in the shell. Hence, the string printed in the example below will be displayed in the Python shell.

        exc.PythonShell()
        print("Hello world!")

## Raise

Generates a run-time error. An error message is displayed to the user and reported in the console. The execution is stopped. The Raise() method can be placed inside the normal script flow or in a dedicated error-handling routine.

Cette méthode n'est disponible que pour les scripts Basic.

### Syntaxe :

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

The code snippets presented next are equivalent. They show alternative ways to raise an exception with code 2100.

        SF_Exception.Raise(2100)

        SF_Exception.Number = 2100
        SF_Exception.Raise()

        SF_Exception.Raise Number := 2100

### Paramètres :

Number: The error code, as a number or as a string. Default value is that of Err Basic builtin function.

Source: The location of the error, as a number or as a string. Default value is that of Erl Basic builtin function.

Description: The message to display to the user and to report in the console. Default value is that of Error$ Basic builtin function.

### Exemple :

        Sub Example_Raise()
            Dim a, b, c
            On Local Error GoTo Catch
            Try:
                a = 10 : b = 0
                c = a / b
                '...
                Exit Sub
            Catch:
                'See variants below ...
        End Sub

To raise an exception with the standard values:

        Catch:
            SF_Exception.Raise()

To raise an exception with a specific code:

        Catch:
            SF_Exception.Raise(11)

To replace the usual message:

        Catch:
            SF_Exception.Raise(, , "It is not a good idea to divide by zero.")

To raise an application error:

        Catch:
            SF_Exception.Raise("MyAppError", "Example_Raise()", "Something wrong happened !")

## RaiseWarning

This method has exactly the same syntax, arguments and behavior as the Raise() method.

However, when a warning is raised, the macro execution is not stopped.

Cette méthode n'est disponible que pour les scripts Basic.

### Syntaxe :

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

### Paramètres :

Number: The error code, as a number or as a string. Default value is that of Err Basic builtin function.

Source: The location of the error, as a number or as a string. Default value is that of Erl Basic builtin function.

Description: The message to display to the user and to report in the console. Default value is that of Error$ Basic builtin function.

### Exemple :

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

Rubriques connexes

Fonctions de gestion des erreurs