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.

tip

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.

note

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


tip

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


note

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.

note

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
  
tip

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.

note

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


Syntaxe :


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

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

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.

warning

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.

note

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.

note

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