typedargs 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18e8da4103e973fd33e84a569315cfa95fb7731d2e180b6f49ab262419276523
-  data.tar.gz: 8d5de8f82a6457fa2aba84aacb90b844cd85df516b1913c4f1478713dbd86037
+  metadata.gz: 9b1ff45511cabd1ddd347f7bf662753fefb1c1aa53a9dbb06ea258a94617c24b
+  data.tar.gz: 3b6a22c83f792a6a3c87416479c529aa09a48d21523c84140f32960a2bc01964
 SHA512:
-  metadata.gz: a76557b9aae2ddc4be5cdf109527df2327a7331dcc49a83516f791a144fb575b6d25b63949a6f60184fd7c2d3d752139898c5d2c693b51e97bad5b35773f1391
-  data.tar.gz: 412f7e5f0d15480df49f57ab5757541887b0f3984e51d05cfcac381d2453b95ac1986751b24e7a6fb4c914787e2931b058e5a1eb2f40d9923c7a8ca754eaba8c
+  metadata.gz: 2747b98351471ec61b2669ff3f7165ca8c96b4d36c31ab964be8e2781bc08584a9aca7824bee4faf301dbc74c891d5d58a124dfa063ff71e5459bcdf5d0f615b
+  data.tar.gz: b4b65d4e167065a4948fd0f3f577f57371c71012a24d2c949f38a5bd455e8d765e112b8723f97908653bfa3ce1fa9cafae55198a48a21ef720748c4b2f7f3d22

data/README.md

@@ -1,324 +1,133 @@
-# TypedArgs  
-*A tiny operator‑typed CLI language for structured data.*
+# TypedArgs
 
-TypedArgs is not an option parser.  
-It is a **mini‑language** for expressing structured data on the command line — scalars, arrays, hashes, and arrays of hashes — using a small set of explicit, shell‑safe operators.
-
-It runs anywhere MRuby runs: embedded systems, containers, CI runners, Windows, macOS, Linux, BusyBox, Alpine, and fully sandboxed MRuby VMs. No dependencies. No shell tricks. No heuristics. No guessing.
-
-TypedArgs behaves the same everywhere.
-
----
-
-# Why TypedArgs Exists
-
-Most CLI parsers try to *guess* what the user meant. TypedArgs refuses.  
-Shells are inconsistent. Quoting rules differ. JSON on the command line is painful.  
-Suffix‑typed flags collide with shells. YAML is too heavy.  
-Users deserve a grammar that is:
-
-- **Explicit** — the operator defines the shape  
-- **Portable** — works in every shell without quoting  
-- **Deterministic** — same input, same output, always  
-- **Minimal** — four operators, one mental model  
-- **Structured** — arrays and hashes are first‑class citizens  
-
-TypedArgs is the answer: a tiny algebra of flags.
-
----
-
-# The Operator Model
-
-TypedArgs is built on four operators.  
-They define the shape of the value — nothing else is needed.
-
-| Operator | Meaning |
-|----------|---------|
-| `=` | scalar assignment |
-| `+=` | append scalar to array |
-| `:fields:=` | assign hash tuple |
-| `+:fields:=` | append hash tuple to array |
-
-This is the entire language.
-
-No suffixes.  
-No brackets.  
-No type inference.  
-No shell‑sensitive characters.  
-Just operators.
-
----
-
-# Installation
-
-TypedArgs is pure Ruby and MRuby‑core‑friendly.  
-Drop the Ruby files into your MRuby build or load them into your VM.
-
----
-
-# Basic Usage
-
-```ruby
-args = TypedArgs.opts("--mode=fast", "--debug=true")
-
-args["mode"]   # => "fast"
-args["debug"]  # => true
-```
-
-If no arguments are passed, `TypedArgs.opts` defaults to `ARGV`.  
-You must supply that array yourself in MRuby; see `tools/typedargs_test/test.c` for an example.
-
----
-
-# Grammar Overview
-
-TypedArgs defines a small, explicit grammar for keys and values.  
-Everything is driven by operators.
-
----
-
-## Scalars
+Structured CLI arguments for mruby and CRuby. Lets you pass arrays, hashes, and arrays of records on the command line without quoting JSON or writing a config file.
 
 ```
 --mode=fast
---count=5
---debug=true
---foo=nil
-```
-
-Values may be:
-
-- strings  
-- integers  
-- floats  
-- booleans (`true` / `false`)  
-- `nil`  
-
----
-
-## Dotted Keys
-
-```
---db.user=root
---cache.redis.host=localhost
-```
-
-Keys may contain:
-
-- letters  
-- digits  
-- underscore  
-- dash  
-- dot  
-
-Keys may **not** start with a digit or dash.  
-Dotted keys are treated as **flat strings**, not nested hashes.
-
----
-
-## Arrays (`+=`)
-
-```
---item+=a
---item+=b
-```
-
-Result:
-
-```ruby
-{ "item" => ["a", "b"] }
-```
-
-`+=` always appends.  
-If the key didn’t exist, an array is created.
-
----
-
-## Hash Tuples (`:fields:=`)
-
-```
+--item+=apple --item+=banana
 --range:min,max:=5,10
-```
-
-Result:
-
-```ruby
-{ "range" => { "min" => 5, "max" => 10 } }
-```
-
-Arity is enforced:  
-If you declare two fields, you must supply two values.
-
----
-
-## Arrays of Hashes (`+:fields:=`)
-
-```
 --servers+:name,port:=alpha,80
 --servers+:name,port:=beta,443
 ```
 
