# Reference: Golo tools

> Neutral description of `.turbo-golo/tools.toml`, the Golo menu, and what running a command does.

## File

| Property | Value |
| --- | --- |
| Path | `./.turbo-golo/tools.toml` |
| Search | The working directory only. Parent directories are **not** searched. |
| Read | Every time one of its menus opens, for the items |
| Re-read | Whenever the file's size or modification time changes, for the **set** of menus |
| Missing file | Not an error |
| Unreadable file | An error, shown in the menu |
| User-level file | **None.** Unlike snippets, there is no `~/.config/turbo-golo/tools.toml`. |

## File format

One `[[tool]]` table per command.

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | What the menu shows. May carry a hot key written with tildes, as in `"~T~est"`. |
| `command` | string | yes | The shell command to run |
| `output` | string | no | Where its output goes: `popup`, `terminal` or `editor`. Absent means `popup`. |
| `menu` | string | no | Which menu it appears in. Absent means `Golo`. Any name; the menu is created for you. May carry a hot key written with tildes. |

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

### Example

```toml
[[tool]]
name = "~T~est"
command = "golo --test"
output = "popup"

[[tool]]
name = "~E~cho"
command = "echo TADA"
output = "terminal"
menu = "Tools"
```

## The starter file

**Golo ▸ Create tools file** writes these nine, in this order:

| Name | Command | Output | Menu |
| --- | --- | --- | --- |
| `~R~un` | `golo {{script, e.g. main.golo}}` | `terminal` | Golo |
| `~T~est` | `golo --test` | `popup` | Golo |
| `Test ~o~ne` | `golo --test {{test file or directory}}` | `popup` | Golo |
| `~D~ebug` | `golo --debug {{script, e.g. main.golo}}` | `terminal` | Golo |
| `R~E~PL` | `golo` | `terminal` | Golo |
| `~N~ew script` | `golo new main --module {{module name, e.g. hello.World}} --name {{file name without .golo}}` | `popup` | Golo |
| `~B~uild native` | `gogolo build -o {{output executable}} {{script, e.g. main.golo}}` | `popup` | Golo |
| `Build ~w~asm` | `wagolo build -target={{target: wasi, js or wasip2}} -o {{output .wasm}} {{script, e.g. main.golo}}` | `popup` | Golo |
| `~E~cho` | `echo 🎉 tada!` | `terminal` | Tools |

`Run` comes first because Golo is a scripting language and running the file is what a Golo programmer does most. Six of them ask for a value before they run — Golo has no manifest, so every command that touches a file has to be told which one — and one names a `menu` of its own. Those two features are invisible unless the starter file shows them.

`Run`, `Debug` and `REPL` get a terminal: the first two may read the keyboard, and the third is nothing else. `Build native` needs the Go toolchain on `PATH`; `Build wasm` needs TinyGo, and `wasm-tools` for the `wasip2` target.

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.

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.

## The Golo menu

Always on the bar, whether or not a tools file exists. Its hot key is `Alt-G`.

| Item | Condition |
| --- | --- |
| One line per tool with no `menu`, in file order | The file holds at least one |
| `Cannot read tools`, greyed out | The file is present but unreadable |
| `Create tools file` | The project has no tools file |
| `Open tools file` | The project has one |

## Menus a tool asks for

A `menu` naming anything other than `Golo` puts a menu of that name on the bar.

| Property | Value |
| --- | --- |
| Position | Between Golo and Help |
| Order | The order each name first appears in the file |
| Items | One line per tool naming that menu, in file order. Nothing else — `Create tools file` and `Open tools file` stay in Golo. |
| Unreadable file | No menus at all; the Golo menu carries the error |
| While the editor runs | Added, removed and renamed as the file changes, without restarting |

### Hot keys

Assigned automatically, because a name from a file cannot be checked against the fixed menus in advance.

| Case | Result |
| --- | --- |
| 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. |
| Tildes naming a free letter | Kept as written. `Doc~k~er` answers to `Alt-K`. |
| Tildes naming a taken letter | Dropped, and a free letter chosen instead. `~F~oo` becomes `F~o~o`. |
| Every letter taken | No hot key. `F10` and the mouse still open it. |

The letters the editor's own menus hold are `F`, `E`, `S`, `R`, `C`, `O`, `W`, `N` (Snippets), `G` (Golo) and `H`.

## Running a command

Common to every output:

| Property | Value |
| --- | --- |
| Shell | `/bin/sh -c "<command>"` on Linux and macOS; `cmd.exe /S /C "<command>"` — the shell `%COMSPEC%` names — on Windows |
| Directory | The directory the editor was started in |
| Standard error | Merged into standard output, in the order the command wrote them |

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.

