turbo-editors/turbo-golo · run-golo-commands.md

⑂ main

run-golo-commands.md · 230 lines · 11.3 KBmarkdown    Blame HistoryRaw
📦 Turbo Golo   1# How to run Golo commands from the editor
3This guide shows how to run, test, debug and compile your scripts without leaving Turbo Golo. It assumes the editor is installed and you have a directory with a `.golo` file in it.
5## Get a starter file
7Start the editor **from the directory your scripts live in**, then choose **Golo ▸ Create tools file** (`Alt-G`, then `C`).
9That writes `.turbo-golo/tools.toml` with the commands a Golo programmer runs most, and opens it. The first three:
13name = "~R~un"
14# The interpreter, on the file you name. A terminal, not a popup: a script that
15# reads the keyboard has to be able to be answered, and one that runs long has
16# to be able to be interrupted.
17command = "golo {{script, e.g. main.golo}}"
18output = "terminal"
21name = "~T~est"
22# Every *_test.golo under the current directory, with gololang.Testing.
23command = "golo --test"
24output = "popup"
27name = "Test ~o~ne"
28command = "golo --test {{test file or directory}}"
29output = "popup"
32Each `[[tool]]` becomes one line of the **Golo** menu, in the order they appear — unless it names a `menu` of its own, which a later section covers. The file is read every time the menu opens, so an edit takes effect immediately.
34
36`Alt-G`, then the letter between the tildes — `R` to run, `T` to test.
38**Run** asks first, because Golo has no manifest that says which file is the program:
41┌──────────────── Run ────────────────┐
42│  script, e.g. main.golo             │
44└─────────────────────────────────────┘
47Type `main.golo` and press `Enter`. A terminal window opens and the script runs in it; when it ends the window stays, showing what it printed. Press `Ctrl-W` to close it. Run it again and the box remembers the name for the rest of the session.
49**Test** opens a **popup** at once, which fills in as the command runs. Its title carries the command and, once it has ended, how it went:
52┌──────────────── golo --test — ok ─────────────────┐
53│  🧪 Running Golo tests...                          │
55│  📝 shapes_test.golo                               │
56│    ✓ a point describes itself                      │
57│    ✅ 1 test(s) passed                             │
60└────────────────────────────────────────────────────┘
63| Key | Effect |
64| --- | --- |
65| `↑` `↓` `PgUp` `PgDn` `Home` `End` | Read through the output |
66| `Escape` | Close it — and **stop the command** if it is still running |
67| `Enter` | Close it |
69A command that succeeded silently shows `(no output)` rather than a blank box, so you can tell it from one that has not started.
71## The rest of the menu
73| Item | What it runs | Where |
74| --- | --- | --- |
75| **Debug** | `golo --debug <script>` — the interpreter with its step debugger on | a terminal, because the debugger reads the keyboard |
76| **REPL** | `golo` — the read-eval-print loop | a terminal |
77| **New script** | `golo new main --module <name> --name <file>` — a starter program from GoloScript's own template | a popup; the new file appears in the project tree |
78| **Build native** | `gogolo build -o <out> <script>` — Golo → Go → a native executable | a popup; needs the Go toolchain |
79| **Build wasm** | `wagolo build -target=<wasi\|js\|wasip2> -o <out.wasm> <script>` — Golo → Go → TinyGo → WebAssembly | a popup; needs TinyGo, and `wasm-tools` for `wasip2` |
81`Build native` can take a while: it runs the Go compiler. The popup is modal, so while it runs you cannot type anywhere else; `Escape` closes it and stops the compile.
83## Choose where the output goes
85Set `output` on a tool:
87| `output` | What you get |
88| --- | --- |
89| `popup` | A dialog that fills in as it runs. The default. |
90| `terminal` | A terminal window: colours, `Ctrl-C`, and the keyboard reaches the program |
91| `editor` | An editing window once it has finished, to search with `Ctrl-F` |
93`Run`, `Debug` and `REPL` are `terminal` in the starter file, and they are the example of why the key exists: a popup cannot answer a script that calls `readln`, cannot be interrupted with `Ctrl-C` while `httpServe` is listening, and cannot be a REPL at all.
95Reach for `editor` when the output is something to work through — the Go source that `gogolo transpile main.golo` prints, or a long test report you want to search.
97## A long command holds the editor
99A popup is modal: while `gogolo build` runs, you cannot type anywhere else. `Escape` closes it and stops the command.
101If that gets in the way for a particular command, give it `output = "terminal"` — the window is an ordinary one and you can carry on working beside it. That is what making the key configurable is for.
103## What happens to your open files
105Golo has no formatter, so nothing in the starter file rewrites the file you are looking at. But `New script` writes a new file into the directory, `gogolo build -keep-go` leaves a `.go` beside your script, and a tool of your own may do anything. When a command finishes, the editor **re-reads every open file that has no unsaved changes**, so a file another command changed appears as it now is, and the project tree is refreshed so a new one shows up. The status bar says how many.
107A file with unsaved changes is **left alone**, and the status bar says so too:
110Reloaded 2 files; 1 file with unsaved changes left alone
113That is deliberate: your edit and the command genuinely disagree, and the editor is not the one that should decide which wins. Save first (`F2`) and run the command again, or keep editing.
115## Add your own commands
117Edit `.turbo-golo/tools.toml`. A command goes to `sh -c`, so one entry can be a whole sequence:
120
121name = "Test and ~b~uild"
122command = "golo --test && gogolo build -o bin/app main.golo"
123output = "popup"
125
126name = "~T~ranspile"
127command = "gogolo transpile {{script, e.g. main.golo}}"
128output = "editor"
130
131name = "Run in ~D~ocker"
132command = "docker run --rm -v \"$PWD:/app\" -w /app k33g/gololang:latest /golo ./{{script}}"
133output = "terminal"
136Give each a hot key with tildes, and keep them distinct — the menu answers the first match it finds.
138## Put a tool in a menu of its own
140A tool that has nothing to do with Golo does not belong in the Golo menu. Give it a `menu`:
143
144name = "~E~cho"
145command = "echo TADA"
146output = "terminal"
147menu = "Tools"
149
150name = "~U~p"
151command = "docker compose up -d"
152menu = "Docker"
154
155name = "~D~own"
156command = "docker compose down"
157menu = "Docker"
160That gives you a **Tools** menu and a **Docker** menu on the bar, between Golo and Help, in the order the names first appear in the file. Docker holds both its tools. Nothing needs restarting: save the file and the bar follows.
162The name is yours to choose — there is no list to pick from. Leave `menu` out and the tool stays in Golo, which is where eight of the nine starter commands are.
164### The hot key is chosen for you
166You cannot know, when writing the file, which letters the editor's own menus have taken. So it works it out: the first letter of the name that nothing else claims gets the tildes.
168`Tools` gets `Alt-T`, because `T` is free. A menu called `Format` would get `Alt-A`, because `F` is File's, `o` is Options' and `r` is Run's. A menu called `Go` would get `Alt-O`… no — `O` is Options'; it would get no hot key at all, because `G` is Golo's, and `F10` would be the way to it.
170Write the tildes yourself — `menu = "Doc~k~er"` — and a free letter is kept. A taken one is not: the bar answers the *first* menu matching a key, so honouring your choice would make one of the two menus unreachable. It picks another letter and says nothing.
172## Variants
174- **You have one script and never another.** Replace `golo {{script, e.g. main.golo}}` with `golo main.golo`, and the box stops appearing. The placeholder is there because a starter file cannot know which file is the program.
175- **You started the editor from a subdirectory.** Commands run there, and relative paths in the box are relative to it. Start from the directory the scripts are in.
176- **The file has a mistake in it.** The menu shows a greyed-out `Cannot read tools` where the commands would be, and **Create tools file** is still there.
177- **`gogolo` or `wagolo` is not installed.** The popup shows `command not found` and `— exit 127`, which is what a shell would have said. GoloScript's `install.sh` installs all three binaries together; a release download is one binary at a time.
178- **You want a menu named after one that exists.** `menu = "File"` gives you a second File menu, further along the bar, with a different hot key. Nothing stops you; nothing recommends it either.
179- **Your menu has no hot key.** Every letter in its name was already taken. `F10` and the arrow keys reach it, and so does the mouse. Rename it to something with a free letter.
180- **You misspelt `output`'s value.** The whole file is refused and the menu says `Cannot read tools`, naming the tool and listing what it could have been. A silent fallback would have sent the output somewhere you did not ask for.
182## Ask for a value when the command runs
184Six of the starter commands already do. The pattern is a `{{label}}` where the value goes:
187
188name = "~N~ew script"
189command = "golo new main --module {{module name, e.g. hello.World}} --name {{file name without .golo}}"
190output = "popup"
193Choosing it opens a box titled **New script** with two fields, one per placeholder, in the order they appear. **Tab** moves between them, **Enter** runs the command. Escape, and nothing runs.
195The value is quoted, so a path with a space in it stays one argument.
197### One field standing for several arguments
199Quoting is wrong when you mean "put these on the end". Add `...` inside the braces and the value goes in verbatim:
202
203name = "Run with ~a~rguments"
204command = "golo main.golo {{arguments...}}"
205output = "terminal"
208Type `--verbose input.txt` and both reach the script as separate arguments — `args` in `function main = |args|` holds them.
210### The same value twice
212Write the label twice; you are asked once:
215
216name = "~C~ompile and run"
217command = "gogolo build -o /tmp/app {{script}} && /tmp/app"
220### Variants
222- **The value is the same most times.** Run it once and the box remembers what you typed, for the rest of the session. It is not written to disk.
223- **Your command has braces in it already.** `awk '{print $1}'` and `find . -exec rm {} +` are left alone: only double braces ask for anything.
224- **The command asks for more values than fit on screen.** The editor says so rather than opening a box whose OK button is below the bottom of the terminal. Make the terminal taller, or split the command into two tools.
226## See also
228- Every key of the file and every rule: [Golo tools reference](../reference/golo-tools.md)
229- Why Run comes first, and why an unmodified file reloads: [Golo tools](../explanation/golo-tools.md)
230- The windows the commands run in: [Terminal windows](../reference/terminal.md)