-Result:
+becomes
 
 ```ruby
 {
+  "mode"    => "fast",
+  "item"    => ["apple", "banana"],
+  "range"   => {"min" => 5, "max" => 10},
   "servers" => [
-    { "name" => "alpha", "port" => 80 },
-    { "name" => "beta",  "port" => 443 }
+    {"name" => "alpha", "port" => 80},
+    {"name" => "beta",  "port" => 443}
   ]
 }
 ```
 
-`+:` always appends a hash to an array.
-
----
+It's a small, dependency-free parser that runs anywhere mruby runs (embedded, BusyBox, Alpine, sandboxed VMs) and on CRuby ≥ 2.5.
 
-## Short‑Flag Aliases
+## When you'd want this
 
-```ruby
-TypedArgs.alias("-v", "--verbose")
-TypedArgs.opts("-v")
-# => { "verbose" => true }
-```
-
-Aliases expand before parsing.  
-They can target dotted keys and any operator form.
-
----
-
-# Error Reporting
-
-TypedArgs provides compiler‑style diagnostics with caret indicators.
-
-Example:
-
-```
---range:min,max:=5
-                 ^
-Syntax error: Arity mismatch: expected 2, got 1
-```
+You have a CLI that takes input that's genuinely structured — a list of servers, a set of feature toggles, a hash of coordinates — and the alternatives don't fit:
 
-Every error includes:
+- JSON on argv means escaping `'{"servers":[{"name":"alpha"}]}'` past the shell.
+- Repeating a flag with an ad-hoc convention (`--server alpha:80 --server beta:443`) means inventing a mini-syntax per tool.
+- A config file is heavy when you only have three values to pass.
 
-- the original argument  
-- a caret pointing to the exact byte  
-- a clear error class  
+If your CLI takes scalars and the occasional list, a normal option parser is probably a better fit. TypedArgs earns its place when structure is the point.
 
-TypedArgs is self‑teaching.
+## The four operators
 
----
+| Form | Meaning |
+|---|---|
+| `--key=value` | scalar |
+| `--key+=value` | append to array |
+| `--key:f1,f2:=v1,v2` | hash with named fields |
+| `--key+:f1,f2:=v1,v2` | append a hash to an array |
 
