typedargs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f905abf1feb54c54d778f3e7239251181f2945bfd8347207f8d7a1e4bb093c81
+  data.tar.gz: 2ecbbddd89b00e902fcf7963628831d6a16f5cdf2ea7e5aec52d2e7b164470eb
+SHA512:
+  metadata.gz: 4edb87ba2b567ff67af4ef5a86e4a9d3318c181b2c326e0f99c40424980f0634311e039dff710c92f884eb171032313e019d47910ddb71b41c694cc32b97ae21
+  data.tar.gz: 41f77dafb3c330addda8b5b6189311f391eed4cdf069b5c13d1f8b2dadfd3ad20b523c6fe76229e4930dd5e5c4840c2301472867ea15cc61ae98b067ce3bfef8

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,324 @@
+# TypedArgs  
+*A tiny operator‑typed CLI language for structured data.*
+
+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
+
+```
+--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:=`)
+
+```
+--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:
+
+```ruby
+{
+  "servers" => [
+    { "name" => "alpha", "port" => 80 },
+    { "name" => "beta",  "port" => 443 }
+  ]
+}
+```
+
+`+:` always appends a hash to an array.
+
+---
+
+## Short‑Flag Aliases
+
+```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
+```
+
+Every error includes:
+
+- the original argument  
+- a caret pointing to the exact byte  
+- a clear error class  
+
+TypedArgs is self‑teaching.
+
+---
+
+# Operator Semantics
+
+TypedArgs applies flags **in order**.  
+Later flags overwrite earlier ones unless using accumulation operators.
+
+---
+
+## Scalar Assignment (`=`)
+
+| Syntax | Meaning |
+|--------|---------|
+| `--key=value` | assign scalar |
+
+Overwrites previous value.
+
+---
+
+## Scalar Accumulation (`+=`)
+
+| Syntax | Meaning |
+|--------|---------|
+| `--key+=value` | append scalar to array |
+
+Creates array if missing.  
+Overwrites previous non‑array values.
+
+---
+
+## Hash Tuple Assignment (`:fields:=`)
+
+| Syntax | Meaning |
+|--------|---------|
+| `--key:field1,field2:=v1,v2` | assign hash |
+
+Overwrites previous value.
+
+---
+
+## Array of Hashes (`+:fields:=`)
+
+| Syntax | Meaning |
+|--------|---------|
+| `--key+:field1,field2:=v1,v2` | append hash to array |
+
+Creates array if missing.
+
+---
+
+# Sequential Override Rules
+
+| 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.
+
+---
+
+# Conformance Suite
+
+TypedArgs ships with a full conformance suite covering:
+
+- 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  
+
+The suite **is the specification**.  
+If an implementation passes the suite, it is TypedArgs.
+
+---
+
+# Design Philosophy
+
+TypedArgs is intentionally:
+
+- **Explicit** — no guessing  
+- **Portable** — no shell dependencies  
+- **Minimal** — four operators, one grammar  
+- **Deterministic** — predictable and stable  
+- **Structured** — arrays and hashes are first‑class  
+
+TypedArgs does **not** depend on:
+
+- shell brace expansion  
+- shell quoting rules  
+- environment‑specific behavior  
+- Bash‑only features  
+
+The shell’s only job is to pass raw strings.  
+TypedArgs does everything else.
+
+---
+
+# License
+
+Apache‑2

data/lib/typedargs.rb

@@ -0,0 +1,6 @@
+# lib/typedargs.rb
+mrblib = File.expand_path("../mrblib", __dir__)
+
+Dir[File.join(mrblib, "*.rb")].sort.each do |file|
+  require file
+end

data/mrblib/alias.rb

@@ -0,0 +1,26 @@
+module TypedArgs
+  module Internal
+    @alias_map = {}
+
+    class << self
+      def register_alias(short, long)
+        @alias_map[short] = long
+      end
+
+      def resolve_name(raw)
+        mapped = @alias_map[raw]
+        mapped ? strip_leading_dashes(mapped) : strip_leading_dashes(raw)
+      end
+
+      private
+      def strip_leading_dashes(str)
+        i = 0
+        n = str.bytesize
+        while i < n && str[i,1] == "-"
+          i += 1
+        end
+        str[i, n - i]
+      end
+    end
+  end
+end

data/mrblib/impl.rb

@@ -0,0 +1,178 @@
+module TypedArgs
+  module Internal
+    module Impl
+      class << self
+        def parse(argv)
+          out = {}
+          i = 0
+          n = argv.size
+          while i < n
+            a = argv[i]
+            if a && a.length > 0
+              if long_flag?(a)
+                parse_long(out, a)
+              elsif short_flag?(a)
+                parse_short(out, a)
+              end
+            end
+            i += 1
+          end
+          out
+        end
+
+        private
+        def long_flag?(arg)
+          arg.length >= 2 &&
+          arg[0,1] == "-" &&
+          arg[1,1] == "-"
+        end
+
+        def short_flag?(arg)
+          arg.length >= 1 &&
+          arg[0,1] == "-" &&
+          !(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
+
+          # 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
+          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])
+
+          # 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)
+
+            case key_ast[:kind]
+            when :scalar, :array_scalar
+              value = vp.parse_scalar
+            when :hash, :array_hash
+              tuple = vp.parse_tuple(key_ast[:fields].size)
+              value = build_hash(key_ast[:fields], tuple)
+            end
+          else
+            value = true
+          end
+
+          assign(out, name, key_ast, value)
+        end
+
+
+        def parse_short(out, arg)
+          raw  = arg[0,2]
+          name = Internal.resolve_name(raw)
+
+          if name.nil? || name.length == 0
+            raise InvalidKeyStartError.new(
+              "Invalid key start",
+              1,
+              arg
+            )
+          end
+
+          # first character validation (character-mode)
+          c0 = name[0,1]
+          unless c0 == "_" ||
+                (c0 >= "A" && c0 <= "Z") ||
+                (c0 >= "a" && c0 <= "z") ||
+                (c0 > "\u007F") # treat non-ASCII single-char as letter candidate
+            raise InvalidCharacterError.new(
+              "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
+
+          # 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)
+            vp      = ValueParser.new(val_lex)
+            value   = vp.parse_scalar
+          else
+            value = true
+          end
+
+          out[name] = value
+        end
+
+
+        def build_hash(fields, vals)
+          h = {}
+          i = 0
+          while i < fields.size
+            h[fields[i]] = vals[i]
+            i += 1
+          end
+          h
+        end
+
+        def assign(out, name, spec, value)
+          case spec[:kind]
+          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
+          when :array_scalar
+            existing = out[name]
+            arr = existing.is_a?(Array) ? existing : []
+            arr.push(value)
+            out[name] = arr
+          when :array_hash
+            existing = out[name]
+            arr = existing.is_a?(Array) ? existing : []
+            arr.push(value)
+            out[name] = arr
+          end
+        end
+      end
+    end
+  end
+end

data/mrblib/key_parser.rb

@@ -0,0 +1,108 @@
+# key_parser.rb
+module TypedArgs
+  module Internal
+    class KeyParser
+      def initialize(lexer)
+        @lx  = lexer
+        @tok = @lx.next_token
+      end
+
+      def parse
+        key    = parse_key_string
+        array  = false
+        fields = nil
+
+        if key.length > 0 && key[key.length - 1,1] == "."
+          raise UnexpectedTokenError.new("Expected IDENT after DOT", @tok.pos, @lx.str)
+        end
+
+        i = 0
+        while i + 1 < key.length
+          if key[i,1] == "." && key[i + 1,1] == "."
+            raise UnexpectedTokenError.new("Unexpected DOT", @tok.pos, @lx.str)
+          end
+          i += 1
+        end
+
+        if key.index(".") && @tok.type == :PLUS
+          raise InvalidSuffixPositionError.new("Suffix must be at end of key", @tok.pos, @lx.str)
+        end
+
+        if @tok.type == :PLUS
+          consume(:PLUS)
+          array = true
+        end
+
+        if @tok.type == :COLON
+          consume(:COLON)
+          fields = parse_ident_list
+          consume(:COLON)
+        end
+
+        if @tok.type == :PLUS || @tok.type == :COLON || @tok.type == :IDENT || @tok.type == :DOT
+          raise InvalidSuffixPositionError.new("Suffix must be at end of key", @tok.pos, @lx.str)
+        end
+
+        kind =
+          if array && fields then :array_hash
+          elsif array        then :array_scalar
+          elsif fields       then :hash
+          else                   :scalar
+          end
+
+        { name: key, kind: kind, fields: fields }
+      end
+
+      private
+
+      def parse_key_string
+        if @tok.type != :IDENT
+          raise InvalidKeyStartError.new("Invalid key start", @tok.pos, @lx.str)
+        end
+
+        first = expect(:IDENT).value
+        buf   = first
+
+        while @tok.type == :DOT
+          consume(:DOT)
+          if @tok.type != :IDENT
+            raise UnexpectedTokenError.new("Expected IDENT, got " + @tok.type.to_s, @tok.pos, @lx.str)
+          end
+          part = expect(:IDENT).value
+          buf = buf + "." + part
+        end
+
+        buf
+      end
+
+      def parse_ident_list
+        list = []
+        if @tok.type != :IDENT
+          raise InvalidFieldListError.new("Expected IDENT", @tok.pos, @lx.str)
+        end
+        list.push(expect(:IDENT).value)
+        while @tok.type == :COMMA
+          consume(:COMMA)
+          if @tok.type != :IDENT
+            raise InvalidFieldListError.new("Expected IDENT", @tok.pos, @lx.str)
+          end
+          list.push(expect(:IDENT).value)
+        end
+        list
+      end
+
+      def expect(type)
+        if @tok.type != type
+          raise UnexpectedTokenError.new("Expected #{type}, got #{@tok.type}", @tok.pos, @lx.str)
+        end
+        tok = @tok
+        @tok = @lx.next_token
+        tok
+      end
+
+      def consume(type)
+        expect(type)
+      end
+    end
+  end
+end

data/mrblib/lexer.rb

@@ -0,0 +1,212 @@
+# lexer.rb (optimized)
+module TypedArgs
+  module Internal
+    class Lexer
+      attr_reader :str
+
+      def initialize(str, start_pos, char_length, parsing_key = false)
+        @str = str || ""
+        @parsing_key = !!parsing_key
+        @i = start_pos || 0
+        @start = @i
+        @end = [@start + (char_length || 0), @str.length].min
+      end
+
+      def parsing_key?
+        @parsing_key
+      end
+
+      def next_token
+        s = @str
+        i = @i
+        end_i = @end
+
+        # skip whitespace
+        while i < end_i
+          ch = s[i,1]
+          break unless ch <= " "
+          i += 1
+        end
+        @i = i
+        return Token.new(:EOF, nil, i) if i >= end_i
+
+        ch = s[i,1]
+
+        # single-char tokens
+        case ch
+        when "," then @i = i + 1; return Token.new(:COMMA, nil, i)
+        when "=" then @i = i + 1; return Token.new(:EQUAL, nil, i)
+        when "." then @i = i + 1; return Token.new(:DOT, nil, i)
+        when "+" then @i = i + 1; return Token.new(:PLUS, nil, i)
+        when ":" then @i = i + 1; return Token.new(:COLON, nil, i)
+        when "\""
+          start = i
+          i += 1
+
+          # scan UTF‑8 codepoints until closing quote
+          while i < end_i
+            cp, ni = Internal.utf8_next(s, i)
+
+            if cp == 0x22  # '"'
+              val = s[start + 1, i - (start + 1)]
+              @i = ni
+              return Token.new(:STRING, val, start)
+            end
+
+            i = ni
+          end
+
+          raise UnterminatedStringError.new("Unterminated string", start, s)
+        end
+
+        # parsing_key fast path
+        if @parsing_key
+          return ident_token_fast(s, i, end_i)
+        end
+
+        # value side: number, ident-like, or raw
+        if ascii_digit?(ch) || (ch == "-" && peek_ascii_digit?(s, i, end_i))
+          return number_token_fast(s, i, end_i)
+        end
+
+        if ident_start_char?(ch)
+          # try to scan an ident-like token; if any char fails ident_continue, fall back to raw
+          j = i
+          all_ident = true
+          while j < end_i
+            cc = s[j,1]
+            break if cc == ","
+            unless ident_continue_char?(cc)
+              all_ident = false
+              break
+            end
+            j += 1
+          end
+          if all_ident
+            # produce IDENT token
+            val = s[i, j - i]
+            @i = j
+            return Token.new(:IDENT, val, i)
+          else
+            # raw value: scan until whitespace or comma
+            start = i
+            while i < end_i
+              cc = s[i,1]
+              break if cc == ","
+              i += 1
+            end
+            val = s[start, i - start]
+            @i = i
+            # detect all-dash invalid number
+            if all_dashes?(val)
+              raise InvalidCharacterError.new("Illegal number", start, s)
+            end
+            return Token.new(:STRING, val, start)
+          end
+        end
+
+        # fallback raw value
+        start = i
+        while i < end_i
+          cc = s[i,1]
+          break if cc == ","
+          i += 1
+        end
+        val = s[start, i - start]
+        @i = i
+        if all_dashes?(val)
+          raise InvalidCharacterError.new("Illegal number", start, s)
+        end
+        Token.new(:STRING, val, start)
+      end
+
+      private
+
+      # IDENT token when parsing_key true
+      def ident_token_fast(s, i, end_i)
+        start = i
+        ch = s[i,1]
+        unless ident_start_char?(ch)
+          if ascii_digit?(ch)
+            raise InvalidKeyStartError.new("Invalid key start", i, s)
+          else
+            raise InvalidCharacterError.new("Illegal character in key", i, s)
+          end
+        end
+        i += 1
+        while i < end_i
+          c = s[i,1]
+          break unless ident_continue_char?(c)
+          i += 1
+        end
+        val = s[start, i - start]
+        @i = i
+        Token.new(:IDENT, val, start)
+      end
+
+      def number_token_fast(s, i, end_i)
+        start = i
+        digits = 0
+        dot = false
+
+        if s[i,1] == "-"
+          i += 1
+        end
+
+        while i < end_i
+          c = s[i,1]
+          if ascii_digit?(c)
+            digits += 1
+            i += 1
+          elsif c == "."
+            raise InvalidNumberError.new("Invalid number format", start, s) if dot
+            dot = true
+            i += 1
+          else
+            break
+          end
+        end
+
+        raise InvalidCharacterError.new("Illegal number", start, s) if digits == 0
+
+        val = s[start, i - start]
+        @i = i
+        Token.new(:NUMBER, val, start)
+      end
+
+      # helpers (inlined ASCII fast paths)
+      def ascii_digit?(ch)
+        ch >= "0" && ch <= "9"
+      end
+
+      def all_dashes?(str)
+        k = 0
+        while k < str.length
+          return false if str[k,1] != "-"
+          k += 1
+        end
+        true
+      end
+
+      def ident_start_char?(ch)
+        return true if ch == "_"
+        return true if (ch >= "A" && ch <= "Z") || (ch >= "a" && ch <= "z")
+        # non-ASCII single-char candidate
+        ch.length == 1 && ch > "\u007F"
+      end
+
+      def ident_continue_char?(ch)
+        return true if ident_start_char?(ch)
+        return true if ascii_digit?(ch)
+        return true if ch == "-" || ch == "."
+        false
+      end
+
+      def peek_ascii_digit?(s, i, end_i)
+        return false if (i + 1) >= end_i
+        c = s[i + 1,1]
+        c >= "0" && c <= "9"
+      end
+    end
+  end
+end

data/mrblib/script_check.rb

@@ -0,0 +1,62 @@
+# script_check.rb (optimized)
+module TypedArgs
+  module Internal
+    module ScriptCheck
+      LATIN_RANGES = [
+        ["\u00C0", "\u024F"]
+      ]
+      GREEK_RANGES = [
+        ["\u0370", "\u03FF"]
+      ]
+      CYRILLIC_RANGES = [
+        ["\u0400", "\u04FF"]
+      ]
+
+      def self.in_ranges?(ch, ranges)
+        j = 0
+        while j < ranges.length
+          start_ch, end_ch = ranges[j]
+          return true if ch >= start_ch && ch <= end_ch
+          j += 1
+        end
+        false
+      end
+
+      def self.char_bucket(ch)
+        return :latin    if (ch >= "A" && ch <= "Z") || (ch >= "a" && ch <= "z") || in_ranges?(ch, LATIN_RANGES)
+        return :greek    if in_ranges?(ch, GREEK_RANGES)
+        return :cyrillic if in_ranges?(ch, CYRILLIC_RANGES)
+        :other
+      end
+
+      def self.validate_key(str)
+        seen = nil
+        i = 0
+        n = str.length
+        while i < n
+          ch = str[i,1]
+          # skip punctuation
+          if ch == "." || ch == "+" || ch == ":" || ch == ","
+            i += 1
+            next
+          end
+          # underscore and digits ignored for bucket
+          if ch == "_" || (ch >= "0" && ch <= "9")
+            i += 1
+            next
+          end
+
+          bucket = char_bucket(ch)
+          if bucket != :other
+            if seen && seen != bucket
+              raise InvalidCharacterError.new("Invalid or mixed-script key", i, str)
+            end
+            seen ||= bucket
+          end
+          i += 1
+        end
+        true
+      end
+    end
+  end
+end

data/mrblib/token.rb

@@ -0,0 +1,12 @@
+module TypedArgs
+  module Internal
+    class Token
+      attr_accessor :type, :value, :pos
+      def initialize(type, value, pos)
+        @type  = type
+        @value = value
+        @pos   = pos
+      end
+    end
+  end
+end

data/mrblib/typedargs.rb

@@ -0,0 +1,35 @@
+module TypedArgs
+  class Error < StandardError; end
+  class SyntaxError < Error
+    attr_reader :pos, :source
+
+    def initialize(msg, pos, source)
+      @pos    = pos
+      @source = source || ""
+      line    = @source
+      pointer = " " * @pos + "^"
+      pretty  = "\n" + line + "\n" + pointer + "\nSyntax error: " + msg
+      super(pretty)
+    end
+  end
+
+  class InvalidCharacterError < SyntaxError; end
+  class InvalidKeyStartError < SyntaxError; end
+  class UnterminatedStringError < SyntaxError; end
+  class ArityMismatchError < SyntaxError; end
+  class UnexpectedTokenError < SyntaxError; end
+  class InvalidSuffixPositionError < SyntaxError; end
+  class InvalidFieldListError < SyntaxError; end
+  class InvalidNumberError < SyntaxError; end
+
+  class << self
+    def alias(short, long)
+      Internal.register_alias(short, long)
+    end
+
+    def opts(*argv)
+      args = argv.empty? ? ::ARGV : argv
+      Internal::Impl.parse(args)
+    end
+  end
+end

data/mrblib/utf8.rb

@@ -0,0 +1,46 @@
+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
+      b >= 0xA0
+    end
+
+    def self.utf8_next(str, i)
+      b0 = str.getbyte(i)
+      return [nil, i + 1] if b0.nil?
+
+      if b0 < 0x80
+        return [b0, i + 1]
+      elsif (b0 & 0xE0) == 0xC0
+        b1 = str.getbyte(i + 1)
+        return [nil, i + 1] if b1.nil? || (b1 & 0xC0) != 0x80
+        cp = ((b0 & 0x1F) << 6) | (b1 & 0x3F)
+        return [cp, i + 2]
+      elsif (b0 & 0xF0) == 0xE0
+        b1 = str.getbyte(i + 1)
+        b2 = str.getbyte(i + 2)
+        return [nil, i + 1] if b1.nil? || b2.nil?
+        return [nil, i + 1] if (b1 & 0xC0) != 0x80 || (b2 & 0xC0) != 0x80
+        cp = ((b0 & 0x0F) << 12) | ((b1 & 0x3F) << 6) | (b2 & 0x3F)
+        return [cp, i + 3]
+      elsif (b0 & 0xF8) == 0xF0
+        b1 = str.getbyte(i + 1)
+        b2 = str.getbyte(i + 2)
+        b3 = str.getbyte(i + 3)
+        return [nil, i + 1] if b1.nil? || b2.nil? || b3.nil?
+        return [nil, i + 1] if (b1 & 0xC0) != 0x80 || (b2 & 0xC0) != 0x80 || (b3 & 0xC0) != 0x80
+        cp = ((b0 & 0x07) << 18) | ((b1 & 0x3F) << 12) | ((b2 & 0x3F) << 6) | (b3 & 0x3F)
+        return [cp, i + 4]
+      else
+        return [nil, i + 1]
+      end
+    end
+  end
+end

data/mrblib/value_parser.rb

@@ -0,0 +1,116 @@
+# value_parser.rb
+module TypedArgs
+  module Internal
+    class ValueParser
+      def initialize(lexer)
+        @lx  = lexer
+        @tok = @lx.next_token
+      end
+
+      def parse_tuple(expected)
+        vals = []
+        vals.push(parse_scalar)
+        while @tok.type == :COMMA
+          consume(:COMMA)
+          vals.push(parse_scalar)
+        end
+        if vals.size != expected
+          raise ArityMismatchError.new("Arity mismatch: expected #{expected}, got #{vals.size}", @tok.pos, @lx.str)
+        end
+        vals
+      end
+
+      def parse_scalar
+        if @tok.type == :EOF
+          raise UnexpectedTokenError.new("Unexpected EOF", @tok.pos, @lx.str)
+        end
+
+        case @tok.type
+        when :STRING
+          v = @tok.value
+          consume(:STRING)
+          v
+        when :NUMBER
+          v = @tok.value
+          consume(:NUMBER)
+          convert_number_token(v)
+        when :IDENT
+          v = @tok.value
+          consume(:IDENT)
+          case v
+          when "true"  then true
+          when "false" then false
+          when "nil"   then nil
+          else
+            v
+          end
+        else
+          buf = ""
+          while @tok.type != :COMMA && @tok.type != :EOF
+            buf += @tok.value.to_s
+            @tok = @lx.next_token
+          end
+          buf
+        end
+      end
+
+      private
+
+      def convert_number_token(s)
+        return s.to_i if integer_string?(s)
+        if Object.const_defined?(:Float)
+          return s.to_f if float_string?(s)
+        end
+        raise InvalidNumberError.new("Invalid number", @tok.pos, s)
+      end
+
+      def integer_string?(s)
+        i = 0
+        n = s.length
+        return false if n == 0
+        if s[0,1] == "-"
+          return false if n == 1
+          i = 1
+        end
+        while i < n
+          ch = s[i,1]
+          return false unless ch >= "0" && ch <= "9"
+          i += 1
+        end
+        true
+      end
+
+      def float_string?(s)
+        i = 0
+        n = s.length
+        return false if n == 0
+        if s[0,1] == "-"
+          return false if n == 1
+          i = 1
+        end
+        seen_dot = false
+        digits = 0
+        while i < n
+          ch = s[i,1]
+          if ch == "."
+            return false if seen_dot
+            seen_dot = true
+          elsif ch >= "0" && ch <= "9"
+            digits += 1
+          else
+            return false
+          end
+          i += 1
+        end
+        seen_dot && digits > 0
+      end
+
+      def consume(type)
+        if @tok.type != type
+          raise UnexpectedTokenError.new("Expected #{type}, got #{@tok.type}", @tok.pos, @lx.str)
+        end
+        @tok = @lx.next_token
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: typedargs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Asmod4n
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Pure Ruby implementation of TypedArgs, a small explicit grammar for structured
+  CLI argument parsing. Works on both MRuby and CRuby.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/typedargs.rb
+- mrblib/alias.rb
+- mrblib/impl.rb
+- mrblib/key_parser.rb
+- mrblib/lexer.rb
+- mrblib/script_check.rb
+- mrblib/token.rb
+- mrblib/typedargs.rb
+- mrblib/utf8.rb
+- mrblib/value_parser.rb
+homepage: https://github.com/Asmod4n/mruby-typedargs
+licenses:
+- Apache-2.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+- mrblib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A tiny, deterministic operator-typed CLI language.
+test_files: []