fusion-lang 0.0.1.alpha1

data/docs/lang/roadmap.md

@@ -0,0 +1,97 @@
+# Fusion roadmap
+
+Tracked future work and open questions. Decisions that have already been made
+live in [design.md](./design.md); this file is only for things still ahead.
+
+---
+
+## 1. Ergonomics: the most-wanted improvements
+
+**Operator sugar (planned).** Reintroduce infix `+ - * / % == != < <= > >= && || !`
+and string `++`, desugaring to the existing built-ins over pairs. Pure ergonomics,
+no semantic change. This is the single biggest readability win available and was
+always intended. Open question: exact precedence table and how it interleaves with
+`|` and `=>`.
+
+**`@`-namespace resolution polish.** Decide on project-root confinement
+(sandboxing) for `@../` escapes; consider a configurable standard-library search
+path; consider tooling to surface *which* target a given `@name` resolves to in
+a directory, since shadowing is invisible at the call site.
+
+---
+
+## 2. Error model
+
+**Payload shape consistency** *(open)*. The payload *shape* is inconsistent:
+built-ins use bare strings (`"divide: division by zero"`) while runtime
+mechanics use structured objects (`{"kind":"missing_key","key":"foo"}`). The
+string form is human-friendlier; the structured form is machine-friendlier
+(catchable via `!{"kind": k}`). Three plausible resolutions:
+
+- (a) all errors get structured payloads with a `kind` and an optional `message`;
+- (b) all errors get human strings, and structured matching is left to user code;
+- (c) keep both, document the rule that built-in operations use strings and
+  runtime mechanics use objects.
+
+This is a small but irreversible decision (it shapes how catch clauses are
+written) and should be decided before any external code grows that depends on
+the current shapes.
+
+**Better diagnostics.** `FUSION_DEBUG` exists for file/parse errors; extend
+principled diagnostics to runtime error origins (where did this error first
+arise?). One option: attaching a source position to the payload (an extra
+`"at": "file.fsn:L:C"` field) when `FUSION_DEBUG` is set.
+
+**Stack traces** *(deferred)*. A propagated error tells you what happened, but
+not the chain of function applications it passed through. A capped trace
+(last N frames, accessible as an extra payload field, opt-in via env) would
+help in deep pipelines.
+
+---
+
+## 3. Standard library completion
+
+Populate Tier 1 (written in Fusion): `filter`, `reduce`/`fold`, `reverse`,
+`head`, `tail`, `last`, `init`, `take`, `drop`, `zip`, `flatten`, `member`,
+`find`, `all`, `any`, `count`; comparison derivatives `lessEq`, `greaterThan`,
+`greaterEq`, `notEquals`; object helpers `entries`, `get`, `set`, `merge`; an
+`if` helper. This is also the best stress test of whether the language is
+pleasant to *write* in, not just to implement.
+
+---
+
+## 4. Runtime and tooling
+
+- **Streaming I/O** (NDJSON): map a program over a stream of JSON values.
+- **A faster implementation** once semantics are frozen.
+
+## 5. Open semantic questions to settle
+
+- Numeric tower: keep int/float split, or move to a single number type /
+  arbitrary precision? Affects `divide`, `floor`, `equals`, and the
+  `Integer`/`Float` predicates.
+- Function equality: `equals` on two functions — always `false`, or an error?
+  (Function equality is undecidable beyond trivial identity.)
+
+---
+
+## 6. Bigger experiments
+
+**Destructuring functions (homoiconicity).** Treat a function as a list of
+`(pattern, output)` clause-pairs and pattern-match on it, enabling macros and
+function transformers with the same matching machinery. The clean path is
+explicit, opt-in reflection (`reflect : function → data`,
+`reify : data → function`) representing patterns as reflective AST objects, so
+normal code keeps functions opaque and "three ingredients" intact. High payoff
+(metaprogramming), moderate disruption.
+
+**Running functions backwards (relational mode).** Given an output, find an
+input — unification and search, à la Prolog/miniKanren. Clean only for
+invertible functions; hopeless for many-to-one. Would change Fusion from
+functional to relational and needs backtracking search. The most exciting and
+most disruptive possible direction; best pursued as a separate mode or sibling
+project rather than folded into the core.
+
+**A static checker.** Because "types" are predicates, an optional static layer
+could attempt to verify predicate-guarded clauses and exhaustiveness without
+changing the dynamic semantics. Speculative.

data/docs/user/explanation.md

