fusion-lang 0.0.1.alpha1 → 0.0.1

data/docs/user/tutorial.md

@@ -5,8 +5,8 @@ every example. By the end you will have written a recursive program and understo
 Fusion's pieces fit together.*
 
 > **What you need:** Ruby installed and the `fusion` interpreter available on your
-> `PATH` (along with its bundled `stdlib/` folder). All commands below can be run
-> from any directory containing your `.fsn` files.
+> `PATH`. All commands below can be run from any directory containing your `.fsn`
+> files.
 
 ---
 
@@ -16,7 +16,7 @@ Fusion programs read JSON on standard input and write JSON on standard output. L
 create our first program. Create a file `lesson.fsn` containing exactly:
 
 ```fusion
-(n => [n, 2] | @multiply)
+(n => [n, 2] | @OP.product)
 ```
 
 Now run it:
@@ -32,10 +32,11 @@ being told:
   statements. The file *is* the program.
 - The input `21` was piped *into* the function. That is what `|` means: **`value |
   function`** applies the function to the value.
-- `[n, 2] | @multiply` built a two-element array and piped it into the built-in
-  `@multiply`. Fusion has no `*` operator (yet); arithmetic is done by piping a pair
-  into a named function. **Built-ins are reached with an `@` prefix**, just like files
-  — `@multiply`, `@add`, and so on. (You'll see why `@` is used for both in Step 8.)
+- `[n, 2] | @OP.product` built a two-element array and piped it into `@OP.product`, a
+  member of the built-in operator object `@OP`. Fusion has no `*` operator (yet);
+  arithmetic is done by piping a pair into a built-in. **Built-ins are reached with an
+  `@` prefix**, just like files — `@OP.product`, `@OP.sum`, and so on. (You'll see why
+  `@` is used for both in Step 8.)
 
 Note: on the right side of `=>` you can use regular parentheses `()` to group
 expressions and influence execution order.
@@ -126,8 +127,8 @@ number's absolute value:
 
 ```fusion
 (n =>
-  [n, 0] | @lessThan | (
-    true  => [0, n] | @subtract,
+  [n, 0] | @OP.compare | @lt | (
+    true  => n | @OP.negate,
     false => n
   )
 )
@@ -140,9 +141,10 @@ echo '-5' | fusion lesson.fsn    # => 5
 echo '5'  | fusion lesson.fsn    # => 5
 ```
 
-Read the middle line carefully: `[n, 0] | @lessThan` produces `true` or `false`. That
-boolean is then piped into a *second, inline function* whose two clauses are the two
-branches. **An `if` is just a function with a `true` clause and a `false` clause.**
+Read the middle line carefully: `[n, 0] | @OP.compare` orders the pair as `-1`/`0`/`1`,
+and `@lt` turns that into `true`/`false`. That boolean is then piped into a *second,
+inline function* whose two clauses are the two branches. **An `if` is just a function
+with a `true` clause and a `false` clause.**
 
 Note: you don't need to restrict yourself to the two values `true` and `false` as
 an intermediate result. Don't use it purely as an `if / else`. Use it like a `case`
@@ -161,7 +163,7 @@ To make recursion easier, `@` always means *the current file*. Create a new file
 ```fusion
 (
   [] => 0,
-  [x, ...rest] => [x, rest | @ ] | @add
+  [x, ...rest] => [x, rest | @ ] | @OP.sum
 )
 ```
 
@@ -198,7 +200,7 @@ Let's compute the factorial:
 ```fusion
 (
   0 => 1,
-  n ? @Integer => [n, [n, 1] | @subtract | @] | @multiply
+  n ? @Integer => [n, [n, -1] | @OP.sum | @] | @OP.product
 )
 ```
 
@@ -214,7 +216,7 @@ Create a function that sorts a pair of values:
 
 ```fusion
 (
-  [a, b] ? @lessThan => [a, b],
+  [a, b] ? (p => p | @OP.compare | @lt) => [a, b],
   [a, b] => [b, a]
 )
 ```
@@ -232,7 +234,7 @@ standard library and are reached with a plain `@name` — the same `@map` you'd
 a sibling file. The classic `map` is in the standard library. Create `doubler.fsn`:
 
 ```fusion
-(xs => {"f": (n => [n, 2] | @multiply), "xs": xs} | @map)
+(xs => {"f": (n => [n, 2] | @OP.product), "c": xs} | @map)
 ```
 
 ```sh
@@ -240,7 +242,7 @@ echo '[1, 2, 3]' | fusion doubler.fsn    # => [2, 4, 6]
 ```
 
 Because every Fusion function takes exactly one argument, `map` takes an *object*
-bundling the function `f` and the list `xs`. You just passed a function as a value
+bundling the function `f` and the collection `c`. You just passed a function as a value
 nested within an object — functions are values like any other.
 
 Now the payoff for using `@` everywhere. A bare `@name` is resolved in the following
@@ -249,7 +251,7 @@ order:
 2. A **built-in** called `name`.
 3. A **standard-library** file `name.fsn`.
 
-The first match wins. So `@multiply` finds the built-in and `@map` falls through to
+The first match wins. So `@OP` finds the built-in and `@map` falls through to
 the standard library. And if *you* put a `map.fsn` next to your program, *your* `map`
 shadows the standard one — but only for files in that directory.
 
@@ -264,22 +266,23 @@ So far you have written programs that succeed. What happens when something goes
 wrong? Try dividing by zero. Save as `boom.fsn`:
 
 ```fusion
-(n => [n, 0] | @divide)
+(n => [n, 0] | @math.divide)
 ```
 
 ```sh
 echo '5' | fusion boom.fsn
 ```
 
-You will see no output on stdout, a message like `"divide: division by zero"` on
-stderr, and the process will exit with status `1`. The result *was* an error, and
-the interpreter knows the difference: it routes the error's **payload** to
-stderr, leaves stdout empty, and signals failure. That makes Fusion programs
-well-behaved Unix filters.
+You will see no output on stdout, an error payload like
+`{"kind":"math_error",…,"message":"division by zero"}` on stderr, and the process
+will exit with status `1`. The result *was* an error, and the interpreter knows
+the difference: it routes the error's **payload** to stderr, leaves stdout empty,
+and signals failure. That makes Fusion programs well-behaved Unix filters.
 
-An error is always written as `!` followed by a **payload** — any regular JSON value.
-The built-ins above produced `!"divide: division by zero"` (an error whose payload
-is a string). You can construct your own:
+An error is always written as `!` followed by a **payload**. Errors the
+interpreter produces (like the one above) use a standardized payload shape —
+see [reference §6.5](./reference.md#65-the-standardized-error-payload). You can
+also construct your own, with any payload you like:
 
 | Example                             | Meaning                  |
 | ----------------------------------- | ------------------------ |
@@ -306,7 +309,7 @@ Catching is done with an error pattern:
 Here's `safeDivide` that returns `null` instead of failing:
 
 ```fusion
-(p => p | @divide | (! => null, n => n))
+(p => p | @math.divide | (! => null, n => n))
 ```
 
 Run `echo '[10, 0]' | fusion safeDivide.fsn` and you get `null` rather than an
@@ -330,7 +333,7 @@ In about an hour you have used every major feature of the language:
 - `if` is a function matching `true`/`false`; a loop is recursion via `@` (a bare
   `@` means "this file").
 - `?` attaches a predicate to refine a match, and predicates double as types.
-- Everything reachable lives in one `@` namespace: built-ins (`@add`, `@Integer`),
+- Everything reachable lives in one `@` namespace: built-ins (`@OP`, `@Integer`),
   the standard library (`@map`), sibling files (`@helper`), and the current file
   (`@`). A bare `@name` checks sibling → built-in → standard library, so you can
   locally shadow a built-in or stdlib function per directory.

data/examples/double.fsn

@@ -1,4 +1,4 @@
 (
   [] => [],
-  [first, ...rest] => [[first, first] | @add, ...rest | @]
+  [first, ...rest] => [2 * first, ...rest|@]
 )

data/examples/ends.fsn

@@ -0,0 +1,4 @@
+(
+  [first, ..., last] => [first, last],
+  _ => !{ "message": "Requires an array with at least 2 elements!" }
+)

data/examples/factorial.fsn

@@ -1,6 +1,6 @@
 # Factorial: n! for a non-negative integer.
 (
-  _ ? (i ? @Integer => [i, 0] | @lessThan, _ => true) => !"Only non-negative integers, please!",
+  _ ? (i ? @Integer => (i ?? 0)|@lt, _ => true) => !"Only non-negative integers, please!",
   0 => 1,
-  n => [n, [n, 1] | @subtract | @] | @multiply
+  n => n * (n - 1)|@
 )

data/examples/fizzbuzz.fsn

@@ -1,10 +1,7 @@
 # FizzBuzz for a single integer
 (
   n =>
-    [
-      [n, 3] | @mod,
-      [n, 5] | @mod,
-    ]
+    [n % 3, n % 5]
       |
     (
       [0, 0] => "FizzBuzz",

data/examples/json_test.fsn

@@ -0,0 +1,4 @@
+# JSON with comments, trailing commas and inline computation.
+{
+  "duration": 24 * 60,
+}

data/examples/palindrome.fsn

@@ -1,8 +1,9 @@
 # Check, whether input string or array is a palindrome
 (
+  n ? @Number => n | @toString | @,
   s ? @String => s | @chars | @,
   []  => "palindrome",
   [_] => "palindrome",
-  [_, ...rest, _] ? ([first, ..., last] => [first, last] | @equals) => rest | @,
+  [_, ...rest, _] ? @ends | @OP.equal => rest | @,
   _   => "not a palindrome"
 )

data/exe/fusion

@@ -3,55 +3,28 @@
 
 # Fusion CLI entrypoint.
 #
-# A file contains exactly one value. A file is "executable" if that value is a
-# function; the runtime computes  STDIN | thatFunction  and prints the result.
-#
 # Usage:
 #   echo '[1,2,3]' | fusion path/to/main.fsn
-#   fusion path/to/main.fsn '<json-input>'        # input as an argument
-#   fusion -e '(n => [n,2] | @multiply)' '21'     # inline program
+#   fusion path/to/main.fsn                            # no input: the file's value is the result
+#   echo '21' | fusion -e '(n => [n,2] | @multiply)'   # inline program
+#   fusion --stream path/to/main.fsn                   # NDJSON in, NDJSON out
+#   fusion --repl                                      # interactive expressions/statements
+#
+# Run `fusion --help` for the input/output modes (--input / --output / -!).
 
 require_relative "../lib/fusion"
 
-args = ARGV.dup
-inline = nil
-if args[0] == "-e"
-  inline = args[1]
-  program_path = nil
-  explicit_input = args[2]
-else
-  program_path = args[0]
-  explicit_input = args[1]
+if ARGV.intersect?(["--help", "-h"])
+  puts Fusion::CLI::Options::USAGE
+  exit 0
 end
 
-stdlib = File.expand_path("../stdlib", __dir__)
-interp = Fusion::Interpreter.new(stdlib_dir: (Dir.exist?(stdlib) ? stdlib : nil))
-
-# Determine the program function value.
-program_value =
-  if inline
-    ast = Fusion::Parser.parse_file(inline)
-    env = interp.root_env.child
-    env.define("__dir__", Dir.pwd)
-    interp.eval_expr(ast, env)
-  else
-    abort("usage: fusion <file.fsn> [json-input]   or   fusion -e '<src>' [json-input]") unless program_path
-    interp.load_file(File.expand_path(program_path)).force
-  end
-
-# Read input: explicit arg wins, else stdin.
-input_text = explicit_input || ($stdin.tty? ? "" : $stdin.read)
-input_text = "null" if input_text.nil? || input_text.strip.empty?
-input_value = Fusion::JsonInput.parse(input_text)
-
-result = interp.apply(program_value, input_value)
-
-if Fusion.error?(result)
-  # Print only the payload (as JSON) to stderr; stdout stays empty so that
-  # shell pipelines can rely on "stdout has the result, or there isn't one".
-  $stderr.puts Fusion::Serializer.to_json(result.payload)
-  exit 1
-else
-  puts Fusion::Serializer.to_json(result)
-  exit 0
+begin
+  options = Fusion::CLI::Options.parse(ARGV)
+  Fusion::CLI.run(options)
+rescue Fusion::CLI::Options::UsageError => err
+  # A command-line misuse is plain text on stderr, not a payloaded Fusion error,
+  # whether caught while parsing options or early during execution, e.g. by
+  # detecting empty stdin plus "-!".
+  abort("fusion: #{err.message}\n\n#{Fusion::CLI::Options::USAGE}")
 end

data/lib/fusion/ast.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# === Data Structure ===
+#
+# An AST::Expression is
+# - output of the parser
+# - input of the interpreter
+
+require_relative "typed_data"
+require_relative "atom"
+
+module Fusion
+  module AST
+    # A syntactic identifier: a bound/looked-up name, a `.key`, or a `...rest`
+    # binder. Mirrors the lexer's ident rule (Lexer#ident_start? / #ident_part?).
+    # Object *keys* are arbitrary strings, not identifiers, so they stay `String`.
+    Identifier = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    # Expression and Pattern nodes each form a closed family, declared up front
+    # (empty) so a member of either may reference the other. Each module is
+    # mixed into all of its members at the bottom of its body, so the module
+    # doubles as a marker: a field typed `Expression` accepts any expression
+    # node, `Pattern` any pattern node.
+    module Expression; end
+    module Pattern; end
+    module Statement; end
+
+    # Auxiliary typed parts: the elements a collection node holds. NOT themselves
+    # expressions or patterns, so they live outside the marker families and never
+    # satisfy an `Expression`/`Pattern` field.
+    ArrayItem    = TypedData.define(value: Expression)                            # an array element
+    ArraySpread  = TypedData.define(value: Expression)                            # ...expr inside an array
+    KeyValuePair = TypedData.define(key: String, value: Expression)               # "k": expr inside an object
+    ObjectSpread = TypedData.define(value: Expression)                            # ...expr inside an object
+    Clause       = TypedData.define(pattern: Pattern, body: Expression)           # one  pattern => body  of a function
+    PatternItem  = TypedData.define(pattern: Pattern)                             # a sub-pattern of an array pattern
+    PatternPair  = TypedData.define(key: String, pattern: Pattern)                # "k": pat inside an object pattern
+    PatternRest  = TypedData.define(name: ->(v) { Identifier === v || v.nil? })   # ...name (name nil = ignore) in either
+
+    module Expression
+      Lit       = TypedData.define(value: Atom)                                                      # atom literal (incl NULL)
+      ErrLit    = TypedData.define(payload: ->(v) { Expression === v || v.nil? })                    # !expr or bare ! (payload nil = !null)
+      ArrLit    = TypedData.define(items: ->(v) { v.is_a?(Array) && v.all? { |e| ArrayItem === e || ArraySpread === e } })
+      ObjLit    = TypedData.define(pairs: ->(v) {                                                    # [KeyValuePair|ObjectSpread], distinct fixed keys
+        v.is_a?(Array) &&
+          v.all? { |m| KeyValuePair === m || ObjectSpread === m } &&
+          v.filter_map { |m| m.key if KeyValuePair === m }.then { |keys| keys.uniq.size == keys.size }
+      })
+      FuncLit   = TypedData.define(clauses: ->(v) { v.is_a?(Array) && v.all? { |c| Clause === c } }) # [] = the empty function
+      Ident     = TypedData.define(name: Identifier)                                                 # read a builtin/bound name
+      FileRef   = TypedData.define(variety: ->(v) { %i[self super super_name name path].include?(v) }, path: ->(v) { String === v || v.nil? })
+      Pipe      = TypedData.define(left: Expression, right: Expression)                              # left | right
+      Member    = TypedData.define(obj: Expression, key: Identifier)                                 # obj.key
+      Index     = TypedData.define(obj: Expression, idx: Expression)                                 # obj[expr]
+      IndexSet  = TypedData.define(obj: Expression, idx: Expression, value: Expression)              # obj[expr = expr]
+
+      constants.each do |name|
+        node = const_get(name)
+        node.include(self) if node.is_a?(Class) && node < Data
+      end
+    end
+
+    module Pattern
+      PLit      = TypedData.define(value: Atom)                                                     # literal pattern
+      PErr      = TypedData.define(inner: Pattern)                                                  # ! or !pat ; inner=PWild matches any error
+      PBind     = TypedData.define(name: Identifier)                                                # binds
+      PWild     = TypedData.define(dummy: NilClass)                                                 # _
+      PArr      = TypedData.define(items: ->(v) {                                                   # [PatternItem|PatternRest], at most one rest
+        v.is_a?(Array) &&
+          v.all? { |e| PatternItem === e || PatternRest === e } &&
+          v.count { |e| PatternRest === e } <= 1
+      })
+      PObj      = TypedData.define(pairs: ->(v) {                                                   # [PatternPair|PatternRest], one rest, distinct keys
+        v.is_a?(Array) &&
+          v.all? { |m| PatternPair === m || PatternRest === m } &&
+          v.count { |m| PatternRest === m } <= 1 &&
+          v.filter_map { |m| m.key if PatternPair === m }.then { |keys| keys.uniq.size == keys.size }
+      })
+      PGuard    = TypedData.define(inner: Pattern, pred_expr: Expression)                           # inner ? predicate
+
+      constants.each do |name|
+        node = const_get(name)
+        node.include(self) if node.is_a?(Class) && node < Data
+      end
+    end
+
+    module Statement
+      # The only statement. Only allowed in the REPL. `name = expression`.
+      Assignment = TypedData.define(name: Identifier, expression: Expression)
+
+      constants.each do |name|
+        node = const_get(name)
+        node.include(self) if node.is_a?(Class) && node < Data
+      end
+    end
+  end
+end

data/lib/fusion/atom.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# === Value ===
+#
+# An atomic runtime value.
+
+require_relative "typed_data"
+require_relative "null"
+
+module Fusion
+  # A scalar literal value: the JSON atoms plus NULL (everything the lexer
+  # emits as a token value, see Lexer#lex_number and #lex_word).
+  Atom = ->(v) {
+    v == NULL ||  v == true || v == false ||
+      v.is_a?(Integer) || v.is_a?(Float) || v.is_a?(String)
+  }
+end

data/lib/fusion/cli/decoder.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# === CLI internals ===
+
+require "json"
+require_relative "../wire_pair"
+
+module Fusion
+  module CLI
+    module Decoder
+      extend self
+
+      EXPECTED_ENVELOPE_SHAPES = {
+        array: ["[0, _]", "[1, _]"],
+        object: ['{"value": _}', '{"error": _}'],
+      }.freeze
+
+      # String -> WirePair
+      # Doesn't support mode `:unix`
+      def decode(text, mode:)
+        case mode
+        when :bang
+          decode_bang(text)
+        when :array
+          decode_envelope(text, mode) do |raw|
+            next unless raw.is_a?(Array) && raw.length == 2 && raw[0].is_a?(Integer)
+
+            # The tag must be exactly the integer 0 or 1 (no 0.0 — Fusion equality is exact).
+            [raw[0], raw[1]] if raw[0] == 0 || raw[0] == 1
+          end
+        when :object
+          decode_envelope(text, mode) do |raw|
+            next unless raw.is_a?(Hash) && raw.size == 1
+
+            if raw.key?("value") then [0, raw["value"]]
+            elsif raw.key?("error") then [1, raw["error"]]
+            end
+          end
+        else
+          raise Unreachable, "Unknown input mode #{mode}"
+        end
+      end
+
+      private
+
+      # bang: a leading "!" marks an error value; its payload is the JSON after
+      # the "!". A lone "!" is the error !null, mirroring the language's bare !.
+      def decode_bang(text)
+        stripped = text.strip
+        return WirePair.new(status: 0, data: text) unless stripped.start_with?("!")
+
+        payload = stripped.delete_prefix("!")
+        # TODO: BUG? should we really convert "" to "null"?
+        # Feels inconsistent with '-!' flag, but might be slightly different case.
+        # Also, definitely inconsistent with non-error case above.
+        # Also, the "!" == "!null" leniency holds only in code, not in input/output JSON.
+        WirePair.new(status: 1, data: payload.strip.empty? ? "null" : payload)
+      end
+
+      # array/object: the input is an envelope around the actual value. The block
+      # inspects the JSON (raw Ruby, so nulls are nil) and returns [status, inner]
+      # or nil for a wrong shape. The inner is re-emitted as JSON text for the
+      # pair; invalid JSON falls through to `parse` as a value to fail on, so the
+      # syntax_error stays in one place.
+      def decode_envelope(text, mode)
+        raw = JSON.parse(text)
+        status, inner = yield(raw)
+        return WirePair.new(status: status, data: JSON.generate(inner)) if status
+
+        WirePair.new(status: 1, data: JSON.generate(
+          "kind" => "argument_error",
+          "origin" => "input",
+          "operation" => "decoding input",
+          "status" => 0,
+          "input" => raw,
+          "expected" => EXPECTED_ENVELOPE_SHAPES.fetch(mode)
+        ))
+      rescue JSON::ParserError
+        # TODO: BUG ???
+        WirePair.new(status: 0, data: text)
+      end
+    end
+  end
+end

data/lib/fusion/cli/encoder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# === CLI internals ===
+
+module Fusion
+  module CLI
+    module Encoder
+      extend self
+
+      # WirePair -> String
+      # Doesn't support mode `:unix`
+      def encode(wire_pair, mode:)
+        case mode
+        when :bang
+          bang = wire_pair.status.zero? ? "" : "!"
+          "#{bang}#{wire_pair.data}"
+        when :array
+          "[#{wire_pair.status},#{wire_pair.data}]"
+        when :object
+          key = wire_pair.status.zero? ? "value" : "error"
+          "{\"#{key}\":#{wire_pair.data}}"
+        else
+          raise Unreachable, "Unknown output mode #{mode}"
+        end
+      end
+    end
+  end
+end