Build, test, deploy / site (push) Successful in 7m44s
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.
786 lines
41 KiB
Lua
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("&", "&"):gsub("<", "<"):gsub(">", ">"):gsub('"', """)
|
|
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 " stands for one.
|
|
local function kwarg(kwargs, name)
|
|
local v = kwargs[name]
|
|
if v == nil then return nil end
|
|
local s = str(v):gsub(""", '"')
|
|
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
|