Standard metadata spec

[evincarofautumn]

Just getting down some thoughts on standard metadata keys in about blocks.

Currently, metadata keys used by the compiler are mixed with user-defined keys, which could be problematic if the user makes a typo or if a previously unused key becomes significant to the compiler. So I’d like to put all keys relevant to the compiler under a kitten key, and generate warnings for keys that the compiler doesn’t understand.

At the moment, the only key actually used by the compiler is operator: [left|right] [0-9] (default 6), which defines operator associativity and precedence. I’d like to have keys for the following things:

docs

Standard documentation in Markdown format. People should be able to use alternative documentation generators with different formats, but this will be the standard one for common vocabulary docs on the Kitten site.

optimizations

Per-definition optimisation flags, such as: inline (never, avoid, auto, prefer, always), cold (called rarely), hot (called frequently), const (does not examine values except arguments, has no effects except return value, even if it uses permissions that would normally disallow this such as +IO), pure (like const but can additionally depend on globals) flatten (inline all calls within definition), omit_frame (omit frame pointer), leaf (returns only by return, does not invoke callbacks), no_return (cannot return).

version

Flags to assist with library versioning, such as version, deprecated, warning, error, used, and unused.

laws

Laws suitable as rewrite rules for optimisation, such as commutative (e.g., x + y = y + x, +Read<H1> commutes with +Read<H2>, +Read<H1> commutes with +Write<H2> if H1 ≠ H2), associative (e.g., (a + b) + c = a + (b + c)), distributive (e.g. + distributes over * and vice versa), and idempotent (e.g., x abs abs = x abs, x && x = x).

display

Metadata about presentation and editing modes of source code in the future visual editor. I don’t fully know what we’ll need yet, but I know I want to include a “display mode” setting: table for dataflow table notation, math for mathematical typesetting, or text for ordinary source code. I don’t want to include things like layout information, which will just clutter up source files that have been edited with the visual editor—layout should be entirely automatic and predictable, depending on a few metadata keys at most, with no inline annotations. Some examples follow.

Input:

define repl<A, B> (-> +IO):
  get_line
  if (dup (<> "quit")):
    eval say
    loop
  else:
    "Bye!" say

Output with table display mode:

┌─[ repl ]──────────────────────┐
│ ┌───────────────────────────┐ │
│ │          get_line         │ │
│ ├───────────────────────────┤ │
│ │            dup            │ │
│ │      ┌────────────────────┤ │
│ │      │    (<> "quit")     │ │
│ ├──────┴────────────────────┤ │
│ │            if             │ │
│ │ ┌─[ true ]─┬─[ false ]──┐ │ │
│ │ │          │            │ │ │
│ │ │    │     │            │ │ │
│ │ │ ┌──┴───┐ │ ┌────────┐ │ │ │
│ │ │ │ eval │ │ │ "Bye!" │ │ │ │
│ │ │ ├──────┤ │ ├────────┤ │ │ │
│ │ │ │ say  │ │ │  say   │ │ │ │
│ │ │ └──────┘ │ └────────┘ │ │ │
│ │ │ ┌──────┐ │            │ │ │
│ │ │ │ loop │ │            │ │ │
│ │ │ └──┬───┘ │            │ │ │
│ │ │    │     │            │ │ │
│ │ │   repl   │            │ │ │
│ │ └──────────┴────────────┘ │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

Input:

define quadratic (Float64, Float64, Float64 -> Float64, Float64):
  -> a, b, c;
  (b ^ 2 - 4 * a * c) sqrt -> d;
  ((b neg + d) / (2 * a)) ((b neg - d) / (2 * a))

Output with math display mode:

define quadratic (Float64, Float64, Float64 → Float64, Float64):

→ a, b, c;

√(b² − 4 × a × c) → d;

((−b + d) ÷ (2 × a)) ((−b − d) ÷ (2 × a))

Or something more like this MathJAX version with proper fractions instead of ÷.