@graffiticode/basis 1.6.1 → 1.6.3

package/spec/spec.md

@@ -1,8 +1,8 @@
 # Graffiticode Core Language Specification
 
 ```
-Version: 0.1.0
-Date: 2025-04-30
+Version: 0.1.2
+Date: 2026-01-26
 ```
 
 # Introduction
@@ -44,6 +44,8 @@ Function application is written in prefix style:
 add 1 2
 ```
 
+Functions have fixed arity, so applications can be parsed unambiguously without grouping syntax. For example, `add 1 mul 2 3` parses as `add(1, mul(2, 3))` because the parser knows `add` takes 2 arguments and `mul` takes 2 arguments.
+
 Parentheses are used to defer application:
 ```
 map (double) [1 2 3]
@@ -55,10 +57,53 @@ map (double) [1 2 3]
 ```
 
 ### Records
+
+Records may use **shorthand syntax** for fields where the value is a reference to a variable of the same name.
+
+```gc
+let foo = 10..
+{foo}         | equivalent to {foo: 10}
+```
+
+This provides a concise way to construct records using in-scope variable names as field keys and values.
+
+You can also mix shorthand and explicit fields:
+
+```gc
+let x = 1..
+let y = 2..
+{x y z: 3}    | equivalent to {x: 1, y: 2, z: 3}
 ```
+
+```gc
 { name: "Alice", age: 30 }
 ```
 
+### Tags
+
+A **tag value** is an arity-0 symbolic value used to represent symbolic variants in pattern matching or other symbolic forms.
+
+Tag values are **only defined** by using record shorthand syntax. For example:
+
+```gc
+{red blue green}   | defines the tag values red, blue, and green
+```
+
+Tag values:
+
+- Must be introduced via record shorthand notation
+- Are resolved as symbolic constants with identity semantics
+- Match directly in `case` expressions:
+
+```
+let color = get "red" {red blue green}
+case color of
+  red: "warm"
+  blue: "cool"
+  _: "other"
+end
+```
+
 ### Lambdas
 ```
 <x: add x 1>
@@ -76,6 +121,7 @@ let double = <x: mul 2 x>..
 ## Pattern Matching
 
 Pattern matching is done using `case`:
+
 ```
 case x of
   0: "zero"
@@ -92,29 +138,126 @@ Supports:
 
 Pattern matching on function arguments is disallowed.
 
-### Tag Values
+# Type System
+
+Graffiticode includes a implicit structural type system. Every expression has
+a statically inferred type, and type errors are detected at compile time.
+Explicit type annotations are not included in the grammar.
+
+## Primitive Types
 
-A **tag value** is an arity-0 symbolic value that can be used in pattern matching or to encode variant types.
+- `number` – Represents integers or floating-point numbers.
+- `string` – Represents UTF-8 strings.
+- `bool` – Represents Boolean values: `true` and `false`.
+- `json` – Represents any JSON-compatible value (opaque, untyped).
+- `any` – Used internally to denote an unconstrained type (e.g., during inference).
 
+## Composite Types
+
+- **Lists** – Written as `[T]` where `T` is any type.
+  ```
+  [string]       | list of strings
+  [number]       | list of numbers
+  [[bool]]       | list of lists of booleans
+  ```
+
+- **Records** – Key-value maps with known keys and types.
+  ```
+  { name: string, age: number }
+  ```
+  
+- **Tuples** – Ordered, fixed-length collections with heterogeneous types.
+  ```
+  (number, string, bool)
+  ```
+
+## Function Types
+
+Functions are written using Graffiticode lambda signature syntax:
 ```
-red
+<number number: number>   | function taking two numbers and returning a number
+<string: [string]>        | function taking a string and returning a list of strings
+<list record: record>     | common signature for structural transformation
 ```
 
-Tag values:
+Function types are curried by default. That means:
+```
+<number number: number>
+```
+is equivalent to a function that returns another function:
+```
+<number: <number: number>>
+```
 
-- Are unbound identifiers that appear in expression position.
-- May optionally be introduced via implicit enum definitions.
-- Match directly in `case` expressions:
+## Tag Sets and Tag Value Type
+
+Tag values are symbolic constants introduced using record shorthand syntax. They have a default type of `tag`, and their identity is preserved across bindings.
+
+### Tag Identity and Type
+
+Tag values are symbolic constants identified **solely by their name**. The same tag name (e.g., `A`) refers to the same symbolic value, regardless of where it is defined.
+
+Tag values compare equal by name. For example, `A` in `{A B}` and `A` in `{A C}` are equal.
+
+### Tag Sets as Structural Types
+
+Although tag values are globally identified by name, the **type system tracks which tags are expected to co-occur**.
+
+For example, `{A B}` and `{A C}` are different types:
 
 ```
