prolog-notebook 0.1.2 → 0.3.1

package/src/engine.js

@@ -6,11 +6,29 @@
 
 let fileSerial = 0;
 
-// SWI reports "Redefined static procedure" and friends by printing to user_error
-// and then carrying on, so a consult that quietly destroyed another cell's
-// clauses still succeeds. message_hook/3 is the documented way to intercept
-// those; failing at the end lets the normal printing happen as well.
-const MESSAGE_HOOK = `
+// What we teach the engine about itself, consulted once at startup.
+//
+// TWO THINGS, and both are about telling the truth to a reader.
+//
+// 1. SWI reports "Redefined static procedure" and friends by printing to
+//    user_error and then carrying on, so a consult that quietly destroyed
+//    another cell's clauses still succeeds. message_hook/3 is the documented way
+//    to intercept those; failing at the end lets the normal printing happen too.
+//
+// 2. AN ANSWER IS RENDERED BY PROLOG, NOT BY US. Formatting each binding in a
+//    separate round trip loses the one thing a Prolog answer is mostly about —
+//    which variables are the SAME variable. `app([1,2], Tail, L)` really does
+//    print `L = [1, 2|Tail]` at a toplevel, and we printed
+//    `L = [1,2|_20306],  Tail = _20428`: two differently-numbered variables
+//    where there is one, with the reader's own name for it thrown away
+//    (869erjw27). For a chapter about partial lists that is the opposite of the
+//    lesson.
+//
+// The rule the toplevel follows, and this reproduces: a variable is NAMED by the
+// last binding that mentions it, and that binding is then omitted — so `X = Y`
+// prints as `X = Y`, and an unbound `Tail` disappears from the list of bindings
+// and reappears inside `L`. Anything still unnamed becomes _A, _B, … as SWI does.
+const HOOK = String.raw`
 :- dynamic '$nb_message'/2.
 user:message_hook(_Term, Kind, Lines) :-
     memberchk(Kind, [warning, error]),
@@ -19,6 +37,68 @@ user:message_hook(_Term, Kind, Lines) :-
           _, S = ''),
     assertz('$nb_message'(Kind, S)),
     fail.