-# Operator Semantics
+Scalar values are auto-typed: integers, floats, `true`, `false`, `nil`, and otherwise strings. Tuple arity is enforced — declaring two fields means you must supply two values.
 
-TypedArgs applies flags **in order**.  
-Later flags overwrite earlier ones unless using accumulation operators.
+## Usage
 
----
-
-## Scalar Assignment (`=`)
-
-| Syntax | Meaning |
-|--------|---------|
-| `--key=value` | assign scalar |
-
-Overwrites previous value.
-
----
-
-## Scalar Accumulation (`+=`)
+```ruby
+require "typedargs"
 
-| Syntax | Meaning |
-|--------|---------|
-| `--key+=value` | append scalar to array |
+args = TypedArgs.opts("--mode=fast", "--debug=true")
+args["mode"]   # => "fast"
+args["debug"]  # => true
+```
 
-Creates array if missing.  
-Overwrites previous non‑array values.
+Calling `TypedArgs.opts` with no arguments reads from `ARGV`. In mruby you provide `ARGV` yourself; see `tools/typedargs_test/test.c`.
 
----
+## Keys
 
-## Hash Tuple Assignment (`:fields:=`)
+Keys are letters, digits, underscore, dash, and dot. They can't start with a digit or dash. Dotted keys (`--db.host=localhost`) are stored as **flat strings**, not nested hashes — `args["db.host"]`, not `args["db"]["host"]`. Auto-nesting opens ambiguities the grammar avoids.
 
-| Syntax | Meaning |
-|--------|---------|
-| `--key:field1,field2:=v1,v2` | assign hash |
+## Short-flag aliases
 
-Overwrites previous value.
+```ruby
+TypedArgs.alias("-v", "--verbose")
+TypedArgs.opts("-v")        # => {"verbose" => true}
+TypedArgs.opts("-vfoo")     # => {"verbose" => "foo"}
+```
 
----
+The alias target can be any long-flag form, including operators:
 
-## Array of Hashes (`+:fields:=`)
+```ruby
+TypedArgs.alias("-r", "--range:min,max:=")
+TypedArgs.opts("-r5,10")    # => {"range" => {"min" => 5, "max" => 10}}
 
-| Syntax | Meaning |
-|--------|---------|
-| `--key+:field1,field2:=v1,v2` | append hash to array |
+TypedArgs.alias("-S", "--servers+:name,port:=")
+TypedArgs.opts("-Salpha,80", "-Sbeta,443")
+# => {"servers" => [{"name"=>"alpha","port"=>80}, {"name"=>"beta","port"=>443}]}
+```
 
-Creates array if missing.
+Aliases are textual rewrites performed before parsing. `TypedArgs.reset_aliases!` clears the alias map (useful in tests).
 
----
+## Override rules
 
-# Sequential Override Rules
+Flags apply in argv order. Later flags overwrite earlier ones unless they're accumulating.
 
 | Sequence | Result |
-|----------|--------|
-| `--foo=1` → `--foo+=2` | `[2]` |
-| `--foo+=1` → `--foo+=2` | `[1,2]` |
-| `--foo:min,max:=1,2` → `--foo:min,max:=3,4` | `{ "min"=>3,"max"=>4 }` |
-| `--foo+:min,max:=1,2` → `--foo+:min,max:=3,4` | `[{"min"=>1,"max"=>2},{"min"=>3,"max"=>4}]` |
-| `--foo=1` → `--foo+=2` → `--foo:name:=alpha` → `--foo=bar` | `"bar"` |
-
-TypedArgs is explicit:  
-the operator determines the shape.
-
----
+|---|---|
+| `--foo=1` then `--foo+=2` | `[2]` |
+| `--foo+=1` then `--foo+=2` | `[1, 2]` |
+| `--foo:a,b:=1,2` then `--foo:a,b:=3,4` | `{"a"=>3, "b"=>4}` |
+| `--foo+:a,b:=1,2` then `--foo+:a,b:=3,4` | `[{"a"=>1,"b"=>2}, {"a"=>3,"b"=>4}]` |
+| `--foo=1`, `--foo+=2`, `--foo:n:=x`, `--foo=bar` | `"bar"` |
 
