Editor Support

Refingere has an extension for Visual Studio Code: errors as you type, the outline, go to definition, hover, completion and formatting for .rfn files, from the compiler itself, plus syntax highlighting and two color themes that match the code on this site. The same colors are also available for the terminal.

Install the VS Code extension

Download refingere.vsix - the whole extension is this one file. In VS Code, open the Extensions view (Ctrl+Shift+X) and drop the file onto it. Choosing Install from VSIX... from the view's ... menu works too, as does the command line:

Reload the window (Ctrl+Shift+P, Developer: Reload Window). Open an .rfn file and the status bar's language shows Refingere. To update, install a newer file the same way - it replaces the old version.

The language features run on Bun, like the compiler - see Getting Started. If Bun isn't on your PATH, set refingere.bunPath in VS Code's settings to where it is.

What it does

The compiler reads the whole folder you have open - every file, as you're typing it, saved or not - and the extension shows what it finds:

  • Errors as you type, underlined where they are, in every file of the folder at once. A mistake in one definition doesn't hide the rest of the file.
  • The outline (the Outline view, and Ctrl+Shift+O): every definition in the file, with a struct's fields, an enum's cases and an interface's members.
  • Go to definition (F12, or Ctrl+click) on a name: a local variable, a parameter, or a definition anywhere in the folder. On a builtin - a type, a method, &stdout, @require, an operator - it opens the line of core.md, the language's reference, that declares it.
  • Hover on a name to see its definition's first line and its /// comment - and, for a value, the type the type checker gave it. A builtin, a keyword or an operator shows what this site's reference says about it, with a link to its card here.
  • Completion (Ctrl+Space): the names in scope, the definitions your file can see, builtin types and keywords - a function with its parameters to fill in. After a . (or ?., !., !?.), the members of what's before it, as the type checker knows them - a struct's fields, its methods and those core.md gives builtin types, or a type's cases and functions - each with its signature. After &, the context values that reach the file; after @, the attributes; after #, the macros, their quotes or {{{ }}} written in. Building a struct, Point{ offers the fields not given yet, and after an annotation's : only types are offered.
  • Formatting (Shift+Alt+F, or on every save with the setting below) - see Formatting.
  • Expand Macro (the context menu, the command palette, or Ctrl+. on a line using one) replaces the macro uses on the cursor's line by what they stand for - and Expand All Macros in File every one in the file. One undo takes it back. A program macro's output opens beside the file instead. It saves the file and runs the compiler bundled with the extension, so the project has to compile - see Expanding a macro in place.

Alongside those, it:

  • Highlights keywords, the names definitions introduce, types, strings and numbers, attributes, context values like &stdout, backtick paths, compact powers and indexes like x² and xᵢ, and comments.
  • Shows the #{ } placeholders in a string macro like #format"..." as code, and the body of an embedded language in that language: #SQL {{{ ... }}} is highlighted as SQL, and likewise #HTML, #CSS, #SVG, #JSON, #YAML, #MARKDOWN and #SHELL.
  • Toggles comments with Ctrl+/ (///), matches and closes brackets and quotes, and indents after an opening bracket.
  • Gives .rfn files the Refingere logo as their icon.

It knows the language's words from the Keyword Index, the same lists this site highlights with, so both color code the same way.

Debugging

Press F5 in a .rfn file - or add a Refingere configuration to launch.json - and the program runs under VS Code's debugger: put a breakpoint on a line of Refingere, step through its statements, and read the call stack and the locals when it stops. "test": true in the configuration debugs the project's @tests instead of its @main, and "args" is what the program is run with.

The extension builds the program to JavaScript with a source map back to your files and has VS Code's own JavaScript debugger run it on Node, so Node has to be installed. The locals are named as the compiled program names them - v8_total for total. From the command line, bun run src/index.ts --debug does the same and waits for any debugger that speaks Node's inspector - Chrome's chrome://inspect too.

Formatting

Much of how Refingere code is laid out is already fixed by the grammar - see Syntax - and the formatter does the rest: two spaces per level (lines inside ( ) and [ ] included), one blank line between definitions and at most one anywhere else, no trailing spaces, one space after a comma or : and around :=, and none just inside ( ) and [ ]. Comments stay where they are, and a trailing comment keeps its column, so comments lined up stay lined up.

Spacing can carry meaning - f(x) is a call and f (x) isn't - so the formatter only ever moves whitespace, and checks that the result reads as exactly the same program before changing anything. A file with a mistake other than its indentation is left as it is. To format every file as you save it, add this to your settings:

Refingere: Format All Files, in the command palette, formats every .rfn file in the open folders at once - one undo takes it back - and saves them. The same formatter runs from the command line as rfn --format - see Command Line.

Color themes

The extension comes with Refingere Light and Refingere Dark: keywords in bold purple, names in indigo, strings and numbers in teal, on the same gray backgrounds as the code on this site. Pick one with Ctrl+K Ctrl+T (Preferences: Color Theme). They color other languages and VS Code's terminal too. To follow the system's light or dark mode, add this to your settings:

The terminal

refingere.palette has the same colors for Ptyxis, GNOME's terminal, in a light and a dark variant. Copy it into place, then pick Refingere under Preferences → Profile → Palette:

Magenta is the keyword purple, blue the indigo of names and cyan the teal of literals, while red, green and yellow keep meaning error, success and warning.

Building it yourself

The extension lives in editors/vscode/, the language server it starts in src/lsp/ and the terminal palette in editors/terminal/. The server speaks the Language Server Protocol, so other editors can use it too. From the Refingere-Language folder:

bun test fails while the committed grammar is behind the Keyword Index. See Working on the Compiler for the rest of the repository.