📦 Turbo Golo d710c1b k33g 12h ago	1	# How to run Golo commands from the editor
	2
	3	This guide shows how to run, test, debug and compile your scripts without leaving Turbo Golo. It assumes the editor is installed and you have a directory with a `.golo` file in it.
	4
	5	## Get a starter file
	6
	7	Start the editor from the directory your scripts live in, then choose Golo ▸ Create tools file (`Alt-G`, then `C`).
	8
	9	That writes `.turbo-golo/tools.toml` with the commands a Golo programmer runs most, and opens it. The first three:
	10
	11	```toml
	12	[[tool]]
	13	name = "~R~un"
	14	# The interpreter, on the file you name. A terminal, not a popup: a script that
	15	# reads the keyboard has to be able to be answered, and one that runs long has
	16	# to be able to be interrupted.
	17	command = "golo {{script, e.g. main.golo}}"
	18	output = "terminal"
	19
	20	[[tool]]
	21	name = "~T~est"
	22	# Every *_test.golo under the current directory, with gololang.Testing.
	23	command = "golo --test"
	24	output = "popup"
	25
	26	[[tool]]
	27	name = "Test ~o~ne"
	28	command = "golo --test {{test file or directory}}"
	29	output = "popup"
	30	```
	31
	32	Each `[[tool]]` becomes one line of the Golo menu, in the order they appear — unless it names a `menu` of its own, which a later section covers. The file is read every time the menu opens, so an edit takes effect immediately.
	33
	34	## Run one
	35
	36	`Alt-G`, then the letter between the tildes — `R` to run, `T` to test.
	37
	38	Run asks first, because Golo has no manifest that says which file is the program:
	39
	40	```
	41	┌──────────────── Run ────────────────┐
	42	│ script, e.g. main.golo │
	43	│ [ ] │
	44	└─────────────────────────────────────┘
	45	```
	46
	47	Type `main.golo` and press `Enter`. A terminal window opens and the script runs in it; when it ends the window stays, showing what it printed. Press `Ctrl-W` to close it. Run it again and the box remembers the name for the rest of the session.
	48
	49	Test opens a popup at once, which fills in as the command runs. Its title carries the command and, once it has ended, how it went:
	50
	51	```
	52	┌──────────────── golo --test — ok ─────────────────┐
	53	│ 🧪 Running Golo tests... │
	54	│ │
	55	│ 📝 shapes_test.golo │
	56	│ ✓ a point describes itself │
	57	│ ✅ 1 test(s) passed │
	58	│ │
	59	│ [ Close ] │
	60	└────────────────────────────────────────────────────┘
	61	```
	62
	63	\| Key \| Effect \|
	64	\| --- \| --- \|
