@fraczak/k 6.7.0 → 6.9.0

package/DOCS/REPL.md

@@ -33,29 +33,23 @@ complete.
 | Command | Meaning |
 | --- | --- |
 | `:help` | Show command summary |
-| `:type name = <...>` | Define a type alias |
 | `:type name` | Show the canonical definition of a type |
 | `:code name` | Alias for `:C name` |
-| `:rel name = expr` | Define a relation alias |
-| `:def name = expr` | Alias for `:rel` |
 | `:run expr` | Evaluate `expr` on the current value |
 | `:eval expr` | Alias for `:run` |
 | `:time expr` | Evaluate `expr` and report compilation and execution time |
-| `:timing [on\|off]` | Toggle compilation and execution timing reporting for all evaluations |
 | `:t name` | Show relation input/output filters |
 | `:d name` | Show relation definition |
 | `:C name` | Show canonical code definition |
 | `:codes` | List type aliases |
 | `:rels` | List relation aliases |
-| `:codec load name\|file` | Load a built-in codec (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file |
-| `:codec define n t b` | Define an inline custom codec: `name type { parse: ..., print: ... }` |
+| `:codec load file` | Load a codec from an ES module file (e.g. `:codec load codecs/int.mjs`) |
 | `:codec unload name` | Unload a registered codec |
 | `:codec list` | List loaded REPL codecs (alias: `:codecs`) |
-| `:input type [codec]` | Read the next line as codec input for a type |
+| `:input <codec.mjs> [text]` | Read next input line or parse inline text using specified codec |
 | `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
 | `:klib file` | Export the active relation closure as a `.klib` library |
 | `:ko file expr` | Export a `.ko` executable with `expr` as main |
-| `:val` | Print current value and JSON form |
 | `:reset` | Reset interpreter state |
 | `:quit` / `:exit` | Exit |
 
@@ -142,9 +136,8 @@ Tab completion covers:
 
 Type aliases also complete in `$name` position inside raw k input.
 
-For codec commands, completion covers `:codec load`, `:codec list`, file paths
-after `:codec load`, type names after `:input`, and loaded codec names
-after the input type.
+For codec commands, completion covers `:codec load`, `:codec unload`, `:codec list`,
+file paths after `:codec load`, and codec names after `:input`.
 
 ## Loading
 
@@ -162,75 +155,73 @@ unless `--no-alias` is used.
 
 ## Codecs
 
-REPL codecs are usually keyed by canonical code hashes. Patterns are not used
-for codec dispatch. A codec may also export `universal = true` to make it
-available for any type selected by `:input`; the parsed value is still validated
-against the requested type before it enters the session.
+A codec is a recipe for translating between external text and enveloped *k* values:
+- `parse(text)`: parses an external string into an enveloped *k* value.
+- `print(value)`: serializes an enveloped *k* value to external string, throwing an `Error` if the value is not representable.
+
+Codecs can define a family of target patterns (e.g. `int` parses/prints single integers as well as lists like `[0,1,2]`).
+
+For printing in the REPL, every value is printed with the standard *k* envelope representation, followed by lines for all loaded codecs that can format it:
+```text
+> 42 int
+{}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+int: 42
+```
 
 For a complete guide to writing a new codec module, see
 [`CODECS.md`](./CODECS.md).
 
-### `:codec load name|file`
+### `:codec load file`
 
-Loads either a built-in codec by name (`int`, `utf8`, `json`, `ieee`, `unit`) or an ES module file. Loading a built-in codec automatically loads its corresponding `.k` definition file if not already present:
-- `int` auto-loads `Examples/arithmetics.k`
-- `ieee` auto-loads `Examples/ieee.k`
-- `utf8`, `json`, `unit` auto-load `Examples/core.k`
+Loads a codec module from an ES module file (e.g. `:codec load codecs/int.mjs`). Codecs are identified by their file name, and export `parse(text)` and `print(value)` functions.
 
-Loading a codec also creates code aliases matching the codec name (e.g. `$ int = @...`, `$ float64 = @...`, `$ utf8 = @...`).
+### `:codec unload name`
 
-An external codec module exports:
+Unloads a previously loaded codec by name (e.g. `:codec unload int.mjs`).
 
-```js
-export const name = "utf8";
-export const codes = ["@..."];
-export function parse(text) { /* text -> Value */ }
-export function print(value) { /* Value -> text */ }
-```
+### `:codec list` (or `:codecs`)
 
-A codec may export `patterns` instead of `codes`; each pattern must be a closed
-property-list pattern that can be canonicalized to a code hash, and that hash is
-recalculated by the REPL. A universal codec exports `universal = true` instead
-of `codes` or `patterns`.
+Lists all currently loaded codecs and their source files.
 
-### `:codec define name type { parse: ..., print: ... }`
+### `:input <codec.mjs> [text]`
 
-Registers a dynamic custom codec directly from the REPL:
+Parses external input using the specified codec file.
 
-```k
-> :type bool = <{} true, {} false>
-> :codec define yn bool ({ parse: (t) => Value.variant(t.trim() === 'yes' ? 'true' : 'false', Value.product({})), print: (v) => v.tag === 'true' ? 'YES' : 'NO' })
-```
-
-### `:codec unload name`
+- **Interactive mode**: `:input <codec.mjs>` switches the REPL prompt to `<codec.mjs>> `, and the next input line is parsed using that codec:
+  ```text
+  > :input json.mjs
+  json.mjs> {"hello": "world"}
+  {...} ?<{...}>
+  json.mjs: {"hello":"world"}
+  ```
 
-Unloads a previously registered codec by name.
+- **One-line mode**: `:input <codec.mjs> <text>` immediately parses `<text>`:
+  ```text
+  > :input int.mjs 42
+  {}|_|0|1|0|1|0|1|+ ?<{} _, ...>
+  int.mjs: 42
 
-### `:input type [codec]`
+  > :input int.mjs [0,1,2]
+  {...} ?<{...}>
+  int.mjs: [0,1,2]
+  ```
 
-Resolves `type` to a canonical code hash, selects the registered codec, and
-consumes the next line verbatim as codec input. `type` may be a type alias, a
-canonical code hash, or an inline type expression such as
-`<{} true, {} false>`. The parsed value is validated against that type before
-becoming the current value.
+Entering `:input` with no arguments displays usage and a list of loaded codecs.
 
 ## Timing and Profiling
 
-### `:time expr`
-
-Evaluates `expr` and reports the elapsed time broken down into compilation
-(type derivation + WebAssembly lowering/compilation) and runtime execution:
+Timing reporting is enabled by default for all evaluations, reporting elapsed time
+broken down into compilation (type derivation + WebAssembly lowering/compilation) and runtime execution:
 
 ```text
-> :time {10 int x, 5 int y} plus
+> {10 int x, 5 int y} plus
 {}|_|1|1|1|1|+ ?<{} _, ...>
 /* comp: 12.4ms, exec: 0.8ms */
 ```
 
-### `:timing [on|off]`
+### `:time expr`
 
-Toggles automatic timing reporting for every snippet or expression evaluated in
-the session.
+Evaluates `expr` with explicit timing and records performance metrics in session state.
 
 ## Web REPL (Studio)
 
@@ -279,11 +270,9 @@ Evaluated values print in k syntax together with the inferred envelope:
 ## Example Session
 
 ```text
-> :type nat = <{} 0, nat +1>
-$ nat = @...
-> :rel inc = |+1
-inc = @...
-> {} |0
+> $ nat = < {} 0, nat +1 >;
+> inc = | +1;
+> {} | 0
 {}|0 ?<{} 0, ...>
 > :t inc
 inc : ?X0  -->  ?<X0 +1, ...>  (@...)

package/Examples/arithmetics.k

@@ -92,6 +92,7 @@ _fromBitList =
 
 --------------------------------------
 $ int = < bits '+', bits '-' >;
+$ ints = <{int car, ints cdr} cons, {} nil>;
 
 remove_leading_zeros = <
   /0 remove_leading_zeros, 

package/Examples/poly.k

@@ -65,3 +65,49 @@ zip = <
     {.xs cdr xs, .ys cdr ys} zip cdr
   } cons
 >;