-case color of
+{A B}    | type: { A: tag, B: tag }
+{A C}    | type: { A: tag, C: tag }
+```
+
+This allows the type system to constrain the expected context for pattern matching, record shapes, or enum-style uses of tags.
+
+Using tags not part of the expected set results in a type error.
+
+### Default Type: `tag`
+
+By default, a tag value has the type:
+
+```gc
+tag
+```
+
+When tags are introduced with:
+
+```
+{A B C}
+```
+
+the resulting type is:
+
+```
+{ A: tag, B: tag, C: tag }
+```
+
+This allows for composition and safe comparison.
+
+### Example
+
+```gc
+let colors = {red blue green}..
+case red of
   red: "warm"
   blue: "cool"
   _: "other"
 end
 ```
 
-Tags are resolved as special constants with symbolic identity. They are case-sensitive and may be compared for equality using regular pattern match semantics.
+In this case, `red`, `blue`, and `green` are all of type `tag`, and `case` matches by identity.
+
+## Example: Annotated Definitions
+
+```gc
+let inc = <x: add x 1>  | type: <number: number>
+let greet = <name: concat ["Hello, " name]>  | type: <string: string>
+let zip = <xs ys: zipLists xs ys>  | type: <[T] [U]: [(T, U)]>
+```
+
+(Note: actual Graffiticode does not use type annotations in `let` bindings; types are inferred.)
 
 # Semantics
 
@@ -173,6 +316,7 @@ This approach draws inspiration from **Model-View-Update** (MVU) architectures,
 | `get` | `<string record: any>` | Retrieves a value from a record by key |
 | `hd` | `<list: any>` | First item of list |
 | `isEmpty` | `<list: bool>` | Returns true if the list is empty |
+| `log` | `<any: any>` | Logs the value to console and returns it (identity function) |
 | `map` | `<function list: list>` | Applies function to each item |
 | `max` | `<number number: number>` | Returns the larger of two numbers |
 | `min` | `<number number: number>` | Returns the smaller of two numbers |
@@ -266,6 +410,15 @@ Return true if list is empty, otherwise return false
 isEmpty []  | returns true
 ```
 
+### log
+
+Log a value to the console and return the value unchanged
+
+```
+log "Hello"  | prints "Hello" to console and returns "Hello"
+log (add 1 2)  | prints 3 to console and returns 3
+```
+
 ### map
 
 Apply a function to each element

package/src/compiler.js

@@ -73,6 +73,7 @@ class Visitor {
     case "STR":
     case "IDENT":
     case "BOOL":
+    case "TAG":
       elts[0] = n.elts[0];
       break;
     default:
@@ -173,6 +174,11 @@ export class Checker extends Visitor {
     const val = node;
     resume(err, val);
   }
+  TAG(node, options, resume) {
+    const err = [];
+    const val = node;
+    resume(err, val);
+  }
   STR(node, options, resume) {
     const err = [];
     const val = node.elts[0];
@@ -506,6 +512,13 @@ export class Checker extends Visitor {
       resume(err, val);
     });
   }
