| 🛟 Updated. 28d5985 k33g 19h ago | 1 | # Référence : l'API app |
| 2 | |
| 3 | > Description neutre de ce qu'une commande peut appeler sur un éditeur bâti sur turbo-core. Ce n'est pas tout `app` ; c'est la partie qu'une commande et ses tests utilisent. |
| 4 | |
| 5 | ## Construction |
| 6 | |
| 7 | | Fonction | Description | |
| 8 | | --- | --- | |
| 9 | | `New(screen tcell.Screen, themeName string, p profile.Profile) *App` | Un éditeur dessinant sur `screen`, étant l'éditeur que `p` décrit. Un nom de thème inconnu retombe sur le thème par défaut plutôt que d'échouer. | |
| 10 | | `ProjectRoot(p profile.Profile, files []string) string` | Le répertoire où un serveur de langage doit travailler : le premier répertoire, à partir du premier fichier et en remontant, contenant l'un des `p.RootMarkers`, ou le répertoire courant. | |
| 11 | |
| 12 | ## Le faire tourner |
| 13 | |
| 14 | | Méthode | Description | |
| 15 | | --- | --- | |
| 16 | | `Run() error` | Dessine et traite les événements jusqu'à ce que l'utilisateur parte. Renvoie nil quand l'écran a été rendu. | |
| 17 | | `Quitting() bool` | Si l'éditeur est en train de sortir. | |
| 18 | | `Tick()` | Un tour du travail piloté par l'état, sans attendre d'événement. | |
| 19 | | `Handle(event tcell.Event)` | Route un événement dans toute la chaîne, comme le fait la boucle. | |
| 20 | | `Render()` | Dispose et peint une image. | |
| 21 | |
| 22 | `Tick`, `Handle` et `Render` sont exportés pour qu'un éditeur puisse se piloter de bout en bout depuis un test, sans terminal et sans boucle d'événements. |
| 23 | |
| 24 | ## Fichiers |
| 25 | |
| 26 | | Méthode | Description | |
| 27 | | --- | --- | |
| 28 | | `NewFile()` | Ouvre une fenêtre vide. | |
| 29 | | `Open(path string)` | Ouvre un fichier, en remontant la fenêtre s'il est déjà ouvert. | |
| 30 | | `SaveFile()`, `SaveFileAs()`, `CloseFile()` | Comme le menu Fichier. | |
| 31 | | `Undo()`, `Redo()`, `Cut()`, `Copy()`, `Paste()`, `SelectAll()` | Comme le menu Edit. Rétablir est `Ctrl-R` ; `Ctrl-Y` supprime une ligne. | |
| 32 | | `InsertLine()`, `DeleteLine()` | Les `Ctrl-N` et `Ctrl-Y` de Turbo C : une ligne vide ouverte au-dessus du curseur, et la ligne du curseur supprimée. | |
| 33 | | `ActiveView() *editor.View` | La vue d'édition de la fenêtre du dessus, ou nil quand c'est un terminal, l'arborescence, ou rien. | |
| 34 | |
| 35 | ## Réglages |
| 36 | |
| 37 | | Méthode | Description | |
| 38 | | --- | --- | |
| 39 | | `UseSettings(s settings.Settings, path string)` | Applique les réglages d'un projet et retient d'où ils viennent. Le thème n'est pas appliqué ici — l'appelant le résout, parce qu'un drapeau `-theme` l'emporte sur le choix du projet. | |
| 40 | | `SettingsPath() string` | Le fichier de réglages suivi, ou `""`. | |
| 41 | | `SetAutosave(on bool, delay time.Duration)` | Active ou désactive la sauvegarde automatique. | |
| 42 | |
| 43 | Le fichier de réglages est aussi relu **après chaque enregistrement qui l'écrit**, par l'un ou l'autre des chemins d'enregistrement : un changement fait dans l'éditeur prend donc effet sans redémarrage. La sauvegarde automatique et son délai sont ré-appliqués ; le thème ne l'est pas. Un fichier qui ne s'analyse plus signale `Saved, but not applied: …` et laisse les valeurs précédentes en vigueur. |
| 44 | |
| 45 | ## Les trois fichiers du projet |
| 46 | |
| 47 | `settings.toml`, `snippets.toml` et `tools.toml` se comportent de la même façon, et exactement une entrée de chaque paire créer/ouvrir est disponible à la fois : on peut créer le fichier que le projet n'a pas, et ouvrir celui qu'il a. Les menus grisent l'autre. |
| 48 | |
| 49 | | Méthode | Description | |
| 50 | | --- | --- | |
| 51 | | `CreateProjectSettings()`, `CreateSnippets()`, `CreateTools()` | Écrivent le fichier de départ à partir du gabarit du profil et l'ouvrent. Créer par-dessus un fichier existant signale `Already there` et l'ouvre inchangé — inatteignable depuis le menu, qui grise l'entrée. | |
| 52 | | `OpenProjectSettings()`, `OpenSnippets()`, `OpenTools()` | Ouvrent le fichier du projet. N'écrivent jamais : un projet qui n'en a pas se voit indiquer l'entrée qui le crée. `OpenSnippets` ouvre le fichier **du projet**, jamais celui de l'utilisateur. | |
| 53 | | `HasProjectSettings() bool`, `HasProjectSnippets() bool`, `HasProjectTools() bool` | Si le projet a chaque fichier. Ce qui décide, pour les six entrées de menu, laquelle de la paire est grisée. | |
| 54 | |
| 55 | ## Le serveur de langage |
| 56 | |
| 57 | | Méthode | Description | |
| 58 | | --- | --- | |
| 59 | | `StartLanguageServer(ctx context.Context, root string)` | Le démarre en arrière-plan, pour qu'un démarrage lent ne retienne pas la première frappe. | |
| 60 | | `Language() *Language` | Le côté serveur de langage. Toutes ses méthodes ne font rien quand rien n'est connecté. | |
| 61 | | `RequestCompletion()` | Demande une complétion au curseur. | |
| 62 | | `DescribeSymbol()`, `GoToDefinition()`, `GoToTypeDefinition()`, `FindImplementations()`, `FindReferences()` | Les questions du menu Code sur le symbole sous le curseur. Chacune saute s'il y a une réponse, propose une liste s'il y en a plusieurs, et distingue « rien trouvé » de « le serveur n'est pas prêt ». | |
| 63 | | `SymbolInFile()`, `SymbolInProject()` | Le plan du fichier, et une recherche dans tout le projet. Les deux proposent toujours la liste, même pour une seule correspondance : savoir *quelle* chose porte ce nom est la réponse. | |
| 64 | | `ShowProblems()` | Tous les diagnostics signalés par le serveur, pour tous les fichiers dont il a parlé. | |
| 65 | |
| 66 | ### Language |
| 67 | |
| 68 | | Méthode | Description | |
| 69 | | --- | --- | |
| 70 | | `Ready() bool` | Si un serveur est connecté et initialisé. | |
| 71 | | `Knows(path string) bool` | Si le serveur a été prévenu que le document est ouvert. Indépendant de l'orthographe : un fichier ouvert par un chemin relatif est aussi connu par son chemin absolu. | |
| 72 | | `Status() string` | L'état d'une ligne affiché sur la barre d'état. | |
| 73 | | `Report() Report` | État, chemin du serveur, racine et disponibilité ensemble. | |
| 74 | | `Stop(ctx context.Context)` | Arrête le serveur. | |
| 75 | | `TypeDefinition`, `Implementation`, `References` | Les trois requêtes de localisation à côté de `Definition`. `References` compte la déclaration parmi les réponses. | |
| 76 | | `DocumentSymbols(ctx, path) ([]lsp.Symbol, error)` | Ce qu'un fichier déclare, aplati, dans l'ordre du fichier. | |
| 77 | | `WorkspaceSymbols(ctx, query) ([]lsp.Symbol, error)` | Les symboles correspondant à une requête dans tout le projet. Ce que « correspondre » veut dire appartient au serveur. | |
| 78 | | `Diagnostics(path string) []lsp.Diagnostic` | Ce que le serveur a signalé pour un fichier. Le chemin est d'abord rendu absolu : un serveur publie des URI absolues et un tampon peut porter le chemin relatif que la ligne de commande lui a donné. | |
| 79 | | `FirstError(path string) (lsp.Diagnostic, bool)` | Le premier diagnostic de niveau erreur. | |
| 80 | | `AllDiagnostics() []FileDiagnostic` | Tous les problèmes de tous les fichiers, triés par fichier puis par ligne. | |
| 81 | |
| 82 | Sauvegarder maintient exact l'ensemble des documents que le serveur croit ouverts. Écrire un fichier que le serveur connaît envoie `didSave` ; écrire un fichier qu'il ne connaît pas — une fenêtre née sans titre, sauvée pour la première fois — envoie `didOpen`, si bien que le document fonctionne dès cette sauvegarde. Un « Enregistrer sous » vers un nom réellement différent ferme d'abord l'ancien document côté serveur ; un simple changement d'orthographe du même fichier ne compte pas comme un renommage. |
| 83 | |
| 84 | ## Ce qui est à l'écran |
| 85 | |
| 86 | | Méthode | Description | |
| 87 | | --- | --- | |
| 88 | | `Profile() profile.Profile` | Quel éditeur c'est. | |
| 89 | | `Theme() *theme.Theme`, `ThemeName() string` | Le thème en usage. | |
| 90 | | `Desktop() *ui.Desktop` | Les fenêtres. | |
| 91 | | `MenuBar() *ui.MenuBar` | La barre. | |
| 92 | | `StatusBar() *ui.StatusBar` | La barre du bas. | |
| 93 | | `Completion() *CompletionBox` | Le popup de complétion. | |
| 94 | | `Modals() int`, `TopModal() *ui.Dialog` | La pile de dialogues. | |
| 95 | | `Message(text string)` | Une note d'une ligne sur la barre d'état. | |
| 96 | | `ShowMessage(title, message string)` | Une boîte modale. | |
| 97 | |
| 98 | ## Paramètres d'un outil |
| 99 | |
| 100 | Une commande peut demander des valeurs avant de se lancer, en écrivant `{{libellé}}` à l'endroit où la valeur va. `app.RunTool` ouvre une boîte pour elles ; rien ici ne dessine quoi que ce soit. |
| 101 | |
| 102 | | Fonction ou méthode | Description | |
| 103 | | --- | --- | |
| 104 | | `(Tool) Placeholders() []Placeholder` | Les valeurs demandées, dans l'ordre de première apparition, un libellé répété n'étant signalé qu'une fois. Nil quand il n'y en a aucune. | |
| 105 | | `(Tool) Fill(values map[string]string) string` | La commande avec chaque libellé remplacé. Une valeur est protégée pour le shell sauf si son libellé est `Raw` ; un libellé sans entrée devient vide. | |
| 106 | | `ShellQuote(value string) string` | Entoure une chaîne pour que `sh -c` n'y voie qu'un seul argument, quoi qu'elle contienne. | |
| 107 | |
| 108 | | Champ de `Placeholder` | Type | Description | |
| 109 | | --- | --- | --- | |
| 110 | | `Label` | `string` | Ce qu'il faut demander : le texte entre les accolades, sans espaces autour ni `...` final. | |
| 111 | | `Raw` | `bool` | La valeur passe telle quelle plutôt que protégée. | |
| 112 | |
| 113 | `Load` refuse une commande dont un `{{` n'est jamais fermé, ou dont un libellé est vide : un `Tool` venu d'un fichier s'analyse donc toujours. |
| 114 | |
| 115 | | Fonction | Description | |
| 116 | | --- | --- | |
| 117 | | `app.MaxParameterFields(screenHeight int) int` | Combien de valeurs une boîte peut demander sur un écran de cette hauteur. Un appelant qui en a plus doit le dire plutôt qu'en ouvrir une. | |
| 118 | | `app.NewParametersDialog(title string, labels []string, initial map[string]string, screen ui.Rect) *ParametersDialog` | La boîte. `initial` pré-remplit un champ par libellé. | |
| 119 | | `(*ParametersDialog) Dialog() *ui.Dialog` | La modale à empiler. | |
| 120 | | `(*ParametersDialog) Values() map[string]string` | Ce qui a été tapé, par libellé. | |
| 121 | |
| 122 | ## Erreurs |
| 123 | |
| 124 | `app` ne renvoie aucune erreur depuis ses actions : tout ce qui peut échouer est signalé à l'utilisateur sur la barre d'état ou dans un dialogue, parce que l'éditeur est ce dont il se servirait pour le réparer. |
| 125 | |
| 126 | ## Voir aussi |
| 127 | |
| 128 | - [Construire un éditeur](../tutorials/build-an-editor.md) |
| 129 | - [Référence profile](profile.md) |