full-spec.ktg

Kintsugi [
  name: 'full-spec
  date: 2026-03-29
  file: %script-spec.ktg
  version: 0.4.0
]

; ============================================================
; Learn Kintsugi in Y Minutes
; ============================================================
;
; Kintsugi is a homoiconic, dynamically-typed programming
; language with rich built-in datatypes, preprocessing,
; and a number of useful facilities powered by DSLs called
; "dialects".
;
; Influenced by REBOL, Red, Ren-C, Common Lisp, D, Python,
; Kotlin, and Raku.
;
; Headers:
;   Kintsugi [...]    - marks a file as an entrypoint (with metadata)
;   (no header)       - module (loaded via import)
;
; The header determines prelude inclusion when compiling.
; Compilation is always explicit via -c flag.
;
; File extensions:
;   .ktg - For all source files.
;
; ============================================================


; ============================================================
; DATATYPES
; ============================================================
; Kintsugi has many built-in datatypes. Every value carries
; its type at runtime. Type names are suffixed with !

; --- Scalars ---

my-int: 42                              ; integer!
negative: -7                            ; integer!
my-float: 3.14                          ; float!
my-pair: 100x200                        ; pair! (2D coordinates)
my-version: 1.2.3                       ; tuple! (versions, colors, IPs)

; --- Logic ---
; true and false are literals. on/off/yes/no are words bound
; to logic values -- available as aliases in normal code, but
; usable as keywords inside dialects without collision.

a: true                                 ; logic!
b: false
c: on                                   ; same as true
d: off                                  ; same as false
e: yes                                  ; same as true
f: no                                   ; same as false

; --- None ---

empty: none                             ; none! (null/nil)

; --- Temporal ---

my-date: 2026-03-15                     ; date!
my-time: 14:30:00                       ; time!

; --- Text ---

my-string: "Hello, world"              ; string!
escaped: "Line one\nLine two"          ; \n is newline escape

; --- Identifiers & Resources ---

my-file: %path/to/file.txt             ; file!
my-url: https://example.com/api        ; url!
my-email: user@example.com             ; email!

; --- Money ---
; money! is a precise numeric type stored as integer cents.
; No float drift -- $0.10 + $0.20 is exactly $0.30.
; Negative money displays with leading minus: -$0.50, -$19.99

my-money: $19.99                        ; money! (1999 cents)
probe $0.00 - $0.50                     ; -$0.50 (sign preserved)

; --- Composite ---

my-block: [1 2 "three" 4.0]            ; block! (the universal container)
nested: [[1 2] [3 4] [5 6]]            ; blocks nest freely
code-as-data: [print "I am data"]      ; code is just a block
my-paren: (1 + 2)                       ; paren! evaluates immediately: 3

; --- Internal types ---
; These are not constructed directly in user code, but
; are returned by type and used internally:
;   native!    -- built-in function
;   op!        -- operator (infix symbol)
;   type!      -- type name value (integer!, string!, etc.)
;   context!   -- mutable key-value scope
;   object! -- frozen object with typed field specs
;   set!       -- unordered unique collection
;   map!       -- hash-based key-value store


; ============================================================
; VARIABLES & WORDS
; ============================================================
; Words are the primary identifiers. A prefix or suffix
; controls how the word evaluates.
;
;   word    - evaluate / lookup
;   word:   - set-word (bind a value)
;   :word   - get-word (get without calling)
;   'word   - lit-word (the symbol itself)
;   @word   - meta-word (lifecycle hooks / metamethods)
;
; The same system applies to paths:
;   path/to          - evaluate / lookup
;   path/to:         - set-path (assign through path)
;   path/:var        - dynamic index (evaluate var, use as index)
;   :path/to         - get-path (get without calling)
;   'path/to         - lit-path (the path as data)

name: "Kintsugi"                        ; set-word  (bind a value)
print name                              ; word      (evaluate / lookup)
ref: :name                              ; get-word  (get without calling)
sym: 'name                              ; lit-word  (the symbol itself)

; Words can contain letters, digits, hyphens, ?, !, _, ~
is-valid?: true
my-variable!: 42

; --- Sigils ---
; Every prefix, suffix, and punctuation character in Kintsugi
; has a fixed meaning. Nothing is arbitrary.
;
; Word prefixes (change how the word evaluates):
;   :    - get-word   (retrieve value without calling)
;   '    - lit-word   (the symbol itself, unevaluated)
;   @    - meta-word  (lifecycle hooks, runtime metadata)
;
; Word suffixes (naming conventions enforced by type):
;   :    - set-word   (bind a value)
;   !    - type name  (integer!, string!, user!, etc.)
;   ?    - predicate  (returns logic! -- empty?, none?, odd?)
;
; Operators:
;   =    - value equality (cross-type for numbers)
;   ==   - strict equality (same type and same value)
;   <>   - not-equal
;
; Other sigils:
;   %    - file path  (%path/to/file.txt)
;   $    - money      ($19.99)
;   /    - path separator or refinement (obj/field, func/refine)


; ============================================================
; EVALUATION MODEL & ARITHMETIC
; ============================================================
; Kintsugi evaluates left to right with no operator precedence.
; Use parens to control evaluation order. Operators are just
; infix functions -- none is special.

x: 10
y: 3
print x + y                             ; 13
print x - y                             ; 7
print x * y                             ; 30
print x % y                             ; 1
print 2 + 3 * 4                         ; 20 (left to right, NOT 14)
print 2 + (3 * 4)                       ; 14 (parens force order)

; --- Division ---
; Division returns integer when exact, float otherwise.
print 10 / 2                            ; 5 (integer! -- exact)
print 10 / 3                            ; 3.333... (float! -- inexact)

; Use round for explicit rounding
print round/down 10 / 3                 ; 3 (truncate toward zero)
print round 3.7                         ; 4 (nearest)
print round/up 3.2                      ; 4 (away from zero)

; --- Comparisons ---

print 5 > 3                             ; true
print 5 < 3                             ; false
print 5 = 5                             ; true
print 5 <> 3                            ; true
print 5 >= 5                            ; true
print 3 <= 5                            ; true

; --- Numeric cross-type ---
print 42 = 42.0                         ; true (= compares by value across types)
print 42 == 42.0                        ; false (== is strict -- requires same type)
print 42 == 42                          ; true (same type, same value)

; --- Logic ---
; and/or are infix operators. They do NOT short-circuit --
; both sides are always evaluated because the evaluator must
; consume the right operand.
; Only false and none are falsy. 0, "", and [] are truthy.

print not 1 = 2                         ; true
print 1 = 1 and 2 = 2                  ; true
print 1 = 2 or 2 = 2                   ; true

; all?/any? -- block-based short-circuit predicates
; all? returns true if every expression is truthy, false otherwise.
; any? returns true if at least one is truthy, false otherwise.
print all? [1 2 3]                      ; true
print all? [1 false 3]                  ; false
print any? [false none 42]             ; true

; --- Money arithmetic ---
print $10.00 + $5.50                    ; $15.50
print $10.00 - $3.25                    ; $6.75
print $10.00 * 3                        ; $30.00
print $10.00 / 4                        ; $2.50
print $10.00 > $5.00                    ; true