-# Conformance Suite
+The operator on each flag determines the shape of the value at that key.
 
-TypedArgs ships with a full conformance suite covering:
+## Errors
 
-- scalars  
-- arrays  
-- hashes  
-- arrays of hashes  
-- dotted keys  
-- alias expansion  
-- invalid characters  
-- invalid suffix placement  
-- invalid field lists  
-- tuple arity  
-- invalid numbers  
-- unterminated strings  
-- invalid short flags  
-- invalid dotted paths  
-- empty keys  
-- alias expansion to invalid keys  
+Invalid input raises a `TypedArgs::SyntaxError` subclass with a caret pointing at the offending byte:
 
-The suite **is the specification**.  
-If an implementation passes the suite, it is TypedArgs.
+```
+--range:min,max:=5
+                 ^
+Syntax error: Arity mismatch: expected 2, got 1
+```
 
----
+The exception classes are `InvalidCharacterError`, `InvalidKeyStartError`, `UnterminatedStringError`, `ArityMismatchError`, `UnexpectedTokenError`, `InvalidSuffixPositionError`, `InvalidFieldListError`, and `InvalidNumberError`.
 
-# Design Philosophy
+## Caveats
 
-TypedArgs is intentionally:
+The shell still owns word-splitting and metacharacter handling — `--secret=p$ssw0rd` will need quoting in bash regardless of what TypedArgs does after argv arrives. Strictness around scalars (e.g. `12.34.56` raises rather than parsing as a string) is intentional but stricter than most option parsers.
 
-- **Explicit** — no guessing  
-- **Portable** — no shell dependencies  
-- **Minimal** — four operators, one grammar  
-- **Deterministic** — predictable and stable  
-- **Structured** — arrays and hashes are first‑class  
+## Installation
 
-TypedArgs does **not** depend on:
+For CRuby:
 
-- shell brace expansion  
-- shell quoting rules  
-- environment‑specific behavior  
-- Bash‑only features  
+```
+gem install typedargs
+```
 
-The shell’s only job is to pass raw strings.  
-TypedArgs does everything else.
+For mruby, add to your `build_config.rb`:
 
----
+```ruby
+conf.gem mgem: 'typedargs'
+```
 
-# License
+## License
 
-Apache‑2
+Apache-2.0.

data/mrblib/alias.rb

@@ -7,19 +7,38 @@ module TypedArgs
         @alias_map[short] = long
       end
 
-      def resolve_name(raw)
-        mapped = @alias_map[raw]
-        mapped ? strip_leading_dashes(mapped) : strip_leading_dashes(raw)
+      def reset_aliases!
+        @alias_map = {}
       end
 
-      private
-      def strip_leading_dashes(str)
-        i = 0
-        n = str.bytesize
-        while i < n && str[i,1] == "-"
-          i += 1
+      # If `arg` is a short flag whose first 2 characters are registered as an
+      # alias, return the textually-expanded long-flag form. Otherwise return
+      # nil.
+      #
+      # Expansion rule:
+      #   "-X" alone        →  alias_target
+      #   "-X<payload>"     →  alias_target + payload          (if target ends in "=")
+      #                        alias_target + "=" + payload    (otherwise)
+      #
+      # This makes the README's claim literally true: aliases are textual
+      # substitutions performed before parsing, and they can target dotted
+      # keys and any operator form (`=`, `+=`, `:fields:=`, `+:fields:=`).
+      def expand_short_alias(arg)
+        return nil if arg.nil? || arg.length < 2
+        short_key = arg[0, 2]
+        target = @alias_map[short_key]
+        return nil if target.nil?
+
+        if arg.length > 2
+          payload = arg[2, arg.length - 2]
+          if target.length > 0 && target[target.length - 1, 1] == "="
+            target + payload
+          else
+            target + "=" + payload
+          end
+        else
+          target
         end