+  LOG(node, options, resume) {
+    this.visit(node.elts[0], options, (err1, val1) => {
+      const err = [].concat(err1);
+      const val = node;
+      resume(err, val);
+    });
+  }
 }
 
 function enterEnv(ctx, name, paramc) {
@@ -602,7 +615,7 @@ export class Transformer extends Visitor {
       }
       const patternNid = this.internPattern(pattern);
       if (patternNid === this.internPattern(node) ||
-          patternNid === this.internPattern(newNode('_', []))) {
+          patternNid === this.internPattern(newNode('TAG', ['_']))) {
         return true;
       }
       if (pattern.tag === node.tag) {
@@ -641,8 +654,9 @@ export class Transformer extends Visitor {
     return matches;
   }
   CATCH_ALL(node, options, resume) {
+    // Fallback for unknown node types.
     const err = [];
-    const val = node;  // Use the node as the tag value.
+    const val = node;
     resume(err, val);
   }
   PROG(node, options, resume) {
@@ -735,6 +749,11 @@ export class Transformer extends Visitor {
     const val = word?.val !== undefined ? word.val : node.elts[0];
     resume(err, val);
   }
+  TAG(node, options, resume) {
+    const err = [];
+    const val = { tag: node.elts[0] };
+    resume(err, val);
+  }
   STR(node, options, resume) {
     const err = [];
     const val = node.elts[0];
@@ -820,6 +839,10 @@ export class Transformer extends Visitor {
       const ndx = [];
       for (let elt of node.elts) {
         this.visit(elt, options, (e0, v0) => {
+          console.log(
+            "RECORD()",
+            "v0=" + JSON.stringify(v0, null, 2),
+          );
           err = err.concat(e0);
           ndx[elt] = v0;
           if (++len === node.elts.length) {
@@ -1028,7 +1051,8 @@ export class Transformer extends Visitor {
       const val = `${v0}`;
       const expr = (
         v0 === null && {tag: "NUL", elts: []} ||
-        v0.tag !== undefined && v0 ||   // We've got a tag value.
+        v0?.tag !== undefined && !v0.elts && {tag: "TAG", elts: [v0.tag]} ||
+        v0?.tag !== undefined && v0 ||   // Already an AST node.
         type === "boolean" && {tag: "BOOL", elts: [val]} ||
         type === "number" && {tag: "NUM", elts: [val]} ||
         {tag: "STR", elts: [val]}
@@ -1364,6 +1388,19 @@ export class Transformer extends Visitor {
       }
     });
   }
+  LOG(node, options, resume) {
+    this.visit(node.elts[0], options, (e0, v0) => {
+      const err = [].concat(e0);
+      try {
+        // Log the value to the console
+        console.log(`LOG: ${v0}`);
+        // Return the value unchanged (identity function)
+        resume(err, v0);
+      } catch (e) {
+        resume([...err, `Error in LOG operation: ${e.message}`], null);
+      }
+    });
+  }
 }
 
 export class Renderer {

package/src/lexicon.js

@@ -3,256 +3,256 @@ export const lexicon = {
     "tk": 1,
     "name": "PRINT",
     "cls": "function",
-    "length": 1,
     "arity": 1,
+    "type": "<any: record>",
     "description": "Outputs a value to the form."
   },
   "get": {
     "tk": 1,
     "name": "GET",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<integer record|list: any>",
     "description": "Retrieves a value from a record or list by key or index."
   },
   "set": {
     "tk": 1,
     "name": "SET",
     "cls": "function",
-    "length": 3,
     "arity": 3,
+    "type": "<integer any record|list: record|list>",
     "description": "Returns a new record or list with the specified key or index updated."
   },
   "nth": {
     "tk": 1,
     "name": "NTH",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<integer list: any>",
     "description": "Returns the nth element of a list by index."
   },
   "sub": {
     "tk": 1,
     "name": "SUB",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Subtracts the second number from the first."
   },
   "filter": {
     "tk": 1,
     "name": "FILTER",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<lambda list: list>",
     "description": "Returns a list of elements that match a predicate."
   },
   "reduce": {
     "tk": 1,
     "name": "REDUCE",
     "cls": "function",
-    "length": 3,
     "arity": 3,
+    "type": "<lambda any list: any>",
     "description": "Reduces a list to a single value using a binary function and initial value."
   },
   "map": {
     "tk": 1,
     "name": "MAP",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<lambda list: list>",
     "description": "Applies a function to each element in a list and returns a new list."
   },
   "lt": {
     "tk": 1,
     "name": "LT",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: boolean>",
     "description": "Returns true if the first value is less than the second."
   },
   "le": {
     "tk": 1,
     "name": "LE",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: boolean>",
     "description": "Returns true if the first value is less than or equal to the second."
   },
   "gt": {
     "tk": 1,
     "name": "GT",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: boolean>",
     "description": "Returns true if the first value is greater than the second."
   },
   "ge": {
     "tk": 1,
     "name": "GE",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: boolean>",
     "description": "Returns true if the first value is greater than or equal to the second."
   },
   "ne": {
     "tk": 1,
     "name": "NE",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: boolean>",
     "description": "Returns true if the two values are not equal."
   },
   "len": {
     "tk": 1,
     "name": "LEN",
     "cls": "function",
-    "length": 1,
     "arity": 1,
+    "type": "<list|string: integer>",
     "description": "Returns the length of a list or string."
   },
   "concat": {
     "tk": 1,
     "name": "CONCAT",
     "cls": "function",
-    "length": 1,
     "arity": 1,
+    "type": "<list: list|string>",
     "description": "Concatenates a list of strings or nested lists."
   },
   "add": {
     "tk": 1,
     "name": "ADD",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Adds two numbers."
   },
   "mul": {
     "tk": 1,
     "name": "MUL",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Multiplies two numbers."
   },
   "pow": {
     "tk": 1,
     "name": "POW",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Raises the first number to the power of the second."
   },
   "apply": {
     "tk": 1,
     "name": "APPLY",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Applies a function to a list of arguments."
   },
   "data": {
     "tk": 1,
     "name": "DATA",
     "cls": "function",
-    "length": 1,
     "arity": 1,
-    "description": "Returns the raw data payload from a structured input."
+    "type": "<record: record>",
+    "description": "Returns the data from the upstream task, or the argument value if no input exists."
   },
   "json": {
     "tk": 1,
     "name": "JSON",
     "cls": "function",
-    "length": 1,
     "arity": 1,
-    "description": "Parses a string as JSON or serializes a value to JSON."
+    "type": "<string: any>",
+    "description": "Parses a string as JSON."
   },
   "eq": {
     "tk": 1,
     "name": "EQ",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: boolean>",
     "description": "Returns true if the two values are equal."
   },
   "mod": {
     "tk": 1,
     "name": "MOD",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: integer>",
     "description": "Returns the remainder of dividing the first number by the second."
   },
   "min": {
     "tk": 1,
     "name": "MIN",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Returns the smaller of two values."
   },
   "max": {
     "tk": 1,
     "name": "MAX",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<number number: number>",
     "description": "Returns the larger of two values."
   },
   "range": {
     "tk": 1,
     "name": "RANGE",
     "cls": "function",
-    "length": 3,
     "arity": 3,
+    "type": "<number number number: list>",
     "description": "Generates a list of numbers from start to end using a step."
   },
   "not": {
     "tk": 1,
     "name": "NOT",
     "cls": "function",
-    "length": 1,
     "arity": 1,
+    "type": "<boolean: boolean>",
     "description": "Returns the logical negation of a boolean value."
   },
   "equiv": {
     "tk": 1,
     "name": "EQUIV",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<any any: boolean>",
     "description": "Returns true if the two values are semantically equivalent."
   },
   "or": {
     "tk": 1,
     "name": "OR",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<boolean boolean: boolean>",
     "description": "Returns true if at least one of the two values is true."
   },
   "and": {
     "tk": 1,
     "name": "AND",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<boolean boolean: boolean>",
     "description": "Returns true if both values are true."
   },
   "hd": {
     "tk": 1,
     "name": "HD",
     "cls": "function",
-    "length": 1,
     "arity": 1,
+    "type": "<list: any>",
     "description": "Returns the first element of a list."
   },
   "tl": {
     "tk": 1,
     "name": "TL",
     "cls": "function",
-    "length": 1,
     "arity": 1,
+    "type": "<list: list>",
     "description": "Returns the list without its first element."
   },
   "cons": {
@@ -261,14 +261,23 @@ export const lexicon = {
     "cls": "function",
     "length": 2,
     "arity": 2,
+    "type": "<any list: list>",
     "description": "Prepends an element to the front of a list."
   },
   "append": {
     "tk": 1,
     "name": "APPEND",
     "cls": "function",
-    "length": 2,
     "arity": 2,
+    "type": "<any list: list>",
     "description": "Appends an element to the end of a list."
+  },
+  "log": {
+    "tk": 1,
+    "name": "LOG",
+    "cls": "function",
+    "arity": 1,
+    "type": "<any: any>",
+    "description": "Logs the value to the console and returns the value (identity function)."
   }
 };