; --- Pair arithmetic ---
print 100x200 + 10x20                  ; 110x220
print 100x200 - 10x20                  ; 90x180

; --- String concatenation ---
; Use rejoin to concatenate strings. + on strings is an error.
print rejoin ["hello" " world"]        ; hello world


; ============================================================
; CONTROL FLOW
; ============================================================

; if -- evaluates block when condition is truthy
print if true [42]                      ; 42

; either -- two branches, always returns a value
sign: function [n] [
  either n > 0 [1] [
    either n < 0 [-1] [0]
  ]
]
print sign 5                            ; 1
print sign -3                           ; -1
print sign 0                            ; 0

; unless -- negated if
print unless false ["ran"]              ; ran

; --- Loops ---
; loop is the only looping construct. See LOOP DIALECT below.
; For conditional loops, use loop with if/break:

; "while" pattern
n: 1
factorial: 1
loop [
  if n > 5 [break]
  factorial: factorial * n
  n: n + 1
]
print factorial                         ; 120

; "until" pattern
counter: 0
loop [
  counter: counter + 1
  if counter = 10 [break]
]
print counter                           ; 10


; ============================================================
; FUNCTIONS
; ============================================================
; The spec block inside 'function' is a dialect. Words,
; type blocks, refinements, and return: have special meaning.
;
; Type annotations are enforced at runtime -- passing the
; wrong type raises a type error. A future compiler can
; trust these annotations for static optimization.

; Basic definition
add: function [a b] [a + b]
print add 3 4                           ; 7

; Type constraints (enforced at call time)
add-typed: function [a [integer!] b [integer!] return: [integer!]] [
  a + b
]
print add-typed 3 4                     ; 7
; add-typed "hi" 3                      ; ERROR: a expects integer!, got string!

; Typesets for polymorphism
double: function [value [number!]] [
  value * 2
]
print double 5                          ; 10
print double 2.5                        ; 5.0

; Refinements add optional behavior
greet: function [name [string!] /loud] [
  message: join "Hello, " name
  if loud [message: uppercase message]
  message
]
print greet "world"                       ; Hello, world
print greet/loud "world"                  ; HELLO, WORLD

; Refinements with parameters
format-val: function [val /pad size [integer!]] [
  either pad [
    rejoin [to string! val " (padded to " to string! size ")"]
  ] [
    to string! val
  ]
]
print format-val 42                       ; 42
print format-val/pad 42 10               ; 42 (padded to 10)

; Multiple refinements
announce: function [msg [string!] /loud /prefix tag [string!]] [
  result: msg
  if prefix [result: join tag result]
  if loud [result: uppercase result]
  result
]
print announce "hello"                    ; hello
print announce/loud "hello"               ; HELLO
print announce/prefix "hello" "[!] "      ; [!] hello

; Inactive refinements default to false, params to none
check-ref: function [/active] [active]
print check-ref                           ; false
print check-ref/active                    ; true

; Functions are first-class values
operation: :add                         ; get-word grabs the function value
print operation 3 4                     ; 7

; Higher-order -- pass functions with get-word
print apply :add [3 4]                  ; 7

; Early return
clamp: function [val lo hi] [
  if val < lo [return lo]
  if val > hi [return hi]
  val
]
print clamp 5 1 10                      ; 5
print clamp -3 1 10                     ; 1
print clamp 15 1 10                     ; 10

; Closures capture their defining context
make-adder: function [n] [function [x] [x + n]]
add5: make-adder 5
print add5 10                           ; 15

; function with no parameters
greet-world: function [] [print "Hello, world!"]
greet-world                             ; Hello, world!

; does -- shorthand for function [] [body]
say-hi: does [print "hi"]
say-hi                                  ; hi


; ============================================================
; LOOP DIALECT
; ============================================================
; loop is the only looping construct. The block inside loop
; is a dialect when it starts with 'for' or 'from'.
; Otherwise, the entire block is the body (infinite loop).
;
; Refinements:
;   loop            - side effects only, returns none
;   loop/collect    - gathers body results into a block
;   loop/fold       - accumulates: first var is accumulator
;   loop/partition  - body is predicate; values go into
;                     [truthy falsy] based on result
;
; Dialect keywords:
;   for   - declare iteration variable(s)
;   in    - the data to iterate over
;   from  - counting start value
;   to    - counting end value
;   by    - step value (default 1 or -1 based on direction)
;   when  - guard clause (filter)
;   do    - required before body block
;   it    - implicit variable when for is omitted

; --- Basic iteration ---

loop [for [item] in [1 2 3 4 5] do [print item]]

; Multi-line:
loop [
  for [item] in [6 7 8]
  do [print item]
]

; --- Iterating strings ---
; for/in works on strings too, yielding one character per iteration.
loop [for [c] in "abc" do [print c]]
; a
; b
; c

; --- Counting ---

loop [for [n] from 1 to 5 do [print n]]
; 1
; 2
; 3
; 4
; 5

; Counting with step
loop [from 0 to 10 by 5 do [print it]]
; 0
; 5
; 10

; Counting down (direction inferred)
loop [from 5 to 1 do [print it]]
; 5
; 4
; 3
; 2
; 1

; --- Collecting ---

squares: loop/collect [for [n] from 1 to 5 do [n * n]]
probe squares                           ; 1 4 9 16 25

; --- Filtering ---

evens: loop/collect [
  for [n] in [1 2 3 4 5 6 7 8]
  when [even? n]
  do [n]
]
probe evens                             ; 2 4 6 8

; --- Folding ---

total: loop/fold [for [acc n] from 1 to 10 do [acc + n]]
print total                             ; 55

; --- Partitioning ---

set [evens odds] loop/partition [for [x] from 1 to 8 do [even? x]]
probe evens                             ; 2 4 6 8
probe odds                              ; 1 3 5 7

; --- Break inside loop ---

partial: loop/collect [
  for [x] from 1 to 5 do [
    if x = 4 [break]
    x * 10
  ]
]
probe partial                           ; 10 20 30

; --- Loop variables are scoped ---
; After the loop, iteration variables do not exist in the
; parent scope. This prevents accidental leaks.
; Use loop/fold or loop/collect to get values out.
;   loop [for [i] from 1 to 5 do [i]]
;   print i                             ; ERROR: i has no value


