ScriptForge.Exception service (SF_Exception)

Contenu

# 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

Lorsqu'une erreur est détectée lors d'un appel à l'API ScriptForge, le comportement de l'application est déterminé par des propriétés spécifiques :

1. Enregistrer l'erreur dans la console Exception. C'est systématiquement effectuée.

2. Informer l'utilisateur de l'erreur au moyen d'un message standard ou localisé.

   Pour forcer un mode silencieux, définissez :

   exception.ReportScriptErrors = False ' Default = True

3. Pour ne pas arrêter l'exécution de la macro en cours, définissez :

   exception.StopWhenError = False ' Default = True

   Cela a du sens, avant de poursuivre le traitement, d'explorer les valeurs de :

   exception.ReturnCode ' Short error description

   exception.ReturnCodeDescription ' Long error description

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

Avant d'utiliser le service Exception, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

##### 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. Elles sont relatives aux erreurs survenant dans n'importe quelle instruction de macro.

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.

Les propriétés listées ci-dessous sont disponibles pour les scripts Basic et Python. Elles sont relatives uniquement aux erreurs détectées par l'API ScriptForge.

Nom | En lecture seule | Type de retour | Description
--- | --- | --- | ---
ReportScriptErrors | Non | Booléen | Indique si les erreurs de script sont affichées dans une boîte de message lorsqu'elles surviennent. La valeur par défaut est False.
ReturnCode | Oui | Chaîne de caractères | Le code renvoyé par le dernier appel à l'API ScriptForge depuis un script utilisateur. Il s'agit de la chaîne de longueur nulle si tout s'est déroulé sans erreur.
ReturnCodeDescription | Oui | Chaîne de caractères | La description du code renvoyé par le dernier appel à l'API ScriptForge depuis un script utilisateur. Il s'agit de la chaîne de longueur nulle si tout s'est déroulé sans erreur.
StopWhenError | Non | Booléen | Indique si la macro est arrêtée lorsque ScriptForge détecte une erreur dans un script utilisateur.

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

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.

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

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.

### Syntaxe :

exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

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

background : couleur d'arrière-plan de la console spécifiée comme valeur entière RVB 24 bits. L'arrière-plan par défaut est celui d'APSO.

foreground : couleur de premier plan de la console spécifiée comme valeur entière RVB 24 bits. Le premier plan par défaut est celui d'APSO.

### Exemple :

L'exemple ci-dessous ouvre le shell Python APSO en transmettant toutes les variables globales et locales en fonction du contexte dans lequel le script est exécuté. La console s'affiche avec des caractères blancs sur fond noir.

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

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.

        s = CreateScriptService('Basic')
        RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
        exc.PythonShell(background=RED, foreground=BLUE)
        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.

### Syntaxe :

        SF_Exception.Raise(Number := Err, [Source := Erl], [Description := Error$])

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 : code d'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction intégrée de base Err, auquel cas Number est facultatif.

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.

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 : code d'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction intégrée de base Err, auquel cas Number est facultatif.

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

Rubriques connexes

Fonctions de gestion des erreurs

Aidez-nous !