Files
pplus-web/quarto/_extensions/pplus/pplus.lua
T
alexm 7000662539
Build, test, deploy / site (push) Successful in 7m44s
A proof's time limit is the reader's to set
The Prove view gives each routine 3 seconds on the clock. On a slow or
busy device that runs out before the proof does, and claims stay open
with nothing to say why.

- The view says when the time, not the proof, stopped the checker, that
  what was not finished is open and not disproved, and offers to prove
  again with the next longer time. The setting is at the foot of the
  view: 3, 10 or 30 seconds or 2 minutes for each routine, kept in the
  browser (pplus.proveclock).
- A proof rendered with Quarto takes prove-seconds on the shortcode or
  pplus-prove-seconds for the site, and the render warns when the time
  ran out.
- The home page's own example is proved with no time on the clock, and
  the tests that hold a proof's outcome give it time to spare, so
  neither depends on the machine.
- core moves to 38e6e2c, whose report says which routines the clock
  stopped.
2026-11-13 07:01:35 -05:00

786 lines
41 KiB
Lua

-- pplus.lua: the shortcodes of the Programming+ Quarto extension. See README.md beside _extensions/.
--
-- Two kinds of shortcode, over the same program files beside the page (count.pseudo, count.lingo, mean.tex,
-- spec.speco, demo.mojo, demo.asm):
--
-- Rendered with the page. The program runs while Quarto renders, through the app's own engines and views
-- (render.mjs, with a built Programming+), and the result is part of the page: no iframe, no network, and it
-- prints. A run that does not print its EXPECT lines is reported as the page renders.
-- pplus-run what it prints and returns, checked against its EXPECT lines
-- pplus-steps the listing with a stepper: every step, its line, the values after it
-- pplus-table the table of values
-- pplus-flow the flowchart, shaded by how often each line ran
-- pplus-dataflow the data-flow graph
-- pplus-lifetimes each Mojo value made, copied, moved and destroyed
-- pplus-proof every claim of the specification: proved, broken or open
-- pplus-tests the fuzzer's report, every routine
-- pplus-check what the checker says about each file
-- pplus-translate the procedure in every notation, Mojo generated from the pseudo
-- pplus-machine the x86-64 run on the model machine: cycles, misses, branches
-- pplus-view any of these by name: view="flow"
--
-- The machine, rendered with the page: the Hardware area's board over an x86-64 file (asm=, setup=), the course's
-- own views drawn at every step of the run, with a stepper that moves through them.
-- pplus-hw the board: preset="regs" (default) | "caches" | "pipeline" | "chip", or views="registers,cache"
-- pplus-hw-<view> one view: code, explain, registers, flags, address, memory, stack, dataflow, alu, branches,
-- vectors, lines (cache lines), cache, hierarchy, paging (virtual memory, switched on), pipeline,
-- uops, timeline, bottleneck, counters, chip (the whole core), core (out of order), encoding
--
-- Live. An <iframe> of the app (pplus.scient.ing by default), with the program in its URL: the reader edits,
-- steps and runs it on the page.
-- pplus-playground the whole playground
-- pplus-embed one view of it: view="trace" (and every view= of the original {{< pplus >}})
-- pplus the original shortcode: a live embed, a listing, or both (show=)
--
-- And plain:
-- pplus-listing the files as highlighted listings (matho typeset as equations)
-- pplus-tabs the files as a tabset, one tab per notation
-- pplus-link a link that opens the program in the app
--
-- Every rendered view also takes live="click": a button under it puts the live view in its place.
--
-- Options shared by all
-- lingo, matho, pseudo, speco, mojo, asm files next to the page whose text fills that pane
-- setup a file next to the page holding the x86-64 pane's setup block (registers, 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 own `// CALL:` line, else the engine's choice)
-- input lines INPUT reads, separated by | (default: the file's `// INPUT:` lines)
-- machine the x86-64 machine model preset
-- t the step the stepper starts on (or is parked at, live)
-- title a title over the view (and the iframe's title, for accessibility)
-- caption a sentence under the view, before the Programming+ links
-- collapse 1 folds it into a <details> block titled with `title` (or "Show the program")
-- area bridge (default), dev or hw: the area the "open in Programming+" link (and the live playground) opens in
--
-- Options of the rendered views
-- code 1 prints the program's listing above the view (run, table, flow, dataflow, proof, tests)
-- numbers 1 numbers the lines of a listing
-- follow steps, table: the variables to show, comma-separated (default: those of the routine that does the most work)
-- max steps: the most steps kept (default 400)
-- to translate: the notations to show, comma-separated (lingo,matho,pseudo,speco,mojo)
-- layout translate: tabs (default) | columns | grid (the app's own panes side by side)
-- compiler run, for a Mojo file: auto (default: the real `mojo` when one is on the PATH) | on (it must be) | off
-- preset, views pplus-hw: the board's arrangement, or the views (comma-separated) to show
-- listing pplus-hw: 0 leaves out the x86-64 listing beside the cards
-- column body | page | screen | ...: Quarto's column for the figure (pplus-hw's board is page-wide by default)
-- stepper pplus-hw: 0 draws only step t (no stepper); max: the most steps drawn (a longer run is sampled)
-- prove-seconds proof: the seconds the prover has for each routine (default 3, or pplus-prove-seconds)
-- live click: a button that puts the live view in place of the rendered one
-- height the live frame's height in px when live="click" is pressed (default 520)
--
-- Options of the live views: see `live_embed` below (view, panel, build, dock, docktab, editor, side, dockheight,
-- theme, ro, showcall, split, height, mode, text, show, state, problem).
--
-- Project metadata (_quarto.yml or the page's front matter)
-- pplus-url where the live views point (default https://pplus.scient.ing)
-- pplus-engine a built Programming+ (its folder, or its dist/) for the rendered views; see README.md for where it is
-- looked for. none: render nothing with the page (each rendered view shows its listing and the live view)
-- pplus-node the node to run it with (default: node on the PATH)
-- pplus-strict true: a view that cannot be rendered, or a run that does not print its EXPECT lines (a program with EXPECT lines that does not run at all among them), stops the render
-- pplus-prove-seconds the seconds the prover has for each routine in a rendered proof (default 3, the app's own); a
-- slow build machine can run out of 3 and show a claim open that is provable, and the render warns
-- pplus-cache false: render every view again each time (by default results are kept in .quarto/pplus/)
local str = pandoc.utils.stringify
local function esc(s)
s = tostring(s or "")
s = s:gsub("&", "&amp;"):gsub("<", "&lt;"):gsub(">", "&gt;"):gsub('"', "&quot;")
return s
end
local function warn(msg) io.stderr:write("pplus: " .. msg .. "\n") end
local function raw(html) return pandoc.RawBlock("html", html) end
local function is_html() return quarto.doc.is_format("html") end
-- A shortcode argument cannot hold a literal double quote inside double quotes, so &quot; stands for one.
local function kwarg(kwargs, name)
local v = kwargs[name]
if v == nil then return nil end
local s = str(v):gsub("&quot;", '"')
return s ~= "" and s or nil
end
local function meta_str(meta, name)
local v = meta and meta[name]
if v == nil then return nil end
local s = str(v)
return s ~= "" and s or nil
end
local function meta_bool(meta, name, default)
local v = meta and meta[name]
if v == nil then return default end
if type(v) == "boolean" then return v end
local s = str(v)
if s == "true" or s == "1" or s == "yes" then return true end
if s == "false" or s == "0" or s == "no" then return false end
return default
end
-- Absolute path of the file being rendered, with forward slashes.
local function input_path()
local f = quarto and quarto.doc and quarto.doc.input_file or ""
return (tostring(f):gsub("\\", "/"))
end
local function page_dir() return input_path():match("^(.*)/[^/]*$") or "." end
-- This file's folder: the extension, where render.mjs and the stylesheets are.
local EXT_DIR = (function()
local src = debug.getinfo(1, "S").source or ""
src = src:gsub("^@", ""):gsub("\\", "/")
return src:match("^(.*)/[^/]*$") or "."
end)()
local function exists(path)
local f = io.open(path, "r")
if f then f:close() return true end
return false
end
-- The extension's stylesheets and script, attached once per page that uses a shortcode.
local deps_added = false
local function ensure_deps()
if deps_added or not is_html() then return end
deps_added = true
quarto.doc.add_html_dependency({ name = "pplus", version = "2.1.0", stylesheets = { "pplus-views.css", "pplus.css" }, scripts = { "pplus.js" } })
end
-- The machine views' stylesheets: the course's own (course/, written for Quarto pages) and the board's adjustments
-- to them; attached only to a page that shows the machine.
local hw_deps_added = false
local function ensure_hw_deps()
if hw_deps_added or not is_html() then return end
hw_deps_added = true
quarto.doc.add_html_dependency({ name = "pplus-hw", version = "2.1.0", stylesheets = { "course/tokens.css", "course/kit.css", "course/asm86.css", "pplus-hw.css" } })
end
local PPLUS_DEFAULT_URL = "https://pplus.scient.ing"
local function pplus_url(meta)
return ((meta_str(meta, "pplus-url") or PPLUS_DEFAULT_URL):gsub("/+$", ""))
end
local function read_beside_page(name)
local f = io.open(page_dir() .. "/" .. name, "r")
if not f then return nil end
local s = f:read("a"); f:close()
return (s:gsub("\n+$", ""))
end
local function base64url(s)
local b = quarto.base64.encode(s)
return (b:gsub("%+", "-"):gsub("/", "_"):gsub("=+$", ""))
end
local function json_encode(v) return quarto.json.encode(v) end
local function json_decode(s)
if quarto.json and quarto.json.decode then return quarto.json.decode(s) end
return pandoc.json.decode(s, false)
end
-- The call and input lines a program file carries for scripts/check-pages.mjs (// CALL: ..., // INPUT: ...),
-- so the embed runs exactly what the checker verified.
local function header_of(text)
local h = { input = {} }
for line in (text .. "\n"):gmatch("(.-)\n") do
local call = line:match("^%s*//%s*CALL:%s*(.-)%s*$") or line:match("^%s*%%%s*CALL:%s*(.-)%s*$") or line:match("^%s*#%s*CALL:%s*(.-)%s*$")
if call then h.call = call end
local inp = line:match("^%s*//%s*INPUT:%s?(.*)$") or line:match("^%s*%%%s*INPUT:%s?(.*)$") or line:match("^%s*#%s*INPUT:%s?(.*)$")
if inp then h.input[#h.input + 1] = inp end
end
return h
end
-- The file as a page shows it: the checker's header lines (// CALL:, // EXPECT:, ...) removed. A Mojo
-- file's header is its leading block of `# key: value` comments (mojo/local/'s origin, probe, mode, args,
-- expect...; check-pages' EXPECT), so only that block goes: a `# note:` further down is the program's.
-- (src/quarto/program.ts listingText does the same for the rendered views; tests/quarto.test.mjs holds them together.)
local function listing_text(text, pane)
local out = {}
local head = pane == "mojo"
for line in (text .. "\n"):gmatch("(.-)\n") do
if head then
if line:match("^#%s*[%w%-]+:") then goto continue end
if line:match("^%s*$") and #out == 0 then goto continue end
head = false
end
if pane ~= "mojo" and (line:match("^%s*//%s*[A-Z]+:") or line:match("^%s*%%%s*[A-Z]+:")) then goto continue end
out[#out + 1] = line
::continue::
end
local s = table.concat(out, "\n")
return (s:gsub("^\n+", ""):gsub("\n+$", ""))
end
-- A LaTeX file as display mathematics: one block per equation, where an equation continues while a
-- brace or \begin{cases} is open or the next line starts with an operator.
local function math_blocks(text)
local eqs, cur, depth, cases = {}, nil, 0, 0
local function flush() if cur and cur:match("%S") then eqs[#eqs + 1] = cur end cur = nil end
for raw_line in (text .. "\n"):gmatch("(.-)\n") do
local line = raw_line:gsub("%%.*$", "")
if not line:match("%S") then
if depth <= 0 and cases <= 0 then flush() end
else
local continues = depth > 0 or cases > 0 or line:match("^%s*[=+%-&]") or line:match("^%s*\\cdot") or (cur and cur:match("[=+%-{]%s*$"))
if not continues then flush() end
cur = cur and (cur .. "\n" .. line) or line
for ch in line:gmatch("[{}]") do depth = depth + (ch == "{" and 1 or -1) end
for _ in line:gmatch("\\begin{cases}") do cases = cases + 1 end
for _ in line:gmatch("\\end{cases}") do cases = cases - 1 end
end
end
flush()
local blocks = pandoc.Blocks({})
for _, eq in ipairs(eqs) do
blocks:insert(pandoc.Para({ pandoc.Math("DisplayMath", (eq:gsub("%s*\\\\%s*$", ""))) }))
end
return blocks
end
local function split_on(s, sep)
local out = {}
for piece in (s .. sep):gmatch("(.-)" .. sep:gsub("%p", "%%%0")) do out[#out + 1] = piece end
return out
end
local function split_bar(s) return split_on(s, "|") end
local function split_list(s)
local out = {}
for piece in s:gmatch("[^,%s]+") do out[#out + 1] = piece end
return out
end
local PANES = { "lingo", "matho", "pseudo", "speco", "mojo", "asm" }
local PANE_LABEL = { lingo = "lingo", matho = "matho", pseudo = "pseudo", speco = "speco", mojo = "Mojo", asm = "x86-64" }
local function set_of(list) local t = {} for _, k in ipairs(list) do t[k] = true end return t end
-- what view= can show (src/core/state.ts EMBED_VIEWS) and what the state's own view (the open tab) can be
local VIEWS = set_of({ "playground", "trace", "table", "flow", "data", "life", "problems", "proof", "tests", "compiler", "asm", "lingo", "matho", "pseudo", "speco", "mojo" })
local TABS = set_of({ "trace", "table", "flow", "data", "life", "problems", "proof", "tests", "compiler", "asm" })
local DOCK_TABS = set_of({ "setup", "output", "problems", "compiler", "asm" })
-- the options that arrange the example; the app reads them from the embed's query (applyEmbedParams)
local ARRANGE = { "area", "lang", "panel", "build", "machine", "dock", "docktab", "editor", "side", "dockheight", "theme" }
-- the rendered views (src/quarto/render.ts STATIC_VIEWS), and the live view each one opens as
local STATIC = { run = "trace", steps = "trace", table = "table", flow = "flow", data = "data", life = "life", proof = "proof", tests = "tests", check = "problems", translate = "playground", machine = "asm", hw = "playground" }
-- the machine's views, as pplus-hw-<name> names them (src/quarto/machine.ts HW_NAMES)
local HW_VIEWS = { "code", "explain", "registers", "flags", "address", "memory", "stack", "dataflow", "alu", "branches", "vectors",
"lines", "cache", "hierarchy", "paging", "pipeline", "uops", "timeline", "bottleneck", "counters", "chip", "core", "encoding" }
local function urlencode(v)
return (tostring(v):gsub("[^%w%-%._~,]", function(c) return string.format("%%%02X", string.byte(c)) end))
end
local function fraction(v)
local n = tonumber(v)
return (n and n > 0 and n < 1) and n or nil
end
-- The program files the shortcode names, read from beside the page: { pane = text } in pane order, the panes given,
-- and the name of a file that could not be read.
local function read_files(kwargs)
local files, given = {}, {}
for _, pane in ipairs(PANES) do
local file = kwarg(kwargs, pane)
if file then
local text = read_beside_page(file)
if not text then return nil, nil, file end
files[pane] = text
given[#given + 1] = pane
end
end
return files, given, nil
end
local function missing(file)
warn("cannot read " .. file .. " next to " .. input_path())
return pandoc.Blocks({ pandoc.Para({ pandoc.Str("[pplus: missing file " .. file .. "]") }) })
end
local function wrap_collapse(kwargs, blocks)
if kwarg(kwargs, "collapse") ~= "1" or not is_html() then return blocks end
local out = pandoc.Blocks({ raw('<details class="pplus-details"><summary>' .. esc(kwarg(kwargs, "title") or "Show the program") .. '</summary>') })
out:extend(blocks)
out:insert(raw('</details>'))
return out
end
-- One file as a listing: a highlighted code block, or (matho) its equations typeset.
local function listing_blocks(pane, text, kwargs)
local shown = listing_text(text, pane)
if pane == "matho" and kwarg(kwargs, "math") ~= "0" then return math_blocks(shown) end
local attr = kwarg(kwargs, "numbers") == "1" and { ["code-line-numbers"] = "true" } or {}
-- matho is written in LaTeX: give its listing the class pandoc highlights as LaTeX
return pandoc.Blocks({ pandoc.CodeBlock(shown, pandoc.Attr("", { pane == "matho" and "latex" or pane }, attr)) })
end
------------------------------------------------------------------------------------------------------------------
-- Live: the app in an <iframe>
------------------------------------------------------------------------------------------------------------------
-- {{< pplus pseudo="count-base.pseudo" >}}
-- {{< pplus lingo="count-base.lingo" pseudo="count-base.pseudo" lang="lingo" view="trace" t=7 >}}
-- {{< pplus problem="count-base" view="trace" >}}
-- {{< pplus pseudo="x.pseudo" mode="link" text="Open it in the playground" >}}
-- {{< pplus mojo="demo.mojo" asm="demo.asm" setup="demo.setup" view="playground" area="hw" >}}
-- {{< pplus problem="demo" view="playground" panel="compiler" build="default" >}}
-- {{< pplus state="<blob from Share>" view="playground" >}}
--
-- Options (beside the shared ones at the top of this file)
-- problem a catalog problem id instead of files (its embed URL is #/embed/<view>/p/<id>)
-- state a state from the playground's Share dialog (the part of the link after #/<area>/s/): the
-- example exactly as it was arranged there, panes, layout, build and step included.
-- Share also writes this shortcode for you. (Pane files cannot be combined with it.)
-- view playground | trace | table | flow | data | life | problems | proof | tests | compiler | asm,
-- or a pane name to show just that editor (default trace). playground is the whole
-- playground in the frame: every pane, the stepper, the variables, every inspect tab and
-- the dock, arranged by the options below.
-- panel the tab the playground opens on: trace table flow data life proof tests (beside the
-- editor) or output problems compiler asm setup (the dock)
-- build O0 (as written, every function kept; the default) | default (as `mojo build` does)
-- dock open | closed: the dock under the editors; docktab picks its tab
-- editor 0.25-0.8: the editor column's share of the width
-- side the variables panel's share of the right column
-- dockheight 0.3-0.9: the editors' share of the height above the dock
-- theme light | dark (default: follow the page's own switch)
-- ro 1 makes the embedded editors read-only (and the frame keeps no save)
-- showcall 0 hides the run box above a flow, data or table view
-- height iframe height in px (default 520, or 720 for view="playground"), or auto: the frame
-- grows to fit its content (not for the playground, which fills its frame)
-- split the share of a fixed-height frame the code takes above the panel (default 0.7)
-- mode embed (default) | link: only a link to the full playground
-- text the link text (mode=link)
-- show embed (default) | listing | both: the file(s) as listings, the embed, or the listings then the embed
--
-- The state travels in the URL as `~` + base64url(JSON), which the app reads without decompression,
-- so no script of the app runs on this site: the page holds a plain <iframe>. In non-HTML output the
-- embed becomes a link.
-- Where the example opens: { embed = the iframe's src, open = the app link }, or nil and blocks to show instead.
local function live_target(kwargs, meta, view, listings, default_area)
local base = pplus_url(meta)
local playground = view == "playground"
local area = kwarg(kwargs, "area") or default_area or "bridge"
if area ~= "bridge" and area ~= "dev" and area ~= "hw" then
warn("unknown area=\"" .. area .. "\" (use bridge, dev or hw); using bridge")
area = "bridge"
end
local height = kwarg(kwargs, "height")
local query = {}
local function q_add(k, v) query[#query + 1] = k .. "=" .. urlencode(v) end
for _, k in ipairs({ "t", "ro", "showcall", "split" }) do
if kwarg(kwargs, k) then q_add(k, kwarg(kwargs, k)) end
end
for _, k in ipairs(ARRANGE) do
local v = kwarg(kwargs, k)
if v then q_add(k, v) end
end
-- a view of the machine opens in the Hardware area unless the page says otherwise
if default_area and not kwarg(kwargs, "area") then q_add("area", default_area) end
if height == "auto" and not playground then query[#query + 1] = "autosize=1" end
local q = #query > 0 and ("?" .. table.concat(query, "&")) or ""
local problem = kwarg(kwargs, "problem")
local given_state = kwarg(kwargs, "state")
if given_state then
-- a state made in the playground: Share -> Quarto writes this shortcode; the blob is opaque here
local blob = given_state:gsub("^.*#/%a+/s/", ""):gsub("^.*#/embed/[^/]+/", ""):gsub("%?.*$", "")
for _, pane in ipairs(PANES) do
if kwarg(kwargs, pane) then warn("state= already holds every pane; " .. pane .. "= is ignored (drop state= to build the example from files)") end
end
return { embed = base .. "/#/embed/" .. view .. "/" .. blob .. q, open = base .. "/#/" .. area .. "/s/" .. blob }
elseif problem then
local embed = base .. "/#/embed/" .. view .. "/p/" .. problem .. q
-- the arranged example, whole, in a tab of its own
return { embed = embed, open = playground and embed or (base .. "/#/" .. area .. "/p/" .. problem) }
end
local files, given, bad = read_files(kwargs)
if bad then return nil, missing(bad) end
if #given == 0 then
warn("give at least one of lingo=, matho=, pseudo=, speco=, mojo=, asm=, or problem= or state=")
return nil, pandoc.Blocks({})
end
local sources, file_call, file_input = {}, nil, nil
for _, pane in ipairs(given) do
local text = files[pane]
sources[pane] = listing_text(text, pane)
local h = header_of(text)
file_call = file_call or h.call
if #h.input > 0 and not file_input then file_input = table.concat(h.input, "\n") end
if listings then listings:extend(listing_blocks(pane, text, kwargs)) end
end
local panel = kwarg(kwargs, "panel")
local state = {
v = 3,
sources = sources,
lang = kwarg(kwargs, "lang") or given[1],
view = (TABS[panel or ""] and panel) or (TABS[view] and view) or "trace",
}
local setup_file = kwarg(kwargs, "setup")
if setup_file then
local text = read_beside_page(setup_file)
if text then state.setup = text else warn("cannot read " .. setup_file .. " next to " .. input_path()) end
end
if kwarg(kwargs, "build") == "O0" or kwarg(kwargs, "build") == "default" then state.build = kwarg(kwargs, "build") end
if kwarg(kwargs, "machine") then state.machine = kwarg(kwargs, "machine") end
local layout = {}
local dock = kwarg(kwargs, "dock")
if dock == "open" or dock == "closed" then layout.dockCollapsed = dock == "closed" end
local tab = kwarg(kwargs, "docktab") or ((panel == "output" or panel == "setup") and panel) or nil
if tab and DOCK_TABS[tab] then layout.dockTab = tab end
layout.split = fraction(kwarg(kwargs, "editor"))
layout.right = fraction(kwarg(kwargs, "side"))
layout.dock = fraction(kwarg(kwargs, "dockheight"))
if next(layout) then state.layout = { [area] = layout } end
local call = kwarg(kwargs, "call") or file_call
if call then state.call = call end
local input = kwarg(kwargs, "input") and table.concat(split_bar(kwarg(kwargs, "input")), "\n") or file_input
if input then state.input = input end
if kwarg(kwargs, "t") then state.t = tonumber(kwarg(kwargs, "t")) end
if kwarg(kwargs, "title") then state.title = kwarg(kwargs, "title") end
local blob = "~" .. base64url(json_encode(state))
return { embed = base .. "/#/embed/" .. view .. "/" .. blob .. q, open = base .. "/#/" .. area .. "/s/" .. blob }
end
local function figcaption(caption, links)
return '<figcaption>' .. (caption and ('<span class="pplus-caption">' .. esc(caption) .. '</span> · ') or '')
.. '<span class="pplus-brand">Programming+</span>' .. links .. '</figcaption>'
end
local function live_embed(kwargs, meta, view_override)
ensure_deps()
local view = view_override or kwarg(kwargs, "view") or "trace"
if not VIEWS[view] then
if STATIC[view] then
warn("view=\"" .. view .. "\" is a rendered view: use {{< pplus-view view=\"" .. view .. "\" >}} (or {{< pplus-" .. view .. " >}}); showing the live " .. STATIC[view])
view = STATIC[view]
else
warn("unknown view=\"" .. view .. "\" (use playground, trace, table, flow, data, life, problems, proof, tests, compiler, asm, or a pane name); showing trace")
view = "trace"
end
end
local playground = view == "playground"
local mode = kwarg(kwargs, "mode") or "embed"
local show = kwarg(kwargs, "show") or "embed"
local height = kwarg(kwargs, "height") or (playground and "720" or "520")
if playground and height == "auto" then
warn("height=\"auto\" does not apply to view=\"playground\", which fills its frame; using 720")
height = "720"
end
local listings = pandoc.Blocks({})
local target, instead = live_target(kwargs, meta, view, show ~= "embed" and listings or nil)
if not target then return instead end
local title = kwarg(kwargs, "title")
local caption = kwarg(kwargs, "caption")
if show == "listing" or mode == "link" or not is_html() then
local text = kwarg(kwargs, "text") or "Open this in Programming+"
listings:insert(pandoc.Para({ pandoc.Link({ pandoc.Str(text) }, target.open, "", pandoc.Attr("", { "pplus-link" })) }))
return wrap_collapse(kwargs, listings)
end
local auto = height == "auto"
local label = title or ("Programming+: " .. view)
local html = '<figure class="pplus-embed' .. (auto and ' pplus-auto' or '') .. (playground and ' pplus-playground' or '') .. '">'
.. '<iframe class="pplus-frame" src="' .. esc(target.embed) .. '" height="' .. esc(auto and "360" or height)
.. '" loading="lazy" title="' .. esc(label) .. '"' .. (auto and ' data-pplus-auto="1"' or '')
.. ' allow="clipboard-write"></iframe>'
.. figcaption(caption, ' · <a href="' .. esc(target.open) .. '" target="_blank" rel="noopener">open in the playground</a>'
.. ' · <a href="' .. esc(target.embed) .. '" target="_blank" rel="noopener">full screen</a>')
.. '</figure>'
listings:insert(raw(html))
return wrap_collapse(kwargs, listings)
end
------------------------------------------------------------------------------------------------------------------
-- Rendered with the page: render.mjs runs the app's views on the files
------------------------------------------------------------------------------------------------------------------
-- A built Programming+ for render.mjs, looked for in this order: pplus-engine (project or page metadata), the
-- PPLUS_ENGINE environment variable, an engine/ folder in this extension (`pixi run quarto-engine <dir>` puts one
-- there), and the repository this extension sits in (quarto/_extensions/pplus inside a Programming+ checkout).
local function engine_dir(meta)
local function built(dir)
if not dir then return nil end
dir = dir:gsub("\\", "/"):gsub("/+$", "")
if exists(dir .. "/quarto/render.js") then return dir end
if exists(dir .. "/dist/quarto/render.js") then return dir .. "/dist" end
return nil
end
local configured = meta_str(meta, "pplus-engine")
-- none: render nothing with the page; every rendered view becomes its listing and the live view
if configured == "none" or configured == "false" then return nil end
if configured and not configured:match("^/") and not configured:match("^%a:") then
-- relative to the project (or, without one, to the page)
local root = (quarto.project and quarto.project.directory) or page_dir()
configured = root .. "/" .. configured
end
return built(configured) or built(os.getenv("PPLUS_ENGINE")) or built(EXT_DIR .. "/engine") or built(EXT_DIR .. "/../../..")
end
local engine_warned = false
local function cache_dir(meta)
if not meta_bool(meta, "pplus-cache", true) then return nil end
local root = (quarto.project and quarto.project.directory) or page_dir()
return root .. "/.quarto/pplus"
end
-- Run one view. Returns the result (a table), or nil and why not.
local function render_view(req, meta)
local engine = engine_dir(meta)
if not engine then
local off = meta_str(meta, "pplus-engine")
if off == "none" or off == "false" then return nil, "pplus-engine is none" end
return nil, "no built Programming+ found (set pplus-engine in _quarto.yml, or see README.md)"
end
req.cache = cache_dir(meta)
local node = meta_str(meta, "pplus-node") or os.getenv("PPLUS_NODE") or "node"
local ok, out = pcall(pandoc.pipe, node, { EXT_DIR .. "/render.mjs", engine }, json_encode(req))
if not ok then return nil, "could not run " .. node .. " (" .. tostring(out):gsub("%s+$", "") .. ")" end
local ok2, res = pcall(json_decode, out)
if not ok2 or type(res) ~= "table" then return nil, "render.mjs answered something that is not JSON: " .. tostring(out):sub(1, 300) end
if res.error then return nil, res.error end
return res
end
local function strict_fail(meta, what)
if meta_bool(meta, "pplus-strict", false) then error("pplus: " .. what .. " (pplus-strict is on)") end
end
-- The tabs of a translate view, or of pplus-tabs: one per notation, a code block (matho typeset) in each.
local function tabset(panes, kwargs)
if not is_html() then
local out = pandoc.Blocks({})
for _, p in ipairs(panes) do
out:insert(pandoc.Para({ pandoc.Strong({ pandoc.Str(p.label) }), pandoc.Str(p.generated and " (generated)" or "") }))
if p.text ~= "" then out:extend(listing_blocks(p.lang, p.text, kwargs)) else out:insert(pandoc.Para({ pandoc.Emph({ pandoc.Str(p.note or "") }) })) end
end
return out
end
local tabs = {}
for _, p in ipairs(panes) do
local content = pandoc.Blocks({})
if p.text ~= "" then
if p.lang == "matho" and kwarg(kwargs, "math") ~= "0" then
content:extend(math_blocks(p.text))
content:extend(listing_blocks("matho", p.text, { math = pandoc.Str("0") }))
else
local attr = kwarg(kwargs, "numbers") == "1" and { ["code-line-numbers"] = "true" } or {}
content:insert(pandoc.CodeBlock(p.text, pandoc.Attr("", { p.lang == "matho" and "latex" or p.lang }, attr)))
end
if p.generated and p.lang == "mojo" then
content:insert(raw('<p class="pplus-tab-note"><span class="pplus-tag-generated">generated</span> ' .. esc(p.note or "Generated from the pseudo.") .. '</p>'))
elseif p.generated then
content:insert(raw('<p class="pplus-tab-note"><span class="pplus-tag-generated">generated</span> Written by Programming+ from the ' .. esc(PANE_LABEL[p.from or "pseudo"] or "pseudo") .. '.</p>'))
end
else
content:insert(raw('<p class="pplus-tab-note">' .. esc(p.note or "") .. '</p>'))
end
tabs[#tabs + 1] = { title = p.label, content = content }
end
local attr = pandoc.Attr("", { "panel-tabset", "pplus-tabs" })
-- Quarto turns a .panel-tabset div into tabs before shortcodes run, so a shortcode makes the tabset node itself
if quarto.Tabset and quarto.Tab then
local list = pandoc.List({})
for _, t in ipairs(tabs) do list:insert(quarto.Tab({ title = pandoc.Inlines({ pandoc.Str(t.title) }), content = t.content })) end
return pandoc.Blocks({ quarto.Tabset({ level = 3, tabs = list, attr = attr }) })
end
local inner = pandoc.Blocks({})
for _, t in ipairs(tabs) do
inner:insert(pandoc.Header(3, { pandoc.Str(t.title) }))
inner:extend(t.content)
end
return pandoc.Blocks({ pandoc.Div(inner, attr) })
end
local function static_view(view, kwargs, meta, extra)
ensure_deps()
if view == "hw" then ensure_hw_deps() end
local files, given, bad = read_files(kwargs)
if bad then return missing(bad) end
if #given == 0 then
warn("pplus-" .. view .. ": give a program file: lingo=, matho=, pseudo=, speco=, mojo= or asm=")
return pandoc.Blocks({})
end
local req = { view = view, files = files }
req.lang = kwarg(kwargs, "lang")
if kwarg(kwargs, "call") then req.call = kwarg(kwargs, "call") end
if kwarg(kwargs, "input") then req.input = split_bar(kwarg(kwargs, "input")) end
local setup_file = kwarg(kwargs, "setup")
if setup_file then
local text = read_beside_page(setup_file)
if text then req.setup = text else warn("cannot read " .. setup_file .. " next to " .. input_path()) end
end
req.machine = kwarg(kwargs, "machine")
req.t = tonumber(kwarg(kwargs, "t") or "")
req.title = kwarg(kwargs, "title")
req.max = tonumber(kwarg(kwargs, "max") or "")
if view == "proof" then req.proveSeconds = tonumber(kwarg(kwargs, "prove-seconds") or meta_str(meta, "pplus-prove-seconds") or "") end
if kwarg(kwargs, "follow") then req.follow = split_list(kwarg(kwargs, "follow")) end
if kwarg(kwargs, "to") then req.to = split_list(kwarg(kwargs, "to")) end
req.compiler = kwarg(kwargs, "compiler") or "auto"
if view == "hw" then
req.hw = (extra and extra.hw) or (kwarg(kwargs, "views") and split_list(kwarg(kwargs, "views"))) or (kwarg(kwargs, "view") and kwarg(kwargs, "view") ~= "hw" and { kwarg(kwargs, "view") }) or nil
req.preset = kwarg(kwargs, "preset")
req.listing = kwarg(kwargs, "listing") ~= "0"
req.stepper = kwarg(kwargs, "stepper") ~= "0"
end
local name = (extra and extra.name) or ("pplus-" .. view)
local where = name .. " in " .. (input_path():match("[^/]*$") or "")
local res, why = render_view(req, meta)
local blocks = pandoc.Blocks({})
local title = kwarg(kwargs, "title")
local caption = kwarg(kwargs, "caption")
local target = live_target(kwargs, meta, STATIC[view], nil, view == "hw" and "hw" or nil)
if not res then
-- no engine (or it failed): the page still renders, with the program and the live view in its place
if not engine_warned then warn(where .. ": " .. why .. "; showing the live view instead") engine_warned = true end
strict_fail(meta, where .. ": " .. why)
for _, pane in ipairs(given) do blocks:extend(listing_blocks(pane, files[pane], kwargs)) end
if target then blocks:extend(live_embed(kwargs, meta, STATIC[view])) end
return wrap_collapse(kwargs, blocks)
end
for _, w in ipairs(res.warnings or {}) do warn(where .. ": " .. w) end
if res.expect and not res.expect.ok then strict_fail(meta, where .. ": the run does not print its EXPECT lines") end
local code = pandoc.Blocks({})
if kwarg(kwargs, "code") == "1" then
for _, pane in ipairs(given) do
local shows = pane == res.lang or #given == 1
or (res.lang == "pseudo" and (pane == "lingo" or pane == "matho" or (pane == "speco" and view == "proof")))
if shows then code:extend(listing_blocks(pane, files[pane], kwargs)) end
end
end
-- translate, as tabs: Quarto's own tabset over pandoc code blocks (highlighted by the syntax definitions)
local layout = kwarg(kwargs, "layout") or "tabs"
if view == "translate" and (layout == "tabs" or layout == "columns" or not is_html()) and res.panes then
if layout == "columns" and is_html() then
local cols = pandoc.Blocks({})
for _, p in ipairs(res.panes) do
local col = pandoc.Blocks({ pandoc.Para({ pandoc.Strong({ pandoc.Str(p.label) }), pandoc.Str(p.generated and " (generated)" or "") }) })
if p.text ~= "" then col:extend(listing_blocks(p.lang, p.text, kwargs)) else col:insert(pandoc.Para({ pandoc.Emph({ pandoc.Str(p.note or "") }) })) end
cols:insert(pandoc.Div(col, pandoc.Attr("", { "pplus-col" })))
end
blocks:insert(pandoc.Div(cols, pandoc.Attr("", { "pplus-columns" })))
else
blocks:extend(tabset(res.panes, kwargs))
end
if is_html() and (caption or target) then
blocks:insert(raw('<div class="pplus-under">' .. figcaption(caption, target and (' · <a href="' .. esc(target.open) .. '" target="_blank" rel="noopener">open in the playground</a>') or '') .. '</div>'))
end
return wrap_collapse(kwargs, blocks)
end
if not is_html() then
if title then blocks:insert(pandoc.Para({ pandoc.Strong({ pandoc.Str(title) }) })) end
blocks:extend(code)
blocks:extend(pandoc.read(res.markdown or "", "markdown").blocks)
if caption then blocks:insert(pandoc.Para({ pandoc.Emph({ pandoc.Str(caption) }) })) end
if target then blocks:insert(pandoc.Para({ pandoc.Link({ pandoc.Str(kwarg(kwargs, "text") or "Open this in Programming+") }, target.open, "", pandoc.Attr("", { "pplus-link" })) })) end
return wrap_collapse(kwargs, blocks)
end
local live = kwarg(kwargs, "live")
local links = ''
if target then
if live == "click" then
links = links .. ' · <button type="button" class="pplus-golive" data-src="' .. esc(target.embed) .. '" data-height="' .. esc(kwarg(kwargs, "height") or (STATIC[view] == "playground" and "720" or "520")) .. '">make it live</button>'
end
links = links .. ' · <a href="' .. esc(target.open) .. '" target="_blank" rel="noopener">open in the playground</a>'
end
-- a div, not a raw <figure>, so a listing inside it is still pandoc's (highlighted, numbered)
local fig = pandoc.Blocks({})
if title then fig:insert(raw('<div class="pplus-figtitle">' .. esc(title) .. '</div>')) end
if #code > 0 then fig:insert(pandoc.Div(code, pandoc.Attr("", { "pplus-figcode" }))) end
fig:insert(raw(res.html))
fig:insert(raw(figcaption(caption, links)))
local classes = { "pplus-figure", "pplus-figure-" .. view }
-- column= widens the figure into Quarto's page grid (body, page, screen, margin...); the whole machine board is page-wide
local column = kwarg(kwargs, "column") or ((view == "hw" and not (extra and extra.name)) and "page" or nil)
if column and column ~= "body" then classes[#classes + 1] = "column-" .. column end
blocks:insert(pandoc.Div(fig, pandoc.Attr("", classes)))
return wrap_collapse(kwargs, blocks)
end
------------------------------------------------------------------------------------------------------------------
-- Plain: listings, tabs, a link
------------------------------------------------------------------------------------------------------------------
local function listing(kwargs, meta)
ensure_deps()
local files, given, bad = read_files(kwargs)
if bad then return missing(bad) end
local blocks = pandoc.Blocks({})
for _, pane in ipairs(given) do blocks:extend(listing_blocks(pane, files[pane], kwargs)) end
if kwarg(kwargs, "link") == "1" then
local target = live_target(kwargs, meta, kwarg(kwargs, "view") or "trace", nil)
if target then blocks:insert(pandoc.Para({ pandoc.Link({ pandoc.Str(kwarg(kwargs, "text") or "Open this in Programming+") }, target.open, "", pandoc.Attr("", { "pplus-link" })) })) end
end
return wrap_collapse(kwargs, blocks)
end
local function tabs(kwargs, meta)
ensure_deps()
local files, given, bad = read_files(kwargs)
if bad then return missing(bad) end
local panes = {}
for _, pane in ipairs(given) do panes[#panes + 1] = { lang = pane, label = PANE_LABEL[pane], text = listing_text(files[pane], pane), generated = false } end
return wrap_collapse(kwargs, tabset(panes, kwargs))
end
local function link(kwargs, meta)
ensure_deps()
local view = kwarg(kwargs, "view") or "playground"
local target, instead = live_target(kwargs, meta, VIEWS[view] and view or "playground", nil)
if not target then return instead end
-- the whole playground opens in its area; a single view opens as that embed, full screen
local href = view == "playground" and target.open or target.embed
return pandoc.Para({ pandoc.Link({ pandoc.Str(kwarg(kwargs, "text") or "Open this in Programming+") }, href, "", pandoc.Attr("", { "pplus-link" })) })
end
------------------------------------------------------------------------------------------------------------------
local function static(view) return function(args, kwargs, meta) return static_view(view, kwargs, meta) end end
local shortcodes = {
["pplus"] = function(args, kwargs, meta) return live_embed(kwargs, meta) end,
["pplus-embed"] = function(args, kwargs, meta) return live_embed(kwargs, meta) end,
["pplus-playground"] = function(args, kwargs, meta) return live_embed(kwargs, meta, "playground") end,
["pplus-view"] = function(args, kwargs, meta)
local view = kwarg(kwargs, "view") or (args[1] and str(args[1])) or "steps"
if view == "dataflow" then view = "data" elseif view == "lifetimes" then view = "life" end
if not STATIC[view] then
warn("pplus-view: unknown view=\"" .. view .. "\" (use run, steps, table, flow, data, life, proof, tests, check, translate, machine)")
return pandoc.Blocks({})
end
return static_view(view, kwargs, meta)
end,
["pplus-run"] = static("run"),
["pplus-steps"] = static("steps"),
["pplus-table"] = static("table"),
["pplus-flow"] = static("flow"),
["pplus-dataflow"] = static("data"),
["pplus-lifetimes"] = static("life"),
["pplus-proof"] = static("proof"),
["pplus-tests"] = static("tests"),
["pplus-check"] = static("check"),
["pplus-translate"] = static("translate"),
["pplus-machine"] = static("machine"),
-- the machine: the Hardware board over an x86-64 run, every card steppable
["pplus-hw"] = function(args, kwargs, meta) return static_view("hw", kwargs, meta) end,
["pplus-listing"] = function(args, kwargs, meta) return listing(kwargs, meta) end,
["pplus-tabs"] = function(args, kwargs, meta) return tabs(kwargs, meta) end,
["pplus-link"] = function(args, kwargs, meta) return link(kwargs, meta) end,
}
for _, name in ipairs(HW_VIEWS) do
shortcodes["pplus-hw-" .. name] = function(args, kwargs, meta) return static_view("hw", kwargs, meta, { hw = { name }, name = "pplus-hw-" .. name }) end
end
return shortcodes