-        str[i, n - i]
       end
     end
   end

data/mrblib/impl.rb

@@ -12,7 +12,21 @@ module TypedArgs
               if long_flag?(a)
                 parse_long(out, a)
               elsif short_flag?(a)
-                parse_short(out, a)
+                # Alias expansion happens BEFORE parsing, per the README.
+                # If a 2-char short prefix is aliased, we textually rewrite
+                # the entire arg into a long-flag form and dispatch there.
+                expanded = Internal.expand_short_alias(a)
+                if expanded
+                  if long_flag?(expanded)
+                    parse_long(out, expanded)
+                  else
+                    # Alias target wasn't a long-flag form; treat the original
+                    # arg as a short flag (best-effort fallback).
+                    parse_short(out, a)
+                  end
+                else
+                  parse_short(out, a)
+                end
               end
             end
             i += 1
@@ -21,6 +35,7 @@ module TypedArgs
         end
 
         private
+
         def long_flag?(arg)
           arg.length >= 2 &&
           arg[0,1] == "-" &&
@@ -33,35 +48,28 @@ module TypedArgs
           !(arg.length >= 2 && arg[1,1] == "-")
         end
 
-
-        # In impl.rb, replace parse_long or parse_long-like logic with:
-
         def parse_long(out, arg)
-          # body as character substring (character-mode)
-          body = arg[2, arg.length - 2]   # "--" removed, character-based
+          body = arg[2, arg.length - 2]   # strip "--"
 
-          # find '=' in character mode
           eq_idx = body.index("=")
-
           if eq_idx
-            key_str = body[0, eq_idx]    # character substring for key
-            val_str = body[(eq_idx + 1), body.length - (eq_idx + 1)] # character substring for value
+            key_str = body[0, eq_idx]
+            val_str = body[(eq_idx + 1), body.length - (eq_idx + 1)]
           else
             key_str = body
             val_str = nil
           end
 
-          # parse key in character mode
           key_lex = Lexer.new(key_str, 0, key_str.length, true)
           key_ast = KeyParser.new(key_lex).parse
 
-          name = Internal.resolve_name(key_ast[:name])
+          # Long-flag keys are taken at face value; the alias map applies
+          # only to short flags (per README).
+          name = key_ast[:name]
 
-          # script check (character indices)
           ScriptCheck.validate_key(key_str)
 
           if val_str
-            # parse value in character mode (value lexer now also character-based)
             val_lex = Lexer.new(val_str, 0, val_str.length, false)
             vp = ValueParser.new(val_lex)
 
@@ -79,55 +87,34 @@ module TypedArgs
           assign(out, name, key_ast, value)
         end
 
-
+        # parse_short handles short flags that DO NOT have an alias.
+        # Aliased short flags are rewritten and dispatched to parse_long.
         def parse_short(out, arg)
-          raw  = arg[0,2]
-          name = Internal.resolve_name(raw)
+          # Strip the leading dash; everything after it is the bare name
+          # candidate (until any attached value).
+          name = arg[1, arg.length - 1]
 
           if name.nil? || name.length == 0
             raise InvalidKeyStartError.new(
-              "Invalid key start",
-              1,
-              arg
+              "Invalid key start", 1, arg
             )
           end
 
-          # first character validation (character-mode)
+          # Validate the first character of the short-flag name.
           c0 = name[0,1]
           unless c0 == "_" ||
                 (c0 >= "A" && c0 <= "Z") ||
                 (c0 >= "a" && c0 <= "z") ||
