UnoCode: the VS Code-class editor

A full code workbench that runs on the machine itself, in the shape of Visual Studio Code: an activity bar and side bar, tabbed editors with a minimap, a command palette, an integrated terminal - and extensions. Colour themes, languages, syntax grammars and snippets are the same file formats Visual Studio Code uses, so a theme or a snippet file written for VS Code works here unchanged.

The five keys worth learning

Everything in UnoCode is a command, and every command is in one searchable list. If you remember nothing else, remember the first line:

If the palette can find it, a key can be bound to it and an extension can call it. That is the whole design: nothing is wired to a key directly, so anything can be rebound.

The editor

Open a file from the Explorer, with Ctrl+P, or by typing open SDK\SAMPLE.C in the terminal. Each file gets a tab; the breadcrumb bar above the text shows where it came from.

The editing keys are the ones you already know - arrows and Home/End/PgUp/PgDn to move, Shift+movement to select, Ctrl+X/C/V/A, Ctrl+Z to undo - plus the ones that make an editor worth using:

Suggestions

Ctrl+Space asks for suggestions, and they appear as you type. They come from four places at once and are ranked together: the language's keywords, every distinct word already in the file (which is what makes completion useful in a language nothing knows about), snippets, and anything an extension offers.

The integrated terminal

Ctrl+` opens a panel at the bottom with Problems, Output and Terminal tabs. The terminal is UnoCode's own small shell - UnoDOS has no shell process for it to host - so help lists exactly what it has, and a word it does not know is an error rather than a silent nothing.

Two of its commands are worth knowing about:

• run file runs a .UNO app, or wraps a .PY file for the Python runtime and runs that - the same thing F5 does to the file you are editing.
• js expression evaluates JavaScript in the extension host itself, which is how you find out what an extension is actually doing.

Colour themes

Six themes are built in - Dark+, Light+, Monokai, Solarized Dark, High Contrast and UnoDOS Blue - and more arrive as extensions. Ctrl+K then Ctrl+T, or Preferences: Color Theme in the palette, switches between them; your choice is saved.

A theme file is a Visual Studio Code theme file, unchanged:

{
    "name": "Nord",
    "type": "dark",
    "colors": {
        "editor.background": "#2E3440",
        "editor.foreground": "#D8DEE9",
        "activityBar.background": "#3B4252",
        "statusBar.background": "#3B4252"
    },
    "tokenColors": [
        { "scope": "comment",
          "settings": { "foreground": "#616E88", "fontStyle": "italic" } },
        { "scope": ["keyword", "storage"],
          "settings": { "foreground": "#81A1C1" } }
    ]
}

Two rules make writing one by hand reasonable. A colour key UnoCode does not know is ignored, so a theme written for a newer editor still loads; and a key you leave out is worked out from the ones you set, so a theme with three colours in it still renders a complete, coherent workbench.

Extensions

An extension is a folder. Copy it onto the disk under EXT and UnoCode finds it at startup - on any drive, so an extension on a USB stick needs no installing.

Three of the four kinds of extension need no programming whatever - they are JSON files that describe something:

The manifest is package.json, with VS Code's keys:

{
    "name": "nord",
    "displayName": "Nord Theme",
    "description": "An arctic, north-bluish colour theme.",
    "version": "1.0.0",
    "publisher": "you",

    // no "main", so no code ever runs for this extension
    "contributes": {
        "themes": [
            { "label": "Nord", "uiTheme": "vs-dark", "path": "THEMES/NORD.JSN" }
        ]
    }
}

The fourth kind runs JavaScript. An extension with a main gets a real programming interface - commands, messages, quick picks, the active editor and its text, settings, files, and events when a document is opened, changed or saved:

var vscode = require('vscode');

function activate(context) {
    vscode.commands.registerCommand('hello.sayHello', function () {
        var ed = vscode.window.activeTextEditor;
        vscode.window.showInformationMessage(
            'Hello from an extension - ' + (ed ? ed.document.fileName : 'no editor'));
    });

    // completions, offered only in C files
    vscode.languages.registerCompletionItemProvider('c', {
        provideCompletionItems: function (document, position) {
            return [{ label: 'uno_fs_read', detail: 'UnoDOS',
                      insertText: 'uno_fs_read(vol, name, buf, max)' }];
        }
    });

    vscode.workspace.onDidSaveTextDocument(function (doc) {
        console.log('saved: ' + doc.fileName);
    });
}

exports.activate = activate;

One thing about the interface is deliberately different from Visual Studio Code, and it is stated rather than hidden: require() resolves 'vscode' and nothing else, because there is no package manager to resolve anything else against.

Language servers

UnoCode contains a Language Server Protocol client: a server per language, spoken to in JSON-RPC over pipes, feeding diagnostics, completions, hover, go-to-definition, find-references, rename and format back into the editor. It is configured from settings, one command line per language, and an empty command switches one off.

Two decisions in the client are worth knowing if you are reading the source. It syncs the whole document after a pause in typing rather than sending incremental edits, because incremental sync means client and server each keep a copy and one mis-ranged edit makes them diverge silently. And a server that dies is restarted with a widening delay and has its documents re-opened on the replacement, because a language server exiting is ordinary rather than exceptional.

Settings and keyboard shortcuts

Both are files, both are yours to edit, and both are the formats Visual Studio Code uses - including its habit of allowing comments and trailing commas in them.

// UnoCode settings.  Comments and trailing commas are allowed.
{
    "editor.fontSize": 15,
    "editor.tabSize": 4,
    "editor.insertSpaces": true,
    "editor.minimap.enabled": true,
    "editor.renderWhitespace": "boundary",
    "workbench.colorTheme": "Nord",
    "files.trimTrailingWhitespace": true,
}

A keybinding is { "key", "command", "when" }. when is a real condition - editorTextFocus, editorHasSelection, terminalFocus and the rest, combined with !, && and || - so the same key can do different things in different places. A command written with a leading - removes a shipped binding. Yours win over an extension's, which win over the defaults.

What it does not do

Honestly, so you are not looking for them:

• No word wrap. Long lines scroll sideways.
• No language server runs on this machine, so there is no hover documentation, no go-to-definition and no rename-across-a-project here. UnoCode has a language-server client - see Language servers below - but a server is a separate program, and pc64 has no way to start one. Completions come from the language's keywords, the words already in the file and any snippets, which is what you get.
• Source Control tracks your unsaved edits against the file as it was opened, and marks changed lines in the gutter. There is no repository on this machine and it says so rather than pretending.
• Function keys depend on the keyboard. PS/2 keyboards deliver them; USB keyboards do not, in this build. Every default shortcut is a Ctrl chord for that reason, and nothing needs an F-key.

For extension authors

The complete file formats - the manifest keys, the theme colour keys, the grammar model and its one documented difference from TextMate, the settings table and the whole JavaScript interface - are in pc64/unocode/UNOCODE.md in the source tree, beside the three sample extensions the disk ships: a theme, a language with a grammar and snippets, and one with code in it.