@mark1russell7/coeval 0.15.0 → 0.17.0

package/src/syntax.ts

@@ -37,6 +37,23 @@ export interface SyntaxLiterals {
   readonly strings?: false | { readonly quote?: '"' | "'"; readonly escape?: "backslash" | "double" };
   /** The words that are literals, with their values. The default is `true`, `false` and `null`. */
   readonly words?: Readonly<Record<string, unknown>>;
+  /**
+   * The kinds of the data envelopes of a text, a number and a truth value, with dots between the keys (K159, D65). A
+   * literal in a place that takes a document gets its envelope. Such a place is the whole text, the document after a
+   * header name, or an argument that its form names in `wrap`. Thus `list(1)` gives `list(number(1))`, and `print`
+   * writes the envelope as the bare literal there. Without this field, a literal stays bare in each place.
+   */
+  readonly envelopes?: SyntaxEnvelopes;
+}
+
+/** The kinds of the data envelopes of the literals (K159, D65). A literal without a kind stays bare, for example `null`. */
+export interface SyntaxEnvelopes {
+  /** The kind of a finite number, for example `number`. */
+  readonly number?: string;
+  /** The kind of a text, for example `text`. */
+  readonly text?: string;
+  /** The kind of a truth value, for example `bool`. */
+  readonly bool?: string;
 }
 
 /** A reference syntax that a pattern gives, for example the address `A1` of a cell. */
@@ -63,16 +80,40 @@ export interface SyntaxRefs {
 
 /** A call form: a name with arguments in parentheses that makes a construct, for example `if(test, then, else)`. */
 export interface SyntaxForm {
-  /** The name in the text. */
+  /**
+   * The name in the text: a plain name, or plain names with dots between them, for example `math.product` (K161). A
+   * name with dots needs the field steps of `refs.fields`, and its first key is not a word operator.
+   */
   readonly name: string;
   /** The type of the document, with dots between the keys. */
   readonly kind: string;
-  /** The fields of the value, in the order of the arguments. Without them, the value is the list of the arguments. */
+  /**
+   * The fields of the value, in the order of the arguments. Without them, the value is the list of the arguments. A
+   * form `named` permits only these keys, and without them it permits each key.
+   */
   readonly fields?: readonly string[];
-  /** The smallest number of arguments. The default is the number of the fields, or `0`. */
+  /** The smallest number of arguments. The default is the number of the fields, or `0`. Only `list` and `fields` read it. */
   readonly min?: number;
+  /**
+   * The way that the arguments make the value (D63). The default is `fields` with fields, or `list`.
+   *
+   * - `list`: the value is the list of the arguments, for example `list(1, 2)`.
+   * - `fields`: the arguments go into the fields, in order, for example `if(test, then, else)`.
+   * - `named`: each argument is a key and a document, and the value is a record, for example `panel(width: 300)`.
+   * - `literal`: the one argument is a literal, and the value is its data, for example `text("big")`.
+   */
+  readonly args?: SyntaxFormArgs;
+  /**
+   * The arguments that take a document (K159, D65): `true` for each argument, or the names of some fields. A literal
+   * in such an argument gets its data envelope of `literals.envelopes`. Without that field, `wrap` changes nothing. A
+   * form `literal` takes no `wrap`, and a form `list` takes only `true`.
+   */
+  readonly wrap?: boolean | readonly string[];
 }
 
+/** The way that the arguments of a call form make the value of its document (D63). */
+export type SyntaxFormArgs = "list" | "fields" | "named" | "literal";
+
 /** The call syntax of a syntax profile. */
 export interface SyntaxCalls {
   /** The operations that a call `name(args)` can name. `true` permits each name. The default is `true`. */
@@ -83,6 +124,16 @@ export interface SyntaxCalls {
   readonly separator?: string;
 }
 
+/** The text of the header of a document (K157, D62). */
+export interface SyntaxHeader {
+  /**
+   * The symbol between a name and its document, for example `=` in `total = 2 + 3`. The text gives the document the
+   * header `name`. Without the symbol, a document with a name has no text. The symbol is a group of symbols, and no
+   * infix or postfix operator is the symbol or the start of it.
+   */
+  readonly bind?: string;
+}
+
 /**
  * The text syntax of a language (D41): an operator table, literal rules, reference syntax and call syntax. `parse`
  * reads a text into a document, and `print` writes a document as text. The profile is data, thus a site, an editor
@@ -97,6 +148,8 @@ export interface SyntaxProfile {
   readonly refs?: SyntaxRefs;
   /** The call syntax. */
   readonly calls?: SyntaxCalls;
+  /** The text of the header of a document. */
+  readonly header?: SyntaxHeader;
   /** The deepest nesting that `parse` accepts. The default is `256`. */
   readonly maxDepth?: number;
 }
@@ -117,7 +170,8 @@ export type ParseResult = { readonly ok: true; readonly doc: Json } | { readonly
 /**
  * The standard syntax of the formula kit. It gives the site and the playground a text form. The operators are
  * `or`, `and`, `not`, the comparisons, `+ - * / %`, a minus sign and `^`, from the loosest to the tightest. A call
- * `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs.
+ * `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs. The
+ * text `total = 2 + 3` gives the document the header name `total` (D62).
  */
 export const STD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
   operators: [
@@ -145,6 +199,7 @@ export const STD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
       { name: "list", kind: "list" },
     ],
   },
+  header: { bind: "=" },
 } satisfies SyntaxProfile);
 
 // === The compiled profile ===
