How to enable Golo completion

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# How to enable Golo completion

This guide shows how to get completion, hovers, go-to-definition and error marks working. It assumes Turbo Golo is already installed.

Completion comes from **`golo lsp`** — the GoloScript interpreter itself, started in language-server mode. There is no separate server to install: a machine that can run a Golo script can complete one. Turbo Golo does not bundle the interpreter, though: editing and colouring work without it, and only completion and the error marks are lost.

## 1. Install golo

Either download a binary from the [releases page](https://codeberg.org/TypeUnsafe/golo-script/releases):

```bash
chmod +x golo-<version>-<platform>
sudo mv golo-<version>-<platform> /usr/local/bin/golo
golo --version
```

or build it from source, which also gives you the two compilers:

```bash
git clone https://codeberg.org/TypeUnsafe/golo-script.git && cd golo-script
./install.sh
```

Turbo Golo's own installer will do the second for you: `scripts/install.sh --with-server`. [How to install GoloScript](install-goloscript.md) has the details.

## 2. Make sure Turbo Golo can find it

Turbo Golo looks on `PATH` first, then in `/usr/local/bin`, which is where GoloScript's installer writes. Check:

```bash
golo --version
```

```
v0.1.1 | dev.20260802.🤓
```

If that says "command not found" but Turbo Golo still finds it, that is expected and fine: the editor searched `/usr/local/bin` itself.

## 3. Open a script

```bash
cd /path/to/your/scripts
turbo-golo main.golo
```

Golo has no project manifest, so there is nothing to look for: `golo lsp` is started in the directory of the file you opened, and it answers about that file. Where you start the editor changes nothing about completion — it decides where the Golo menu's commands run, which is a different matter.

## 4. Ask for a completion

Type the first letters of a name and press **Ctrl-Space**:

```golo
prin
```

A list drops down under the cursor — `print`, `println`, with their signatures. Keep typing to narrow it, **↑ ↓** to walk it, **Enter** or **Tab** to accept, **Escape** to dismiss.

## What the list holds

`golo lsp` offers four kinds of thing:

| Offered | Example |
| --- | --- |
| Keywords | `function`, `foreach`, `augment` |
| The interpreter's builtins, with their signatures and documentation | `println`, `readFile`, `httpGet`, `DynamicObject` |
| Functions and unions declared **at top level** in the file | your own `function helper = …` |
| Symbols pulled in by `import` from the modules embedded in the binary | `Some`, `None`, `isSome`, `either` after `import gololang.Errors` |

Two things are deliberately **not** in it, and both look like a broken server if you did not know:

- **A function declared inside another function.** Only top-level declarations are collected. Move it out, or accept that it will not be offered.
- **Anything from a `.golo` file of your own.** `import` resolves the modules built into the interpreter — `gololang.Errors`, `gololang.Types`, `gololang.Ui`, `gololang.Testing`, … — and nothing on disk. A helper in `lib/util.golo` is not seen from `main.golo`.

## Checking what the server is doing

The right-hand end of the status bar shows the language server's state: `LSP: starting…`, `LSP: ready`, or why there is none:

```
LSP: no golo — see https://codeberg.org/TypeUnsafe/golo-script/releases
```

`Run ▸ Language server status` shows the same thing in a box, with the path it found the binary at and the directory it started it in.

## Variants

**You do not want a language server at all:**

```bash
turbo-golo -no-lsp main.golo
```

**Completion is dead in a window that started without a name.** An Untitled window has no file to announce to `golo lsp` until it is saved — press **F2** and give it a name ending in `.golo`. From that save on, completion, hover and the error marks work in that window; there is no need to quit and relaunch.

**The list is empty.** `golo lsp` answers for any file, including one that does not parse — it lists keywords and builtins regardless — so an empty list almost always means the server is not running. Read the status bar.

**Ctrl-Space does nothing.** tmux, screen and IDE terminals frequently claim `Ctrl-Space` before the editor sees it. Use `Run ▸ Completion` instead.

**A request takes too long.** Every request gives up after a few seconds, so a stuck server slows the editor but never freezes it. The status bar reports the failure.

**You installed golo somewhere unusual.** The editor searches `PATH` and `/usr/local/bin`, and nowhere else — there is no environment variable naming another directory. Put the directory on `PATH`, or a symbolic link in `/usr/local/bin`.

## What else the server gives you

Completion is the loudest thing it does and the least of what it knows. The same connection answers four more questions, all of them in the **Code** menu — three about the symbol under the cursor, no selection needed, and one about a name you type.

| Key | What it does | With `golo lsp` |
| --- | --- | --- |
| **Ctrl-Space** | Completion list | yes |
| **F1** | Describe the symbol under the cursor | yes — for a function you declared, the `#` comments written just above it; for a builtin, its signature and a worked example |
| **F12** | Jump to where it is declared | yes, within the file |
| **Shift-F12** | List everywhere it is used | yes, within the file: its declaration and every call |
| **Ctrl-T** | Find a symbol by name anywhere in the project | yes: the top-level functions, unions and module names of every `.golo` file under the project root, open or not |

And, without a key: *Symbol in file…* lists the file's top-level functions and unions, with each union's variants nested under it; *Problems…* lists every diagnostic; *Find implementations…* answers with the function's declaration, the same place **F12** goes — Golo has no interfaces, so a function is its own implementation; *Go to type definition* reports nothing found.

The one that reports nothing is the server's boundary, not the editor's: `golo lsp` advertises `completion`, `hover`, `definition`, `documentSymbol`, `references`, `implementation` and `workspaceSymbol`, and not `typeDefinition`. Until GoloScript v0.2.0 it advertised only the first four and this table said so; a test in this repository failed the day the server started answering the other three, which is how the table came to be revised. The menu item stays because greying it out depending on what a server said at start-up would make the menu a different shape on different machines, and the same kind of test still fails the day a future golo answers type definitions too.

## The error marks

Problems the server finds arrive unasked, on open and on every edit. The first error in the file you are editing appears on the right of the status bar, prefixed with `⚠`; every line with a problem gets a `×` in the gutter; and **Code ▸ Problems…** lists all of them.

`golo lsp` reports three kinds:

- **Syntax errors** from the lexer and parser — a missing brace, a token the parser does not accept. The parser's messages carry a line and no column, so the mark lands on the whole line; a message with no line at all lands on line 1.
- **A `:`/`.` confusion** — `obj.method()` where Golo wants `obj: method()`.
- **A C-style comment** — `//` or `/* */`, which Golo does not have. Golo comments are `#` and `----`.

A script that parses and then fails when run gets no mark: the server parses, it never runs anything.

[How to ask what the code means](ask-about-code.md) walks through the Code menu.

## See also

- Why the server is optional, and why the interpreter is the server: [Colouring and completion](../explanation/colouring-and-completion.md)
- Installing the interpreter: [How to install GoloScript](install-goloscript.md)
- Every key: [keyboard reference](../reference/keyboard.md)