# FSON for Visual Studio Code

Syntax highlighting and editing support for **FSON** — the hand-editable
configuration notation used by the FFS project. FSON is a pragmatic
superset of [JSON5](https://json5.org/) that adds nested block comments, a
narrower bare-key grammar, `--` disabled members, `%include` directives,
and `|`-block multi-line strings.

## Features

- **Syntax highlighting** for every FSON token (TextMate grammar,
  scope `source.fson`):
  - `//` line and nested `/* … */` block comments
  - bare and quoted keys
  - single-, double-, and `|`-block strings, with escape sequences
  - numbers, hex (`0xFF`), `Infinity` / `NaN`, leading/trailing-dot forms
  - `true` / `false` / `null`
  - `%include` … `as` directives
  - `--` disabled members (dimmable via the
    `keyword.operator.disabled.fson` scope)
- **Editing support** (language configuration):
  - line/block comment toggling
  - bracket matching and auto-closing for `{}`, `[]`, `""`, `''`
  - a `wordPattern` that matches FSON's narrow bare-key grammar

## Install

**Marketplace** (publisher **Fedem**): search *FSON* in the Extensions view,
or

```bash
code --install-extension Fedem.vscode-fson
```

**From a `.vsix`** (e.g. the one hosted on <https://fson.fedem.eu>): download
it, then either

```bash
code --install-extension vscode-fson-<version>.vsix
```

or, in VS Code, open the Extensions view → `⋯` menu → **Install from VSIX…**
and pick the file.

For development, open this folder in VS Code and press <kbd>F5</kbd> to
launch an Extension Development Host, then open any `.fson` file.

## Verifying scopes

Open a `.fson` file and run **Developer: Inspect Editor Tokens and
Scopes** from the Command Palette to see the TextMate scope under the
cursor.

## Formatting

The extension registers a document formatter for `.fson` files — use
**Format Document** (or format-on-save) as usual. The formatter is a
faithful JavaScript port of FFS's canonical FSON writer, so its output
matches what the FFS `fson` library itself would produce:

- 2-space indentation, one member/element per line, `key: value` with a
  single space after `:`
- **nothing is lost**: comments (header, leading, trailing, dangling,
  footer, and nested block comments), `--` disabled members, `%include`
  directives, `|`-block multi-line strings, and the exact spelling of each
  number (`0xFF` stays `0xFF`, `1.50` stays `1.50`, `Infinity` stays
  `Infinity`) are all preserved
- empty containers stay compact (`{}` / `[]`) unless they carry comments
- strings are re-emitted double-quoted, escaping only the mandatory
  characters; raw UTF-8 (including `\uXXXX` escapes) is decoded and passed
  through — e.g. `"\u00FC"` becomes `"ü"`
- the output is a fixed point: formatting an already-formatted file changes
  nothing

If the document contains parse errors, the formatter declines to run (so a
half-typed file is never mangled) and shows a warning.

### Setting

- `fson.format.preferBareKeys` (default `false`) — when on, quoted keys are
  rewritten without quotes wherever the name satisfies the FSON bare-name
  grammar (`host`, `maxRetries`, `a_1_b2`). Off by default to preserve the
  author's chosen key style.

## Notes

- A `|`-block is highlighted as a single string; Markdown embedded inside
  it is intentionally **not** separately highlighted.
- The bare-key grammar follows FSON's narrow `name` production, not JSON5's
  `IdentifierName` — keys like `$foo`, `_x`, `name_`, or `a__b` must be
  quoted. The exact production is:

  ```
  name = [A-Za-z] ( _? [A-Za-z0-9] )*
  ```

## Development

```bash
npm install
npm test              # formatter tests + inline scope tests + corpus snapshots
npm run test:formatter   # formatter golden + corpus idempotency only
npm run test:update      # regenerate corpus snapshots after grammar changes
```

Grammar tests use [`vscode-tmgrammar-test`](https://github.com/PanAeon/vscode-tmgrammar-test)
over the project's real `corpus/fson/` files. The formatter (`formatter/`)
is validated against golden cases derived from FFS's own `FsonWriterTests`
and checked for idempotency on the corpus.

## License

MIT