Service ScriptForge.Exception

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.

• Le service SF_Exception est similaire à l'objet VBA Err.

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

La console de service Exception stocke les événements, les valeurs des variables et les informations sur les erreurs. Utilisez la console lorsque l'IDE de base n'est pas facilement accessible, par exemple dans les fonctions définies par l'utilisateur (UDF) de Calc ou lors du traitement d'événements.

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

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

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.

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.

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.

    SF_Exception.Clear()
  

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
  

Pour une liste complète des codes d'erreur d'exécution Basic, reportez-vous à Débogage d'un programme Basic.

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.

exc.Console(modal: bool = True)

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

        SF_Exception.Console(Modal := False)
  

    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.

exc.ConsoleClear(keep: int = 0)

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

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

        SF_Exception.ConsoleClear(10)
  

    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.

exc.ConsoleToFile(filename: str): bool

filename : le nom du fichier texte dans lequel la console doit être copiée. Le nom est exprimé en fonction de la propriété FileNaming actuelle du service SF_FileSystem. Par défaut, la notation d'URL et le format du système d'exploitation natif sont tous deux admis.

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

    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.

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

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

    SF_Exception.DebugDisplay("Current Value", someVar)
  

    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.

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

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

    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
  

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

PythonPrint

Affiche la liste des arguments sous une forme lisible dans la console de la plateforme. Les arguments sont séparés par un caractère TAB (simulé par des espaces).

La même chaîne est ajoutée à la console de débogage ScriptForge.

Si Python shell (APSO) est actif, le contenu PythonPrint est écrit sur la console APSO à la place de la console de la plate-forme.

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

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

arg0[, arg1, ...] : n'importe quel nombre d'arguments de n'importe quel type. La longueur maximale de chaque argument individuel est de 1024 caractères.

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

En Python, utilisez une instruction print pour imprimer sur la console APSO ou utilisez la méthode DebugPrint pour imprimer sur la console de ScriptForge.

PythonShell

Ouvre un shell APSO Python en tant que fenêtre non modale. Le script Python continue de s'exécuter après l'ouverture du shell. La sortie des instructions print à l'intérieur du script est affichée dans le shell.

Une seule instance du shell APSO Python peut être ouverte à tout moment. Par conséquent, si un shell Python est déjà ouvert, l'appel de cette méthode n'aura aucun effet.

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.

exc.PythonShell(variables: dict)

variables : un dictionnaire Python avec des noms de variables et des valeurs qui seront transmises au shell APSO Python. Par défaut, toutes les variables locales sont transmises à l'aide de la fonction intégrée locals() de Python.

L'exemple ci-dessous ouvre le shell APSO Python en passant toutes les variables globales et locales en tenant compte du contexte dans lequel le script s'exécute.

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

Lorsque le shell APSO Python est ouvert, toute sortie ultérieure imprimée par le script sera affichée dans le shell. Par conséquent, la chaîne imprimée dans l'exemple ci-dessous sera affichée dans le shell Python.

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

Raise

Génère une erreur d'exécution. Un message d'erreur est affiché à l'utilisateur et signalé dans la console. L'exécution est arrêtée. La méthode Raise() peut être placée dans le flux de script normal ou dans une routine de gestion des erreurs dédiée.

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

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

Les extraits de code présentés ensuite sont équivalents. Ils montrent d'autres moyens de déclencher une exception avec le code 2100.

    SF_Exception.Raise(2100)
  

    SF_Exception.Number = 2100
    SF_Exception.Raise()
  

    SF_Exception.Raise Number := 2100
  

Number : le code d'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction Basic intégrée Err.

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.

Source : l'emplacement de l'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction Basic intégrée Erl.

Description : le message à afficher à l'utilisateur et à signaler dans la console. La valeur par défaut est celle de la fonction Basic intégrée Error$.

    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            'Voir les variantes ci-dessous...
    End Sub
  

Pour déclencher une exception avec les valeurs standard :

    Catch:
        SF_Exception.Raise()
  

Pour déclencher une exception avec un code spécifique :

    Catch:
        SF_Exception.Raise(11)
  

Pour remplacer le message habituel :

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

Pour générer une erreur d'application :

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

RaiseWarning

Cette méthode a exactement la même syntaxe, les mêmes arguments et le même comportement que la méthode Raise().

Cependant, lorsqu'un avertissement est émis, l'exécution de la macro n'est pas arrêtée.

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

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

Number : le code d'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction Basic intégrée Err.

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.

Source : l'emplacement de l'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction Basic intégrée Erl.

Description : le message à afficher à l'utilisateur et à signaler dans la console. La valeur par défaut est celle de la fonction Basic intégrée Error$.

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