+
+% One solution: the text a toplevel would print, and the bindings by name.
+% The goal arrives as a STRING BOUND TO A VARIABLE, never interpolated into this
+% query, so a goal containing quotes or brackets needs no escaping anywhere.
+'$nb_answer'(GoalText, Text, Names, Values) :-
+    read_term_from_atom(GoalText, Goal, [variable_names(Bindings)]),
+    call(Goal),
+    '$nb_render'(Bindings, Text),
+    findall(N, member(N=_, Bindings), Names),
+    findall(V, member(_=V, Bindings), Values).
+
+'$nb_render'(Bindings, Text) :-
+    '$nb_names'(Bindings, Bindings, Named),
+    exclude('$nb_named_itself'(Named), Bindings, Shown),
+    (   Shown == []
+    ->  Text = true
+    ;   '$nb_anonymous'(Shown, Named, All),
+        maplist('$nb_pair'(All), Shown, Parts),
+        % An ATOM, not a string: swipl-wasm hands an atom to JavaScript as a
+        % plain string and a Prolog string as a wrapper object, and one
+        % representation crossing the boundary is one fewer thing to unwrap.
+        atomic_list_concat(Parts, ',  ', Text)
+    ).
+
+% Each unbound variable takes the LAST name bound to it.
+'$nb_names'([], _, []).
+'$nb_names'([Name=Value|T], All, Named) :-
+    (   var(Value),
+        '$nb_last_name'(All, Value, Name)
+    ->  Named = [Name=Value|Rest]
+    ;   Named = Rest
+    ),
+    '$nb_names'(T, All, Rest).
+
+'$nb_last_name'(All, Var, Name) :-
+    findall(N, (member(N=V, All), V == Var), Names),
+    last(Names, Name).
+
+% A binding that only says "this variable is called what it is called".
+'$nb_named_itself'(Named, Name=Value) :-
+    var(Value),
+    member(N=V, Named),
+    V == Value,
+    N == Name.
+
+'$nb_anonymous'(Shown, Named, All) :-
+    term_variables(Shown, Vars),
+    exclude('$nb_has_name'(Named), Vars, Unnamed),
+    findall(A, ( between(0'A, 0'Z, C), char_code(Ch, C), atom_concat('_', Ch, A) ), Alphabet),
+    '$nb_zip'(Unnamed, Alphabet, Extra),
+    append(Named, Extra, All).
+
+'$nb_has_name'(Named, Var) :- member(_=V, Named), V == Var.
+
+'$nb_zip'([], _, []).
+'$nb_zip'([V|Vs], [N|Ns], [N=V|T]) :- '$nb_zip'(Vs, Ns, T).
+
+'$nb_pair'(Names, Name=Value, Part) :-
+    with_output_to(string(S),
+        write_term(Value, [ quoted(true), portray(true), numbervars(true),
+                            spacing(next_argument), variable_names(Names) ])),
+    format(atom(Part), '~w = ~w', [Name, S]).
 `;
 
 export class PrologSession {
@@ -31,7 +111,7 @@ export class PrologSession {
     const session = new PrologSession(module);
     // No `$` in the path: SWI expands $var in file names like a shell does, so
     // /$nb-hook.pl resolves to nothing and the consult fails silently.
-    module.FS.writeFile('/nb-hook.pl', MESSAGE_HOOK);
+    module.FS.writeFile('/nb-hook.pl', HOOK);
     module.prolog.query("user:consult('/nb-hook.pl')").once();
     return session;
   }
@@ -77,10 +157,16 @@ export class PrologSession {
    * @returns {PrologQuery}
    */
   query(goal) {
-    // Cells consult into `user`, but prolog.query/1 runs with `system` as the
-    // context module, so an unqualified goal resolves against the wrong one.
+    // The goal is BOUND, not interpolated: `'$nb_answer'` reads it in the `user`
+    // module (where cells consult) and renders each solution there, so operators,
+    // quoting and shared variables are SWI's own work rather than ours. It also
+    // means a goal containing quotes or brackets needs no escaping at any point.
     const cleaned = goal.trim().replace(/\.$/, '');
-    return new PrologQuery(this.module.prolog.query(`user:( ${cleaned} )`), this);
+    const handle = this.module.prolog.query(
+      "user:'$nb_answer'(G, Text, Names, Values)",
+      { G: cleaned }
+    );
+    return new PrologQuery(handle, this);
   }
 
   /**
@@ -131,9 +217,38 @@ export class PrologQuery {
     this.handle = handle;
     this.session = session;
     this.exhausted = false;
+    // Ended by something other than its own search — see close(). Kept apart from
+    // `exhausted` because "the search finished" and "we stopped it" are different
+    // facts, and only the first may ever be written down as `false.` (format §6).
+    this.superseded = false;
     this.count = 0;
   }
 
+  /**
+   * Give the query frame back to the engine.
+   *
+   * SWI KEEPS OPEN QUERIES ON A STACK, and swipl-wasm enforces it: both
+   * `next()` and `close()` call `__must_be_innermost_query`, which throws
+   * "Attempt to access not innermost query". An abandoned query is therefore not
+   * merely untidy — it is a frame every later query has to nest inside, and the
+   * abandoned one can never be stepped again (869epzqpc).
+   *
+   * Nothing else releases it. Running the search to `done` does, because
+   * swipl-wasm closes the query itself at that point, which is why a drained
+   * sequence costs nothing. Everything else must come through here.
+   *
+   * @param {{superseded?: boolean}} [options] `superseded` when the session
+   *   closed this to make room for another query rather than the caller being
+   *   finished with it. It changes what next() reports, and it must: a caller
+   *   that reads plain `done` concludes the search was exhausted.
+   */
+  close({ superseded = false } = {}) {
+    if (superseded) this.superseded = true;
+    if (this.exhausted) return;
+    this.exhausted = true;
+    this.handle.close();
+  }
+
   /**
    * Pull the next solution.
    *
@@ -144,17 +259,20 @@ export class PrologQuery {
    * @returns {{done: boolean, solution?: object, text?: string, error?: string}}
    */
   next() {
-    if (this.exhausted) return { done: true };
+    // `superseded` travels with the done, because a closed query and an exhausted
+    // one are indistinguishable from `{done: true}` alone — and the difference is
+    // whether the caller may write `false.` under it.
+    if (this.exhausted) return this.superseded ? { done: true, superseded: true } : { done: true };
     let r;
     try {
       r = this.handle.next();
     } catch (e) {
       this.exhausted = true;
-      return { done: true, error: e.message };
+      return { done: true, error: readableError(e.message) };
     }
     if (r.error) {
       this.exhausted = true;
-      return { done: true, error: r.message };
+      return { done: true, error: readableError(r.message) };
     }
 
     // The engine can deliver the final solution *together with* done:true — a
@@ -163,10 +281,11 @@ export class PrologQuery {
     const out = { done: !!r.done };
     if (r.value) {
       this.count += 1;
-      out.solution = bindingsOf(r.value);
-      // Safe while the outer query is still open — verified by stepping a
-      // three-solution query with a term_string call between every step.
-      if (this.session) out.text = this.session.formatSolution(out.solution);
+      // `Text` is what a toplevel would print for this solution, rendered inside
+      // Prolog (see HOOK). `Names`/`Values` are the same answer as data, for a
+      // caller that wants the bindings rather than the line.
+      out.text = r.value.Text;
+      out.solution = zipBindings(r.value.Names, r.value.Values);
     }
     if (r.done) this.exhausted = true;
     return out;
@@ -188,7 +307,74 @@ export class PrologQuery {
   }
 }
 
+/**
+ * Drop the frame that is ours rather than the reader's.
+ *
+ * SWI prefixes an error with the goal it was raised from, which is usually worth
+ * keeping — `//2: Arithmetic: evaluation error` names the division. But every
+ * goal we run is wrapped for the WASM boundary, so an unknown predicate reads
+ * `wasm:wasm_call_string/3: Unknown procedure: is_son/1`. That prefix is our
+ * plumbing in the middle of a teaching page: the reader did not write it, cannot
+ * act on it, and it is the same words whatever they got wrong.
+ *
+ * Only that one frame is removed. Any other context is the reader's own code.
+ */
+export function readableError(message) {
+  return String(message ?? '')
+    .replace(/^wasm:wasm_call_string\/\d+:\s*/, '')
+    // Our own wrapper, which the reader did not write and cannot act on. It is
+    // the same plumbing argument as the frame above: `'$nb_answer'/4: Unknown
+    // procedure: son_a/1` names a predicate of ours in the middle of a teaching
+    // page.
+    .replace(/^'\$nb_answer'\/\d+:\s*/, '');
+}
+
+/**
+ * A message about THIS cell, said the way the cell would say it.
+ *
+ * One cell is one virtual file, so SWI's line numbers are already the cell's own
+ * — that half of the problem solved itself. What is left is the path: a reader
+ * looking at a syntax error printed on the very cell that caused it does not need
+ * to be told which file it was in, and `/p-family.pl` is a filename they never
+ * chose and cannot open.
+ *
+ *   /p-family.pl:4:6: Syntax error: Operator expected
+ *   line 4, column 6: Syntax error: Operator expected
+ *
+ * ONLY THIS CELL'S OWN PATH IS REMOVED, which is the whole reason the name is a
+ * parameter rather than a wildcard. A consult warning naming a DIFFERENT cell —
+ * "Redefined static procedure male/1", the one that says another cell's clauses
+ * have just been destroyed — is only useful because it names that other file, and
+ * a regex that stripped any path would delete exactly the part worth reading.
+ *
+ * @param {string} message
+ * @param {string} name the cell's own consult name
+ */
+export function readableInCell(message, name) {
+  const path = `/${String(name ?? '')}.pl:`;
+  const text = readableError(message);
+  if (!text.startsWith(path)) return text;
+  return text
+    .slice(path.length)
+    .replace(/^(\d+):(\d+):\s*/, 'line $1, column $2: ')
+    .replace(/^(\d+):\s*/, 'line $1: ');
+}
+
 /** Strip the engine's bookkeeping keys from a solution. */