@@ -0,0 +1,157 @@
+# Explanation
+
+*This is an understanding-oriented discussion: it provides context and answers "why?".
+This article may hold opinions and approach the subject from several angles. For the
+formal decision ledger (who decided what, alternatives, trade-offs) see the
+[Design documentation](../lang/design.md).*
+
+---
+
+## What Fusion is, in one breath
+
+Fusion is "functional JSON": take JSON — its atoms, arrays, and objects — and add one
+more ingredient, the function. Keep the count of concepts brutally small. From those
+pieces, recover everything a small language needs: branching, looping, types,
+modules, and error handling. The whole design is an exercise in *not adding things*
+and discovering that the pieces you already have are enough.
+
+---
+
+## Why only three ingredients
+
+Most languages accrete features: statements, loops, conditionals, classes,
+exceptions, a type system, a module system, each with its own syntax. Fusion's bet is
+that almost all of that is unnecessary if your three composite ingredients — arrays,
+objects, functions — are chosen well and made to compose.
+
+The discipline pays a recurring dividend. Again and again, a feature that would
+normally be its own language construct turns out to be expressible with what already
+exists:
+
+- An **`if`** is a function with `true` and `false` clauses.
+- A **`for` loop** is recursion that pattern-matches a list down to `[]`.
+- A **type** is a predicate function attached with `?`.
+- A **module** is a file, and an import is a reference to that file's value.
+- **Error propagation** is just how application treats the error value.
+
+None of these required new syntax. That is the aesthetic core of the language: when
+you feel the urge to add a construct, look harder at the three you have.
+
+---
+
+## Why functions take exactly one argument
+
+This looks like a severe restriction and is actually a simplification that makes
+everything else line up. With exactly one input and one output:
+
+- **Application has one shape:** `value | function`. There is no argument list, no
+  call syntax, no arity to track. A pipeline `a | f | g | h` reads like a sentence.
+- **Multi-argument needs are met by data:** pass an array `[a, b]` or an object
+  `{"f": ..., "xs": ...}`. The "arguments" become a value you can also store, inspect,
+  and destructure — there's no separate notion of "argument tuple."
+- **Pattern matching has one job:** match the single input. A function's clauses are
+  just alternative shapes that one input might have.
+
+The cost is verbosity in arithmetic (`[a, b] | @add` instead of `a + b`) and a little
+ceremony for multi-argument library functions. The first is a candidate for later
+syntactic sugar; the second is mild. In exchange, the evaluation model is almost
+trivially simple, which is exactly what you want in a language meant to be small.
+
+---
+
+## Why bare words are "holes"
+
+The keystone trick is that a bare identifier means *bind* in a pattern and *read* in
+an expression. This works because JSON has no bare identifiers — strings are quoted,
+so an unquoted word is an unused syntactic slot. Fusion claims that slot for local
+variables.
+
+The consequence is a pleasing symmetry: a pattern and a result are mirror images.
+`[a, b] => [b, a]` reads almost pictorially — the same names appear on both sides,
+filled from the input on the left and poured into the output on the right. You never
+write "get element 0, get element 1, now build a new array"; you draw the shape you
+have and the shape you want, and the names connect them. Destructuring stops being an
+operation and becomes a *correspondence*.
+
+---
+
+## Why pattern matching is the only control flow
+
+Because functions dispatch by matching their single input against ordered clauses,
+"choosing what to do" and "taking apart the data" are the same act. A clause is
+simultaneously a condition (does this shape match?) and a binding (here are the
+pieces). This collapses two things most languages keep separate — `switch` and
+destructuring assignment — into one.
+
+Once control flow *is* matching, recursion naturally absorbs iteration. A list is
+either `[]` or `[head, ...tail]`; those two shapes are the two clauses of almost every
+list function; the recursive call shrinks the input until the base shape matches. The
+"loop" is invisible because it isn't a loop — it's a function rediscovering a smaller
+version of its own input.
+
+The one wrinkle this introduces: what should happen when *nothing* matches? Fusion's
+answer is `null` by default. If you want to make a function total, simply append
+`_ => default_value` as a final clause. If you want to make it strict, append
+`_ => !error` instead.
+
+---
+
+## Why a file is exactly one value
+
+Earlier drafts had a program be a list of top-level `name = value` bindings plus a
+"main" expression — essentially a second little language stacked on top of the
+expression language, with its own scoping rules (the bindings had to be mutually
+recursive, a `letrec`). The "one value per file" rule deletes all of that. The
+outermost layer of a program is now the same kind of thing as every inner layer: a
+value. A program is just a file whose value happens to be a function, and running it
+is `STDIN | thatFunction`.
+
+This also resolved the module system for free. If a file is a value, then referencing
+a file *is* importing a value — no separate `import` construct, no namespace syntax.
+The directory tree becomes the namespace. The standard library is just a folder of
+files. One mechanism (`@`-references) now does top-level structure, modules, and
+library delivery — and, in the current design, built-in access too: `@add` and
+`@Integer` are looked up through the very same `@name` machinery as files. A bare
+`@name` checks for a sibling file, then a built-in, then a standard-library file, so
+your own files can locally shadow a built-in or a stdlib function without affecting
+any other directory. The cost of folding built-ins into `@` is that a bare word like
+`add` is no longer the built-in — it is only ever a pattern hole — so built-ins must
+always be written with `@`.
+
+---
+
+## Why references are lazy
+
+If `@`-references resolved eagerly (when a file loads), then a file referencing itself
+would loop forever before it could ever run. Lazy resolution — resolve a reference
+only when it is actually used — is what makes self-recursion and mutual recursion
+possible at all. It is not a performance nicety; it is load-bearing for the whole
+recursion story. Memoization on top means a referenced file is evaluated once and
+shared, so diamond-shaped dependencies are cheap and a referenced-but-unused file is
+never loaded.
+
+A side effect is that *data* cycles (files whose values point at each other directly,
+not through a function) are non-productive — there's no pattern match to bottom out
+on. The runtime detects the cycle and yields `!` at that point, while keeping whatever
+productive structure surrounds it.
+
+---
+
+## The roads not taken (and one we're still tempted by)
+
+Two ideas were explored and deliberately set aside, both documented in the design doc.
+
+**Operator sugar.** We could write `a + b` and desugar it to `[a, b] | @add`. We rolled
+this back early to keep the core honest, with the explicit intent to reintroduce it
+once the semantics were settled. It is a pure ergonomics layer; it changes nothing
+underneath.
+
+**Destructuring functions.** The tantalizing one. Since a function literal is visibly
+a list of `pattern => output` clauses, could we pattern-match *on a function*, taking
+it apart as data? That would give Lisp-like metaprogramming with the same matching
+machinery — and, in its wildest form, the ability to run functions *backwards* (given
+an output, find an input), which is logic programming. We kept it out of the grammar
+because the clean version requires representing patterns as data (a function's pattern
+contains unbound binders, so it isn't an ordinary value), and the wild version would
+turn Fusion from a functional language into a relational one. It remains the most
+interesting possible future for the language, and the most disruptive.

data/docs/user/how-to-guides.md

@@ -0,0 +1,205 @@
+# How-to guides
+
+*These are recipes for specific real-world tasks and assume you already know the
+basics. Scan for the problem you have and copy the solution.*
+
+---
+
+## Diagnose a program that returns an error unexpectedly
+
+When you run a program and see an error payload on stderr, the payload itself
+usually tells you what went wrong (e.g. `"divide: division by zero"` or
+`{"kind":"missing_key","key":"email"}`). For errors arising *during reference
+resolution* — typically a missing file or a parse error in an `@`-referenced file —
+enable extra diagnostics:
+
+```sh
+FUSION_DEBUG=1 fusion program.fsn '...'
+```
+
+With `FUSION_DEBUG` set, the interpreter prints to stderr the exact path it failed
+to find or the parse error it hit. The most common cause is that the `stdlib/`
+folder is not where the interpreter expects it, so `@`-references can't be resolved.
+
+---
+
+## Emulate control structures from other programming languages
+
+1. Branch on a condition (emulate `if`)
+
+Compute a boolean, then pipe it into a two-clause function:
+
+```fusion
+(n =>
+  [n, 0] | @lessThan | (
+    true  => "negative",
+    false => "non-negative"
+  )
+)
+```
+
+You don't need to restrict yourself to 2 branches and the intermediate values `true` and `false`.
+Here's an elegant way of writing FizzBuzz:
+
+```fusion
+(
+  n =>
+    [
+      [n, 3] | @mod,
+      [n, 5] | @mod,
+    ]
+      |
+    (
+      [0, 0] => "FizzBuzz",
+      [0, _] => "Fizz",
+      [_, 0] => "Buzz",
+      _      => n,
+    )
+)
+```
+
+2. Loop over a list (emulate `for`)
+
+Use recursion on lists with the base case `[]` and the recursive case `[x, ...rest]`.
+You could write `sum` like this:
+
+```fusion
+(
+  [] => 0,
+  [x, ...rest] => [x, rest | @] | @add
+)
+```
+
+If you don't have a list yet, but want to repeat something `n` times, use the
+standard library function `range` to construct a list. `5 | @range` will evaluate
+to `[0,1,2,3,4]`.
+
+If you need further inputs in addition to your list, e.g. a function, use an object:
+`{"function": f, "list": [1, 2, 3]}`.
+
+3. Apply a function partially (only provide a subset of required inputs and emulate `currying`)
+
+A Fusion function takes exactly one input. Functions that require multiple inputs bundle
+them into an array (or object) and destructure that in the pattern:
+
+```fusion
+([a, b] => [a, b] | @add)
+```
+
+Call it as `[3, 4] | @thatFunction`
+
+To curry a function call (that means to supply arguments one at a time) write a function that
+takes a single argument (`x` in the example below) and returns a simpler function that only
+needs the remaining arguments (`y` in the example below). Each `=>` consumes one argument
+and hands back a function waiting for the next:
+
+```fusion
+(x => (y => [x, y] | @add))
+```
+
+Call it as `4 | (3 | @thatFunction)`. `3 | f` yields a one-argument function that adds 3,
+and piping a second value into that finishes the sum.
+
+With this, you can partially apply functions. Apply the first argument now and then use
+the resulting function later.
+
+---
+
+## Match on a condition involving several captured values
+
+A `?` predicate sees **only** the value its own pattern matched — it cannot see
+sibling bindings. To compare two captured values, attach the predicate to the
+**parent container** so it receives the whole thing.
+
+For example, to recognise a three-element palindrome you have to compare the first
+and last elements. A predicate guarding `first` on its own could never see `last`,
+so guard the whole array instead:
+
+```fusion
+(
+  []  => "palindrome",
+  [_] => "palindrome",
+  [_, ...rest, _] ? ([first, ..., last] => [first, last] | @equals) => rest | @,
+  _   => "not a palindrome"
+)
+```
+
+The outer pattern `[_, ...rest, _]` is what you destructure for retrieving the middle
+of the array which you need to continue your recursion. The inline predicate
+`([first, ..., last] => [first, last] | @equals)` independently destructures the same
+array again to compare its two ends.
+
+---
+
+## Shadow a built-in or stdlib function locally
+
+Because a sibling file wins over a built-in or the standard library, you can override
+either — but only for files in the same directory, so you can't break things
+globally. Put an `add.fsn` next to your program and every `@add` *in that directory*
+uses yours; files elsewhere still get the built-in.
+
+---
+
+## Read environment variables
+
+`@ENV` evaluates to an object of all environment variables (every value is a string;
+nothing is auto-parsed). Read one with member access:
+
+```fusion
+# with CI=1 in the environment, yields the string "1"
+(_ => @ENV.CI)
+```
+
+A missing variable (`@ENV.NOPE`) yields `!`. Note `@ENV` is itself shadowable: a
+sibling `ENV.fsn` replaces it for that directory.
+
+---
+
+## Load a file by a runtime filename
+
+`@map` and friends require the name at parse time and imply the `.fsn` extension.
+When you need to load a file whose name is computed at runtime, or whose name isn't a
+plain identifier (e.g. contains a `.`), use the `@load` built-in. It takes a filename
+**verbatim** — no extension is added — resolved relative to the current file:
+
+```fusion
+# Load a file with exactly the given name. Don't append ".fsn".
+("data.config.json" | @load)
+```
+
+```fusion
+# Load a file chosen at runtime.
+(name => name | @load)
+```
+
+A missing file yields an error.
+
+---
+
+## Keep a recursive file independent of its name and location
+
+A recursive function should never call itself by its own filename. Writing `@fact`
+inside `fact.fsn` works until someone renames or moves the file — then the reference
+dangles. Refer to the current file with a bare `@` ("this file", whatever it happens
+to be called) instead:
+
+```fusion
+# factorial
+(0 => 1, n ? @Integer => [n, [n, 1] | @subtract | @] | @multiply)
+```
+
+If the file evaluates to an **object** and a recursive *helper* lives inside it as a
+member, reach that member with `@.helper` — the current file's value (`@`) followed
+by a `.member` access — rather than `@filename.helper`:
+
+```fusion
+{
+  "sumTo": (
+    0 => 0,
+    n ? @Integer => [n, [n, 1] | @subtract | @.sumTo] | @add
+  )
+}
+```
+
+Both forms move and rename along with the file, so nothing dangles when you
+reorganise your directory.