# Flash language — VS Code support

Syntax highlighting for `.flash` source files: keywords, types, strings
(single-line, `'c'` chars, and `\\` raw multiline lines), `///` doc comments,
`#builtin` calls, numbers (decimal + `0x` hex), and operators.

It is a pure TextMate grammar — it ships **no colors of its own**. It assigns
standard TextMate scopes (`keyword.control`, `storage.type`, `string.quoted`,
`comment.line`, …) and your active VS Code color theme paints them. So `.flash`
files immediately match the look of every other language you already use.

## Install (no build needed)

Symlink this folder into your VS Code extensions directory, then reload:

```sh
ln -s "$PWD/editors/vscode" ~/.vscode/extensions/flash-lang-0.1.0
```

Run from the repository root so `$PWD` resolves correctly. Then in VS Code:
**Cmd+Shift+P → "Developer: Reload Window"** (or just restart it).

Open any `examples/*.flash` file. The language indicator in the status bar
(bottom-right) should read **Flash**. If it does not, click it and pick *Flash*
from the list — VS Code remembers the association for `.flash` afterwards.

To update later, edit the files in place; a reload window picks up the changes.

## Uninstall

```sh
rm ~/.vscode/extensions/flash-lang-0.1.0
```

## What it knows

The grammar tracks the lexical surface defined in `src/token.zig` and
`src/lexer.zig`:

- **Keywords** — the 33 in `token.zig` (`use as link fn export extern callconv
  align pub inline comptime const var orelse if else while for in break continue
  return try catch defer errdefer struct enum union switch asm error test`).
- **Comments** — `//` line comments, `///` doc comments (exactly three slashes;
  `////` and `//!` are ordinary comments, matching the lexer's rule).
- **Strings** — `"…"` with `\n \t \r \\ \" \0 \xNN \u{NNNNNN}` escapes, `'c'`
  char literals, and `\\…` Zig-style raw multiline lines.
- **Builtins** — `#import`, `#intCast`, … as `#name`.
- **Numbers** — decimal, `0x` hexadecimal, `0o` octal, `0b` binary (all with
  optional `_` digit separators), and decimal float literals (`3.14`, `1.5e-3`).
- **Primitive types** — `u8 i32 f64 usize bool void anyopaque anyerror type …`.

When the grammar drifts from the lexer (new keyword, new literal form), update
`syntaxes/flash.tmLanguage.json` — `token.zig` is the source of truth.

## Format on save

`flashc fmt` rewrites a file to canonical Flash — there is exactly one
accepted rendering, so formatting on save keeps every file canonical
from the start and avoids diff churn later.

There is no VS Code formatter extension yet. Two ways to wire it up:

**A task** (`.vscode/tasks.json` in your project), bound to a key or run
via *Tasks: Run Task* after saving:

```jsonc
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "flashc fmt",
      "type": "shell",
      "command": "/path/to/Flash/zig-out/bin/flashc",
      "args": ["fmt", "${file}"],
      "presentation": { "reveal": "silent" },
      "problemMatcher": []
    }
  ]
}
```

**Automatic on save** via a "Run on Save"-style extension that executes a
shell command per file pattern, e.g.:

```jsonc
// settings.json, with the emeraldwalk.runonsave extension installed
"emeraldwalk.runonsave": {
  "commands": [
    {
      "match": "\\.flash$",
      "cmd": "/path/to/Flash/zig-out/bin/flashc fmt ${file}"
    }
  ]
}
```

Both run after the save, rewriting the file on disk; VS Code reloads an
unmodified editor automatically, so the canonical form appears in place.
A file with a parse error is left untouched — the formatter refuses
rather than destroys.

## Language server

Flash ships a language server, `flashd` (`zig build lsp`, lands at
`zig-out/bin/flashd`): live compiler diagnostics over stdio. This folder
does **not** yet include a VS Code client extension to launch it — that
is planned. Until then, any generic LSP client extension that can run a
stdio server binary for a file type will work; in Neovim it runs with
the built-in client (see `editors/nvim/README.md`).