fusion-lang 0.0.1.alpha2 → 0.0.2

data/docs/user/tutorial.md

@@ -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 | @OP.lt | (
+    true  => n | @OP.negate,
     false => n
   )
 )
@@ -140,9 +141,11 @@ 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 `@OP.lt` turns that into `true`/`false` (the infix `n < 0` is sugar for exactly
+this pipeline). 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 +164,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 +201,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 +217,7 @@ Create a function that sorts a pair of values:
 
 ```fusion
 (
-  [a, b] ? @lessThan => [a, b],
+  [a, b] ? (p => p | @OP.compare | @OP.lt) => [a, b],
   [a, b] => [b, a]
 )
 ```
@@ -232,7 +235,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 +243,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 +252,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,7 +267,7 @@ 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
@@ -307,7 +310,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
@@ -331,7 +334,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,7 @@
+# Double every number in an array or object.
+# Equivalent to: (c ? @Collection => c |: (n => 2 * n))
 (
   [] => [],
-  [first, ...rest] => [[first, first] | @add, ...rest | @]
+  [first, ...rest] => [2 * first, ...rest|@],
+  obj ? @Object => obj | @entries |: ([key, value] => [key, 2 * value]) | @toObject
 )

data/examples/factorial.fsn

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

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/gcd.fsn

@@ -0,0 +1,9 @@
+# Greatest common divisor of a pair of non-negative integers (Euclidean algorithm).
+(
+  pair ? ([a ? @Integer, b ? @Integer] => a >= 0 && b >= 0) =>
+    pair | (
+      [a, 0] => a,
+      [a, b] => [b, a % b] | @
+    ),
+  _ => !"Only pairs of non-negative integers, please!"
+)

data/examples/json_test.fsn

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

data/examples/matrix/OP.fsn

@@ -0,0 +1,2 @@
+# This directory computes with matrices: the operators are the matrix reskin.
+@matrix/OP

data/examples/matrix/average.fsn

@@ -0,0 +1,2 @@
+# Average two matrices: elementwise sum, then halve each entry.
+([a, b] => [0.5, a + b] | @matrix/scale)

data/examples/matrix/solve.fsn

@@ -0,0 +1,2 @@
+# Solve the linear system a * x = b for x (b a column matrix): x = a⁻¹ * b.
+([a, b] => /a * b)

data/examples/palindrome.fsn

@@ -4,6 +4,6 @@
   s ? @String => s | @chars | @,
   []  => "palindrome",
   [_] => "palindrome",
-  [_, ...rest, _] ? @ends | @equals => rest | @,
+  [_, ...rest, _] ? @ends | @OP.equal => rest | @,
   _   => "not a palindrome"
 )

data/exe/fusion

@@ -5,10 +5,10 @@
 #
 # 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 --stream path/to/main.fsn              # NDJSON in, NDJSON out
-#   fusion --repl                                 # interactive expressions/statements
+#   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 / -!).
 
@@ -19,12 +19,12 @@ if ARGV.intersect?(["--help", "-h"])
   exit 0
 end
 
-options = begin
-  Fusion::CLI::Options.parse(ARGV)
-rescue Fusion::CLI::Options::UsageError => err
-  # A command-line misuse happens before the input/output contract begins, so
-  # it is plain text on stderr, not a payloaded error.
-  abort("fusion: #{err.message}\n\n#{Fusion::CLI::Options::USAGE}")
+begin
+  options = Fusion::CLI::Options.parse(ARGV)
+  Fusion::CLI.run(options)
+rescue Fusion::CLI::Options::UsageError => e
+  # 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: #{e.message}\n\n#{Fusion::CLI::Options::USAGE}")
 end
-
-Fusion::CLI.run(options)

data/lib/fusion/ast.rb

@@ -14,7 +14,7 @@ module Fusion
     # 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/
+    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
@@ -28,30 +28,66 @@ module Fusion
     # 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
+
+    # An array element
+    ArrayItem = TypedData.define(value: Expression)
+
+    # `...expr` inside an array
+    ArraySpread = TypedData.define(value: Expression)
+
+    # `"k": expr` inside an object
+    KeyValuePair = TypedData.define(key: String, value: Expression)
+
+    # `...expr` inside an object
+    ObjectSpread = TypedData.define(value: Expression)
+
+    # One `pattern => body` of a function
+    Clause = TypedData.define(pattern: Pattern, body: Expression)
+
+    # A sub-pattern of an array pattern
+    PatternItem = TypedData.define(pattern: Pattern)
+
+    # `"k": pat` inside an object pattern
+    PatternPair = TypedData.define(key: String, pattern: Pattern)
+
+    # `...name` in array/object pattern. (name nil = don't bind)
+    PatternRest = TypedData.define(name: ->(v) { IDENTIFIER === v || v.nil? })
 
     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