@@ -162,8 +217,17 @@ interface Op {
 interface Form {
   readonly name: string;
   readonly type: Json;
+  readonly args: SyntaxFormArgs;
   readonly fields: readonly string[] | undefined;
   readonly min: number;
+  /** The arguments that take a document: `true` for each, or the names of the fields. */
+  readonly wrap: boolean | ReadonlySet<string>;
+}
+
+/** The type of a data envelope, and its key for a comparison with the path of a type. */
+interface EnvelopeKind {
+  readonly type: Json;
+  readonly key: string;
 }
 
 interface Pattern {
@@ -184,6 +248,7 @@ interface Compiled {
   readonly quote: string | undefined;
   readonly doubled: boolean;
   readonly words: ReadonlyMap<string, unknown>;
+  readonly envelopes: { readonly number?: EnvelopeKind; readonly text?: EnvelopeKind; readonly bool?: EnvelopeKind } | undefined;
   readonly bare: string;
   readonly roots: ReadonlySet<string>;
   readonly fields: boolean;
@@ -192,6 +257,7 @@ interface Compiled {
   readonly forms: ReadonlyMap<string, Form>;
   readonly formsByKind: ReadonlyMap<string, readonly Form[]>;
   readonly separator: string;
+  readonly bind: string | undefined;
   readonly reserved: ReadonlySet<string>;
   readonly opWords: ReadonlySet<string>;
   readonly maxDepth: number;
@@ -204,6 +270,7 @@ const NUMBER_AT = /(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/y;
 const SYMBOL = /^[^\sA-Za-z0-9_"'`()$.]+$/;
 const DEFAULT_WORDS: Readonly<Record<string, unknown>> = { true: true, false: false, null: null };
 const DEFAULT_ROOTS: readonly string[] = ["self", "world", "event", "caps"];
+const FORM_ARGS: readonly SyntaxFormArgs[] = ["list", "fields", "named", "literal"];
 
 const compiledProfiles = new WeakMap<SyntaxProfile, Compiled>();
 
@@ -249,6 +316,40 @@ function compileOps(profile: SyntaxProfile, separator: string): Pick<Compiled, "
   return { prefix, binary, prefixSymbols: longestFirst(prefix), binarySymbols: longestFirst(binary), byKind, opWords };
 }
 
+/** This function examines the bind symbol of a header. A text with the symbol after a name was not valid before. */
+function compileBind(bind: string | undefined, separator: string, binary: ReadonlyMap<string, Op>): string | undefined {
+  if (bind === undefined) return undefined;
+  if (!SYMBOL.test(bind) || bind.includes(separator)) throw new TypeError(`The bind symbol "${bind}" is not a group of symbols.`);
+  for (const symbol of binary.keys()) {
+    if (bind.startsWith(symbol)) throw new TypeError(`The bind symbol "${bind}" starts with the operator "${symbol}".`);
+  }
+  return bind;
+}
+
+/** This function examines the field `wrap` of a call form (K159). A name that is not a field of the form throws. */
+function compileWrap(given: SyntaxForm, args: SyntaxFormArgs): boolean | ReadonlySet<string> {
+  const wrap = given.wrap;
+  if (wrap === undefined || wrap === false) return false;
+  if (args === "literal") throw new TypeError(`The call form "${given.name}" with the arguments literal takes no wrap.`);
+  if (wrap === true) return true;
+  if (args === "list") throw new TypeError(`The call form "${given.name}" with the arguments list takes only the wrap true.`);
+  for (const name of wrap) {
+    if (given.fields !== undefined && !given.fields.includes(name)) throw new TypeError(`The call form "${given.name}" has no field ${name} for its wrap.`);
+  }
+  return new Set(wrap);
+}
+
+/** This function gives the types of the data envelopes of a profile (K159), or `undefined` without them. */
+function compileEnvelopes(given: SyntaxEnvelopes | undefined): Compiled["envelopes"] {
+  if (given === undefined) return undefined;
+  const out: { number?: EnvelopeKind; text?: EnvelopeKind; bool?: EnvelopeKind } = {};
+  for (const key of ["number", "text", "bool"] as const) {
+    const kind = given[key];
+    if (kind !== undefined) out[key] = typeOfKind(kind);
+  }
+  return out;
+}
+
 function compileProfile(profile: SyntaxProfile): Compiled {
   const cached = compiledProfiles.get(profile);
   if (cached !== undefined) return cached;
@@ -263,9 +364,16 @@ function compileProfile(profile: SyntaxProfile): Compiled {
   const forms = new Map<string, Form>();
   const formsByKind = new Map<string, Form[]>();
   for (const given of calls.forms ?? []) {
-    if (!NAME.test(given.name)) throw new TypeError(`The call form "${given.name}" is not a plain name.`);
+    const keys = given.name.split(".");
+    if (!keys.every((key) => NAME.test(key))) throw new TypeError(`The call form "${given.name}" is not a plain name or a path of plain names.`);
+    if (keys.length > 1 && refs.fields === false) throw new TypeError(`The call form "${given.name}" has dots, but the syntax has no field steps.`);
+    if (keys.length > 1 && ops.opWords.has(keys[0] as string)) throw new TypeError(`The call form "${given.name}" starts with the word operator "${keys[0] as string}".`);
     const { type, key } = typeOfKind(given.kind);
-    const form: Form = { name: given.name, type, fields: given.fields, min: given.min ?? given.fields?.length ?? 0 };
+    const args = given.args ?? (given.fields === undefined ? "list" : "fields");
+    if (!FORM_ARGS.includes(args)) throw new TypeError(`The call form "${given.name}" has the unknown arguments ${String(args)}.`);
+    if ((args === "fields") !== (given.fields !== undefined) && args !== "named") throw new TypeError(`The call form "${given.name}" with the arguments ${args} ${args === "fields" ? "needs" : "takes no"} fields.`);
+    if (given.min !== undefined && (args === "named" || args === "literal")) throw new TypeError(`The call form "${given.name}" with the arguments ${args} takes no min.`);
+    const form: Form = { name: given.name, type, args, fields: given.fields, min: given.min ?? given.fields?.length ?? 0, wrap: compileWrap(given, args) };
     forms.set(form.name, form);
     addTo(formsByKind, key, form);
   }
@@ -276,6 +384,7 @@ function compileProfile(profile: SyntaxProfile): Compiled {
     quote: strings === undefined ? undefined : (strings.quote ?? '"'),
     doubled: strings !== undefined && strings.escape === "double",
     words,
+    envelopes: compileEnvelopes(literals.envelopes),
     bare: refs.bare ?? "names",
     roots,
     fields: refs.fields ?? true,
@@ -287,6 +396,7 @@ function compileProfile(profile: SyntaxProfile): Compiled {
     forms,
     formsByKind,
     separator,
+    bind: compileBind(profile.header?.bind, separator, ops.binary),
     reserved: new Set([...words.keys(), ...ops.opWords, ...roots]),
     maxDepth: profile.maxDepth ?? 256,
   };
@@ -309,6 +419,34 @@ function opDoc(op: Op | Form, value: Json): Json {
   return { type: op.type, value };
 }
 
+/** This function gives the kind of the data envelope of a literal (K159), or `undefined` when the literal has none. */
+function envelopeOf(syn: Compiled, value: unknown): EnvelopeKind | undefined {
+  const kinds = syn.envelopes;
+  if (kinds === undefined || !isScalar(value)) return undefined;
+  return typeof value === "string" ? kinds.text : typeof value === "number" ? kinds.number : typeof value === "boolean" ? kinds.bool : undefined;
+}
+
+/** This function gives a literal in a place that takes a document its data envelope (K159). Each other document stays. */
+function envelop(syn: Compiled, doc: Json): Json {
+  const kind = isEnvelope(doc) ? undefined : envelopeOf(syn, doc);
+  return kind === undefined ? doc : { type: kind.type, value: doc };
+}
+
+/** This function tells if an argument of a form takes a document (K159). */
+function wraps(form: Form, key: Key): boolean {
+  return form.wrap === true || (form.wrap !== false && form.wrap.has(String(key)));
+}
+
+/** This function tells if a value is a literal that JSON writes exactly: a text, a finite number, a truth value or `null`. */
+function isScalar(value: unknown): value is string | number | boolean | null {
+  return value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0));
+}
+
+function setOwn(target: Record<string, Json>, key: string, value: Json): void {
+  if (key === "__proto__") Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  else target[key] = value;
+}
+
 const ESCAPES: Readonly<Record<string, string>> = { '"': '"', "'": "'", "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
 
 class Parser {
@@ -323,10 +461,11 @@ class Parser {
   parse(): Json {
     this.skip();
     if (this.pos >= this.text.length) this.stop("The text is empty.", 0, 0);
-    const doc = this.expr(0);
+    const doc = this.bound();
     this.skip();
     if (this.pos < this.text.length) this.stop("The text continues after the expression.", this.pos, this.tokenLength());
-    return doc;
+    // The whole text is a document, thus a literal gets its data envelope (K159).
+    return envelop(this.syn, doc);
   }
 
   position(): number {
@@ -350,6 +489,53 @@ class Parser {
     return (this.at(NAME_AT) ?? this.at(DIGITS_AT) ?? "x").length;
   }
 
+  /**
+   * This method reads an expression that can have a header name: `name = expr` (D62). The bind symbol of the profile
+   * follows the name. A longer operator that starts with the symbol wins, for example `==` over `=`.
+   */
+  private bound(): Json {
+    const name = this.bindingName();
+    if (name === undefined) return this.expr(0);
+    this.skip();
+    const start = this.pos;
+    const doc = this.expr(0);
+    if (isEnvelope(doc)) {
+      if (doc.name !== undefined) this.stop(`The document already has the name ${doc.name}.`, start, this.pos - start);
+      return { ...doc, name };
+    }
+    const kind = envelopeOf(this.syn, doc);
+    return kind === undefined ? { type: "lit", value: doc, name } : { type: kind.type, value: doc, name };
+  }
+
+  /** This method reads a name and the bind symbol after it. Without them, it gives `undefined` and keeps the position. */
+  private bindingName(): string | undefined {
+    const bind = this.syn.bind;
+    if (bind === undefined) return undefined;
+    this.skip();
+    const back = this.pos;
+    let name: string | undefined;
+    if (this.text[this.pos] === "`") {
+      try {
+        name = this.quoted();
+      } catch (error) {
+        if (!(error instanceof Stop)) throw error;
+      }
+    } else {
+      name = this.at(NAME_AT);
+      if (name !== undefined) this.pos += name.length;
+    }
+    if (name !== undefined) {
+      this.skip();
+      const longer = this.syn.binarySymbols.some((symbol) => symbol.length > bind.length && symbol.startsWith(bind) && this.text.startsWith(symbol, this.pos));
+      if (this.text.startsWith(bind, this.pos) && !longer) {
+        this.pos += bind.length;
+        return name;
+      }
+    }
+    this.pos = back;
+    return undefined;
+  }
+
   /** This method reads an expression by precedence climbing. It stops at an operator below `min`. */
   private expr(min: number): Json {
     const start = this.pos;
@@ -486,7 +672,7 @@ class Parser {
   private group(): Json {
     const open = this.pos;
     this.pos += 1;
-    const inner = this.expr(0);
+    const inner = this.bound();
     this.skip();
     if (this.text[this.pos] !== ")") {
       if (this.pos >= this.text.length) this.stop("A closing parenthesis is missing.", open, 1);
@@ -527,7 +713,7 @@ class Parser {
       if (prefix !== undefined && prefix.word) return opDoc(prefix, [this.expr(prefix.prec + 1)]);
       if (this.syn.binary.get(first)?.word === true) this.stop(`A term is missing before ${first}.`, start, first.length);
     }
-    const path: Key[] = [first];
+    const path: Json[] = [first];
     let allPlain = plain;
     for (;;) {
       const back = this.pos;
@@ -538,6 +724,12 @@ class Parser {
       }
       this.pos += 1;
       this.skip();
+      // A step in parentheses is a document, for example `self.parent.(nearest(type: "panel"))` (SYNTAX.STEP).
+      if (this.text[this.pos] === "(") {
+        path.push(this.group());
+        allPlain = false;
+        continue;
+      }
       if (this.text[this.pos] === "`") {
         path.push(this.quoted());
         allPlain = false;
@@ -553,7 +745,7 @@ class Parser {
     const back = this.pos;
     this.skip();
     if (this.text[this.pos] === "(") {
-      if (!allPlain) this.stop("The name of a call is a plain name.", start, back - start);
+      if (!allPlain) this.stop("Each key of the name of a call is a plain name.", start, back - start);
       return this.call(path.join("."), start, back - start);
     }
     this.pos = back;
@@ -562,39 +754,78 @@ class Parser {
     return { type: "ref", value: full };
   }
 
-  private call(name: string, start: number, nameLength: number): Json {
+  /** This method reads the arguments of a call in parentheses. `item` reads one argument. */
+  private argumentsOf<T>(item: () => T): T[] {
     const open = this.pos;
-    const args: Json[] = [];
+    const args: T[] = [];
     this.pos += 1;
     this.skip();
-    if (this.text[this.pos] === ")") this.pos += 1;
-    else {
-      for (;;) {
-        args.push(this.expr(0));
-        this.skip();
-        if (this.text.startsWith(this.syn.separator, this.pos)) {
-          this.pos += this.syn.separator.length;
-          continue;
-        }
-        if (this.text[this.pos] === ")") {
-          this.pos += 1;
-          break;
-        }
-        if (this.pos >= this.text.length) this.stop("A closing parenthesis is missing.", open, 1);
-        this.stop(`A "${this.syn.separator}" or a closing parenthesis is missing.`, this.pos, this.tokenLength());
+    if (this.text[this.pos] === ")") {
+      this.pos += 1;
+      return args;
+    }
+    for (;;) {
+      args.push(item());
+      this.skip();
+      if (this.text.startsWith(this.syn.separator, this.pos)) {
+        this.pos += this.syn.separator.length;
+        continue;
       }
+      if (this.text[this.pos] === ")") {
+        this.pos += 1;
+        return args;
+      }
+      if (this.pos >= this.text.length) this.stop("A closing parenthesis is missing.", open, 1);
+      this.stop(`A "${this.syn.separator}" or a closing parenthesis is missing.`, this.pos, this.tokenLength());
     }
+  }
+
+  /** This method reads the arguments `key: expr` of a form `named` into a record (SYNTAX.RECORD). */
+  private namedArguments(form: Form): Json {
+    const value: Record<string, Json> = {};
+    this.argumentsOf(() => {
+      this.skip();
+      const at = this.pos;
+      let key: string | undefined;
+      if (this.text[at] === "`") key = this.quoted();
+      else {
+        key = this.at(NAME_AT);
+        if (key !== undefined) this.pos += key.length;
+      }
+      const end = this.pos;
+      this.skip();
+      if (key === undefined || this.text[this.pos] !== ":") {
+        this.stop(`Each argument of the form ${form.name} is a key, a ":" and a document.`, at, Math.max(end - at, this.tokenLength()));
+      }
+      if (form.fields !== undefined && !form.fields.includes(key)) this.stop(`The form ${form.name} has no field ${key}.`, at, end - at);
+      if (Object.hasOwn(value, key)) this.stop(`The form ${form.name} has the field ${key} two times.`, at, end - at);
+      this.pos += 1;
+      const arg = this.bound();
+      setOwn(value, key, wraps(form, key) ? envelop(this.syn, arg) : arg);
+    });
+    return opDoc(form, value);
+  }
+
+  private call(name: string, start: number, nameLength: number): Json {
     const form = this.syn.forms.get(name);
+    if (form?.args === "named") return this.namedArguments(form);
+    const args = this.argumentsOf(() => this.bound());
+    if (form?.args === "literal") {
+      const [only] = args;
+      if (args.length !== 1 || !isScalar(only)) this.stop(`The form ${name} takes one literal that JSON writes.`, start, this.pos - start);
+      return opDoc(form, only);
+    }
     if (form !== undefined) {
       const most = form.fields?.length ?? Number.POSITIVE_INFINITY;
       if (args.length < form.min || args.length > most) {
         const range = most === form.min ? String(most) : most === Number.POSITIVE_INFINITY ? `${String(form.min)} or more` : `${String(form.min)} to ${String(most)}`;
         this.stop(`The form ${name} takes ${range} arguments.`, start, this.pos - start);
       }
-      if (form.fields === undefined) return opDoc(form, args);
+      if (form.fields === undefined) return opDoc(form, form.wrap === true ? args.map((arg) => envelop(this.syn, arg)) : args);
       const value: Record<string, Json> = {};
       args.forEach((arg, index) => {
-        value[form.fields?.[index] as string] = arg;
+        const key = form.fields?.[index] as string;
+        value[key] = wraps(form, key) ? envelop(this.syn, arg) : arg;
       });
       return opDoc(form, value);
     }
@@ -625,13 +856,18 @@ export function parse(profile: SyntaxProfile, text: string): ParseResult {
 
 // === Print ===
 
-/** The text of a part, from its document and its path in the value of the parent. */
-type SubText = (child: unknown, path: readonly Key[]) => Result<string>;
+/**
+ * The text of a part, from its document and its path in the value of the parent. `wrapped` is `true` when the place
+ * of the part takes a document (K159).
+ */
+type SubText = (child: unknown, path: readonly Key[], wrapped?: boolean) => Result<string>;
 
 type Shape =
   | { readonly tag: "text"; readonly text: string }
   | { readonly tag: "op"; readonly op: Op; readonly terms: readonly unknown[] }
-  | { readonly tag: "call"; readonly name: string; readonly args: readonly (readonly [Key, unknown])[] }
+  | { readonly tag: "call"; readonly name: string; readonly args: readonly (readonly [Key, unknown, boolean?])[]; readonly named?: boolean }
+  | { readonly tag: "path"; readonly segments: readonly (string | readonly [Key, unknown])[] }
+  | { readonly tag: "bind"; readonly name: string; readonly doc: unknown }
   | { readonly tag: "none"; readonly reason: string };
 
 function none(reason: string): Shape {
@@ -672,8 +908,10 @@ function plainSegment(syn: Compiled, name: string): boolean {
   return NAME.test(name) && !syn.reserved.has(name) && !syn.patterns.some((p) => p.whole.test(name));
 }
 
-function laterSegment(step: unknown): string | undefined {
+/** This function gives the text of a later step of a path, or the step and its index when the step is a document. */
+function laterSegment(step: unknown, index: number): string | readonly [Key, unknown] | undefined {
   if (typeof step === "string") return NAME.test(step) ? step : quoteName(step);
+  if (isEnvelope(step)) return [index, step];
   return typeof step === "number" && Number.isSafeInteger(step) && step >= 0 ? String(step) : undefined;
 }
 
@@ -686,16 +924,18 @@ function refShape(syn: Compiled, value: unknown): Shape {
   const [root, ...rest] = value as readonly unknown[];
   const many = rest.length > 1 || (root !== syn.bare && rest.length > 0);
   if (many && !syn.fields) return none("This syntax has no field steps.");
-  const later = rest.slice(1).map(laterSegment);
   let first: string | undefined;
-  let tail = later;
-  if (root === syn.bare && typeof rest[0] === "string") first = plainSegment(syn, rest[0]) ? rest[0] : quoteName(rest[0]);
-  else if (typeof root === "string" && syn.roots.has(root) && !syn.patterns.some((p) => p.whole.test(root))) {
+  let tail: (string | readonly [Key, unknown] | undefined)[] = [];
+  if (root === syn.bare && typeof rest[0] === "string") {
+    first = plainSegment(syn, rest[0]) ? rest[0] : quoteName(rest[0]);
+    tail = rest.slice(1).map((step, index) => laterSegment(step, index + 2));
+  } else if (typeof root === "string" && syn.roots.has(root) && !syn.patterns.some((p) => p.whole.test(root))) {
     first = root;
-    tail = rest.map(laterSegment);
+    tail = rest.map((step, index) => laterSegment(step, index + 1));
   }
   if (first === undefined || tail.includes(undefined)) return none("This syntax has no text for the path of the reference.");
-  return { tag: "text", text: [first, ...tail].join(".") };
+  const segments = [first, ...(tail as (string | readonly [Key, unknown])[])];
+  return segments.every((segment) => typeof segment === "string") ? { tag: "text", text: segments.join(".") } : { tag: "path", segments };
 }
 
 function callName(syn: Compiled, keys: readonly Key[]): string | undefined {
@@ -705,17 +945,48 @@ function callName(syn: Compiled, keys: readonly Key[]): string | undefined {
   return syn.ops === true || syn.ops.has(name) ? name : undefined;
 }
 
-function formShape(form: Form, value: unknown): Shape | undefined {
+const WRAPPED = "This syntax reads a literal in this place as its data envelope, thus a bare literal has no text here.";
+
+/**
+ * This function gives the text of a document in a place that takes a document (K159). A data envelope of a literal
+ * is the bare literal. A literal without its envelope has no text, because `parse` gives it the envelope. The
+ * function gives `undefined` for each other document.
+ */
+function wrappedShape(syn: Compiled, doc: unknown): Shape | undefined {
+  if (syn.envelopes === undefined) return undefined;
+  if (!isEnvelope(doc)) return envelopeOf(syn, doc) === undefined ? undefined : none(WRAPPED);
+  if (doc.name !== undefined || doc.own !== undefined || !Object.hasOwn(doc, "value")) return undefined;
+  const path = typePath(doc.type);
+  if (path === undefined) return undefined;
+  const key = JSON.stringify(path);
+  if (key === JSON.stringify(["lit"])) return envelopeOf(syn, doc.value) === undefined ? undefined : none(WRAPPED);
+  if (envelopeOf(syn, doc.value)?.key !== key) return undefined;
+  const literal = literalShape(syn, doc.value);
+  return literal.tag === "text" ? literal : undefined;
+}
+
+function formShape(syn: Compiled, form: Form, value: unknown): Shape | undefined {
+  if (form.args === "literal") {
+    if (!isScalar(value)) return undefined;
+    const literal = literalShape(syn, value);
+    return literal.tag === "text" ? { tag: "text", text: `${form.name}(${literal.text})` } : undefined;
+  }
+  if (form.args === "named") {
+    if (!isRecord(value)) return undefined;
+    const keys = Object.keys(value);
+    if (form.fields !== undefined && !keys.every((key) => form.fields?.includes(key) === true)) return undefined;
+    return { tag: "call", name: form.name, args: keys.map((key) => [key, value[key], wraps(form, key)] as const), named: true };
+  }
   if (form.fields === undefined) {
     if (!Array.isArray(value) || value.length < form.min) return undefined;
-    return { tag: "call", name: form.name, args: value.map((item, index) => [index, item] as const) };
+    return { tag: "call", name: form.name, args: value.map((item, index) => [index, item, wraps(form, index)] as const) };
   }
   if (!isRecord(value)) return undefined;
   // The fields that the value holds must be the first fields of the form, because the arguments go in order.
   const count = Object.keys(value).length;
   const present = form.fields.slice(0, count);
   if (count < form.min || present.length < count || !present.every((key) => Object.hasOwn(value, key))) return undefined;
-  return { tag: "call", name: form.name, args: present.map((key) => [key, value[key]] as const) };
+  return { tag: "call", name: form.name, args: present.map((key) => [key, value[key], wraps(form, key)] as const) };
 }
 
 function opShape(syn: Compiled, key: string, terms: readonly unknown[]): Shape | undefined {
@@ -729,7 +1000,12 @@ function opShape(syn: Compiled, key: string, terms: readonly unknown[]): Shape |
 /** This function gives the shape of a document: a literal or a reference, an operator, a call, or no text. */
 function shapeOf(syn: Compiled, doc: unknown): Shape {
   if (!isEnvelope(doc)) return Array.isArray(doc) || isRecord(doc) ? none("This syntax has no text for a list or a record literal.") : literalShape(syn, doc);
-  if (doc.name !== undefined || doc.own !== undefined) return none("This syntax has no text for the header of a document.");
+  if (doc.own !== undefined) return none("This syntax has no text for the own entries of a document.");
+  if (doc.name !== undefined) {
+    if (syn.bind === undefined) return none("This syntax has no text for the name of a document.");
+    const { name, ...rest } = doc;
+    return { tag: "bind", name, doc: rest };
+  }
   const path = typePath(doc.type);
   if (path === undefined) return none("This syntax has no text for a computed type.");
   const value: unknown = doc.value;
@@ -745,7 +1021,7 @@ function shapeOf(syn: Compiled, doc: unknown): Shape {
   const op = Array.isArray(value) ? opShape(syn, key, value) : undefined;
   if (op !== undefined) return op;
   for (const form of syn.formsByKind.get(key) ?? []) {
-    const shape = formShape(form, value);
+    const shape = formShape(syn, form, value);
     if (shape !== undefined) return shape;
   }
   const called = path[0] === "ops" && Array.isArray(value) ? callName(syn, path.slice(1)) : undefined;
@@ -755,7 +1031,8 @@ function shapeOf(syn: Compiled, doc: unknown): Shape {
 
 function levelOf(syn: Compiled, doc: unknown): number {
   const shape = shapeOf(syn, doc);
-  return shape.tag === "op" ? shape.op.prec : Number.POSITIVE_INFINITY;
+  // A document with a name binds more loosely than each operator, thus it needs parentheses as a term.
+  return shape.tag === "op" ? shape.op.prec : shape.tag === "bind" ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
 }
 
 /** This function tells if a term needs parentheses in its position, so that `parse` reads the same tree. */
@@ -789,20 +1066,46 @@ function printNode(syn: Compiled, doc: unknown, sub: SubText): Result<string> {
   if (shape.tag === "text") return ok(shape.text);
   if (shape.tag === "none") return fail("#VALUE!", shape.reason);
   if (shape.tag === "op") return opText(syn, shape.op, shape.terms, sub);
+  if (shape.tag === "bind") {
+    // The document after a header name takes a document, thus a data envelope of a literal is the bare literal (K159).
+    const head = wrappedShape(syn, shape.doc);
+    const inner = head === undefined ? printNode(syn, shape.doc, sub) : head.tag === "text" ? ok(head.text) : fail("#VALUE!", WRAPPED);
+    return inner.ok ? ok(`${NAME.test(shape.name) ? shape.name : quoteName(shape.name)} ${syn.bind as string} ${inner.value}`) : inner;
+  }
+  if (shape.tag === "path") {
+    const texts: string[] = [];
+    for (const segment of shape.segments) {
+      if (typeof segment === "string") {
+        texts.push(segment);
+        continue;
+      }
+      const result = sub(segment[1], [segment[0]]);
+      if (!result.ok) return result;
+      texts.push(`(${result.value})`);
+    }
+    return ok(texts.join("."));
+  }
   const texts: string[] = [];
-  for (const [key, arg] of shape.args) {
-    const result = sub(arg, [key]);
+  for (const [key, arg, wrapped] of shape.args) {
+    const result = sub(arg, [key], wrapped);
     if (!result.ok) return result;
-    texts.push(result.value);
+    texts.push(shape.named === true ? `${NAME.test(String(key)) ? String(key) : quoteName(String(key))}: ${result.value}` : result.value);
   }
   return ok(`${shape.name}(${texts.join(`${syn.separator} `)})`);
 }
 
 function printTree(syn: Compiled, doc: unknown, place: readonly Key[]): Result<string> {
-  const result = printNode(syn, doc, (child, path) => printTree(syn, child, [...place, ...path]));
+  const result = printNode(syn, doc, (child, path, wrapped) => (wrapped === true ? printPlace : printTree)(syn, child, [...place, ...path]));
   return result.ok || result.error.place !== undefined ? result : fail(result.error.code, result.error.reason, { place });
 }
 
+/** This function writes a document in a place that takes a document, for example the whole text (K159). */
+function printPlace(syn: Compiled, doc: unknown, place: readonly Key[]): Result<string> {
+  const shape = wrappedShape(syn, doc);
+  if (shape === undefined) return printTree(syn, doc, place);
+  return shape.tag === "text" ? ok(shape.text) : fail("#VALUE!", WRAPPED, { place });
+}
+
 /**
  * This function writes a document as text with the rules of a profile (SYNTAX.PRINT). It writes the fewest
  * parentheses that keep the tree. `parse` reads the text back to the same document (SYNTAX.ROUNDTRIP).
@@ -815,7 +1118,7 @@ function printTree(syn: Compiled, doc: unknown, place: readonly Key[]): Result<s
 export function print(profile: SyntaxProfile, doc: unknown): Result<string> {
   const syn = compileProfile(profile);
   try {
-    return printTree(syn, doc, []);
+    return printPlace(syn, doc, []);
   } catch (error) {
     if (isStackOverflow(error)) return fail("#DEPTH!", "The document is too deep for the stack of the host.", { cause: error });
     throw error;
@@ -834,7 +1137,9 @@ export function syntaxFormat(profile: SyntaxProfile): MachinePart {
   const syn = compileProfile(profile);
   const code: EvalFn = ({ doc, parts, place }) => {
     const byPath = new Map<string, Part>(parts.map((part) => [JSON.stringify(part.path), part]));
-    return printNode(syn, doc, (child, path) => {
+    return printNode(syn, doc, (child, path, wrapped) => {
+      const own = wrapped === true ? wrappedShape(syn, child) : undefined;
+      if (own !== undefined) return own.tag === "text" ? ok(own.text) : fail("#VALUE!", WRAPPED, { place: [...place, ...path] });
       const part = byPath.get(JSON.stringify(path));
       if (part === undefined) return printTree(syn, child, [...place, ...path]);
       const result = part.evaluate();