| 🛟 Updated. 28d5985 k33g yesterday | 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 | |
| 📦 Turbo Core — files rewritten outside reload into their windows; the agent window wraps what you type and keeps a long paste aside as a token (#28); configrepo fetches a shared .turbo-<slug> from a forge URL (#25) fe23288 k33g 12h ago | 35 | Un fichier qu'un autre programme réécrit pendant qu'il est ouvert — un formateur, un générateur, un agent de code dans un autre terminal — est **relu dans sa fenêtre sans qu'il faille la fermer et la rouvrir**, et la barre d'état dit `Reloaded main.go`. Le curseur reste où il était, ramené dans le nouveau texte. Le disque est regardé une fois par seconde quand l'éditeur est inactif, et à chaque tour de la boucle d'événements sinon ; la vérification coûte un `stat` par fenêtre ouverte, si bien qu'un fichier dont la taille et la date de modification n'ont pas bougé n'est jamais lu. |
| 36 | |
| 37 | Une fenêtre **qui a des modifications non enregistrées n'est jamais rechargée** : la barre d'état dit `main.go changed on disk; your unsaved changes are kept`, une fois par changement, et le prochain enregistrement écrit la fenêtre par-dessus le fichier. Un fichier qui disparaît du disque est laissé tel quel dans sa fenêtre, sans un mot, et repris quand il revient. Un rechargement dit au serveur de langage ce que le fichier contient désormais, comme l'aurait fait la frappe. |
| 38 | |
| 🛟 Updated. 28d5985 k33g yesterday | 39 | ## Réglages |
| 40 | |
| 41 | | Méthode | Description | |
| 42 | | --- | --- | |
| 43 | | `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. | |
| 44 | | `SettingsPath() string` | Le fichier de réglages suivi, ou `""`. | |
| 45 | | `SetAutosave(on bool, delay time.Duration)` | Active ou désactive la sauvegarde automatique. | |
| 46 | |
| 47 | 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. |
| 48 | |
| 49 | ## Les trois fichiers du projet |
| 50 | |
| 51 | `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. |
| 52 | |
| 53 | | Méthode | Description | |
| 54 | | --- | --- | |
| 55 | | `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. | |
| 56 | | `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. | |
| 57 | | `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. | |
| 58 | |
| 59 | ## Le serveur de langage |
| 60 | |
| 61 | | Méthode | Description | |
| 62 | | --- | --- | |
| 63 | | `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. | |
| 64 | | `Language() *Language` | Le côté serveur de langage. Toutes ses méthodes ne font rien quand rien n'est connecté. | |
| 65 | | `RequestCompletion()` | Demande une complétion au curseur. | |
| 66 | | `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 ». | |
| 67 | | `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. | |
| 68 | | `ShowProblems()` | Tous les diagnostics signalés par le serveur, pour tous les fichiers dont il a parlé. | |
| 69 | |
| 70 | ### Language |
| 71 | |
| 72 | | Méthode | Description | |
| 73 | | --- | --- | |
| 74 | | `Ready() bool` | Si un serveur est connecté et initialisé. | |
| 📦 Turbo Core — canonical paths: symbolic links resolved in URIs and document keys (moon-lsp on macOS) b91316e k33g yesterday | 75 | | `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, et un fichier ouvert à travers un lien symbolique par son chemin réel. | |
| 🛟 Updated. 28d5985 k33g yesterday | 76 | | `Status() string` | L'état d'une ligne affiché sur la barre d'état. | |
| 77 | | `Report() Report` | État, chemin du serveur, racine et disponibilité ensemble. | |
| 78 | | `Stop(ctx context.Context)` | Arrête le serveur. | |
| 79 | | `TypeDefinition`, `Implementation`, `References` | Les trois requêtes de localisation à côté de `Definition`. `References` compte la déclaration parmi les réponses. | |
| 80 | | `DocumentSymbols(ctx, path) ([]lsp.Symbol, error)` | Ce qu'un fichier déclare, aplati, dans l'ordre du fichier. | |
| 81 | | `WorkspaceSymbols(ctx, query) ([]lsp.Symbol, error)` | Les symboles correspondant à une requête dans tout le projet. Ce que « correspondre » veut dire appartient au serveur. | |
| 82 | | `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é. | |
| 83 | | `FirstError(path string) (lsp.Diagnostic, bool)` | Le premier diagnostic de niveau erreur. | |
| 84 | | `AllDiagnostics() []FileDiagnostic` | Tous les problèmes de tous les fichiers, triés par fichier puis par ligne. | |
| 85 | |
| 📦 Turbo Core — a save that creates a file tells the server (workspace/didChangeWatchedFiles), so moon-lsp diagnoses a new .mbt from its first save 3561e52 k33g yesterday | 86 | 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. Une sauvegarde qui crée le fichier le signale aussi comme créé (`workspace/didChangeWatchedFiles`), pour les serveurs qui établissent la liste des fichiers d'un paquet depuis le répertoire et ne le diagnostiqueraient jamais sinon — moon-lsp. 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. |
| 🛟 Updated. 28d5985 k33g yesterday | 87 | |
| 88 | ## Ce qui est à l'écran |
| 89 | |
| 90 | | Méthode | Description | |
| 91 | | --- | --- | |
| 92 | | `Profile() profile.Profile` | Quel éditeur c'est. | |
| 93 | | `Theme() *theme.Theme`, `ThemeName() string` | Le thème en usage. | |
| 94 | | `Desktop() *ui.Desktop` | Les fenêtres. | |
| 95 | | `MenuBar() *ui.MenuBar` | La barre. | |
| 96 | | `StatusBar() *ui.StatusBar` | La barre du bas. | |
| 97 | | `Completion() *CompletionBox` | Le popup de complétion. | |
| 98 | | `Modals() int`, `TopModal() *ui.Dialog` | La pile de dialogues. | |
| 99 | | `Message(text string)` | Une note d'une ligne sur la barre d'état. | |
| 100 | | `ShowMessage(title, message string)` | Une boîte modale. | |
| 101 | |
| 102 | ## Paramètres d'un outil |
| 103 | |
| 104 | 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. |
| 105 | |
| 106 | | Fonction ou méthode | Description | |
| 107 | | --- | --- | |
| 108 | | `(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. | |
| 109 | | `(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. | |
| 110 | | `ShellQuote(value string) string` | Entoure une chaîne pour que `sh -c` n'y voie qu'un seul argument, quoi qu'elle contienne. | |
| 111 | |
| 112 | | Champ de `Placeholder` | Type | Description | |
| 113 | | --- | --- | --- | |
| 114 | | `Label` | `string` | Ce qu'il faut demander : le texte entre les accolades, sans espaces autour ni `...` final. | |
| 115 | | `Raw` | `bool` | La valeur passe telle quelle plutôt que protégée. | |
| 116 | |
| 117 | `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. |
| 118 | |
| 119 | | Fonction | Description | |
| 120 | | --- | --- | |
| 121 | | `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. | |
| 122 | | `app.NewParametersDialog(title string, labels []string, initial map[string]string, screen ui.Rect) *ParametersDialog` | La boîte. `initial` pré-remplit un champ par libellé. | |
| 123 | | `(*ParametersDialog) Dialog() *ui.Dialog` | La modale à empiler. | |
| 124 | | `(*ParametersDialog) Values() map[string]string` | Ce qui a été tapé, par libellé. | |
| 125 | |
| 126 | ## Erreurs |
| 127 | |
| 128 | `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. |
| 129 | |
| 130 | ## Voir aussi |
| 131 | |
| 132 | - [Construire un éditeur](../tutorials/build-an-editor.md) |
| 133 | - [Référence profile](profile.md) |