turbo-editors/turbo-golo · README.md

⑂ main

README.md · 111 lines · 10.6 KBmarkdown    Blame HistoryRaw
📦 Turbo Golo   1# turbo-golo
3A Turbo C-style editor for Golo, written in Go.
5Built on **[turbo-core](https://rickub.com/turbo-editors/turbo-core)**, the library every Turbo editor shares. What is in this repository is the command, the profile that says this editor is for Golo, and the Golo scanner — about a thousand lines, comments and all. Everything else lives in the library.
7A full-screen terminal IDE with the Borland furniture — a menu bar with hot keys, movable windows that cast shadows, modal dialogs, a clickable status bar — and the things a Golo editor needs: syntax colouring written against GoloScript's own lexer, loadable colour themes, completion and diagnostics from `golo lsp`, shell windows, per-project settings, a project tree, snippets, and the GoloScript toolchain a menu away.
10 File  Edit  Search  Run  Code  Options  Window  Snippets  Golo  Help
11╔═[x]═════════════════════════════ hello.golo ══════════════════════════════1═[■]╗
12║ 1 module hello.World                                                          ▲║
14║ 3 # Greet someone several times                                               ░║
15║ 4 struct Greeting = { name, times }                                           ░║
17║ 6 function greet = |g| {                                                      ░║
18║ 7   foreach i in range(1, g: times() + 1) {                                   ░║
19║ 8     println("Hello, " + g: name() + "! (" + i + ")")                        ░║
21║◄▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░►║
22╚════════════════════════════════════════════════════════════════════════════════╝
23 F1 Describe  F2 Save  F3 Open  F6 Window  F7 Next  F10 Menu       1:1  LSP: ready
26## Getting started
29make install
32That builds the editor, puts it where your shell looks for commands, and reports what it found — the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `golo` is installed. Then, from any directory of Golo scripts:
35turbo-golo main.golo
38To build without installing, `make build` leaves the binary in `bin/turbo-golo`. From the module proxy instead of a checkout: `go install rickub.com/turbo-editors/turbo-golo@latest`.
40For completion and diagnostics, install GoloScript as well — the editor works without it, and says so on the status bar. The language server is the interpreter itself, in `golo lsp` mode, so there is nothing separate to install: a machine that can run Golo can complete Golo. Precompiled binaries are on [the release page](https://codeberg.org/TypeUnsafe/golo-script/releases); [the install guide](docs/en/how-to/install-goloscript.md) covers them, building from source, and how to check the editor really found it.
42The [tutorial](docs/en/tutorials/getting-started.md) walks through a first session in about ten minutes, and [`demos/`](demos/) holds three Golo programs to open in it — a small one, one with tests, and a tour of every construct the scanner colours.
44## Features
46- **Every build knows what it is** — `turbo-golo -version` and **Help ▸ About** name the version, the commit and the build date, stamped in by the linker from `git describe` rather than read from a constant somebody forgot to bump
47- **Turbo Vision interface** — menu bar with `Alt`-letter hot keys, overlapping movable and resizable windows, modal dialogs, mouse support throughout
48- **Syntax colouring for nine languages** — Golo by a hand-written scanner that follows GoloScript's lexer: `#` and `----` comments, strings carried to their closing quote wherever it is, `"""` multi-line strings, character literals, the `L` and `F` suffixes, the rule that keeps `1..3` an integer and a range, and names made of any Unicode letter or emoji. Plus TOML, YAML, Markdown, JavaScript, HTML, XML, Dockerfiles and shell scripts from turbo-core
49- **Types by convention** — a capitalised name is a struct, a union or a variant, because that is how Golo writes them; `Some`, `None`, `Ok` and `Err` are types here and not constants, because in Golo they are variants of ordinary unions from `gololang.Errors`
50- **Themes** in TOML, eleven embedded — Borland navy, dark grey, paper white, espresso, Catppuccin Frappé and Latte, cobalt, Darcula and IntelliJ Light, and a hueless monochrome in both polarities — and any number of your own, with inheritance between files and between style keys. Every shipped theme is held to its contrast by tests
51- **Per-project settings** in `.turbo-golo/settings.toml` — pin a theme, turn on automatic saving — created from a menu item, never by itself, and re-read on every save so a change takes effect without a restart
52- **Completion, hover, go-to-definition, references, symbols and diagnostics** from `golo lsp`, entirely optional. The server is the interpreter, looked for on `PATH` and in `/usr/local/bin`, where GoloScript's installer puts it. It does not answer type definitions, and the editor says so rather than pretending
53- **Terminal windows** — `F8` opens a real shell in a window, with its own VT/ANSI emulator, scrollback and job control (Linux, macOS and Windows)
54- **Project tree** — `F9` shows the project's files in a window; walk it with the arrows and press Enter to open one
55- **Snippets** — a `Snippets` menu built from `.turbo-golo/snippets.toml`, grouped into submenus and filtered by the file you are in; the chosen text is inserted at the cursor and re-indented to match
56- **The GoloScript toolchain a menu away** — `Alt-G` runs the script, the tests, the debugger, the REPL, `golo new`, `gogolo build` and `wagolo build` from `.turbo-golo/tools.toml`, each showing its output where the tool asked: a popup that fills in as it goes, a terminal window, or an editing window to search. Golo has no manifest, so six of the eight commands ask which file they are for before they run — and a tool naming a `menu` of its own gets that menu on the bar
57- **Editing** with word movement, block indent, a shared clipboard, and undo that merges a run of typing into one step
58- **Faithful files** — line endings and the trailing newline are preserved, and saving is atomic
59- **Automatic saving**, off by default, writing a short while after you stop typing
61## Commands
63| Command | What it does |
64| --- | --- |
65| `make install` | Build and install onto your `PATH` |
66| `make build` | Compile into `bin/turbo-golo` |
67| `make test` | Run the whole test suite |
68| `make check` | `fmt`, `vet`, then the tests — what a commit should pass |
69| `make run FILE=x.golo` | Build and start the editor on a file |
70| `make help` | List every target |
73turbo-golo [-theme name] [-no-lsp] [file...]
74turbo-golo -list-themes
77## Documentation
79Full documentation in **[English](docs/en/)** and **[French](docs/fr/)**, organised by the [Diátaxis](https://diataxis.fr) method:
82| --- | --- |
83| **Tutorial** | [Your first Golo program in Turbo Golo](docs/en/tutorials/getting-started.md) |
84| **How-to** | [install the editor](docs/en/how-to/install.md) · [install GoloScript](docs/en/how-to/install-goloscript.md) · [run the tests](docs/en/how-to/run-the-tests.md) · [enable completion](docs/en/how-to/enable-completion.md) · [write a theme](docs/en/how-to/write-a-theme.md) · [move around a file](docs/en/how-to/navigate-code.md) · [ask about code](docs/en/how-to/ask-about-code.md) · [use a terminal](docs/en/how-to/use-a-terminal.md) · [configure a project](docs/en/how-to/configure-a-project.md) · [browse a project](docs/en/how-to/browse-a-project.md) · [use snippets](docs/en/how-to/use-snippets.md) · [run Golo commands](docs/en/how-to/run-golo-commands.md) · [make a release](docs/en/how-to/make-a-release.md) |
85| **Reference** | [command line](docs/en/reference/cli.md) · [keyboard](docs/en/reference/keyboard.md) · [menus](docs/en/reference/menus.md) · [theme format](docs/en/reference/themes.md) · [terminal windows](docs/en/reference/terminal.md) · [project settings](docs/en/reference/project-settings.md) · [project tree](docs/en/reference/project-tree.md) · [languages](docs/en/reference/languages.md) · [snippets](docs/en/reference/snippets.md) · [Golo tools](docs/en/reference/golo-tools.md) · [the version number](docs/en/reference/versioning.md) |
86| **Explanation** | [architecture](docs/en/explanation/architecture.md) · [design decisions](docs/en/explanation/design-decisions.md) · [colouring and completion](docs/en/explanation/colouring-and-completion.md) · [terminal windows](docs/en/explanation/terminal-windows.md) · [project settings](docs/en/explanation/project-settings.md) · [project tree](docs/en/explanation/project-tree.md) · [snippets](docs/en/explanation/snippets.md) · [Golo tools](docs/en/explanation/golo-tools.md) |
88The library's packages each carry their own `README.md` beside the code, in [turbo-core](https://rickub.com/turbo-editors/turbo-core).
90## Where the code is
93| --- | --- |
94| `main.go` | flags, the terminal, the wiring |
95| `internal/gololang` | the profile, the Golo scanner, the three starter files |
96| `demos/` | three Golo programs to open in the editor; each runs under `golo` |
97| everything else | [turbo-core](https://rickub.com/turbo-editors/turbo-core) |
99The dependency graph is drawn in [`docs/diagrams/packages.drawio`](docs/diagrams/packages.drawio), checked against `go list` by `diagram_test.go`.
101## Design in one line
103Two dependencies — `tcell/v2` and `BurntSushi/toml` — and everything else from the standard library, including the scanner toolkit and the Language Server Protocol client. Both come through turbo-core; this repository adds none of its own. The [design decisions](docs/en/explanation/design-decisions.md) page explains why.
105## Requirements
107Go 1.26 or later to build it — the editor is written in Go even though it is an editor for Golo. A terminal with mouse reporting, which is all of them. GoloScript is optional, and is what completion, the error marks and the Golo menu's commands need.
109
111See [LICENSE](LICENSE).

📦 Turbo Golo d710c1b k33g 10h ago	1	# turbo-golo
	2
	3	A Turbo C-style editor for Golo, written in Go.
	4
	5	Built on [turbo-core](https://rickub.com/turbo-editors/turbo-core), the library every Turbo editor shares. What is in this repository is the command, the profile that says this editor is for Golo, and the Golo scanner — about a thousand lines, comments and all. Everything else lives in the library.
	6
	7	A full-screen terminal IDE with the Borland furniture — a menu bar with hot keys, movable windows that cast shadows, modal dialogs, a clickable status bar — and the things a Golo editor needs: syntax colouring written against GoloScript's own lexer, loadable colour themes, completion and diagnostics from `golo lsp`, shell windows, per-project settings, a project tree, snippets, and the GoloScript toolchain a menu away.
	8
	9	```
	10	File Edit Search Run Code Options Window Snippets Golo Help
	11	╔═[x]═════════════════════════════ hello.golo ══════════════════════════════1═[■]╗
	12	║ 1 module hello.World ▲║
	13	║ 2 ▓║
	14	║ 3 # Greet someone several times ░║
	15	║ 4 struct Greeting = { name, times } ░║
	16	║ 5 ░║
	17	║ 6 function greet = \|g\| { ░║
	18	║ 7 foreach i in range(1, g: times() + 1) { ░║
	19	║ 8 println("Hello, " + g: name() + "! (" + i + ")") ░║
	20	║ 9 } ▼║
	21	║◄▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░►║
	22	╚════════════════════════════════════════════════════════════════════════════════╝
	23	F1 Describe F2 Save F3 Open F6 Window F7 Next F10 Menu 1:1 LSP: ready
	24	```
	25
	26	## Getting started
	27
	28	```bash
	29	make install
	30	```
	31
	32	That builds the editor, puts it where your shell looks for commands, and reports what it found — the Go version it built with, where the binary went, whether that directory is on your `PATH`, and whether `golo` is installed. Then, from any directory of Golo scripts:
	33
	34	```bash
	35	turbo-golo main.golo
	36	```
	37
	38	To build without installing, `make build` leaves the binary in `bin/turbo-golo`. From the module proxy instead of a checkout: `go install rickub.com/turbo-editors/turbo-golo@latest`.
	39
	40	For completion and diagnostics, install GoloScript as well — the editor works without it, and says so on the status bar. The language server is the interpreter itself, in `golo lsp` mode, so there is nothing separate to install: a machine that can run Golo can complete Golo. Precompiled binaries are on [the release page](https://codeberg.org/TypeUnsafe/golo-script/releases); [the install guide](docs/en/how-to/install-goloscript.md) covers them, building from source, and how to check the editor really found it.
	41
	42	The [tutorial](docs/en/tutorials/getting-started.md) walks through a first session in about ten minutes, and [`demos/`](demos/) holds three Golo programs to open in it — a small one, one with tests, and a tour of every construct the scanner colours.
	43
	44	## Features
	45
	46	- Every build knows what it is — `turbo-golo -version` and Help ▸ About name the version, the commit and the build date, stamped in by the linker from `git describe` rather than read from a constant somebody forgot to bump
	47	- Turbo Vision interface — menu bar with `Alt`-letter hot keys, overlapping movable and resizable windows, modal dialogs, mouse support throughout
	48	- Syntax colouring for nine languages — Golo by a hand-written scanner that follows GoloScript's lexer: `#` and `----` comments, strings carried to their closing quote wherever it is, `"""` multi-line strings, character literals, the `L` and `F` suffixes, the rule that keeps `1..3` an integer and a range, and names made of any Unicode letter or emoji. Plus TOML, YAML, Markdown, JavaScript, HTML, XML, Dockerfiles and shell scripts from turbo-core
	49	- Types by convention — a capitalised name is a struct, a union or a variant, because that is how Golo writes them; `Some`, `None`, `Ok` and `Err` are types here and not constants, because in Golo they are variants of ordinary unions from `gololang.Errors`
	50	- Themes in TOML, eleven embedded — Borland navy, dark grey, paper white, espresso, Catppuccin Frappé and Latte, cobalt, Darcula and IntelliJ Light, and a hueless monochrome in both polarities — and any number of your own, with inheritance between files and between style keys. Every shipped theme is held to its contrast by tests
	51	- Per-project settings in `.turbo-golo/settings.toml` — pin a theme, turn on automatic saving — created from a menu item, never by itself, and re-read on every save so a change takes effect without a restart
	52	- Completion, hover, go-to-definition, references, symbols and diagnostics from `golo lsp`, entirely optional. The server is the interpreter, looked for on `PATH` and in `/usr/local/bin`, where GoloScript's installer puts it. It does not answer type definitions, and the editor says so rather than pretending
	53	- Terminal windows — `F8` opens a real shell in a window, with its own VT/ANSI emulator, scrollback and job control (Linux, macOS and Windows)
	54	- Project tree — `F9` shows the project's files in a window; walk it with the arrows and press Enter to open one
	55	- Snippets — a `Snippets` menu built from `.turbo-golo/snippets.toml`, grouped into submenus and filtered by the file you are in; the chosen text is inserted at the cursor and re-indented to match
	56	- The GoloScript toolchain a menu away — `Alt-G` runs the script, the tests, the debugger, the REPL, `golo new`, `gogolo build` and `wagolo build` from `.turbo-golo/tools.toml`, each showing its output where the tool asked: a popup that fills in as it goes, a terminal window, or an editing window to search. Golo has no manifest, so six of the eight commands ask which file they are for before they run — and a tool naming a `menu` of its own gets that menu on the bar
	57	- Editing with word movement, block indent, a shared clipboard, and undo that merges a run of typing into one step
	58	- Faithful files — line endings and the trailing newline are preserved, and saving is atomic
	59	- Automatic saving, off by default, writing a short while after you stop typing
	60
	61	## Commands
	62
	63	\| Command \| What it does \|
	64	\| --- \| --- \|
65	\| `make install` \| Build and install onto your `PATH` \|
66	\| `make build` \| Compile into `bin/turbo-golo` \|
67	\| `make test` \| Run the whole test suite \|
68	\| `make check` \| `fmt`, `vet`, then the tests — what a commit should pass \|
69	\| `make run FILE=x.golo` \| Build and start the editor on a file \|
70	\| `make help` \| List every target \|
71
72	```bash
73	turbo-golo [-theme name] [-no-lsp] [file...]
74	turbo-golo -list-themes
75	```
76
77	## Documentation
78
79	Full documentation in [English](docs/en/) and [French](docs/fr/), organised by the [Diátaxis](https://diataxis.fr) method:
80
81	\| \| \|
82	\| --- \| --- \|
83	\| Tutorial \| [Your first Golo program in Turbo Golo](docs/en/tutorials/getting-started.md) \|
84	\| How-to \| [install the editor](docs/en/how-to/install.md) · [install GoloScript](docs/en/how-to/install-goloscript.md) · [run the tests](docs/en/how-to/run-the-tests.md) · [enable completion](docs/en/how-to/enable-completion.md) · [write a theme](docs/en/how-to/write-a-theme.md) · [move around a file](docs/en/how-to/navigate-code.md) · [ask about code](docs/en/how-to/ask-about-code.md) · [use a terminal](docs/en/how-to/use-a-terminal.md) · [configure a project](docs/en/how-to/configure-a-project.md) · [browse a project](docs/en/how-to/browse-a-project.md) · [use snippets](docs/en/how-to/use-snippets.md) · [run Golo commands](docs/en/how-to/run-golo-commands.md) · [make a release](docs/en/how-to/make-a-release.md) \|
85	\| Reference \| [command line](docs/en/reference/cli.md) · [keyboard](docs/en/reference/keyboard.md) · [menus](docs/en/reference/menus.md) · [theme format](docs/en/reference/themes.md) · [terminal windows](docs/en/reference/terminal.md) · [project settings](docs/en/reference/project-settings.md) · [project tree](docs/en/reference/project-tree.md) · [languages](docs/en/reference/languages.md) · [snippets](docs/en/reference/snippets.md) · [Golo tools](docs/en/reference/golo-tools.md) · [the version number](docs/en/reference/versioning.md) \|
86	\| Explanation \| [architecture](docs/en/explanation/architecture.md) · [design decisions](docs/en/explanation/design-decisions.md) · [colouring and completion](docs/en/explanation/colouring-and-completion.md) · [terminal windows](docs/en/explanation/terminal-windows.md) · [project settings](docs/en/explanation/project-settings.md) · [project tree](docs/en/explanation/project-tree.md) · [snippets](docs/en/explanation/snippets.md) · [Golo tools](docs/en/explanation/golo-tools.md) \|
87
88	The library's packages each carry their own `README.md` beside the code, in [turbo-core](https://rickub.com/turbo-editors/turbo-core).
89
90	## Where the code is
91
92	\| \| \|
93	\| --- \| --- \|
94	\| `main.go` \| flags, the terminal, the wiring \|
95	\| `internal/gololang` \| the profile, the Golo scanner, the three starter files \|
96	\| `demos/` \| three Golo programs to open in the editor; each runs under `golo` \|
97	\| everything else \| [turbo-core](https://rickub.com/turbo-editors/turbo-core) \|
98
99	The dependency graph is drawn in [`docs/diagrams/packages.drawio`](docs/diagrams/packages.drawio), checked against `go list` by `diagram_test.go`.
100
101	## Design in one line
102
103	Two dependencies — `tcell/v2` and `BurntSushi/toml` — and everything else from the standard library, including the scanner toolkit and the Language Server Protocol client. Both come through turbo-core; this repository adds none of its own. The [design decisions](docs/en/explanation/design-decisions.md) page explains why.
104
105	## Requirements
106
107	Go 1.26 or later to build it — the editor is written in Go even though it is an editor for Golo. A terminal with mouse reporting, which is all of them. GoloScript is optional, and is what completion, the error marks and the Golo menu's commands need.
108
109	## Licence
110
111	See [LICENSE](LICENSE).