+
+-- Gen list of intgers: n -> [0, 1, ..., n]
+gen_list = {() n, nil list} gen_list_; 
+gen_list_ = <
+  {.n neg? if, .list then} .then, 
+  {.n dec n, {.n car, .list cdr} cons list} gen_list_
+>;
+
+-- Identity filter on {x, y} when x is greater than y: ?{X x, X y}=Y -> ?Y
+gt? =
+  <
+    {.x/- if1, .y/+ if2, () then} .then,
+    {{.x/- y, .y/- x} GT if, () then} .then,
+    {{.x/+ x, .y/+ y} GT if, () then} .then
+  >
+;
+
+-- Split list into two halves by alternating elements: xs -> {first, second}
+split = {() xs, nil first, nil second} _split;
+_split = <
+  {.xs /nil if, {.first first, .second second} then} .then,
+  {.xs cdr /nil if, {{.xs car car, .first cdr} cons first, .second second} then} .then,
+  {.xs cdr cdr xs, {.xs car car, .first cdr} cons first, {.xs cdr car car, .second cdr} cons second} _split
+>;
+
+-- Merge two sorted lists: {xs, ys} -> list
+merge = <
+  {.xs /nil if, .ys then} .then,
+  {.ys /nil if, .xs then} .then,
+  {
+    {.xs car x, .ys car y} gt? if,
+    {.ys car car, {.xs xs, .ys cdr ys} merge cdr} cons then
+  } .then,
+  {.xs car car, {.xs cdr xs, .ys ys} merge cdr} cons
+>;
+
+-- Sort a list in ascending order (merge sort): xs -> list
+sort = list? <
+  /nil nil,
+  /cons <
+    {.cdr /nil if, .car singleton then} .then,
+    |cons split {.first sort xs, .second sort ys} merge
+  >
+> list?;
+
+

