Files
pplus-web/src/quarto/shortcodes.ts
T
alexm 75c1d466da
Build, test, deploy / site (push) Successful in 7m38s
A proved routine is not said to have run out of time
In a container running the tests on two processors, the Quarto
gallery's proved example was rendered with the warning that time ran
out: the generated inputs that cross-check a proof had been cut short by
the 3-second clock, with every claim already proved. core 941af6b counts
that only where a claim is still open. The tests that hold what a proof
finds give it time to spare, and the browser-side request builder takes
prove-seconds as the Lua filter does.
2026-11-13 07:33:35 -05:00

152 lines
13 KiB
TypeScript

// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* The shortcodes of the Quarto extension (quarto/_extensions/pplus/pplus.lua), as data: what each is called, what
* it shows, and the options it reads. The app's "With Quarto" gallery (src/ui/quarto.ts) is written from this,
* scripts/check-pages.mjs reads it to know a shortcode when it sees one, and tests/quarto.test.mjs holds it to the
* names pplus.lua returns. DOM-free.
*/
import type { LangId } from '#core/common/types.js';
import type { StaticView, RenderRequest } from './render.js';
import { listingText } from './program.js';
import { emptyState, type PlayState } from '../core/state.js';
import { boardView } from '../core/hardware.js';
import { HW_NAMES } from './machine.js';
export type ShortcodeKind = 'rendered' | 'machine' | 'live' | 'text';
export interface ShortcodeDef {
name: string;
kind: ShortcodeKind;
/** rendered: the view render.ts draws; live: the embed view (or `any`, chosen by view=). */
view?: StaticView | 'playground' | 'any';
/** machine: the board view it shows (its pplus-hw-<name>), or none for the whole board. */
hw?: string;
title: string;
summary: string;
/** The options it reads besides the shared ones (SHARED_OPTIONS). */
options: string[];
}
/** Read by every shortcode that names program files. */
export const SHARED_OPTIONS = ['lingo', 'matho', 'pseudo', 'speco', 'mojo', 'asm', 'setup', 'lang', 'call', 'input', 'machine', 't', 'title', 'caption', 'collapse', 'area'] as const;
/** Read by every rendered view (the machine's too). */
export const RENDERED_OPTIONS = ['code', 'numbers', 'live', 'height', 'column'] as const;
export const SHORTCODES: ShortcodeDef[] = [
{ name: 'pplus-run', kind: 'rendered', view: 'run', title: 'Run it', summary: 'What the program prints and returns, checked against its EXPECT lines. A Mojo file runs on the real compiler when the machine that renders has one.', options: ['compiler'] },
{ name: 'pplus-steps', kind: 'rendered', view: 'steps', title: 'Step through it', summary: 'The listing beside a stepper: every step, the line it ran, what it wrote, the values after it, and what was printed so far. The run is in the page; a small script moves through it.', options: ['follow', 'max'] },
{ name: 'pplus-table', kind: 'rendered', view: 'table', title: 'Table of values', summary: 'The table you would draw by hand: a column per step that changed something, a row per name.', options: [] },
{ name: 'pplus-flow', kind: 'rendered', view: 'flow', title: 'Flowchart', summary: 'The routine as a flowchart, laid out from its structure; each box shaded by how often its line ran, each arrow labeled with how often it was taken.', options: [] },
{ name: 'pplus-dataflow', kind: 'rendered', view: 'data', title: 'Data flow', summary: 'Which names feed which: the parameters on the left, what leaves on the right, an arrow for each assignment.', options: [] },
{ name: 'pplus-lifetimes', kind: 'rendered', view: 'life', title: 'Lifetimes', summary: 'Each Mojo value from the step it is made to the step it is destroyed or moved out of, with every copy and move on the way.', options: [] },
{ name: 'pplus-proof', kind: 'rendered', view: 'proof', title: 'Proof', summary: 'Every claim the specification makes (ENSURE, INVARIANT, a .speco file woven in): proved, broken by a run, or open.', options: [] },
{ name: 'pplus-tests', kind: 'rendered', view: 'tests', title: 'Generated tests', summary: 'The fuzzer\'s report for each routine: what each input must do, how the inputs were made, every failure shrunk to the smallest input, every case run.', options: [] },
{ name: 'pplus-check', kind: 'rendered', view: 'check', title: 'The checker', summary: 'What Programming+ finds in each file before anything runs, on the file\'s own lines, with a link to the guide.', options: [] },
{ name: 'pplus-translate', kind: 'rendered', view: 'translate', title: 'Every notation', summary: 'One file in, the procedure in every notation out: lingo, matho, pseudo, speco, and Mojo generated from the pseudo (and labeled so). As tabs, columns, or the app\'s panes.', options: ['to', 'layout'] },
{ name: 'pplus-machine', kind: 'rendered', view: 'machine', title: 'The machine', summary: 'An x86-64 run on the model machine: instructions, cycles on an in-order and an out-of-order core, cache misses, branches, and what bounds it.', options: [] },
{ name: 'pplus-view', kind: 'rendered', view: undefined, title: 'Any view by name', summary: 'Any of the rendered views, chosen with view= (run, steps, table, flow, data, life, proof, tests, check, translate, machine).', options: ['view'] },
{ name: 'pplus-hw', kind: 'machine', view: 'hw', title: 'The machine board', summary: 'The Hardware area\'s board over an x86-64 run: the listing beside the cards of a preset (registers and memory, caches, pipeline, the whole chip) or the views you name, every one drawn at every step, with a stepper.', options: ['preset', 'views', 'listing', 'stepper', 'max'] },
...Object.entries(HW_NAMES).map(([name, id]): ShortcodeDef => {
const v = boardView(id)!;
return { name: `pplus-hw-${name}`, kind: 'machine', view: 'hw', hw: name, title: v.label, summary: v.blurb, options: ['listing', 'stepper', 'max'] };
}),
{ name: 'pplus-playground', kind: 'live', view: 'playground', title: 'The whole playground', summary: 'The app in the page: every pane, the stepper, every inspect tab and the dock. The reader\'s edits are kept in their browser; Reset brings the page\'s version back.', options: ['panel', 'build', 'dock', 'docktab', 'editor', 'side', 'dockheight', 'theme', 'ro', 'height', 'problem', 'state'] },
{ name: 'pplus-embed', kind: 'live', view: 'any', title: 'One live view', summary: 'One view of the app with the code it reads: trace, table, flow, data, life, problems, proof, tests, compiler, asm, or one pane.', options: ['view', 'panel', 'build', 'theme', 'ro', 'showcall', 'split', 'height', 'problem', 'state'] },
{ name: 'pplus', kind: 'live', view: 'any', title: 'The original shortcode', summary: 'A live embed, a listing, or both (show=). Pages written for it keep working.', options: ['view', 'show', 'mode', 'text', 'panel', 'build', 'theme', 'ro', 'showcall', 'split', 'height', 'problem', 'state'] },
{ name: 'pplus-listing', kind: 'text', title: 'Listings', summary: 'The files as highlighted code blocks, without their header lines; a .tex file typeset as equations.', options: ['numbers', 'math', 'link', 'text'] },
{ name: 'pplus-tabs', kind: 'text', title: 'Tabs', summary: 'The files as a tabset, one tab per notation.', options: ['numbers', 'math'] },
{ name: 'pplus-link', kind: 'text', title: 'A link', summary: 'A link that opens the program in the app.', options: ['view', 'text'] },
];
export const SHORTCODE_NAMES: readonly string[] = SHORTCODES.map((s) => s.name);
export const OPTION_DOCS: Record<string, string> = {
lingo: 'a lingo file beside the page', matho: 'a LaTeX (.tex) file of equations', pseudo: 'a pseudo file', speco: 'a speco file (the specification)',
mojo: 'a Mojo file', asm: 'an x86-64 listing', setup: 'the x86-64 setup block: registers and memory',
lang: 'the pane that runs (default: the first of lingo, matho, pseudo, mojo, asm given)',
call: 'the call to run (default: the file\'s // CALL: line)', input: 'lines INPUT reads, separated by |', machine: 'the x86-64 machine model preset',
t: 'the step the stepper starts on', title: 'a title over the view', caption: 'a sentence under it', collapse: '1 folds it into a block the reader opens',
area: 'bridge, dev or hw: where "open in the playground" goes',
code: '1 prints the program above the view', numbers: '1 numbers the listing\'s lines', live: 'click adds "make it live", which puts the live view in its place',
height: 'the live frame\'s height in px (auto: fits its content)', compiler: 'auto (the real mojo when on the PATH), on, or off',
follow: 'the variables to show, comma-separated', max: 'the most steps kept (default 400; a longer machine run is sampled)', to: 'the notations to show, comma-separated',
layout: 'tabs (default), columns, or grid',
preset: 'the board\'s arrangement: regs (default), caches, pipeline or chip', views: 'the machine views to show, comma-separated (registers, memory, cache, pipeline, chip...)',
listing: '0 leaves out the x86-64 listing', column: 'Quarto\'s column for the figure: body, page (pplus-hw\'s default), screen...', stepper: '0 draws only step t, without a stepper', view: 'which view', panel: 'the tab the playground opens on', build: 'O0 (as written) or default (as mojo build does)',
dock: 'open or closed', docktab: 'the dock\'s tab', editor: 'the editor column\'s share of the width', side: 'the variables panel\'s share', dockheight: 'the editors\' share of the height',
theme: 'light or dark (default: follow the page)', ro: '1: read-only, nothing saved', showcall: '0 hides the run box', split: 'the code\'s share of the frame',
problem: 'a catalog problem instead of files', state: 'a state from the playground\'s Share dialog', show: 'embed, listing or both', mode: 'link: only a link', text: 'the link\'s text', math: '0 prints a .tex file as code', link: '1 adds a link to the app',
};
/** The shortcode as a page writes it. */
export function shortcodeText(name: string, attrs: Record<string, string>): string {
const parts = Object.entries(attrs).map(([k, v]) => `${k}="${v.replace(/"/g, '&quot;')}"`);
return `{{< ${name}${parts.length ? ' ' + parts.join(' ') : ''} >}}`;
}
/**
* A title from a state (which anyone can write into a link) as a shortcode argument the Share dialog hands to a page
* author: one line, at most 120 characters, a double quote as `&quot;` (pplus.lua reads it back), and none of the
* characters that could end the shortcode or start markup in the page it is pasted into (`<`, `>`, `{`, `}`).
*/
export function shortcodeTitle(title: string): string {
return title.replace(/[<>{}]/g, '').replace(/\s+/g, ' ').trim().slice(0, 120).replace(/"/g, '&quot;');
}
const PANES: LangId[] = ['lingo', 'matho', 'pseudo', 'speco', 'mojo', 'asm'];
const list = (s: string | undefined) => (s ? s.split(/[\s,]+/).filter(Boolean) : undefined);
/**
* What a rendered shortcode asks render.ts for, given its options and the files beside the page (by name): the
* same request pplus.lua builds, for the gallery to draw what a page would get.
*/
export function requestFor(view: StaticView, attrs: Record<string, string>, files: Record<string, string>): RenderRequest {
const req: RenderRequest = { view, files: {} };
for (const p of PANES) if (attrs[p] && files[attrs[p]] !== undefined) req.files[p] = files[attrs[p]];
if (attrs.lang) req.lang = attrs.lang as LangId;
if (attrs.call) req.call = attrs.call;
if (attrs.input) req.input = attrs.input.split('|');
if (attrs.setup && files[attrs.setup] !== undefined) req.setup = files[attrs.setup];
if (attrs.machine) req.machine = attrs.machine;
if (attrs.t && Number.isFinite(Number(attrs.t))) req.t = Number(attrs.t);
if (attrs.title) req.title = attrs.title;
if (attrs.max && Number.isFinite(Number(attrs.max))) req.max = Number(attrs.max);
if (Number(attrs['prove-seconds']) > 0) req.proveSeconds = Number(attrs['prove-seconds']);
if (attrs.views) req.hw = list(attrs.views);
if (attrs.preset) req.preset = attrs.preset;
if (attrs.listing === '0') req.listing = false;
if (attrs.stepper === '0') req.stepper = false;
req.follow = list(attrs.follow);
req.to = list(attrs.to) as LangId[] | undefined;
return req;
}
/** The state a live shortcode puts in its iframe's URL: the same one pplus.lua writes. */
export function liveStateFor(attrs: Record<string, string>, files: Record<string, string>): PlayState {
const s = emptyState();
let first: LangId | null = null;
let call: string | undefined; let input: string[] | undefined;
for (const p of PANES) {
const text = attrs[p] ? files[attrs[p]] : undefined;
if (text === undefined) continue;
s.sources[p] = listingText(text, p);
first ??= p;
for (const line of text.split('\n')) {
const m = /^\s*(?:\/\/|%|#)\s*(CALL|INPUT):\s?(.*)$/.exec(line);
if (m?.[1] === 'CALL') call ??= m[2].trim();
if (m?.[1] === 'INPUT') (input ??= []).push(m[2]);
}
}
s.lang = (attrs.lang as LangId) || first || 'pseudo';
s.view = 'trace';
if (attrs.setup && files[attrs.setup] !== undefined) s.setup = files[attrs.setup];
const c = attrs.call ?? call;
if (c) s.call = c;
if (attrs.input) s.input = attrs.input.split('|').join('\n'); else if (input) s.input = input.join('\n');
if (attrs.title) s.title = attrs.title;
if (attrs.t) s.t = Number(attrs.t);
return s;
}