; ============================================================
; MATCH DIALECT
; ============================================================
; Pattern matching with destructuring. First match wins.
;
; Pattern elements:
;   literal    - matches exactly (integers, strings, etc.)
;   bare word  - captures/binds the value at this position
;   type!      - matches any value of that type
;   (expr)     - evaluate expression, match against result
;   'word      - matches the literal word
;   _          - wildcard (matches anything, doesn't bind)
;   when       - guard clause
;   default    - fallback if nothing matched

match [1 2 3] [
  [1 2 3]  [print "got 1 2 3"]
  [1 _ 3]  [print "1, anything, 3"]
  default [print "nothing matched"]
]
; got 1 2 3

; Destructuring
match [10 20] [
  [0 0]   [print "origin"]
  [x 0]   [print rejoin ["x-axis at " x]]
  [0 y]   [print rejoin ["y-axis at " y]]
  [x y]   [print rejoin [x ", " y]]
]
; 10, 20

; Guards
match 25 [
  [n] when [n < 13]  [print "child"]
  [n] when [n < 20]  [print "teenager"]
  [n] when [n < 65]  [print "adult"]
  [_]                [print "senior"]
]
; adult


; ============================================================
; SERIES OPERATIONS
; ============================================================
; Blocks and strings are both "series" types. Many operations
; work on both. Indices are 1-based.

; --- Block operations ---

data: [10 20 30 40 50]

print length data                       ; 5
print empty? []                         ; true
print pick data 3                       ; 30
print first data                        ; 10
print second data                       ; 20
print last data                         ; 50

; Membership and lookup
print has? data 30                      ; true
print find data 30                    ; 3 (1-based)
print has? "hello world" "world"        ; true

; Select -- key-value lookup in flat blocks
config: [width 800 height 600 depth 32]
print select config 'width              ; 800
print select config 'depth              ; 32

; Mutation (blocks are mutable, shared by reference)
buf: [1 2 3]
append buf 4                            ; [1 2 3 4]
insert buf 0 1                          ; insert 0 at position 1
remove buf 1                            ; remove at position 1
print length buf                         ; 4

; Copy creates an independent block
original: [1 2 3]
clone: copy original
append clone 99
print length original                    ; 3 (unaffected)

; Sort mutates in place
nums: [3 1 4 1 5 9 2 6]
sort nums
print first nums                        ; 1
print last nums                         ; 9

; Sort also works on strings (returns a new sorted string)
print sort "hello"                      ; ehllo

; insert and remove on strings return new strings (strings are immutable)
print insert "helo" "l" 4               ; hello
print remove "hello" 2                  ; hllo

; Multiple assignment (block destructuring)
set [a b c] [1 2 3]
print a                                 ; 1
print b                                 ; 2
print c                                 ; 3

; Context destructuring (by name, not position)
ctx: context [name: "Ray" age: 30]
set [name age] ctx
print name                              ; Ray
print age                               ; 30

; @rest captures remaining elements into a block
set [first-item @rest] [10 20 30 40 50]
print first-item                        ; 10
probe rest                              ; [20 30 40 50]

; --- capture: declarative keyword extraction ---
; capture scans a block for keywords defined by meta-words in a schema.
; @name     — greedy: captures everything until next keyword
; @name/N   — exact: captures N values after keyword

parts: capture [source [42] then [it + 1] then [it * 2] retries 3] [
  @source @then @retries
]
print parts/source                      ; [42]
probe parts/then                        ; [[it + 1] [it * 2]]
print parts/retries                     ; 3

; capture enables user-defined dialects — a function that takes
; a block and interprets its keywords:
;
;   entity: function [spec [block!]] [
;     parts: capture spec [@name @hp @attack @defense]
;     ctx: context []
;     ctx/name: parts/name
;     ctx/hp: parts/hp
;     ctx/max-hp: parts/hp
;     ctx
;   ]
;   warrior: entity [name "Warrior" hp 100 attack 15 defense 10]

; Dynamic path indexing -- use :var in a path to evaluate the variable
items: [10 20 30]
i: 2
print items/:i                            ; 20

; Dynamic set-path
items/:i: 99
print items/:i                            ; 99

; Works with nested paths
board: context [cells: [1 2 3]]
pos: 3
print board/cells/:pos                    ; 3

; For computed indices, use pick
print pick items (i + 1)                  ; 30

; Reduce -- evaluate a block, return results as a block
x: 10
result: reduce [x + 1 x * 2 "hello"]
print first result                      ; 11
print second result                     ; 20

; --- String operations ---
; Strings are immutable. Double-quoted. Multiline strings
; use curly braces. Concatenation uses join (two values) or
; rejoin (block of values).

; --- Multiline strings ---

message: {
  Hello,
  This is a multiline string.
  It preserves line breaks.
}

; --- Interpolation via rejoin ---
; rejoin evaluates a block and joins all results into a string.

name: "Ray"
age: 30
print rejoin ["Hello, " name "!"]                ; Hello, Ray!
print rejoin [name " is " age " years old"]      ; Ray is 30 years old
print rejoin ["2 + 2 = " (2 + 2)]               ; 2 + 2 = 4

; rejoin/with — join with a delimiter
print rejoin/with [1 2 3 4 5] ", "              ; 1, 2, 3, 4, 5
print rejoin/with ["a" "b" "c"] " - "           ; a - b - c

; --- String functions ---

print length "hello"                     ; 5
print join "hello" " world"             ; hello world
print trim "  hello  "                  ; hello
print find "hello world" "world"      ; 7
print has? "hello world" "world"        ; true
print split "a,b,c" ","                 ; ["a" "b" "c"]
print uppercase "hello"                 ; HELLO
print lowercase "HELLO"                 ; hello
print replace "hello world" "world" "Ray" ; hello Ray
print replace "aabaa" "a" "x"          ; xxbxx (replace-all by default)

; --- Series operations on strings ---
; first, second, last, pick, find, reverse work on both
; blocks and strings. They are the unified series interface.

print first "hello"                     ; h
print second "hello"                    ; e
print last "hello"                      ; o
print pick "hello" 3                    ; l

; find -- returns 1-based index or none
print find "hello world" "world"        ; 7
print find "hello" "xyz"                ; none
print find [10 20 30] 20               ; 2

; find/where -- first element matching a predicate
print find/where [1 2 3 4 5] function [x] [x > 3]  ; 4

; reverse -- returns new value
print reverse "hello"                   ; olleh
print reverse [1 2 3]                   ; [3 2 1]

; append -- mutates blocks in place. Splices by default.
; Strings are immutable — use rejoin or join to build new strings:
;   rejoin ["hello" " " "world"]   → "hello world"
;   join "hello" " world"          → "hello world"

spec-blk: [1 2]
append spec-blk [3 4]                   ; splice: [1 2 3 4]
append/only spec-blk [5 6]             ; single element: [1 2 3 4 [5 6]]

; subset extracts a range (1-based start, length). Works on strings and blocks.
print subset "hello world" 7 5          ; world
probe subset [10 20 30 40 50] 2 3       ; [20 30 40]

; --- String predicates ---

print starts-with? "hello world" "hello"  ; true
print ends-with? "hello world" "world"    ; true
print starts-with? "hello" "xyz"          ; false

; --- Escape sequences ---
; \n = newline, \" = quote, \\ = backslash, \t = tab

print "line one\nline two"

; --- Padding ---
; pad fills to a width. Left-pad by default, /right for right-pad.
; Works on strings and blocks.

print pad "42" 5 "0"                    ; 00042
print pad/right "hi" 6 "."             ; hi....
probe pad [1 2] 5 0                     ; [0 0 0 1 2]
probe pad/right [1] 4 none              ; [1 none none none]

; --- Character codes ---
; byte: string -> integer (first byte's code)
; char: integer -> string (0-255 range)
print byte "A"                          ; 65
print char 65                           ; A
print char (byte "Z")                   ; Z


; ============================================================
; DATE & TIME FACILITIES
; ============================================================
; now returns the current Unix epoch as integer!.
; time and date are context objects with accessor functions.
;
;   now                  -- integer! (Unix epoch seconds)
;   time/now             -- time! (current local time)
;   date/now             -- date! (current local date)
;   time/hours t         -- integer! (hour component)
;   time/minutes t       -- integer! (minute component)
;   time/seconds t       -- integer! (second component)
;   time/to-seconds t    -- integer! (total seconds since midnight)
;   time/from-epoch n    -- time! (time from epoch seconds)
;   date/from-epoch n    -- date! (date from epoch seconds)
;   date/year d          -- integer! (year component)
;   date/month d         -- integer! (month 1-12)
;   date/day d           -- integer! (day of month)

; Live examples:
epoch: now
print type epoch                        ; integer!

t: time/now
print type t                            ; time!
print time/hours t                      ; (current hour)
print time/minutes t                    ; (current minute)

d: date/now
print type d                            ; date!
print date/year d                       ; (current year)


; ============================================================
; COLLECTIONS: MAP & SET
; ============================================================

; --- Map ---
; map! is a hash-based key-value store for fast lookup.

; Create via make
m: make map! [name: "Ray" age: 30]

; Access via path
print m/name                              ; Ray
print m/age                               ; 30

; Predicates
print has? m "name"                       ; true
print length m                             ; 2

; --- Set & Charset ---
; set! is an unordered unique collection. charset creates a
; set! from a string of characters (custom character classes
; for use in parse).

vowels: charset "aeiou"
consonants: charset "bcdfghjklmnpqrstvwxyz"
alphanumeric: union (charset "abcdefghijklmnopqrstuvwxyz") (charset "0123456789")

; Sets work with parse rules as character classes.
; result: @parse "hello" [some vowels | some consonants]

; union and intersect combine sets
combined: union vowels consonants
; overlap: intersect (charset "abc") (charset "bcd")


; ============================================================
; TYPE SYSTEM
; ============================================================
; Gradual typing. No implicit coercion. Three operations:
;
;   is?  type! value  -- check (returns logic!)
;   to   type! value  -- convert (scalars only, throws on failure)
;   [param [type!]]   -- constrain (in function specs)
;
; Type annotations on function params are enforced at runtime.

; --- @const annotation ---
; @const marks a binding as constant. In Script mode, it behaves
; as a normal assignment. In Lua 5.4, it emits the <const> attribute.
;   @const MAX-SPEED: 100
;   ; In Lua 5.4: local MAX_SPEED <const> = 100
@const MAX-SPEED: 100
print MAX-SPEED                          ; 100

; --- Introspection ---
print type 42                           ; integer!
print type "hello"                      ; string!
print type [1 2 3]                      ; block!

; --- Type predicates ---
; Every type has a predicate (name?), generated from type name.
print integer? 42                       ; true
print float? 3.14                       ; true
print string? "hello"                   ; true
print logic? true                       ; true
print none? none                        ; true
print block? [1 2 3]                    ; true
print pair? 100x200                     ; true
print tuple? 1.2.3                      ; true
print date? 2026-03-15                  ; true
print time? 14:30:00                    ; true
print file? %path/to/file              ; true
print url? https://example.com         ; true
print email? user@example.com          ; true
print money? $19.99                     ; true

; function? returns true for both function! and native!
print function? :add                    ; true
print function? :print                  ; true

; context? and object? check value kind
print context? context [x: 1]          ; true
print object? object [field/optional [x [integer!] 0]]  ; true

; frozen? checks if a value is an object! (frozen)
print frozen? context [x: 1]           ; false
Point: object [field/optional [x [integer!] 0]]
print frozen? :Point                    ; true

; Union predicates
print number? 3.14                      ; true (integer! or float!)
print number? 42                        ; true

; --- Type checking (is?) ---
; is? checks whether a value matches a type. Works with
; built-in types, union types, and custom types.
print is? integer! 42                   ; true
print is? string! 42                    ; false
print is? number! 3.14                  ; true
print is? number! 42                    ; true

; --- Type conversion (to) ---
; to never coerces silently. Every conversion is explicit.
; If it can fail (string parsing), it throws a type error.
print to integer! "42"                  ; 42
print to integer! 3.7                   ; 3 (truncate toward zero)
print to string! 42                     ; 42
print to float! 7                       ; 7.0
print to block! "hello"                 ; ["hello"]

; Numbers and logic don't cross!
; to integer! true                      ; ERROR
; to logic! 0                           ; ERROR

; Word conversions
print to string! 'hello                ; hello
to word! "hello"                        ; => word!
to set-word! "x"                        ; => set-word!
to lit-word! "name"                     ; => lit-word!
to get-word! "name"                     ; => get-word!
to meta-word! "enter"                   ; => meta-word!

; Money conversions
print to money! 42                      ; $42.00
print to money! "19.99"                 ; $19.99
print to integer! $19.99                ; 1999 (cents)
print to float! $19.99                  ; 19.99 (dollars)

; Time conversions
print to integer! 14:30:00             ; 52200 (total seconds)

; Pair/tuple from blocks
print to pair! [10 20]                  ; 10x20

; Logic from string
print to logic! "true"                  ; true
print to logic! "false"                 ; false
; to logic! 0                           ; ERROR

; Logic from none
print to logic! none                    ; false

; --- Math utilities ---
print min 3 7                           ; 3
print max 3 7                           ; 7
print abs -42                           ; 42
print negate 5                          ; -5
print odd? 7                            ; true
print even? 8                           ; true
print sqrt 9                            ; 3.0
print floor 3.7                         ; 3
print ceil 3.2                          ; 4
print pow 2 10                          ; 1024
print log10 100                         ; 2.0

; --- Trig (radians) ---
print sin 0                             ; 0.0
print cos 0                             ; 1.0
print pi                                ; 3.141592653589793
print to-degrees pi                     ; 180.0
print to-radians 180                    ; 3.141592653589793

; --- Random ---
random/seed 42
print random 1.0                        ; (float in [0, 1))
print random/int 100                    ; (integer in [1, 100])
print random/int/range 1 6              ; (integer in [1, 6])
print random/choice [10 20 30]          ; (one of 10, 20, 30)


; ============================================================
; ERROR HANDLING
; ============================================================
; Errors are raised with 'error'. Protected calls with 'try'.
; try returns a context! with path access:
;   result/ok       -- logic! (success or failure)
;   result/value    -- the return value (on success)
;   result/kind     -- lit-word! error kind (on failure)
;   result/message  -- string! error message (on failure)
;   result/data     -- any value attached to the error

; --- Raising errors ---
; error <kind:lit-word> <message:string> <data:any|none>

safe-divide: function [x y] [
  if y = 0 [error 'math "cannot divide by zero" none]
  x / y
]

; --- try (protected call) ---

result: try [safe-divide 10 2]
print result/ok                         ; true
print result/value                      ; 5

result: try [safe-divide 10 0]
print result/ok                         ; false
print result/kind                       ; math
print result/message                    ; cannot divide by zero

; --- Pattern: check and branch on result ---
result: try [safe-divide 10 0]
either result/ok [
  print rejoin ["Got: " result/value]
] [
  print rejoin ["Error: " result/message]
]
; Error: cannot divide by zero

; --- Rethrow ---
; rethrow re-raises an error from a try result context.
; Useful when you catch, inspect, then decide to propagate.

outer: try [
  inner: try [error 'user "boom" none]
  unless inner/ok [
    print rejoin ["caught: " inner/kind]
    rethrow inner
  ]
]
print outer/ok                          ; false
print outer/message                     ; boom

; --- Standard error kinds ---
; 'type       -- wrong type passed to function
; 'arity      -- too few arguments
; 'undefined  -- word has no binding
; 'math       -- division by zero, overflow
; 'range      -- index out of bounds
; 'parse      -- parse failed
; 'load       -- file not found, circular dependency
; 'make       -- required field missing in make
; 'self       -- attempt to rebind self
; 'user       -- raised explicitly by user code

; --- Attempt dialect ---
; Resilient pipelines with error handling.
; Each step receives the previous result as 'it'.
;
; Dialect keywords:
;   source   - initial operation
;   then     - chain step (previous result is 'it')
;   when     - guard (short-circuit to none if falsy)
;   catch    - handle a named error kind
;   retries  - retry count on error
;   fallback - last resort
;
; With source: evaluate source, run pipeline, return result.
; Without source: returns a reusable pipeline function.

result: attempt [
  source ["  Hello, World  "]
  then   [trim it]
  then   [lowercase it]
  then   [split it ", "]
]
print result                            ; ["hello" "world"]

; Reusable pipeline (no source = function)
clean: attempt [
  when [not empty? it]
  then [trim it]
  then [lowercase it]
]
print clean "  HELLO  "                 ; hello

; Error handling in pipelines
result: attempt [
  source [error 'test "fail" none]
  catch 'test ["caught"]
  fallback ["fallback"]
]
print result                            ; caught

; Inside catch/fallback, 'error is bound to the message string
result: attempt [
  source [error 'parse "bad input" none]
  catch 'parse [rejoin ["parse: " error]]
  fallback [rejoin ["other: " error]]
]
print result                            ; parse: bad input

; Retries — retry source N times before giving up
retry-count: 0
result: attempt [
  source [
    retry-count: retry-count + 1
    if retry-count < 3 [error 'test "not ready" none]
    "ok"
  ]
  retries 5
]
print result                            ; ok
print retry-count                       ; 3


; ============================================================
; CONTEXTS & BINDING
; ============================================================
; Contexts are the universal construct. Closures, objects,
; modules, and scopes are all contexts. Runtime type: context!
;
; context! is a mutable scope. object! is a frozen context
; with typed field specs (created by the object dialect).
; freeze converts context! to object! (one-way).
;
; Created by:
;   context [...]  - mutable context
;   function       - parameters and local words
;   object [...]   - frozen object with typed fields (object!)
;   make Object [...]  - mutable instance stamped from object (context!)
;   freeze ctx     - convert context! to object! (one-way)

; context creates a mutable environment
point: context [x: 10 y: 20]
print point/x                           ; 10
print point/y                           ; 20

; Set-path assignment works on context!
point/x: 30
print point/x                           ; 30

; Introspection
print words point                    ; [x y]

; copy/deep -- recursively copies nested blocks and contexts
deep-src: [[1 2] [3 4]]
deep-clone: copy/deep deep-src
append (first deep-clone) 99
print first deep-src                    ; [1 2] (unaffected)
print first deep-clone                  ; [1 2 99] (independent copy)

; --- Write-through scoping ---
; Set-words write to wherever the name exists in the scope chain.
; If the name doesn't exist, it creates a new local binding.
; This means functions and loops can naturally update outer variables.
;
; Context builders (context [...], make map! [...], object [...],
; scope [...]) are isolated -- set-words inside always create local
; entries, never write through.

g-counter: 0
g-tick: does [g-counter: g-counter + 1]
g-tick
g-tick
g-tick
print g-counter                         ; 3

; --- Assignment is by reference ---
; Compound values (blocks, contexts, maps) are shared.
; copy creates an independent value.
a-block: [1 2 3]
b-block: a-block
append b-block 4
print length a-block                     ; 4 (same block!)

c-block: copy a-block
append c-block 5
print length a-block                     ; 4 (independent)
print length c-block                     ; 5

; --- merge ---
; merge creates a new context from two sources. Second overwrites first.
; Skips none values (useful with capture results).
; merge/freeze returns an object! instead of context!.

defaults: context [name: "Unknown" hp: 100 attack: 10]
overrides: context [name: "Warrior" hp: 200]
result: merge defaults overrides
print result/name                       ; Warrior
print result/hp                         ; 200
print result/attack                     ; 10 (not in overrides, kept)

; merge/deep copies blocks and contexts instead of sharing.

; --- @compose ---
; @compose evaluates parens inside a block. If a paren
; result is a block, its contents are SPLICED in (Rebol
; convention). Use /only to insert as a single element.
; /deep recurses into nested blocks.

val: 42
code: @compose [print (val)]             ; => [print 42]
print second code                       ; 42

; Splice vs /only
items: [1 2 3]
probe @compose [before (items) after]         ; [before 1 2 3 after]
probe @compose/only [before (items) after]    ; [before [1 2 3] after]

; /deep -- evaluates parens inside nested blocks too
inner-val: "nested"
deep-code: @compose/deep [outer [(inner-val)] done]
probe second deep-code                  ; [nested]


; ============================================================
; OBJECT DIALECT
; ============================================================
; object defines a frozen object with typed fields and methods.
; make stamps mutable instances (context!) from objects.
; Objects are immutable -- mutation raises 'frozen error.
;
; Convention: objects use PascalCase -- Person, Card,
; Reader. This distinguishes them from regular words.
;
; If you need runtime customization, write a constructor:
;   make-warrior: function [name [string!]] [
;     w: make Unit [name: name class: "warrior"]
;     w/attack: w/attack + 5    ; modify the mutable instance
;     w
;   ]
;
; Field declarations -- three forms:
;
;   field/required [name [type!]]              -- one required field
;   field/optional [name [type!] default]      -- one optional field (default evaluated)
;   fields [                                   -- bulk declaration
;     required [name [type!] ...]
;     optional [name [type!] default ...]
;   ]
;
; Everything after field declarations is the body (methods).
; Methods access the instance via self (lexically bound).

; --- Object with singular field syntax ---

Counter: object [
  field/optional [n [integer!] 0]

  increment: function [] [self/n: self/n + 1]
  value: function [] [self/n]
]

c: make Counter []
c/increment
c/increment
print c/value                           ; 2

; --- Chain operator -> ---
; obj -> method args is equivalent to obj/method args.
; In Lua compilation, obj -> method emits obj:method().
; Chaining: each -> passes the result to the next call.

c2: make Counter []
c2 -> increment
c2 -> increment
c2 -> increment
print c2 -> value                       ; 3

; --- Required fields ---

Person: object [
  field/required [name [string!]]
  field/required [age [integer!]]

  greet: function [] [
    rejoin ["Hi, I'm " self/name " age " self/age]
  ]
  birthday: function [] [
    self/age: self/age + 1
  ]
]

p: make Person [name: "Ray" age: 30]
print p/greet                           ; Hi, I'm Ray age 30
p/birthday
print p/age                             ; 31

; --- Clone from an instance ---
p2: make p [age: 25]
print p2/name                           ; Ray
print p2/age                            ; 25
print p/age                             ; 31 (original unchanged)

; --- Mixed required and defaulted fields ---

Account: object [
  field/required [owner [string!]]
  field/optional [balance [money!] $0.00]

  deposit: function [amount [money!]] [
    self/balance: self/balance + amount
  ]
  summary: function [] [
    rejoin [self/owner ": " self/balance]
  ]
]

acct: make Account [owner: "Ray"]
acct/deposit $100.00
print acct/summary                      ; Ray: $100.00

; Override a default at creation time
acct2: make Account [owner: "Jo" balance: $50.00]
print acct2/summary                     ; Jo: $50.00

; --- Bulk field declaration with fields [...] ---

Enemy: object [
  fields [
    required [
      name [string!]
      pos [pair!]
    ]
    optional [
      hp [integer!] 100
      speed [float!] 40.0
      state [string!] "idle"
    ]
  ]

  damage: function [amount [integer!]] [
    self/hp: self/hp - amount
  ]
]

goblin: make Enemy [name: "Goblin" pos: 10x20]
print goblin/hp                          ; 100 (default)
print goblin/state                       ; idle (default)
goblin/damage 25
print goblin/hp                          ; 75

; --- Auto-generation ---
; When assigned to a set-word, object auto-generates:
;   person!       -- custom type predicate
;   make-person   -- constructor function
;
; Person: object [...] generates person! and make-person.
; make-person takes required field values in declaration order.
;
; is? checks structural compatibility:
;   is? :Person p    ; true if p has all Person fields

; --- No object chains ---
; make is a stamp. No delegation, no inheritance.
; Instances don't know where they came from.
; Compose via embedding:
;
; Damageable: object [
;   field/optional [hp [integer!] 100]
;   damage: function [amount [integer!]] [self/hp: self/hp - amount]
; ]
; Enemy: object [
;   field/required [stats [context!]]
;   field/optional [speed [float!] 40.0]
; ]
; goblin: make Enemy [stats: make Damageable []]
; goblin/stats/damage 10
; goblin/stats/hp                       ; 90

; --- self is bound at make time ---
; self is a regular word pointing to the instance. Each
; instance's methods have their own self. self cannot be
; rebound (self: x is an error inside methods).
; self can be passed to functions: do-something self

; --- Lifecycle hooks ---
; @enter and @exit are meta-words that fire at scope
; boundaries inside any evaluated block.
;
;   @enter [block]  - runs when entering a scope (once)
;   @exit  [block]  - runs when leaving a scope (once, always
;                     runs, even on error -- like finally)
;
; @exit is the primary resource cleanup mechanism.

scope [
  @enter [print "entering scope"]
  @exit  [print "exiting scope"]
  print "inside scope"
]
; entering scope
; inside scope
; exiting scope

; Resource cleanup example:
;   if true [
;     @enter [resource: acquire-lock "database"]
;     @exit  [release-lock resource]
;     result: query resource "SELECT * FROM users"
;     print result
;   ]


; ============================================================
; PARSE DIALECT
; ============================================================
; Rule-based pattern matching on strings and blocks.
; One system, two modes -- same combinators for both.
; The only difference is what "an element" means:
; a character in strings, a value in blocks.
;
; Parse returns a context! with:
;   ok       -- logic! (true if rules matched full input)
;   plus any set-word captures and collect results.
;
; Captures go into the returned context, NOT the caller's
; scope. This is intentional -- dialects don't silently
; modify the caller.
;
; Use @parse/ok? to get a bare logic! result.
;
; Combinators:
;   |         - ordered alternative (lowest precedence)
;   end       - match end of input
;   skip      - match any single element
;   some      - one or more matches (greedy, backtracks like REBOL)
;   any       - zero or more matches (greedy, backtracks like REBOL)
;   opt       - zero or one match
;   not       - negative lookahead (doesn't consume)
;   ahead     - positive lookahead (doesn't consume)
;   to        - scan to (not past) a match
;   thru      - scan through (past) a match
;   into      - descend into nested block
;   quote     - match literally (escape keywords)
;   N rule    - repeat exactly N times
;   N M rule  - repeat between N and M times
;   collect   - wraps rule; keep inside appends to collected
;   keep      - inside collect, appends matched value
;   break     - exit some/any loop with success
;   fail      - force backtracking
;   (...)     - evaluate expression as side effect
;   [...]     - sub-rule grouping
;
; String character classes:
;   alpha digit space upper lower alnum newline
;
; Block matching extras:
;   'word   - match literal word
;   type!   - match by datatype
;
; Custom character classes:
;   charset "abc"           - set of characters
;   charset [alpha "_"]     - set combining classes + chars

; --- String parsing ---

result: @parse "hello" [some alpha]
print result/ok                         ; true

result: @parse "abc123" [some alpha]
print result/ok                         ; false (digits unconsumed)

; --- Captures go into returned context ---

result: @parse "user@example.com" [
  name: some [alpha | digit | "."]
  "@"
  domain: some [alpha | digit | "." | "-"]
]
print result/ok                         ; true
print result/name                       ; user
print result/domain                     ; example.com

; set-word inside some -- last match wins
result: @parse "1,2,3" [some [num: some digit opt ","]]
print result/num                        ; 3

; --- Block parsing ---

result: @parse [name "Alice" age 25] [
  'name who: string!
  'age years: integer!
]
print result/ok                         ; true
print result/who                        ; Alice
print result/years                      ; 25

; --- Collect/keep ---
; collect/keep for explicit accumulation. Must be named
; with a set-word -- unnamed collect discards values.

result: @parse [1 "a" 2 "b" 3] [
  nums: collect [some [keep integer! | skip]]
]
print result/nums                       ; [1 2 3]

; --- Composable rules ---
; Store rules in words and reference them by name.
digit-run: [some digit]
result: @parse "12345" digit-run
print result/ok                         ; true

; --- @parse/ok? refinement ---
; Returns bare logic! when you only care about success.
if @parse/ok? "12345" [some digit] [print "all digits"]

; --- Backtracking ---
; some and any are greedy but backtrack on failure, like REBOL.
; @parse "aab" [some "a" "ab"] succeeds: some matches "a",
; then backtracks to let "ab" match the rest.
; Caution: deeply nested some/any can cause exponential
; backtracking on pathological inputs.


; ============================================================
; BLOCKS & HOMOICONICITY
; ============================================================
; Code is data. Data is code. Blocks hold code or data
; without evaluating.
;
; Metaprogramming happens at compile time via @compose,
; @parse, and @preprocess. The preprocessor is the full
; language — it generates the static code that gets compiled.

data: [print "Hello"]

; Inspect code as data
print length data                        ; 2
print first data                        ; print (a word!)
print second data                       ; Hello (a string)

; @compose -- evaluate parens in a block template
target: "Alice"
code: @compose [greet (target) 42]       ; => [greet "Alice" 42]
print second code                       ; Alice

; reduce -- evaluate every expression, return results block
result: reduce [1 + 2 3 * 4 "hello"]
print first result                      ; 3
print second result                     ; 12


; ============================================================
; MACROS
; ============================================================
; @macro tags a function as a macro. When called, the return
; value (if it's a block) is automatically evaluated in the
; calling context. This is code generation without ceremony.

@macro unless: function [cond body [block!]] [
  @compose [if not (cond) (body)]
]

unless (3 > 5) [print "3 is not greater than 5"]

; Macros can wrap code with before/after logic.
; Use @compose/deep to interpolate inside nested blocks,
; and splicing (default) to inline block contents.

@macro with-timing: function [label [string!] body [block!]] [
  result: @compose/deep [print rejoin ["[" (label) "] start"]]
  append result body
  append result @compose/deep [print rejoin ["[" (label) "] end"]]
  result
]

with-timing "test" [
  print 1 + 2
]
; [test] start
; 3
; [test] end


; ============================================================
; SCOPE
; ============================================================
; scope creates a lexical child scope. Variables defined inside
; don't leak out. Works with @enter/@exit lifecycle hooks.

x-outer: "visible"
scope [
  y-inner: "scoped"
  print x-outer                         ; visible (parent accessible)
]
; y-inner does not exist here

; Lifecycle hooks with scope:
scope [
  @enter [print "entering scope"]
  @exit  [print "exiting scope"]
  print "inside scope"
]
; entering scope
; inside scope
; exiting scope


; ============================================================
; I/O
; ============================================================
; read and write are the unified I/O primitives.
;
; read %file              -> string (file contents)
; read/dir %path          -> block of filenames
; read/lines %file        -> block of strings (one per line)
; read/stdin "prompt"     -> read line from stdin
; write %file "content"   -> write string to file
; print value             -> print with newline
; print/no-newline value  -> print without newline
;
; save %file value        -> serialize value to file (round-trips with load/eval)
; load %file              -> parse file as Kintsugi data (block)
; load/eval %file         -> evaluate -> mutable context!
;
; dir? %path              -> logic! (is it a directory?)
; file? %path             -> logic! (is it a file?)
; exit N                  -> quit with exit code

; Live examples:
print/no-newline "hello "
print "world"                           ; hello world (on one line)

; read/stdin example (cannot run non-interactively):
;   name: read/stdin "What is your name? "
;   print rejoin ["Hello, " name "!"]

;   write %temp.txt "Hello from Kintsugi"
;   contents: read %temp.txt
;   print contents                        ; Hello from Kintsugi
;   entries: read/dir %lib                ; [collections.ktg math.ktg ...]


; ============================================================
; PREPROCESSING & COMPILATION
; ============================================================
; Preprocessing runs before evaluation. The preprocessor is
; the full Kintsugi language -- not a limited macro system.
;
; Two forms:
;   @preprocess [block]  -- evaluate block; emit injects code
;   @inline [expr]              -- inline; evaluate expr, inject result
;
; Available in the preprocess context:
;   system/platform  - current target ('script or 'lua)
;   emit             - inject a block into the output program

@preprocess [
  either system/platform = 'script [
    emit [print "Running in Script mode"]
  ] [
    emit [print "Running on Lua"]
  ]
]

; Code generation -- generates get-name, get-age, get-email
@preprocess [
  loop [
    for [field] in [name age email] do [
      emit @compose [
        (to set-word! join "get-" field) function [obj] [
          select obj (to lit-word! field)
        ]
      ]
    ]
  ]
]

; Inline preprocess -- inject values at preprocess time
; @inline [expr] evaluates expr during preprocessing and splices
; the result into the code stream. If the result is a block,
; its contents are spliced (multiple nodes). Otherwise the
; single value is spliced.
pp-val: @inline [1 + 2]                        ; pp-val = 3 (computed at preprocess time)
print pp-val                            ; 3

; Block splicing -- @compose a whole function definition inline
@inline [@compose [(to set-word! "pp-double") function [x] [x * 2]]]
print pp-double 5                       ; 10

; Platform values:
;   interpreter          -> system/platform = 'script
;   compiled via -c      -> system/platform = 'lua

; --- system: platform and environment ---
; system is a mutable context available everywhere (not just preprocess).
; system/platform tells you what runtime you're on.
; system/env gives path access to environment variables.

print system/platform                   ; 'script (in interpreter)

; Environment variables are auto-populated from the OS:
; print system/env/HOME                 ; /home/raycat
; print system/env/PATH                 ; /usr/bin:...

; You can set env vars locally (program-scoped, not OS-level):
; system/env/MY_APP_MODE: "debug"
; print system/env/MY_APP_MODE          ; debug

; --- raw: emit verbatim Lua (compile-time only) ---
; raw writes a string directly to the compiled Lua output.
; In the interpreter, it is a no-op.
raw "-- This is a Lua comment"
;   raw {import "CoreLibs/graphics"}    ; Playdate SDK import
;   raw {local ffi = require("ffi")}    ; LuaJIT FFI

; --- Bindings dialect ---
; bindings declares foreign API names for compilation targets.
; In Script mode, bindings register placeholder natives so
; the code parses without errors. In Lua mode, they emit
; the correct Lua paths and calling conventions.
;
; Each 'call binding has a fixed arity. For calls that need
; more args than declared, wrap in parens:
;   (draw-text "hello" 10 20)
;
; Syntax:
;   bindings [
;     name  "lua.path"  'call arity       ; callable, fixed arity
;     name  "lua.path"  'const            ; read-only value
;     name  "lua.path"  'alias            ; local alias declaration
;     name  "lua.path"  'assign           ; callback assignment (1 arg)
;     name  "lua.path"  'override         ; function definition form
;   ]
;
; 'assign emits:   lua.path = function(...) ... end
; 'override emits: function lua.path(...) ... end
;
; Example for Playdate SDK:
;   bindings [
;     update-sprites  "playdate.graphics.sprite.update"  'call 0
;     draw-text       "playdate.graphics.drawText"       'call 3
;     display-width   "playdate.display.getWidth"        'const
;     key-pressed     "playdate.buttonIsPressed"         'call 1
;   ]


; ============================================================
; MODULES & HEADERS
; ============================================================
; load is the universal file-reading primitive.
; Refinements determine how the file is processed:
;
;   load %file             -- parse as data, return context!
;   load/eval %file        -- evaluate + cache = context!
;   load/header %file      -- return just the header block
;   load/fresh %file       -- skip cache for one call
;   import/fresh %file    -- import, bypassing cache
;
; import is sugar for load/eval/cache. load is
; the primitive. Results are cached context! values,
; cached by absolute path.
; import/fresh forces a reload even if the module is cached.
;
; Example:
;   math: load/eval %lib/math.ktg
;   math/add 3 4                        ; 7
;
; --- Module file structure ---
;
;   Kintsugi []
;
;   exports [add clamp]                 ; only these are public
;
;   add: function [a b] [a + b]
;   clamp: function [val lo hi] [min hi max lo val]
;   helper: function [x] [x * x]       ; not exported, private
;
; exports is a body-level word, not a header field.
; If exports is never called, everything is public.
;
; --- Caching ---
; load/eval caches by fully resolved absolute path.
; Every consumer gets the same cached context! reference.
;
; --- Circular dependencies ---
; Always an error:
;   ERROR 'load: circular dependency: %a.ktg -> %b.ktg -> %a.ktg
;
; --- Serialization ---
; save %file data writes context data as Kintsugi literals.
; Functions are skipped -- behavior comes from the object.
;   save %save.dat player
;   ; reload:
;   data: load %save.dat
;   p: make Player data

; --- Header dialect ---
; Programs may begin with a header block. The header marks
; the file as an entrypoint. Files without headers are modules.
;
; When compiling (-c), entrypoints get the runtime prelude.
; Modules don't -- they're loaded via import.
;
; Header contents are optional metadata for tooling.
; No required fields.
;
; Common fields:
;   name:       - module name (lit-word)
;   version:    - semantic version (tuple!)
;   date:       - last-modified date
;   file:       - source file path
;   using:      - stdlib modules to unwrap as bare words
;
; Examples:
;   Kintsugi []                         ; entrypoint, no metadata
;   Kintsugi [version: 1.0.0]          ; entrypoint with metadata
;   Kintsugi [using: [math]]           ; unwraps std/math into scope
;   (no header)                         ; module

; --- Standard Library ---
; The stdlib is silently namespaced under std/.
; Always available without importing:
;
;   std/math/clamp 5 0 10
;   std/math/lerp 0 100 0.5
;   std/collections/range 1 10
;   std/collections/unique [1 2 1 3]
;
; To use stdlib words without the std/ prefix, add using:
; to the header:
;
;   Kintsugi [using: [math collections]]
;   clamp 5 0 10            ; bare word, unwrapped from std/math
;   range 1 10              ; bare word, unwrapped from std/collections
;
; User modules are always explicit:
;   sprites: import %lib/sprites.ktg
;   sprites/draw player


; ============================================================
; GOTCHAS
; ============================================================
; Kintsugi descends from REBOL, not C. Many things that look
; familiar behave differently.

; --- For C-style developers ---

; Functions consume arguments greedily.
; No parens on calls. Functions eat N values from the stream.
; f a b means "call f with a and b", not "f; then a; then b".
; You cannot have optional positional arguments -- functions
; always consume their full arity.
;   add 1 2                ; calls add with 1 and 2
;   add 1 add 2 3          ; calls add with 1 and (add 2 3) = 5

; replace replaces ALL occurrences (unlike C's strtok or JS's replace).
print replace "aabaa" "a" "x"           ; xxbxx

; Equality is structural -- blocks, pairs, tuples compare by value.
print [1 2 3] = [1 2 3]                ; true
print 100x200 = 100x200                ; true

; Only false and none are falsy. 0, "", and [] are truthy!
print if 0 ["zero is truthy"]          ; zero is truthy
print if "" ["empty string is truthy"] ; empty string is truthy
print if [] ["empty block is truthy"]  ; empty block is truthy

; to integer! true is ERROR.
; Numbers and logic are different domains. Use either or
; comparison instead.
;   either flag [1] [0]                 ; correct
;   to integer! true                    ; ERROR

; See Evaluation Model above for: no operator precedence,
; division return type, and/or non-short-circuit behavior.
; See Series Operations above for: append on blocks (strings are immutable).

; --- For Rebol/Red developers ---

; No char! type. Single characters are just string! values.
; Use byte/char for code conversion:
;   byte "A"    -> 65
;   char 65     -> "A"

; object uses field keyword with typed fields.
; See Object Dialect above for the full object model.

; first [hello] returns word!, not lit-word!
; Extraction from blocks preserves the original type.
; 'hello (a lit-word!) and first [hello] (a word!) are
; different subtypes, so 'hello = first [hello] is false.

; Word equality is same-subtype only.
; 'hello = 'hello is true (both lit-words).
; 'hello = first [hello] is false (lit-word vs word).
; Compare names: (to string! 'hello) = (to string! first [hello])

; exports is a body-level word, not a header field.

; See Contexts & Binding above for: set-word write-through scoping.
; See Loop Dialect above for: loop variables are scoped.
; See Error Handling above for: try returns a context.
; See Parse Dialect above for: parse returns a context.
; See Datatypes above for: money! is cents-based.
; See Modules above for: import = load/eval/cache.


; ============================================================
; PUTTING IT ALL TOGETHER
; ============================================================

; --- Quicksort (manual) ---
; Kintsugi has built-in sort. This shows off
; loop/partition and recursion.

qsort: function [blk] [
  if (length blk) <= 1 [return blk]
  set [pivot @rest] blk
  set [lo hi] loop/partition [for [x] in rest do [x < pivot]]
  append (append qsort lo pivot) qsort hi
]

unsorted: [3 1 4 1 5 9 2 6 5 3]
sorted: qsort unsorted
probe sorted                            ; 1 1 2 3 3 4 5 5 6 9

; --- Fibonacci ---

fib: function [n] [
  seq: [0 1]
  loop [
    from 1 to (n - 2) do [
      a: pick seq ((length seq) - 1)
      b: last seq
      append seq (a + b)
    ]
  ]
  seq
]

probe fib 10                            ; 0 1 1 2 3 5 8 13 21 34

; --- State Machine ---
; Objects with match for state transitions.

traffic-light-color!: @type/enum ['red | 'yellow | 'green]

TrafficLight: object [
  field/optional [state [traffic-light-color!] 'red]
  field/optional [timer [integer!] 0]

  advance: function [] [
    match self/state [
      ['red]    [self/state: 'green  self/timer: 30]
      ['green]  [self/state: 'yellow self/timer: 5]
      ['yellow] [self/state: 'red    self/timer: 45]
    ]
  ]

  display: function [] [
    rejoin ["[" (uppercase to string! self/state) "] " self/timer "s"]
  ]
]

light: make TrafficLight []
print light/display                     ; [RED] 0s
light/advance
print light/display                     ; [GREEN] 30s
light/advance
print light/display                     ; [YELLOW] 5s
light/advance
print light/display                     ; [RED] 45s

; --- Shared state via context + set-path ---
; The idiomatic way to mutate state from inside a function
; or loop: put state in a context, use path access.

scores: context [total: 0 count: 0]

add-score: function [n] [
  scores/total: scores/total + n
  scores/count: scores/count + 1
]

add-score 90
add-score 85
add-score 92
print rejoin ["Average: " (scores/total / scores/count)]
; Average: 89

; --- Pipeline processing with attempt ---

process-name: attempt [
  when [not empty? it]
  then [trim it]
  then [uppercase it]
]

print process-name "  ray  "            ; RAY

; --- Collect + filter pattern ---

data: [1 2 3 4 5 6 7 8 9 10]

big-evens: loop/collect [
  for [n] in data
  when [n > 5 and even? n]
  do [n]
]
probe big-evens                         ; 6 8 10

; --- Accumulator with fold ---

sum: loop/fold [for [acc n] in [10 20 30 40 50] do [acc + n]]
print sum                               ; 150

; --- Safe division with try ---

safe-calc: function [x y] [
  result: try [x / y]
  either result/ok [
    result/value
  ] [
    rejoin ["ERROR: " result/message]
  ]
]
print safe-calc 10 3                    ; 3.333...
print safe-calc 10 0                    ; ERROR: division by zero