+/**
+ * The query's own variable names, against their values.
+ *
+ * Two parallel lists rather than a list of `Name=Value` terms, because a term
+ * would have to be taken apart on this side and the lists arrive as arrays
+ * already. Order is the order the variables appear in the goal, which is the
+ * order a toplevel reports them in.
+ */
+export function zipBindings(names = [], values = []) {
+  const out = {};
+  names.forEach((name, i) => { out[name] = values[i]; });
+  return out;
+}
+
 export function bindingsOf(value) {
   const out = {};
   for (const [k, v] of Object.entries(value)) {
@@ -198,6 +384,31 @@ export function bindingsOf(value) {
   return out;
 }
 
+/**
+ * Which SWI-Prolog this is.
+ *
+ * Worth asking, and not derivable from anything on disk: swipl-wasm 8.0.4 ships
+ * SWI-Prolog 10.1.10, and the two numbers have no relationship at all. A
+ * chapter's saved answers are only true of the engine that produced them, so
+ * the version is part of their attribution rather than a footnote.
+ *
+ * `version` rather than `version_git`: the integer flag is always present, and
+ * its encoding is documented — MAJOR*10000 + MINOR*100 + PATCH.
+ *
+ * @param {{query: Function}} session any session, in either environment
+ * @returns {Promise<string|null>} e.g. "10.1.10", or null if the engine will not say
+ */
+export async function prologVersion(session) {
+  try {
+    const result = await session.query('current_prolog_flag(version, V)').all(1);
+    const encoded = result.solutions?.[0]?.V;
+    if (!Number.isInteger(encoded)) return null;
+    return `${Math.floor(encoded / 10000)}.${Math.floor(encoded / 100) % 100}.${encoded % 100}`;
+  } catch {
+    return null;
+  }
+}
+
 /** Render a solution the way a Prolog top level would. */
 export function formatSolution(solution) {
   const pairs = Object.entries(solution);

package/src/export.js

@@ -0,0 +1,126 @@
+// The reader leaves with a real file.
+//
+// Explore mode lets a reader edit a published chapter and run it, and until now
+// gave them no way to keep the result. That is a trap rather than a feature: work
+// that lives only in a page is one navigation from gone, and telling someone to
+// experiment while quietly discarding what they produce teaches them not to.
+//
+// The answer is FORK BY DOWNLOAD, never save-back (docs/modes.md §3). The
+// published chapter stays canonical; the reader gets their own `.prolog.md`,
+// which they can commit, open in VS Code, or send back as a pull request. That
+// last one is free: the format is markdown in git, so the contribution path
+// already exists.
+//
+// Cheap by construction — serialise() already emits canonical bytes — so all the
+// work here is in being honest about WHOSE ANSWERS ARE WHOSE.
+import { hashFor, serialise } from './format.js';
+
+/**
+ * The notebook as it now stands on screen.
+ *
+ * @param {{frontMatter: Map<string, string>, cells: object[]}} notebook the published model
+ * @param {Map<string, {source?: string, goal?: string, output?: object|null}>} edits by cell id
+ * @returns {{frontMatter: Map<string, string>, cells: object[]}}
+ */
+export function withEdits(notebook, edits) {
+  const cells = notebook.cells.map((cell) => {
+    const edit = edits.get(cell.id);
+    if (!edit) return cell;
+    if (cell.kind === 'program' && edit.source !== undefined) {
+      return { ...cell, source: edit.source };
+    }
+    if (cell.kind === 'query') {
+      const next = { ...cell };
+      if (edit.goal !== undefined) next.goal = edit.goal;
+      // `output: null` is a deliberate erasure, not a missing key: it is how a
+      // query the reader has half-run says "I have no answers to give you".
+      //
+      // An output is more than its answers — it carries the fence's language and
+      // whatever attributes the author wrote on it, and the serialiser needs
+      // every one of them. So the reader's answers are laid OVER the author's
+      // output rather than replacing the object, and a cell that never had one
+      // gets the defaults the parser would have produced.
+      if ('output' in edit) {
+        next.output = edit.output && { ...blankOutput(), ...cell.output, ...edit.output };
+      }
+      return next;
+    }
+    return cell;
+  });
+
+  const updated = { ...notebook, cells };
+
+  // THE HASHES ARE THE WHOLE ARGUMENT. A downloaded file has to say, of every
+  // output in it, whether it follows from the program above it — and the format
+  // already has the spelling for that (format §6).
+  //
+  // - An answer the READER produced is hashed against the READER's program,
+  //   because that is what produced it. It opens as current, which it is.
+  // - An answer from the CHAPTER keeps the AUTHOR's hash, untouched. If the
+  //   reader edited a program above it, the hash no longer matches and the file
+  //   opens with that output marked stale — which is exactly the truth, and
+  //   exactly what the page they downloaded it from was showing.
+  //
+  // Rehashing everything would be the tempting one-liner and it would be a
+  // forgery: it would certify the author's answers as following from the
+  // reader's program. That is the one failure this project may not have.
+  for (const cell of cells) {
+    if (cell.kind !== 'query' || !cell.output) continue;
+    if (edits.get(cell.id)?.output) {
+      cell.output = { ...cell.output, inputHash: hashFor(updated, cell) };
+    }
+  }
+
+  return updated;
+}
+
+/**
+ * What the parser would have produced for an output that has none of its own.
+ *
+ * A query the chapter never ran has no fence for its answers, so there is
+ * nothing to inherit language or attributes from, and the serialiser reads both
+ * unconditionally — `attrs` in particular is iterated, so a missing one is a
+ * TypeError rather than a silently absent attribute.
+ */
+function blankOutput() {
+  return { solutions: [], terminator: '', inputHash: null, language: 'text', attrs: new Map() };
+}
+
+/**
+ * Serialise the notebook as it now stands.
+ * @returns {string} canonical `.prolog.md` bytes
+ */
+export function exportSource(notebook, edits) {
+  return serialise(withEdits(notebook, edits));
+}
+
+/**
+ * A filename for the reader's copy.
+ *
+ * From the SOURCE, never the title: a title can contain anything, including
+ * slashes, and the reader recognises the file they came from. The name is not
+ * decorated with "my-copy" either — this is their file now, and their filesystem
+ * is where the distinction between copies belongs.
+ */
+export function filenameFor(url) {
+  const path = String(url ?? '').split(/[?#]/)[0];
+  const base = path.slice(path.lastIndexOf('/') + 1);
+  return base || 'notebook.prolog.md';
+}
+
+/**
+ * Hand a file to the reader.
+ *
+ * An object URL and a synthetic click, revoked on the next turn of the event
+ * loop. No network, no server, nothing to own.
+ */
+export function download(filename, text, document_ = document) {
+  const url = URL.createObjectURL(new Blob([text], { type: 'text/markdown;charset=utf-8' }));
+  const anchor = document_.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  document_.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}