+      # Atom literal (incl NULL)
+      Lit = TypedData.define(value: Atom)
+
+      # `!expr` or bare `!` (payload nil = !null)
+      ErrLit = TypedData.define(payload: ->(v) { Expression === v || v.nil? })
+
+      ArrLit = TypedData.define(items: ->(v) { v.is_a?(Array) && v.all? { |e| ArrayItem === e || ArraySpread === e } })
+
+      # [KeyValuePair|ObjectSpread], distinct fixed keys
+      ObjLit = TypedData.define(pairs: ->(v) {
         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 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]
+
+      # [] = the empty function
+      FuncLit = TypedData.define(clauses: ->(v) { v.is_a?(Array) && v.all? { |c| Clause === c } })
+
+      # Read a builtin/bound name
+      Ident = TypedData.define(name: IDENTIFIER)
+
+      FileRef = TypedData.define(variety: ->(v) { [:self, :super, :super_name, :name, :path].include?(v) }, path: ->(v) { String === v || v.nil? })
+
+      # `left | right`
+      Pipe = TypedData.define(left: Expression, right: Expression)
+
+      # `obj.key`
+      Member = TypedData.define(obj: Expression, key: IDENTIFIER)
+
+      # `obj[expr]`
+      Index = TypedData.define(obj: Expression, idx: Expression)
+
+      # `obj[expr = expr]`
+      IndexSet = TypedData.define(obj: Expression, idx: Expression, value: Expression)
 
       constants.each do |name|
         node = const_get(name)
@@ -60,22 +96,35 @@ module Fusion
     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
+      # literal pattern
+      PLit = TypedData.define(value: Atom)
+
+      # `!` or `!pat` ; inner=PWild matches any error
+      PErr = TypedData.define(inner: Pattern)
+
+      # binds
+      PBind = TypedData.define(name: IDENTIFIER)
+
+      # `_`
+      PWild = TypedData.define(dummy: NilClass)
+
+      # [PatternItem|PatternRest], at most one rest
+      PArr = TypedData.define(items: ->(v) {
         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
+
+      # [PatternPair|PatternRest], one rest, distinct keys
+      PObj = TypedData.define(pairs: ->(v) {
         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
+
+      # `inner ? predicate`
+      PGuard = TypedData.define(inner: Pattern, pred_expr: Expression)
 
       constants.each do |name|
         node = const_get(name)
@@ -85,7 +134,7 @@ module Fusion
 
     module Statement
       # The only statement. Only allowed in the REPL. `name = expression`.
-      Assignment = TypedData.define(name: Identifier, expression: Expression)
+      Assignment = TypedData.define(name: IDENTIFIER, expression: Expression)
 
       constants.each do |name|
         node = const_get(name)

data/lib/fusion/atom.rb

@@ -11,7 +11,7 @@ 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 == NULL || v == true || v == false ||
       v.is_a?(Integer) || v.is_a?(Float) || v.is_a?(String)
   }
 end

data/lib/fusion/cli/decoder.rb

@@ -10,9 +10,9 @@ module Fusion
     module Decoder
       extend self
 
-      ENVELOPE_SHAPES = {
-        array: "[0, _] or [1, _]",
-        object: '{"value": _} or {"error": _}',
+      EXPECTED_ENVELOPE_SHAPES = {
+        array: ["[0, _]", "[1, _]"],
+        object: ['{"value": _}', '{"error": _}'],
       }.freeze
 
       # String -> WirePair
@@ -26,7 +26,7 @@ module Fusion
             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
+            [raw[0], raw[1]] if [0, 1].include?(raw[0])
           end
         when :object
           decode_envelope(text, mode) do |raw|
@@ -50,6 +50,10 @@ module Fusion
         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
 
@@ -64,11 +68,12 @@ module Fusion
         return WirePair.new(status: status, data: JSON.generate(inner)) if status
 
         WirePair.new(status: 1, data: JSON.generate(
-          "kind" => "argument_error",
-          "location" => "input",
+          "kind"      => "argument_error",
+          "origin"    => "input",
           "operation" => "decoding input",
-          "input" => raw,
-          "message" => "expected #{ENVELOPE_SHAPES.fetch(mode)}"
+          "status"    => 0,
+          "input"     => raw,
+          "expected"  => EXPECTED_ENVELOPE_SHAPES.fetch(mode),
         ))
       rescue JSON::ParserError
         # TODO: BUG ???

data/lib/fusion/cli/encoder.rb

@@ -12,12 +12,12 @@ module Fusion
       def encode(wire_pair, mode:)
         case mode
         when :bang
-          bang = wire_pair.status.zero? ? "" : "!"
+          bang = wire_pair.status == 0 ? "" : "!"
           "#{bang}#{wire_pair.data}"
         when :array
           "[#{wire_pair.status},#{wire_pair.data}]"
         when :object
-          key = wire_pair.status.zero? ? "value" : "error"
+          key = wire_pair.status == 0 ? "value" : "error"
           "{\"#{key}\":#{wire_pair.data}}"
         else
           raise Unreachable, "Unknown output mode #{mode}"