### `output = "popup"`

| Property | Value |
| --- | --- |
| Opens | Immediately, before the command has finished |
| Modal | Yes: nothing else in the editor can be used while it is up |
| Fills in | As output arrives, following it until you scroll back |
| Title while running | `<command> — running` |
| Title when finished | `<command> — ok`, or `<command> — exit <n>` |
| Empty output, finished | Shows `(no output)` |
| Empty output, running | Shows nothing |
| Output cap | 10000 lines; past it the oldest go and a `… n earlier lines dropped …` line says so |

| Key | Effect |
| --- | --- |
| `↑` `↓` `PgUp` `PgDn` `Home` `End` | Read through the output |
| Wheel | The same |
| `Escape`, `Enter`, **Close** | Close it, **stopping the command** if it is still running |

Closing stops the command because there is no other way to interrupt one whose output is not in a terminal.

### `output = "terminal"`

| Property | Value |
| --- | --- |
| Window | A terminal window of its own, titled with the command |
| Environment | The editor's own, with `TERM` set to `xterm-256color` |
| After it exits | The window stays, showing its output |
| Modal | No: the editor carries on beside it |

Because it is a real terminal, colours, paging, `Ctrl-C` and reading from the keyboard all work — `golo --test`'s green ticks, `readln` in a script, the REPL's prompt. See [Terminal windows](terminal.md).

Keys in a **finished** terminal window:

| Key | Effect |
| --- | --- |
| `Shift-PgUp`, `Shift-PgDn` | Read back through the output |
| `Ctrl-W` | Close the window |
| Anything else | Reaches the editor, not the dead shell |

### `output = "editor"`

| Property | Value |
| --- | --- |
| Shows | A popup while it runs, as above |
| On closing the popup | An editing window holding the output, titled with the command |
| Filled | Once, when the command has finished — not as it goes |
| The window | An ordinary editing window with no file name: searchable with `Ctrl-F`, and `Save as` keeps it |

## Reloading after a command

When a command finishes, every open file is considered.

| The file | What happens |
| --- | --- |
| Unmodified, and changed on disk | Re-read; its syntax is re-decided and its title refreshed |
| Unmodified, and unchanged on disk | Left alone, not counted |
| Has unsaved changes | Left alone and counted as skipped |
| Has never been named | Left alone |
| Has gone from disk | Left alone |

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.

The project tree is refreshed at the same moment — which is how a file written by `golo new` appears in it.

| Status bar | When |
| --- | --- |
| `Running <command>` | The window opens |
| `Reloaded 2 files` | Two files were re-read, none skipped |
| `Reloaded 2 files; 1 file with unsaved changes left alone` | Some were skipped |
| `Command finished; 1 file with unsaved changes left alone` | Nothing was re-read, something was skipped |

## Errors

| Message | Cause |
| --- | --- |
| `Cannot read tools` in the menu | The file is present but not valid TOML, or holds a tool with no name or no command |
| `Already there: .turbo-golo/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. |
| `This project has no .turbo-golo/tools.toml yet.` | Opening in a project that has none, likewise |
| `Cannot tell which directory this is: …` | The working directory could not be read |
| `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) |

## Asking for a value

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.

| Written | Asked for | Substituted |
| --- | --- | --- |
| `{{script, e.g. main.golo}}` | `script, e.g. main.golo` | shell-quoted |
| `{{arguments...}}` | `arguments` | verbatim |

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.

```toml
[[tool]]
name = "Run with ~a~rguments"
command = "golo main.golo {{arguments...}}"
output = "terminal"
```

| Rule | Behaviour |
| --- | --- |
| Several placeholders | One box, one field each, in the order they appear in the command |
| The same label twice | One field; every occurrence gets what is typed into it |
| A label written both ways | Asked for once; each occurrence honours its own braces |
| Escape, or Cancel | The command does not run |
| A field left empty | Substituted as empty — the command reports its own complaint |
| Running the tool again | The box starts from what was typed last time, for this session only |
| More fields than fit on screen | Refused, with a message saying how many fit |

**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`.

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.

### Errors

| Error | Cause |
| --- | --- |
| `tool "X": "{{script" is never closed` | An opening `{{` with no `}}` after it |
| `tool "X": {{}} asks for a value but does not say what it is` | A placeholder with no label, or one that is only `...` |

Both are refused when the file is read, so a half-typed placeholder never reaches the shell with its braces still in it.

## See also

- [How to run Golo commands from the editor](../how-to/run-golo-commands.md)
- [Golo tools](../explanation/golo-tools.md)
- [Terminal windows](terminal.md)