| 📦 Turbo MoonBit cc1f595 k33g 16h ago | 1 | # Reference: MoonBit tools |
| 2 | |
| 3 | > Neutral description of `.turbo-moonbit/tools.toml`, the MoonBit menu, and what running a command does. |
| 4 | |
| 5 | ## File |
| 6 | |
| 7 | | Property | Value | |
| 8 | | --- | --- | |
| 9 | | Path | `./.turbo-moonbit/tools.toml` | |
| 10 | | Search | The working directory only. Parent directories are **not** searched. | |
| 11 | | Read | Every time one of its menus opens, for the items | |
| 12 | | Re-read | Whenever the file's size or modification time changes, for the **set** of menus | |
| 13 | | Missing file | Not an error | |
| 14 | | Unreadable file | An error, shown in the menu | |
| 15 | | User-level file | **None.** Unlike snippets, there is no `~/.config/turbo-moonbit/tools.toml`. | |
| 16 | |
| 17 | ## File format |
| 18 | |
| 19 | One `[[tool]]` table per command. |
| 20 | |
| 21 | | Key | Type | Required | Description | |
| 22 | | --- | --- | --- | --- | |
| 23 | | `name` | string | yes | What the menu shows. May carry a hot key written with tildes, as in `"~T~est"`. | |
| 24 | | `command` | string | yes | The shell command to run | |
| 25 | | `output` | string | no | Where its output goes: `popup`, `terminal` or `editor`. Absent means `popup`. | |
| 26 | | `menu` | string | no | Which menu it appears in. Absent means `MoonBit`. Any name; the menu is created for you. May carry a hot key written with tildes. | |
| 27 | |
| 28 | `menu` is not checked against a list, because there is no list: a name that no other tool uses simply creates a menu. A tool with no `name`, no `command`, or an `output` naming something that does not exist makes the whole file an error. An unknown `output` is **refused rather than corrected**: `"termnial"` would otherwise look as though it had worked while sending the output somewhere else. |
| 29 | |
| 30 | ### Example |
| 31 | |
| 32 | ```toml |
| 33 | [[tool]] |
| 34 | name = "~T~est" |
| 35 | command = "moon test" |
| 36 | output = "popup" |
| 37 | |
| 38 | [[tool]] |
| 39 | name = "~E~cho" |
| 40 | command = "echo TADA" |
| 41 | output = "terminal" |
| 42 | menu = "Tools" |
| 43 | ``` |
| 44 | |
| 45 | ## The starter file |
| 46 | |
| 47 | **MoonBit ▸ Create tools file** writes these nine, in this order: |
| 48 | |
| 49 | | Name | Command | Output | Menu | |
| 50 | | --- | --- | --- | --- | |
| 51 | | `~C~heck` | `moon check` | `popup` | MoonBit | |
| 52 | | `~F~ormat` | `moon fmt` | `popup` | MoonBit | |
| 53 | | `~B~uild` | `moon build --target {{backend: wasm-gc, js, native, llvm or all...}}` | `popup` | MoonBit | |
| 54 | | `~T~est` | `moon test` | `popup` | MoonBit | |
| 55 | | `~R~un` | `moon run {{package, e.g. cmd/main}}` | `terminal` | MoonBit | |
| 56 | | `~A~dd a dependency` | `moon add {{module, e.g. moonbitlang/x}}` | `popup` | MoonBit | |
| 57 | | `~I~nterfaces` | `moon info` | `popup` | MoonBit | |
| 58 | | `C~l~ean` | `moon clean` | `popup` | MoonBit | |
| 59 | | `~E~cho` | `echo 🎉 tada!` | `terminal` | Tools | |
| 60 | |
| 61 | `Check` comes before `Build` because it is the command that answers "is this sound?" without producing anything. Three of them ask for a value before they run, and one names a `menu` of its own — those two features are invisible unless the starter file shows them. |
| 62 | |
| 63 | Every tool names its `output`, including the ones that name the default: the key is the interesting part of the format, and a file where it appears once is a file where nobody notices it exists. |
| 64 | |
| 65 | The item is greyed out once the project has a tools file, so it cannot overwrite one. The file is written through a temporary file in the same directory, renamed into place. |
| 66 | |
| 67 | ## The MoonBit menu |
| 68 | |
| 69 | Always on the bar, whether or not a tools file exists. Its hot key is `Alt-M`. |
| 70 | |
| 71 | | Item | Condition | |
| 72 | | --- | --- | |
| 73 | | One line per tool with no `menu`, in file order | The file holds at least one | |
| 74 | | `Cannot read tools`, greyed out | The file is present but unreadable | |
| 75 | | `Create tools file` | The project has no tools file | |
| 76 | | `Open tools file` | The project has one | |
| 77 | |
| 78 | ## Menus a tool asks for |
| 79 | |
| 80 | A `menu` naming anything other than `MoonBit` puts a menu of that name on the bar. |
| 81 | |
| 82 | | Property | Value | |
| 83 | | --- | --- | |
| 84 | | Position | Between MoonBit and Help | |
| 85 | | Order | The order each name first appears in the file | |
| 86 | | Items | One line per tool naming that menu, in file order. Nothing else — `Create tools file` and `Open tools file` stay in MoonBit. | |
| 87 | | Unreadable file | No menus at all; the MoonBit menu carries the error | |
| 88 | | While the editor runs | Added, removed and renamed as the file changes, without restarting | |
| 89 | |
| 90 | ### Hot keys |
| 91 | |
| 92 | Assigned automatically, because a name from a file cannot be checked against the fixed menus in advance. |
| 93 | |
| 94 | | Case | Result | |
| 95 | | --- | --- | |
| 96 | | No tildes in the name | The first letter no other menu has claimed is marked. `Format` becomes `For~m~at`: `F` is File's, `o` is Options', `r` is Run's. | |
| 97 | | Tildes naming a free letter | Kept as written. `Doc~k~er` answers to `Alt-K`. | |
| 98 | | Tildes naming a taken letter | Dropped, and a free letter chosen instead. `~F~oo` becomes `F~o~o`. | |
| 99 | | Every letter taken | No hot key. `F10` and the mouse still open it. | |
| 100 | |
| 101 | The letters the editor's own menus hold are `F`, `E`, `S`, `R`, `O`, `W`, `N` (Snippets), `G` and `H`. |
| 102 | |
| 103 | ## Running a command |
| 104 | |
| 105 | Common to every output: |
| 106 | |
| 107 | | Property | Value | |
| 108 | | --- | --- | |
| 109 | | Shell | `/bin/sh -c "<command>"` on Linux and macOS; `cmd.exe /S /C "<command>"` — the shell `%COMSPEC%` names — on Windows | |
| 110 | | Directory | The directory the editor was started in | |
| 111 | | Standard error | Merged into standard output, in the order the command wrote them | |
| 112 | |
| 113 | Going through a shell means pipes, globs, `&&` and `;` all work, so one tool can be a sequence. On Windows the shell is cmd.exe, which knows `&&`, `|` and `>` but does not expand globs, and where `;` is not a separator. |
| 114 | |
| 115 | ### `output = "popup"` |
| 116 | |
| 117 | | Property | Value | |
| 118 | | --- | --- | |
| 119 | | Opens | Immediately, before the command has finished | |
| 120 | | Modal | Yes: nothing else in the editor can be used while it is up | |
| 121 | | Fills in | As output arrives, following it until you scroll back | |
| 122 | | Title while running | `<command> — running` | |
| 123 | | Title when finished | `<command> — ok`, or `<command> — exit <n>` | |
| 124 | | Empty output, finished | Shows `(no output)` | |
| 125 | | Empty output, running | Shows nothing | |
| 126 | | Output cap | 10000 lines; past it the oldest go and a `… n earlier lines dropped …` line says so | |
| 127 | |
| 128 | | Key | Effect | |
| 129 | | --- | --- | |
| 130 | | `↑` `↓` `PgUp` `PgDn` `Home` `End` | Read through the output | |
| 131 | | Wheel | The same | |
| 132 | | `Escape`, `Enter`, **Close** | Close it, **stopping the command** if it is still running | |
| 133 | |
| 134 | Closing stops the command because there is no other way to interrupt one whose output is not in a terminal. |
| 135 | |
| 136 | ### `output = "terminal"` |
| 137 | |
| 138 | | Property | Value | |
| 139 | | --- | --- | |
| 140 | | Window | A terminal window of its own, titled with the command | |
| 141 | | Environment | The editor's own, with `TERM` set to `xterm-256color` | |
| 142 | | After it exits | The window stays, showing its output | |
| 143 | | Modal | No: the editor carries on beside it | |
| 144 | |
| 145 | Because it is a real terminal, colours, paging, `Ctrl-C` and reading from the keyboard all work. See [Terminal windows](terminal.md). |
| 146 | |
| 147 | Keys in a **finished** terminal window: |
| 148 | |
| 149 | | Key | Effect | |
| 150 | | --- | --- | |
| 151 | | `Shift-PgUp`, `Shift-PgDn` | Read back through the output | |
| 152 | | `Ctrl-W` | Close the window | |
| 153 | | Anything else | Reaches the editor, not the dead shell | |
| 154 | |
| 155 | ### `output = "editor"` |
| 156 | |
| 157 | | Property | Value | |
| 158 | | --- | --- | |
| 159 | | Shows | A popup while it runs, as above | |
| 160 | | On closing the popup | An editing window holding the output, titled with the command | |
| 161 | | Filled | Once, when the command has finished — not as it goes | |
| 162 | | The window | An ordinary editing window with no file name: searchable with `Ctrl-F`, and `Save as` keeps it | |
| 163 | |
| 164 | ## Reloading after a command |
| 165 | |
| 166 | When a command finishes, every open file is considered. |
| 167 | |
| 168 | | The file | What happens | |
| 169 | | --- | --- | |
| 170 | | Unmodified, and changed on disk | Re-read; its syntax is re-decided and its title refreshed | |
| 171 | | Unmodified, and unchanged on disk | Left alone, not counted | |
| 172 | | Has unsaved changes | Left alone and counted as skipped | |
| 173 | | Has never been named | Left alone | |
| 174 | | Has gone from disk | Left alone | |
| 175 | |
| 176 | The cursor stays where it was, clamped into whatever the file now holds. The undo history is discarded, because undoing back past a reload would restore text the file no longer has. |
| 177 | |
| 178 | The project tree is refreshed at the same moment. |
| 179 | |
| 180 | | Status bar | When | |
| 181 | | --- | --- | |
| 182 | | `Running <command>` | The window opens | |
| 183 | | `Reloaded 2 files` | Two files were re-read, none skipped | |
| 184 | | `Reloaded 2 files; 1 file with unsaved changes left alone` | Some were skipped | |
| 185 | | `Command finished; 1 file with unsaved changes left alone` | Nothing was re-read, something was skipped | |
| 186 | |
| 187 | ## Errors |
| 188 | |
| 189 | | Message | Cause | |
| 190 | | --- | --- | |
| 191 | | `Cannot read tools` in the menu | The file is present but not valid TOML, or holds a tool with no name or no command | |
| 192 | | `Already there: .turbo-moonbit/tools.toml` | Creating in a project that already has one. Unreachable from the menu, which greys the item out; still possible for a caller that is not a menu. | |
| 193 | | `This project has no .turbo-moonbit/tools.toml yet.` | Opening in a project that has none, likewise | |
| 194 | | `Cannot tell which directory this is: …` | The working directory could not be read | |
| 195 | | `Terminal windows are not supported on this platform yet` | Running a command in a terminal needs a pseudo-terminal, which Linux, macOS and Windows have; see [Terminal windows](terminal.md) | |
| 196 | |
| 197 | ## Asking for a value |
| 198 | |
| 199 | A `{{label}}` anywhere in a command is a value the editor asks for before it runs, in a box titled after the tool. The text between the braces is what the box asks for. |
| 200 | |
| 201 | | Written | Asked for | Substituted | |
| 202 | | --- | --- | --- | |
| 203 | | `{{module path}}` | `module path` | shell-quoted | |
| 204 | | `{{extra flags...}}` | `extra flags` | verbatim | |
| 205 | |
| 206 | A value is **shell-quoted** by default, so a path with a space in it stays one argument. A trailing `...` inside the braces asks for it verbatim instead, which is how one field can stand for several arguments. |
| 207 | |
| 208 | ```toml |
| 209 | [[tool]] |
| 210 | name = "~I~nit module" |
| 211 | command = "go mod init {{module path}}" |
| 212 | output = "popup" |
| 213 | ``` |
| 214 | |
| 215 | | Rule | Behaviour | |
| 216 | | --- | --- | |
| 217 | | Several placeholders | One box, one field each, in the order they appear in the command | |
| 218 | | The same label twice | One field; every occurrence gets what is typed into it | |
| 219 | | A label written both ways | Asked for once; each occurrence honours its own braces | |
| 220 | | Escape, or Cancel | The command does not run | |
| 221 | | A field left empty | Substituted as empty — the command reports its own complaint | |
| 222 | | Running the tool again | The box starts from what was typed last time, for this session only | |
| 223 | | More fields than fit on screen | Refused, with a message saying how many fit | |
| 224 | |
| 225 | **Double braces, not single.** `awk '{print $1}'` and `find . -exec rm {} +` are ordinary commands, and a single-brace syntax would read the first as a request for a value called `print $1`. |
| 226 | |
| 227 | Nothing is written to disk. A value somebody typed this afternoon is not a decision the project made, so it does not go in the project's own directory. |
| 228 | |
| 229 | ### Errors |
| 230 | |
| 231 | | Error | Cause | |
| 232 | | --- | --- | |
| 233 | | `tool "X": "{{module" is never closed` | An opening `{{` with no `}}` after it | |
| 234 | | `tool "X": {{}} asks for a value but does not say what it is` | A placeholder with no label, or one that is only `...` | |
| 235 | |
| 236 | Both are refused when the file is read, so a half-typed placeholder never reaches the shell with its braces still in it. |
| 237 | |
| 238 | ## See also |
| 239 | |
| 240 | - [How to run moon commands from the editor](../how-to/run-moon-commands.md) |
| 241 | - [MoonBit tools](../explanation/moonbit-tools.md) |
| 242 | - [Terminal windows](terminal.md) |