-                (c0 > "\u007F") # treat non-ASCII single-char as letter candidate
+                (c0 > "\u007F")
             raise InvalidCharacterError.new(
-              "Illegal character in short flag",
-              1,
-              arg
+              "Illegal character in short flag", 1, arg
             )
           end
 
-          # remaining characters validation (character-mode)
-          j = 1
-          while j < name.length
-            ch = name[j,1]
-            valid =
-              ch == "_" ||
-              (ch >= "A" && ch <= "Z") ||
-              (ch >= "a" && ch <= "z") ||
-              (ch >= "0" && ch <= "9") ||
-              ch == "-" ||
-              ch == "." ||
-              (ch > "\u007F") # allow non-ASCII letters
-            unless valid
-              raise InvalidCharacterError.new(
-                "Illegal character in short flag",
-                1,
-                arg
-              )
-            end
-            j += 1
-          end
+          # The bare name is just the first character. Everything else
+          # (if any) is the attached value.
+          name = c0
 
-          # attached value (character-mode)
           if arg.length > 2
             val_str = arg[2, arg.length - 2]
             val_lex = Lexer.new(val_str, 0, val_str.length, false)
@@ -140,7 +127,6 @@ module TypedArgs
           out[name] = value
         end
 
-
         def build_hash(fields, vals)
           h = {}
           i = 0
@@ -156,10 +142,8 @@ module TypedArgs
           when :scalar
             out[name] = value
           when :hash
-            existing = out[name]
-            h = existing.is_a?(Hash) ? existing : {}
-            value.each { |k, v| h[k] = v }
-            out[name] = h
+            # Hash tuple assignment overwrites the previous value, per README.
+            out[name] = value
           when :array_scalar
             existing = out[name]
             arr = existing.is_a?(Array) ? existing : []

data/mrblib/lexer.rb

@@ -43,7 +43,7 @@ module TypedArgs
           start = i
           i += 1
 
-          # scan UTF‑8 codepoints until closing quote
+          # scan UTF-8 codepoints until closing quote
           while i < end_i
             cp, ni = Internal.utf8_next(s, i)
 
@@ -88,7 +88,7 @@ module TypedArgs
             @i = j
             return Token.new(:IDENT, val, i)
           else
-            # raw value: scan until whitespace or comma
+            # raw value: scan until comma (the only intra-arg terminator)
             start = i
             while i < end_i
               cc = s[i,1]

data/mrblib/typedargs.rb

@@ -27,6 +27,11 @@ module TypedArgs
       Internal.register_alias(short, long)
     end
 
+    # Clear all registered aliases. Useful for test isolation.
+    def reset_aliases!
+      Internal.reset_aliases!
+    end
+
     def opts(*argv)
       args = argv.empty? ? ::ARGV : argv
       Internal::Impl.parse(args)

data/mrblib/utf8.rb

@@ -1,11 +1,5 @@
 module TypedArgs
   module Internal
-    SCRIPT_ASCII    = 1
-    SCRIPT_LATIN    = 1
-    SCRIPT_GREEK    = 3
-    SCRIPT_CYRILLIC = 4
-    SCRIPT_OTHER    = 5
-
     def self.printable_byte?(b)
       return true  if b >= 0x20 && b <= 0x7E
       return false if b >= 0x80 && b <= 0x9F

data/mrblib/value_parser.rb

@@ -61,7 +61,7 @@ module TypedArgs
         if Object.const_defined?(:Float)
           return s.to_f if float_string?(s)
         end
-        raise InvalidNumberError.new("Invalid number", @tok.pos, s)
+        raise InvalidNumberError.new("Invalid number", @tok.pos, @lx.str)
       end
 
       def integer_string?(s)

data/mrblib/version.rb

@@ -1,3 +1,3 @@
 module TypedArgs
-  VERSION="0.2.0"
+  VERSION="0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typedargs
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Asmod4n
@@ -47,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A tiny, deterministic operator-typed CLI language.
 test_files: []