package/TODO.md

@@ -0,0 +1,112 @@
+# Web REPL Improvements & Conceptual Cleanup Plan
+
+This document details the issues, conceptual improvements, and completed enhancements for the `k` Web REPL (`browser/repl-browser.mjs`, `scripts/build-repl-html.mjs`, and `repl.html`).
+
+---
+
+## 1. General Branding & Visual Cleanup
+
+### Removal of `λ` (Lambda) Symbol
+- [x] Remove `<span class="brand-lambda">λ</span>` from the navbar in `scripts/build-repl-html.mjs`.
+- [x] Remove the `.brand-lambda` CSS class.
+- [x] Update welcome banner in `browser/repl-browser.mjs` to `k interactive repl`.
+- [x] Replace `λ` in string codec sample inputs with ASCII/Unicode text samples (e.g. `"abc"`).
+
+---
+
+## 2. Help Modal (`? Help` / `:help`) Overhaul
+
+### Language Overview & Grammar Categorization
+- [x] **Language Overview**: Short, positive, accessible description: `k` is a concise language of types and relations (functions) over tree-like (JSON-like) documents.
+- [x] **Content-Addressed Identity**: Functions and types are identified by their canonical content hash (`@...`) derived directly from their structure; local names are just temporary aliases used for recursion and readability.
+- [x] **Three Clean Grammar Categories**:
+   1. **Definitions (Local Aliases)**:
+     - `name = relExpr;` &mdash; Relation alias (e.g. `swap = { . y x, . x y };`).
+     - `$ name = typeExpr;` &mdash; Type alias (e.g. `$ bool = < {} true, {} false >;`).
+  2. **Type Expressions (`typeExpr`)**: Schemas describing tree-like documents:
+     - `{ Type_1 label_1, ..., Type_k label_k }` &mdash; Product type of arity $k$ (labeled records, e.g. `{float64 x, string n}`; special case: `{}` is the 0-ary product).
+     - `< Type_1 tag_1, ..., Type_k tag_k >` &mdash; Union type of arity $k$ (tagged sum of variants, e.g. `<int ok, string err>`).
+     - `name` / `@hash` &mdash; Type reference.
+  3. **Relation Expressions (`relExpr`)**: Functions transforming an input document to an output document:
+     - `{ rel_1 label_1, ..., rel_k label_k }` &mdash; Product of arity $k$ (evaluates relations into record fields; special case: `{}` evaluates 0 relations, producing empty record `{}`).
+     - `< rel_1, ..., rel_k >` &mdash; Union / ordered choice of arity $k$ (evaluates relations in order until one succeeds).
+     - `( rel_1 ... rel_k )` &mdash; Composition of arity $k$ (sequentially composes relations; special case: `()` is the 0-ary composition denoting identity; parentheses can be omitted when non-empty: `f g`).
+     - `. label` &mdash; Field projection (extracts field `label`).
+     - `/ tag` &mdash; Variant branch projection (extracts payload of variant `tag`).
+     - `| tag` &mdash; Variant constructor (wraps document into variant `tag`).
+     - `$ typeExpr` &mdash; Type constraint (asserts input matches schema; compile-time Type Error on mismatch).
+     - `name` / `@hash` &mdash; Relation reference.
+- [x] **Simplified Intro**:
+  - Made arbitrary arity explicit across products `{...}`, unions `<...>`, and compositions `(...)`; explained `{}` and `()` as the natural 0-ary special cases; omitted the pattern/filter expressions table from the introductory reference.
+- [x] **Replaced Misleading Expressions & Snippets**:
+  - Removed phantom concepts (`10` as literal, "bit-path", `{10 int x, 5 int y} plus` in default state).
+  - Added self-contained snippets (`{} | ok`, `not = < / true | false, / false | true >;`, `$ bool = < {} true, {} false >;`, `not = $ bool < / true | false, {} | true > $ bool;`, `swap = { . y x, . x y };`).
+- [x] **Command Reference Table**:
+  - Added `:time <expr>`.
+  - Removed obsolete commands: `:rel <name> = expr`, `:val`, `:timing [on|off]`, `:codec define n t b`.
+  - Updated `:type <name>` to purely inspect and display type definitions (type definition is native via `$ name = typeExpr;`).
+  - Timing is now always enabled by default across all evaluations.
+  - Updated `:input` documentation to note the interactive browser dialog.
+  - Clarified `:codes` (type aliases/hashes) and `:rels` (relation aliases).
+
+---
+
+## 3. Codecs Modal Overhaul
+
+### Concept Correction: External Format Adapters
+- [x] Reframed codecs as format adapters translating external text to/from $k$ values defined as pairs `(filter, tree)`.
+- [x] **Type-Specific Codecs**:
+  - `int`: Converts decimal integers to/from `$ int = < bits '+', bits '-' >`.
+  - `ieee`: Converts decimal floats to/from `$ float64` records (`sign`, `exponent`, `fraction`).
+  - `utf8`: Converts text to/from `$ string` (aliased to `$ utf8`), a list of Unicode scalar values (`$ unicode`) partitioned by Unicode planes.
+  - `unit`: Converts to/from `{}`.
+- [x] **Parameterized Codecs**:
+  - `json`: JSON text is untyped; deserializing JSON requires a target $k$ type schema parameter (e.g. `:input {float64 x, string n} json`).
+- [x] **Custom Codec Studio**:
+  - Updated explanation to emphasize pairs `(filter, tree)`.
+  - Fixed `yn` preset to provide self-contained type definition `$ bool = < {} true, {} false >;`.
+  - Fixed `blank` preset with proper Value payload formatting.
+
+---
+
+## 4. 'Input' Modal Overhaul
+
+- [x] **Parameterized Codec Support**:
+  - Converted "Target Type" control into an editable combobox / text input with datalist autocomplete for known aliases, while allowing arbitrary composite type expressions (`{float64 x, string n}`, `<int ok, string err>`).
+  - Integrated `resolveInputTypeHash(state, rawType)` into live validation and modal submit.
+  - Marked `json` as a Parameterized Codec requiring a target type schema.
+  - Added composite quick samples demonstrating type + JSON payload pairs (e.g. `{float64 x, string n}` with `{"x":12, "n":"Woj"}`).
+  - Preserved CLI-specified type expressions when opening via `:input <type> [codec]`.
+
+---
+
+## 5. Welcome Banner
+
+- [x] Shortened initial welcome message to just the title line: `k interactive repl`.
+- [x] Removed secondary description and quick link lists to keep the terminal prompt clean and uncluttered.
+
+---
+
+## 6. Curated VFS & Navbar Examples Dropdown
+
+- [x] Added `poly.k` to `verifiedExamples` and `#example-select`.
+- [x] Structured Navbar Examples dropdown into self-contained basic expressions vs. library-dependent workflows.
+- [x] Removed `:val` from example dropdown list.
+- [x] Fixed `() ()` option display text.
+
+---
+
+## 7. Responsive Navbar & Obsolete Command Removal
+
+- [x] **Responsive Navbar on Narrow Screens**:
+  - Changed `.navbar` from fixed `height: 48px;` to `min-height: 48px; height: auto; flex-wrap: wrap; padding: 6px 16px; gap: 8px 12px;`.
+  - Styled `.nav-right` with `flex-wrap: wrap; justify-content: flex-end; min-width: 0;` so controls wrap smoothly without overflowing or clipping buttons (such as `? Help`).
+  - Added comprehensive responsive media query for narrow screens ($\le 768\text{px}$) with full width wrapping and adaptable control inputs.
+  - Verified via headless Chromium CDP automated tests that `#btn-help` is completely visible and interactable at narrow viewport widths (e.g. 600px).
+- [x] **Removed Obsolete Commands**:
+  - Removed `:rel <name> = expr` and `:def` (relations are defined using native syntax `name = expr;`).
+  - Removed `:type <name> = <...>` definition syntax from `:type` (types are defined using native syntax `$ name = typeExpr;`; `:type <name>` remains for inspecting type definitions).
+  - Removed `:val` completely.
+  - Removed `:timing [on|off]` (timing reporting is now permanently enabled by default for all evaluations; `:time <expr>` remains for explicit timing).
+  - Removed `:codec define n t b` (custom codecs are created using the browser Custom Codec Studio UI or loaded from modules via `:codec load`).
+