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.

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.


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.

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

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.

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

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

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.

note

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


Syntaxe :


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

Paramètres :

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.

Exemple :


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

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.

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

Exemple :

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.

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

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
  

Paramètres :

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.

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.


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

Exemple :


    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.

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¬†: 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.

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.


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

Exemple :


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

Aidez-nous !