@fraczak/k 5.1.1 → 6.0.0

package/DOCS/REPL.md

@@ -0,0 +1,191 @@
+# k Interpreter
+
+## Overview
+
+`repl2.mjs` is the interactive k interpreter. It uses the `.klib` format as
+its internal state: definitions accumulate incrementally, expressions compile
+in the context of the current library state, and the session can be exported as
+either a reusable `.klib` library or an executable `.ko` object.
+
+`k-repl` and `k-repl2` both start this interpreter. The primary interface is
+command-based: commands start with `:`, and raw k input remains available as a
+short form for quick interactive work.
+
+## State Model
+
+```
+┌─────────────────────────────────────────────────┐
+│  codes:   { hash → code definition }            │  ← registered types
+│  rels:    { @hash → typed relation }            │  ← compiled relations
+│  aliases: { name → @hash }                      │  ← human names
+│  value:   current value (with .pattern)         │  ← last result
+│  lastMain: last relation/expression             │  ← default .ko main
+└─────────────────────────────────────────────────┘
+```
+
+- `codes` and `rels` are the live .klib content.
+- `aliases` maps human names to canonical hashes. Redefining a name updates
+  the alias; the old definition remains in `rels` (content-addressed, no conflict).
+- `value` is the current pipeline value, initially `{}`.
+
+## Commands
+
+Each line is a command. Multiline commands can be continued with a trailing
+`\`.
+
+Tab completion is available for command names, file paths in file-taking
+commands such as `:load` and `:export`, and canonical names that start with
+`@`.
+
+| Command | Description |
+|---------|-------------|
+| `:type name = <...>` | Define a type |
+| `:rel name = expr` | Define a relation |
+| `:def name = expr` | Alias for `:rel` |
+| `:run expr` | Run an expression on the current value |
+| `:t name` | Show type signature of a relation |
+| `:d name` | Show definition of a relation |
+| `:type name` | Show definition of a type |
+| `:codes` | List type aliases |
+| `:rels` | List relation aliases |
+| `:save file` | Save current state as `.klib` |
+| `:klib file` | Export current state as `.klib` |
+| `:ko file [expr]` | Export executable `.ko`; uses `expr` or the last relation/expression as main |
+| `:export file [expr]` | Export by extension: `.klib` or `.ko` |
+| `:load file` | Load `.k` source or `.klib` into state |
+| `:val` | Print current value with full detail |
+| `:reset` | Clear all state |
+| `:help` | Show available commands |
+| `:quit` | Exit |
+
+The `/` character is never treated as a command prefix, because it is part of
+k expression syntax.
+
+## Shorthand Input
+
+Raw k input is still accepted:
+
+- `$ name = <...>;` is treated like `:type name = <...>`.
+- `name = expr;` is treated like `:rel name = expr`.
+- Any other non-command input is treated like `:run expr`.
+
+For command-based use, semicolons are optional in `:type` and `:rel`.
+
+## Input Handling
+
+### Type Definition: `:type name = <...>`
+
+- Parse and register the code via `codes.register`.
+- Store canonical hash in `aliases[name]`.
+- Print: `$ name = @hash`
+
+### Relation Definition: `:rel name = expr`
+
+- Build source: alias preamble + definition + `name` as main expression.
+- Compile with current `{codes, rels}` as library context.
+- Store compiled rel in `rels[@hash]`.
+- Update `aliases[name] → @hash`.
+- Print: `name = @hash`
+
+### Expression Evaluation: `:run expr`
+
+- Build source: alias preamble + expression as main.
+- Compile with current library context.
+- Run on current `value`.
+- Update `value` with result.
+- Print result with envelope (see Output Format).
+
+## Alias Preamble
+
+Before compiling any user input, the REPL prepends alias definitions so that
+human names resolve to library relations:
+
+```k
+add = @mKEA...; succ = @Swjz...; nat = @w8iS...;
+<user input>
+```
+
+For type aliases, the preamble uses `$ name = @hash;` syntax (referencing
+an existing canonical code by hash).
+
+This reuses the existing parser and compiler without modification.
+
+## Output Format
+
+Values are printed as:
+
+```
+<value-in-k-syntax> ?<pattern-as-filter>
+```
+
+Examples:
+
+```
+> {}|zero|succ|succ
+{succ: {succ: {zero: {}}}} ?<{} zero, X succ>=X
+
+> {{}|1 car, {}|nil cdr}|cons
+{{{}|1 car, {}|nil cdr}|cons} ?<{} nil, {<{} 0, {} 1> car, X cdr} cons>=X
+```
+
+Uses `valueToK` and `propertyListToFilter` from
+`codecs/runtime/show-value.mjs`.
+
+When the result is `undefined`, print:
+
+```
+... undefined
+```
+
+## Loading Files
+
+### `:load file.k`
+
+- Parse and compile the source as a library in the current context.
+- Merge resulting codes and rels into state.
+- Update aliases from `relAlias` (source name → hash).
+
+### `:load file.klib`
+
+- Decode the .klib file.
+- Merge codes and rels into state.
+- Update aliases from `meta` (recover source names from origins).
+
+## Exporting
+
+### `:save file.klib`
+
+- Serialize current `{codes, rels, meta, main: null}` as a .klib.
+- `meta` is built from the alias table (each alias → origin entry).
+
+### `:klib file.klib`
+
+- Alias for saving the current state as a `.klib`.
+
+### `:ko file.ko [expr]`
+
+- Compile `expr` as the executable object's main expression.
+- If `expr` is omitted, reuse the last relation definition or expression that
+  was evaluated in the interpreter.
+- The current `.klib` state is passed as the compilation library context.
+
+### `:export file [expr]`
+
+- If `file` ends in `.klib`, save the current library state.
+- If `file` ends in `.ko`, compile an executable object using `expr` or the
+  last main expression.
+
+## Example
+
+```
+> :type nat = <{} zero, nat succ>
+$ nat = @...
+> :rel succ = |succ
+succ = @...
+> :run succ
+{}|succ ?<{} succ, ...>
+> :klib nat.klib
+saved nat.klib
+> :ko succ.ko succ
+saved succ.ko (succ)
+```

package/DOCS/book/01-introduction.md

@@ -0,0 +1,51 @@
+# Chapter 1 — Introduction
+
+## **1.1  The purpose of this book**
+
+This book describes a small programming language called **k**.
+It is meant to show how data can be represented and transformed in a uniform, precise way.
+
+---
+
+## **1.2 Data as trees**
+
+All information in `k` is treated as a **tree**.
+A tree has:
+
+* a single root,
+* labeled edges (field names or tags),
+* and possibly subtrees.
+
+Both JSON objects and XML documents are trees in this sense.
+Every `k` value is such a finite labeled tree.
+
+---
+
+## **1.3 Functions that may fail**
+
+In ordinary mathematics a function always returns a result.
+In `k`, a function may be **undefined** for some inputs.
+For example, asking for the field `age` in a record that has no `age` is undefined.
+
+We call such mappings **partial functions**.
+
+---
+
+## **1.4 Simplicity over features**
+
+`k` avoids most language constructs: no *variables* and no *control statements*.
+It has only:
+
+1. **types** (which describe tree shapes), and
+2. **partial functions** (which transform one tree into another).
+
+These two ingredients are sufficient and powerful enough to express structured
+computation in a concise and understandable way.
+
+There is another concept in the language, called **filters**.
+Filters play a role in the process of reasoning about types of partial functions.
+Filters have been added to the syntax of the language as they allow explicit annotations
+of "polymorphic" expressions, i.e., expressions which make sense in different contexts.
+Filters are similar to *type classes* in other languages.
+
+---

package/DOCS/book/02-syntax-and-values.md

@@ -0,0 +1,111 @@
+# Chapter 2 — Syntax and Values
+
+## **2.1 Language fragments**
+
+The `k` language has only one kind of program element: a **definition**.
+A program is a sequence of definitions of two kinds:
+
+```k-lang
+$ type_name = ...type_expression... ;
+function_name = ...expression... ;
+```
+
+The definitions are followed in the file by the *main expression*; it represents the partial function defined by the program as a whole.
+
+There is no syntax for values.
+Every syntactic form in an expression describes a **function** -- possibly a constant function that always returns the same value.
+
+---
+
+## **2.2 Types**
+
+A type describes the possible **tree shapes** of values.
+Types are formed from two constructors:
+
+1. **Product**  – written `{ T₁ l₁, T₂ l₂, … }`
+   represents records with fixed labeled fields.
+
+2. **Union**  – written `< T₁ l₁, T₂ l₂, … >`
+   represents a choice between labeled alternatives.
+
+Both are finite and fully explicit.
+Every type denotes a finite tree automaton whose accepted trees are the possible values of that type.
+
+---
+
+## **2.3 Special and limiting cases**
+
+1. **Empty product**
+   `{}` has no fields.
+   It represents the type that admits exactly one value, called *unit*.
+   There is nothing exceptional about the type and its value; it is simply the degenerate case of a product with zero fields.
+
+2. **Empty union**
+   `<>` has no variants.
+   It represents a type with no possible values.
+
+---
+
+## **2.4 Projections**
+
+**Dot** notation, e.g., 
+
+```k
+ . field_name
+```
+
+is used for extracting the value of a field from a record (product type value).
+**Div** notation, e.g., 
+
+```k
+ / variant_name
+```
+
+is used for asserting a particular variant of a union and extracting its value.
+Product type `{ T₁ l₁, T₂ l₂, … , Tₙ lₙ }` naturally defines `n` partial functions: `.l₁, .l₂, … , .lₙ`,  
+and union type `< T₁ l₁, T₂ l₂, … , Tₙ lₙ >` naturally defines `n` partial functions `/l₁, /l₂, … , /lₙ`.
+Those partial functions are called **projections** and they constitute the basis for the definition
+of all other partial functions in the `k` language.
+
+---
+
+## **2.5 Functions**
+
+Expressions combine partial functions using the following operators:
+
+1. **Composition** `(f₁ f₂ …)` — sequential application.
+2. **Union** `< f₁, f₂, … >` — try each in order, first defined wins.
+3. **Product (parallel)** `{ f₁ l₁, f₂ l₂, … }` — apply all to the same input, succeed only if all succeed.
+4. **Variant construction** `| tag` — lift the input as a variant `tag` of a union type.
+
+Parentheses around a composition may be omitted except for the empty composition `()` — the identity function.
+Empty product, `{ }`, defines a constant function (ignoring its input) returning *unit*.
+
+It is important to notice that after the three markers: `dot (.)`, `div (/)`, or `pipe (|)`, there must be a constant label literal. For that reason, it is possible and advised not to leave any blanks after the marker, e.g.:
+
+```k-lang
+  .field /'a-tag' |"strange and long tag name ✅" 
+```
+
+---
+
+## **2.6 Example**
+
+```k-lang
+$ bool = < {} true, {} false >;
+true  = {} |true $ bool;
+false = {} |false $ bool;
+neg = $ bool < /true false, /false true >;
+```
+
+This defines a "two-variant" union type and three functions: two constants and one transformation exchanging the variants.
+
+---
+
+## **2.7 Summary**
+
+* All types describe tree shapes.
+* As type expression, `{}` is the empty product type (with one value, called *unit*).
+* Functions, not values, are the only expressions in `k`.
+
+---

package/DOCS/book/03-types-as-finite-automata.md

@@ -0,0 +1,156 @@
+# Chapter 3 — Types as Finite Automata
+
+## **3.1 Motivation**
+
+A type in `k` describes a set of finite labeled trees, which can be recognized by a finite tree automaton (FTA). Equivalently, a type definition can be seen as a Context-Free Grammar (CFG), where the values of the type are the derivation trees of the grammar.
+
+For example, the recursive type definition of a `list`:
+
+```k-lang
+$ bool = < {} true, {} false >;
+$ list = < {} nil, { bool head, list tail } cons >;
+```
+
+corresponds to the following 4-rule grammar:
+
+```bnf
+1: <bool> ::= {} |true
+2: <bool> ::= {} |false
+3: <list> ::= {} |nil
+4: <list> ::= { <bool> head, <list> tail } |cons
+```
+
+A value of type `list` is a derivation tree of this grammar. For instance, a list containing a single boolean value `true` can be represented by the following derivation:
+
+```
+<list>
+  -- (rule 4) --> { <bool> head, <list> tail } |cons
+                     |            |
+                     |            -- (rule 3) --> {} |nil
+                     |
+                     -- (rule 1) --> {} |true
+```
+
+This derivation tree corresponds to the value generated by constant function: `{ {} |true head, {} |nil tail } |cons`.
+
+Representing types as automata (or CFGs) provides each type with a well-defined structure, independent of the names used in the source code. This allows for canonical normal forms and for comparing types for equality by structure alone.
+
+---
+
+## **3.2 States and Transitions**
+
+Each type definition introduces one or more *states* in the automaton. A union or a product definition corresponds to a state, and the variants or fields correspond to transitions to other states.
+
+For example, consider the `$bool` type:
+
+```k-lang
+$ bool = < {} true, {} false >;
+```
+
+This definition translates to an automaton with two states:
+
+- A root state, let's call it `C0`, representing the `$bool` type itself (a union).
+- A state `C1` representing the empty product `{}`.
+
+From the root state `C0`, there are two transitions:
+
+- A transition labeled `true` to state `C1`.
+- A transition labeled `false` to state `C1`.
+
+`C0` is the root state of the type, and `C1` is a leaf state, representing an empty value.
+
+---
+
+## **3.3 Canonical Form**
+
+Different type expressions can describe the same automaton. For example:
+
+```k-lang
+$ bool = < {} false, {} true >;
+$ pair = { bool x, bool y };
+$ pair2 = { < {} true, {} false > x, bool y };
+```
+
+The types `pair` and `pair2` are structurally equivalent because `$bool` is defined as `< {} true, {} false >`, making the definition of `x` in `pair2` identical to the standalone `$bool` type used in `pair`. Canonicalization is the process of removing these superficial differences by erasing local names and renumbering states to produce a single stable representation for each unique type structure.
+
+The canonical form is generated by traversing the type's graph structure starting from its root state. The process ensures a unique representation by following a consistent ordering:
+
+1. **Start at the Root**: Assign the number `C0` to the root state of the type.
+2. **Explore Neighbors**: Visit all states reachable from `C0`. Sort the transitions alphabetically by their labels (field or variant names) and assign consecutive numbers (`C1`, `C2`, ...) to the destination states in that order.
+3. **Iterate**: Move to the next state in the numbered sequence (`C1`, then `C2`, etc.) and repeat the process for any of its neighbors that have not yet been numbered.
+4. **Complete**: Continue until all reachable states have been assigned a unique number.
+
+This traversal produces a unique and deterministic numbering for any finite directed graph, ensuring that any two structurally identical types will have the exact same canonical representation.
+
+---
+
+## **3.4 Examples**
+
+For a type representing binary natural numbers:
+
+```k-lang
+$ bnat = < bnat 0, bnat 1, {} _ >;
+```
+
+the canonical form is:
+
+```k-lang
+$C0 = < C0 "0", C0 "1", C1 "_" >;
+$C1 = {};
+```
+
+The automaton has two states. `C0` is a recursive state that recognizes sequences of "0"s and "1"s, while `C1` is the terminal state, marked by the "_" transition.
+
+---
+
+## **3.5 Normalization Process**
+
+When compiling a program, the following steps are taken to normalize types:
+
+1. **Collect**: Gather all type definitions from the program.
+2. **Expand**: Recursively replace all named types with their underlying definitions until only products and unions remain.
+3. **Deduplicate**: Eliminate duplicate type structures by comparing them structurally.
+4. **Canonicalize**: Assign stable state numbers to the unique types to produce their canonical text representation.
+
+This process is deterministic, ensuring that the same type structure always produces the exact same canonical form.
+
+---
+
+## **3.6 Hash-Based Naming**
+
+To create a globally unique and stable identifier for each type, the compiler computes a hash of its canonical representation. This hash becomes the official, unambiguous name of the type.
+
+For example:
+
+```text
+Canonical Form: $C0=<C0"0",C0"1",C1"_">;$C1={}
+      ↓
+     Hash
+      ↓
+Identifier: @VtPHxGf5GNMzzyVFxtv7gegFfJRYapBGtCeyV56bs5Zb
+```
+
+Program objects can then refer to types by their hash-based identifiers (prefixed with `@`) without ambiguity.
+
+---
+
+## **3.7 Interpretation**
+
+The canonical representation of a type can be interpreted as:
+
+- A finite set of states, `C0…Cn`.
+- Each state is either a product (a record with named fields) or a union (a set of variants).
+- Transitions between states are labeled with strings (field or variant names).
+
+Every value of a given type is a finite tree that is accepted by this automaton.
+
+---
+
+## **3.8 Summary**
+
+- Types in `k` denote sets of finite, labeled trees.
+- Every type can be expressed as a finite tree automaton or a context-free grammar.
+- The canonical form eliminates naming differences, providing a single representation for structurally identical types.
+- Hash-based naming gives each unique type a stable and globally unique identifier.
+
+---

package/DOCS/book/04-partial-functions-and-composition.md

@@ -0,0 +1,146 @@
+# Chapter 4 — Partial Functions and Composition
+
+## **4.1  Partial functions**
+
+A **partial function** is a mapping that may be undefined for some inputs.
+In `k`, every expression denotes such a function.
+If a function is undefined for a given input, the evaluation process halts at that point, producing no result.
+
+There is no notion of error or exception.
+Undefined means simply “no output”.
+
+---
+
+## **4.2  Composition**
+
+Composition combines two or more partial functions sequentially.
+If `f` and `g` are functions, `(f g)` means “apply `f`, then apply `g` to the result”.
+
+A composition `(f g)` is defined on a value `x` if and only if:
+
+* `f` is defined on `x`, and
+* `g` is defined on the result of `f(x)`.
+
+Otherwise, the composition is undefined.
+
+Composition is **associative**:
+
+```math
+(f (g h))  ≡  ((f g) h)
+```
+
+Therefore, parentheses are unnecessary, except for the special case of the **empty composition**, written `()`, which is the identity function:
+
+```math
+() x  =  x () = x
+```
+
+---
+
+## **4.3  Product composition**
+
+Product composition creates a function that applies several subfunctions in parallel to the same input and gathers their results into a product value.
+
+Syntax:
+
+```math
+{ f₁ l₁, f₂ l₂, …, fₙ lₙ }
+```
+
+This expression is defined on an input value if all component functions are defined on that input.
+Its result is a product with fields labeled `l₁ … lₙ`, each containing the result of the corresponding function.
+
+---
+
+## **4.4  Union composition**
+
+Union composition represents concurrent evaluation with fallback:
+
+```k-lang
+< f₁, f₂, …, fₙ >
+```
+
+The result is defined for an input `x` if at least one subfunction is defined.
+Evaluation proceeds left to right; the first defined result is used.
+If none are defined, the result is undefined.
+
+Example:
+
+```k-lang
+< /x, /y >
+```
+
+extracts variant `x` if present; otherwise `y` if present.
+
+---
+
+## **4.5  Constants**
+
+A constant function is one that always returns the same value, regardless of its input.
+Since `k` lacks a direct syntax for literal values, constants are created using functions that produce them.
+
+For example, we can define functions that return `true` and `false`:
+
+```k-lang
+$ bool = < {} true, {} false >;
+true_bool  =  {} |true $bool ;
+false_bool =  {} |false $bool ;
+```
+
+Here, `true_bool` and `false_bool` are constant functions. They are also **total functions**, meaning they are defined for all inputs. Each function ignores its input and produces a fixed boolean value.
+
+---
+
+## **4.6  Projection and Variant Value constructor**
+
+Projection selects a field or a variant from a product or union.
+It is written with a leading dot `.` or a leading slash `/`, respectively:
+
+```k-lang
+.x     // Selects field 'x' from a product: { T x, ... }
+/x     // Extracts the value from a union variant 'x': < T x, ... >
+```
+
+If the input is a product, `.x` returns the value of field `x`. If the input is a union, `/x` returns the value of variant `x`. In all other cases, the projection is undefined.
+
+Variant value constructors for a given union type `T = <T₁ tag₁, T₂ tag₂, … >` are written as `|tag₁`, `|tag₂`, ….
+
+```k-lang
+|tag₁    // lift a value of type T₁ into a value of type T
+```
+
+Projections and variant constructors are the most basic partial functions.
+
+---
+
+## **4.7  Derived combinations**
+
+Complex functions are built by nesting compositions.
+For example:
+
+```k-lang
+{ .x field1, .y |tag field2 }
+```
+
+---
+
+## **4.8  Identity and emptiness**
+
+The empty composition `()` is the identity function.
+The empty union `<>` is the always-undefined function.
+The empty product `{}` is the constant function returning the unit value.
+
+---
+
+## **4.9  Summary**
+
+* In `k`, all expressions denote **partial functions**.
+* An undefined result simply means “no output,” not an error.
+* **Composition** `(f g)` applies functions sequentially and is associative, so parentheses are often optional.
+* The empty composition `()` is the **identity function**.
+* **Product composition** `{...}` runs functions in parallel and gathers their results.
+* **Union composition** `<...>` tries functions in order, returning the first successful result.
+* **Projections** (`.x`, `/x`) are fundamental building blocks for accessing data structures.
+* **Variant constructor** (`|tag`) allows lifting a value into a variant type value.
+
+---