65	\| `↑` `↓` `PgUp` `PgDn` `Home` `End` \| Read through the output \|
66	\| `Escape` \| Close it — and stop the command if it is still running \|
67	\| `Enter` \| Close it \|
68
69	A command that succeeded silently shows `(no output)` rather than a blank box, so you can tell it from one that has not started.
70
71	## The rest of the menu
72
73	\| Item \| What it runs \| Where \|
74	\| --- \| --- \| --- \|
75	\| Debug \| `golo --debug <script>` — the interpreter with its step debugger on \| a terminal, because the debugger reads the keyboard \|
76	\| REPL \| `golo` — the read-eval-print loop \| a terminal \|
77	\| New script \| `golo new main --module <name> --name <file>` — a starter program from GoloScript's own template \| a popup; the new file appears in the project tree \|
78	\| Build native \| `gogolo build -o <out> <script>` — Golo → Go → a native executable \| a popup; needs the Go toolchain \|
79	\| Build wasm \| `wagolo build -target=<wasi\\|js\\|wasip2> -o <out.wasm> <script>` — Golo → Go → TinyGo → WebAssembly \| a popup; needs TinyGo, and `wasm-tools` for `wasip2` \|
80
81	`Build native` can take a while: it runs the Go compiler. The popup is modal, so while it runs you cannot type anywhere else; `Escape` closes it and stops the compile.
82
83	## Choose where the output goes
84
85	Set `output` on a tool:
86
87	\| `output` \| What you get \|
88	\| --- \| --- \|
89	\| `popup` \| A dialog that fills in as it runs. The default. \|
90	\| `terminal` \| A terminal window: colours, `Ctrl-C`, and the keyboard reaches the program \|
91	\| `editor` \| An editing window once it has finished, to search with `Ctrl-F` \|
92
93	`Run`, `Debug` and `REPL` are `terminal` in the starter file, and they are the example of why the key exists: a popup cannot answer a script that calls `readln`, cannot be interrupted with `Ctrl-C` while `httpServe` is listening, and cannot be a REPL at all.
94
95	Reach for `editor` when the output is something to work through — the Go source that `gogolo transpile main.golo` prints, or a long test report you want to search.
96
97	## A long command holds the editor
98
99	A popup is modal: while `gogolo build` runs, you cannot type anywhere else. `Escape` closes it and stops the command.
100
101	If that gets in the way for a particular command, give it `output = "terminal"` — the window is an ordinary one and you can carry on working beside it. That is what making the key configurable is for.
102
103	## What happens to your open files
104
105	Golo has no formatter, so nothing in the starter file rewrites the file you are looking at. But `New script` writes a new file into the directory, `gogolo build -keep-go` leaves a `.go` beside your script, and a tool of your own may do anything. When a command finishes, the editor re-reads every open file that has no unsaved changes, so a file another command changed appears as it now is, and the project tree is refreshed so a new one shows up. The status bar says how many.
106
107	A file with unsaved changes is left alone, and the status bar says so too:
108
109	```
110	Reloaded 2 files; 1 file with unsaved changes left alone
111	```
112
113	That is deliberate: your edit and the command genuinely disagree, and the editor is not the one that should decide which wins. Save first (`F2`) and run the command again, or keep editing.
114
115	## Add your own commands
116
117	Edit `.turbo-golo/tools.toml`. A command goes to `sh -c`, so one entry can be a whole sequence:
118
119	```toml
120	[[tool]]
121	name = "Test and ~b~uild"
122	command = "golo --test && gogolo build -o bin/app main.golo"
123	output = "popup"
124
125	[[tool]]
126	name = "~T~ranspile"
127	command = "gogolo transpile {{script, e.g. main.golo}}"
128	output = "editor"
129
130	[[tool]]
131	name = "Run in ~D~ocker"
132	command = "docker run --rm -v \"$PWD:/app\" -w /app k33g/gololang:latest /golo ./{{script}}"
133	output = "terminal"
134	```
135
136	Give each a hot key with tildes, and keep them distinct — the menu answers the first match it finds.
137
138	## Put a tool in a menu of its own
139
140	A tool that has nothing to do with Golo does not belong in the Golo menu. Give it a `menu`:
141
142	```toml
143	[[tool]]
144	name = "~E~cho"
145	command = "echo TADA"
146	output = "terminal"
147	menu = "Tools"
148
149	[[tool]]
150	name = "~U~p"
151	command = "docker compose up -d"
152	menu = "Docker"
153
154	[[tool]]
155	name = "~D~own"
156	command = "docker compose down"
157	menu = "Docker"
158	```
159
160	That gives you a Tools menu and a Docker menu on the bar, between Golo and Help, in the order the names first appear in the file. Docker holds both its tools. Nothing needs restarting: save the file and the bar follows.
161
162	The name is yours to choose — there is no list to pick from. Leave `menu` out and the tool stays in Golo, which is where eight of the nine starter commands are.
163
164	### The hot key is chosen for you
165
166	You cannot know, when writing the file, which letters the editor's own menus have taken. So it works it out: the first letter of the name that nothing else claims gets the tildes.
167
168	`Tools` gets `Alt-T`, because `T` is free. A menu called `Format` would get `Alt-A`, because `F` is File's, `o` is Options' and `r` is Run's. A menu called `Go` would get `Alt-O`… no — `O` is Options'; it would get no hot key at all, because `G` is Golo's, and `F10` would be the way to it.
169
170	Write the tildes yourself — `menu = "Doc~k~er"` — and a free letter is kept. A taken one is not: the bar answers the first menu matching a key, so honouring your choice would make one of the two menus unreachable. It picks another letter and says nothing.
171
172	## Variants
173
174	- You have one script and never another. Replace `golo {{script, e.g. main.golo}}` with `golo main.golo`, and the box stops appearing. The placeholder is there because a starter file cannot know which file is the program.
175	- You started the editor from a subdirectory. Commands run there, and relative paths in the box are relative to it. Start from the directory the scripts are in.
176	- The file has a mistake in it. The menu shows a greyed-out `Cannot read tools` where the commands would be, and Create tools file is still there.
177	- `gogolo` or `wagolo` is not installed. The popup shows `command not found` and `— exit 127`, which is what a shell would have said. GoloScript's `install.sh` installs all three binaries together; a release download is one binary at a time.
178	- You want a menu named after one that exists. `menu = "File"` gives you a second File menu, further along the bar, with a different hot key. Nothing stops you; nothing recommends it either.
179	- Your menu has no hot key. Every letter in its name was already taken. `F10` and the arrow keys reach it, and so does the mouse. Rename it to something with a free letter.
180	- You misspelt `output`'s value. The whole file is refused and the menu says `Cannot read tools`, naming the tool and listing what it could have been. A silent fallback would have sent the output somewhere you did not ask for.
181
182	## Ask for a value when the command runs
183
184	Six of the starter commands already do. The pattern is a `{{label}}` where the value goes:
185
186	```toml
187	[[tool]]
188	name = "~N~ew script"
189	command = "golo new main --module {{module name, e.g. hello.World}} --name {{file name without .golo}}"
190	output = "popup"
191	```
192
193	Choosing it opens a box titled New script with two fields, one per placeholder, in the order they appear. Tab moves between them, Enter runs the command. Escape, and nothing runs.
194
195	The value is quoted, so a path with a space in it stays one argument.
196
197	### One field standing for several arguments
198
199	Quoting is wrong when you mean "put these on the end". Add `...` inside the braces and the value goes in verbatim:
200
201	```toml
202	[[tool]]
203	name = "Run with ~a~rguments"
204	command = "golo main.golo {{arguments...}}"
205	output = "terminal"
206	```
207
208	Type `--verbose input.txt` and both reach the script as separate arguments — `args` in `function main = \|args\|` holds them.
209
210	### The same value twice
211
212	Write the label twice; you are asked once:
213
214	```toml
215	[[tool]]
216	name = "~C~ompile and run"
217	command = "gogolo build -o /tmp/app {{script}} && /tmp/app"
218	```
219
220	### Variants
221
222	- The value is the same most times. Run it once and the box remembers what you typed, for the rest of the session. It is not written to disk.
223	- Your command has braces in it already. `awk '{print $1}'` and `find . -exec rm {} +` are left alone: only double braces ask for anything.
224	- The command asks for more values than fit on screen. The editor says so rather than opening a box whose OK button is below the bottom of the terminal. Make the terminal taller, or split the command into two tools.
225
226	## See also
227
228	- Every key of the file and every rule: [Golo tools reference](../reference/golo-tools.md)
229	- Why Run comes first, and why an unmodified file reloads: [Golo tools](../explanation/golo-tools.md)
230	- The windows the commands run in: [Terminal windows](../reference/terminal.md)