rusa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c28ea4a3cf8a916002f8824535cd4ff420762aa9ce83480852b58e1abc094dc
+  data.tar.gz: a69bd45ee7cb9b135b46904cedd492956fe8f8ccf02777632f17b8d0d336c810
+SHA512:
+  metadata.gz: 7a26465250a4347e9645b78638dad53b71460a923fe52c366ebce6c9ef258fa7768cadb18040d24b674a406d8c1494a13a1bd2453094abd7c0ae6f2ceae4d52a
+  data.tar.gz: 4445972fbf14b5163f5b096903129248f16ca14cf01cb25b13478cb57bb818587dd77e4c9f9424d4e07c100ab979e360ea0ecd53d25f931abc9ef40ad4368f95

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# Rusa
+
+Rusa is a pure Ruby LALR(1) parser generator. You define a grammar with a Ruby DSL, and Rusa generates a standalone Ruby parser with no runtime gem dependency.
+
+## Features
+
+- Pure Ruby implementation
+- Ruby-first DSL for tokens, precedence, and productions
+- Standalone parser output as a single `.rb` file
+- Conflict reporting for shift/reduce and reduce/reduce cases
+- Line and column tracking in generated parse errors
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "rusa"
+```
+
+Or install it directly:
+
+```bash
+gem install rusa
+```
+
+## Quick Start
+
+Define a grammar:
+
+```ruby
+Rusa.grammar do
+  token :NUMBER, /\d+/
+  token :PLUS, "+"
+  token :STAR, "*"
+  skip /\s+/
+
+  left :PLUS
+  left :STAR
+
+  start :expr
+
+  rule :expr do
+    alt(:expr, :PLUS, :expr) { |left, _, right| [:add, left, right] }
+    alt(:expr, :STAR, :expr) { |left, _, right| [:mul, left, right] }
+    alt(:NUMBER) { |number| number.to_i }
+  end
+end
+```
+
+Generate a parser:
+
+```bash
+exe/rusa generate examples/calc.rb -o calc_parser.rb --class CalcParser
+```
+
+Use the generated parser:
+
+```ruby
+require_relative "calc_parser"
+
+parser = CalcParser.new
+parser.parse("1 + 2 * 3")
+# => [:add, 1, [:mul, 2, 3]]
+```
+
+## DSL Reference
+
+### Tokens and Skips
+
+```ruby
+token :NUMBER, /\d+/
+token :PLUS, "+"
+skip /\s+/
+```
+
+- `token(name, pattern)` accepts a literal string or regular expression.
+- String literals are escaped and anchored automatically.
+- Identifier-like keywords such as `"if"` are emitted with a trailing word boundary.
+
+### Precedence
+
+```ruby
+left :PLUS, :MINUS
+left :STAR, :SLASH
+right :UMINUS
+nonassoc :EQ, :NEQ
+```
+
+Each call creates one precedence level. Later calls bind tighter.
+
+### Rules
+
+```ruby
+start :expr
+
+rule :expr do
+  alt(:expr, :PLUS, :expr) { |left, _, right| [:add, left, right] }
+  alt(:NUMBER) { |number| number.to_i }
+end
+```
+
+Empty productions are written as `alt`.
+
+### Semantic Actions
+
+File-backed grammar blocks are embedded into generated code automatically:
+
+```ruby
+alt(:NUMBER) { |number| number.to_i }
+```
+
+For REPL or eval-driven grammars, use string actions:
+
+```ruby
+alt(:NUMBER).action("_1.to_i")
+alt(:expr, :PLUS, :expr).action("[:add, _1, _3]")
+```
+
+Context precedence is available with `prec`:
+
+```ruby
+alt(:MINUS, :expr).prec(:UMINUS).action("[:neg, _2]")
+```
+
+## CLI
+
+Generate a parser:
+
+```bash
+exe/rusa generate GRAMMAR.rb [-o OUTPUT.rb] [--class NAME] [--compact] [--verbose] [--no-line-tracking]
+```
+
+Inspect conflicts and warnings:
+
+```bash
+exe/rusa report GRAMMAR.rb
+```
+
+Validate a grammar:
+
+```bash
+exe/rusa check GRAMMAR.rb
+```
+
+## Examples
+
+- `examples/calc.rb`: arithmetic expressions with precedence
+- `examples/json.rb`: JSON parser returning Ruby objects
+- `examples/mini_lang.rb`: small statement language with `if`, `while`, and assignment
+
+## Development
+
+Run the test suite:
+
+```bash
+rake test
+```
+
+Refresh generated signatures and run the type checker:
+
+```bash
+rake sig:generate
+bundle exec steep check
+```
+
+Or directly:
+
+```bash
+ruby -Ilib -Itest -e "Dir['test/test_*.rb'].sort.each { |f| require_relative f }"
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "lib"
+  task.libs << "test"
+  task.pattern = "test/test_*.rb"
+  task.warning = true
+end
+
+desc "Generate RBS files from inline annotations"
+task :"sig:generate" do
+  sh "rbs-inline", "--opt-out", "--output", "sig/generated", "lib"
+end
+
+begin
+  require "steep/rake_task"
+
+  Steep::RakeTask.new(:steep)
+rescue LoadError
+  nil
+end
+
+task default: :test

data/Steepfile

@@ -0,0 +1,9 @@
+target :rusa do
+  check "lib"
+  signature "sig"
+
+  library "base64"
+  library "erb"
+  library "optparse"
+  library "ripper"
+end

data/examples/calc.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../lib/rusa"
+
+Rusa.grammar do
+  token :NUMBER,(/\d+(?:\.\d+)?/)
+  token :PLUS, "+"
+  token :MINUS, "-"
+  token :STAR, "*"
+  token :SLASH, "/"
+  token :LPAREN, "("
+  token :RPAREN, ")"
+
+  skip(/\s+/)
+
+  left :PLUS, :MINUS
+  left :STAR, :SLASH
+
+  start :expr
+
+  rule :expr do
+    alt(:expr, :PLUS, :expr) { |left, _, right| [:add, left, right] }
+    alt(:expr, :MINUS, :expr) { |left, _, right| [:sub, left, right] }
+    alt(:expr, :STAR, :expr) { |left, _, right| [:mul, left, right] }
+    alt(:expr, :SLASH, :expr) { |left, _, right| [:div, left, right] }
+    alt(:LPAREN, :expr, :RPAREN) { |_, expression, _| expression }
+    alt(:NUMBER) { |number| number.include?(".") ? number.to_f : number.to_i }
+  end
+end

data/examples/json.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../lib/rusa"
+
+Rusa.grammar do
+  token :LBRACE, "{"
+  token :RBRACE, "}"
+  token :LBRACKET, "["
+  token :RBRACKET, "]"
+  token :COLON, ":"
+  token :COMMA, ","
+  token :TRUE, "true"
+  token :FALSE, "false"
+  token :NULL, "null"
+  token :STRING,(/"(?:\\.|[^"\\])*"/)
+  token :NUMBER,(/-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/)
+
+  skip(/\s+/)
+
+  start :value
+
+  rule :value do
+    alt(:object).action("_1")
+    alt(:array).action("_1")
+    alt(:STRING).action("_1[1..-2]")
+    alt(:NUMBER).action("_1.match?(/[.eE]/) ? _1.to_f : _1.to_i")
+    alt(:TRUE).action("true")
+    alt(:FALSE).action("false")
+    alt(:NULL).action("nil")
+  end
+
+  rule :object do
+    alt(:LBRACE, :members, :RBRACE).action("_2")
+    alt(:LBRACE, :RBRACE).action("{}")
+  end
+
+  rule :members do
+    alt(:pair).action("{ _1[0] => _1[1] }")
+    alt(:members, :COMMA, :pair).action("_1.merge(_3[0] => _3[1])")
+  end
+
+  rule :pair do
+    alt(:STRING, :COLON, :value).action("[_1[1..-2], _3]")
+  end
+
+  rule :array do
+    alt(:LBRACKET, :elements, :RBRACKET).action("_2")
+    alt(:LBRACKET, :RBRACKET).action("[]")
+  end
+
+  rule :elements do
+    alt(:value).action("[_1]")
+    alt(:elements, :COMMA, :value).action("_1 + [_3]")
+  end
+end

data/examples/mini_lang.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../lib/rusa"
+
+Rusa.grammar do
+  token :IF, "if"
+  token :THEN, "then"
+  token :ELSE, "else"
+  token :WHILE, "while"
+  token :DO, "do"
+  token :END, "end"
+  token :IDENT,(/[a-z_]\w*/)
+  token :NUMBER,(/\d+/)
+  token :ASSIGN, "="
+  token :SEMI, ";"
+  token :PLUS, "+"
+  token :STAR, "*"
+  token :LPAREN, "("
+  token :RPAREN, ")"
+
+  skip(/\s+/)
+
+  left :PLUS
+  left :STAR
+
+  start :program
+
+  rule :program do
+    alt(:stmts).action("[:program, _1]")
+  end
+
+  rule :stmts do
+    alt(:stmt).action("[_1]")
+    alt(:stmts, :SEMI, :stmt).action("_1 + [_3]")
+  end
+
+  rule :stmt do
+    alt(:IDENT, :ASSIGN, :expr).action("[:assign, _1, _3]")
+    alt(:IF, :expr, :THEN, :stmts, :END).action("[:if, _2, _4]")
+    alt(:IF, :expr, :THEN, :stmts, :ELSE, :stmts, :END).action("[:if, _2, _4, _6]")
+    alt(:WHILE, :expr, :DO, :stmts, :END).action("[:while, _2, _4]")
+    alt(:expr).action("_1")
+  end
+
+  rule :expr do
+    alt(:expr, :PLUS, :expr).action("[:add, _1, _3]")
+    alt(:expr, :STAR, :expr).action("[:mul, _1, _3]")
+    alt(:LPAREN, :expr, :RPAREN).action("_2")
+    alt(:NUMBER).action("_1.to_i")
+    alt(:IDENT).action("[:var, _1]")
+  end
+end

data/exe/rusa

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rusa"
+
+exit(Rusa::CLI.new.run(ARGV))

data/lib/rusa/analysis/automaton.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rusa
+  module Analysis
+    # Automaton builds the canonical LR(0) state graph.
+    class Automaton
+      attr_reader :states #: Array[ItemSet]
+      attr_reader :transitions #: Hash[Integer, Hash[Symbol, Integer]]
+
+      #: (Grammar::Grammar) -> void
+      def initialize(grammar)
+        @grammar = grammar
+        @states = []
+        @transitions = Hash.new do |hash, key|
+          hash[key] = {} #: Hash[Symbol, Integer]
+        end
+        build
+      end
+
+      private
+
+      attr_reader :grammar #: Grammar::Grammar
+
+      #: () -> void
+      def build
+        start_item = Item.new(grammar.augmented_production, 0)
+        state0 = ItemSet.new(0, [start_item], grammar)
+        @states << state0
+
+        known_states = { kernel_key(state0.kernel_items) => state0 }
+        worklist = [state0]
+
+        until worklist.empty?
+          current = worklist.shift
+          symbols = current.items.map(&:next_symbol).compact.uniq
+
+          symbols.each do |symbol|
+            kernel_items = current.items.select { |item| item.next_symbol == symbol }.map(&:advance)
+            key = kernel_key(kernel_items)
+            target = known_states[key]
+
+            unless target
+              target = ItemSet.new(states.length, kernel_items, grammar)
+              known_states[key] = target
+              states << target
+              worklist << target
+            end
+
+            transitions[current.id][symbol] = target.id
+          end
+        end
+      end
+
+      #: (Enumerable[Item]) -> Array[Array[Integer?]]
+      def kernel_key(items)
+        items.map { |item| [item.production.id, item.dot] }.sort.freeze
+      end
+    end
+  end
+end

data/lib/rusa/analysis/conflict_resolver.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Rusa
+  module Analysis
+    class ConflictReport
+      attr_reader :state_id #: Integer
+      attr_reader :lookahead #: Symbol
+      attr_reader :existing_action #: Shift | Reduce | Accept
+      attr_reader :new_action #: Shift | Reduce | Accept
+      attr_reader :resolved_action #: Shift | Reduce | Accept | nil
+      attr_reader :message #: String
+
+      #: (state_id: Integer, lookahead: Symbol, existing_action: Shift | Reduce | Accept, new_action: Shift | Reduce | Accept, resolved_action: Shift | Reduce | Accept | nil, message: String) -> void
+      def initialize(
+        state_id:,
+        lookahead:,
+        existing_action:,
+        new_action:,
+        resolved_action:,
+        message:
+      )
+        @state_id = state_id
+        @lookahead = lookahead
+        @existing_action = existing_action
+        @new_action = new_action
+        @resolved_action = resolved_action
+        @message = message
+        freeze
+      end
+    end
+
+    # ConflictResolver applies precedence and associativity rules to ACTION conflicts.
+    class ConflictResolver
+      #: (Shift | Reduce | Accept, Shift | Reduce | Accept, Symbol, Grammar::Grammar, state_id: Integer, productions_by_id: Hash[Integer?, Grammar::Production]) -> [Shift | Reduce | Accept | nil, ConflictReport]
+      def resolve(existing_action, new_action, lookahead, grammar, state_id:, productions_by_id:)
+        report = build_report(
+          existing_action,
+          new_action,
+          lookahead,
+          grammar,
+          state_id: state_id,
+          productions_by_id: productions_by_id
+        )
+
+        [report.resolved_action, report]
+      end
+
+      private
+
+      #: (Shift | Reduce | Accept, Shift | Reduce | Accept, Symbol, Grammar::Grammar, state_id: Integer, productions_by_id: Hash[Integer?, Grammar::Production]) -> ConflictReport
+      def build_report(
+        existing_action,
+        new_action,
+        lookahead,
+        grammar,
+        state_id:,
+        productions_by_id:
+      )
+        return resolve_shift_reduce(
+          existing_action,
+          new_action,
+          lookahead,
+          grammar,
+          productions_by_id,
+          state_id
+        ) if existing_action.is_a?(Shift) && new_action.is_a?(Reduce)
+
+        return resolve_shift_reduce(
+          new_action,
+          existing_action,
+          lookahead,
+          grammar,
+          productions_by_id,
+          state_id
+        ) if existing_action.is_a?(Reduce) && new_action.is_a?(Shift)
+
+        return resolve_reduce_reduce(
+          existing_action,
+          new_action,
+          lookahead,
+          state_id
+        ) if existing_action.is_a?(Reduce) && new_action.is_a?(Reduce)
+
+        duplicate_action_report(
+          state_id,
+          lookahead,
+          existing_action,
+          new_action
+        )
+      end
+
+      #: (Shift, Reduce, Symbol, Grammar::Grammar, Hash[Integer?, Grammar::Production], Integer) -> ConflictReport
+      def resolve_shift_reduce(
+        shift_action,
+        reduce_action,
+        lookahead,
+        grammar,
+        productions_by_id,
+        state_id
+      )
+        shift_precedence = grammar.precedence_for(lookahead)
+        reduce_production = productions_by_id.fetch(reduce_action.production_id)
+        reduce_precedence = reduce_production.precedence(grammar)
+
+        resolved_action, message = if shift_precedence && reduce_precedence
+                                     compare_precedences(
+                                       shift_action,
+                                       reduce_action,
+                                       shift_precedence,
+                                       reduce_precedence
+                                     )
+                                   else
+                                     default_shift_resolution(shift_action, lookahead)
+                                   end
+
+        build_conflict_report(
+          state_id: state_id,
+          lookahead: lookahead,
+          existing_action: shift_action,
+          new_action: reduce_action,
+          resolved_action: resolved_action,
+          message: message
+        )
+      end
+
+      #: (Shift, Reduce, Grammar::Precedence, Grammar::Precedence) -> [Shift | Reduce | nil, String]
+      def compare_precedences(shift_action, reduce_action, shift_precedence, reduce_precedence)
+        if shift_precedence.level > reduce_precedence.level
+          return higher_token_precedence_result(shift_action)
+        end
+
+        if shift_precedence.level < reduce_precedence.level
+          return higher_production_precedence_result(reduce_action)
+        end
+
+        case shift_precedence.associativity
+        when :left
+          [reduce_action, "shift/reduce conflict resolved by left associativity"]
+        when :right
+          [shift_action, "shift/reduce conflict resolved by right associativity"]
+        when :nonassoc
+          [nil, "shift/reduce conflict resolved to syntax error by nonassociativity"]
+        else
+          [shift_action, "shift/reduce conflict resolved by default shift"]
+        end
+      end
+
+      #: (Reduce, Reduce, Symbol, Integer) -> ConflictReport
+      def resolve_reduce_reduce(existing_action, new_action, lookahead, state_id)
+        resolved_action = [existing_action, new_action].min_by do |action|
+          action.production_id || -1
+        end
+
+        build_conflict_report(
+          state_id: state_id,
+          lookahead: lookahead,
+          existing_action: existing_action,
+          new_action: new_action,
+          resolved_action: resolved_action,
+          message: "reduce/reduce conflict on #{lookahead} resolved by earlier production"
+        )
+      end
+
+      #: (Integer, Symbol, Shift | Reduce | Accept, Shift | Reduce | Accept) -> ConflictReport
+      def duplicate_action_report(state_id, lookahead, existing_action, new_action)
+        build_conflict_report(
+          state_id: state_id,
+          lookahead: lookahead,
+          existing_action: existing_action,
+          new_action: new_action,
+          resolved_action: existing_action,
+          message: "duplicate action kept for #{lookahead}"
+        )
+      end
+
+      #: (Shift, Symbol) -> [Shift, String]
+      def default_shift_resolution(shift_action, lookahead)
+        [shift_action, "shift/reduce conflict on #{lookahead} resolved by default shift"]
+      end
+
+      #: (Shift) -> [Shift, String]
+      def higher_token_precedence_result(shift_action)
+        [shift_action, "shift/reduce conflict resolved by higher token precedence"]
+      end
+
+      #: (Reduce) -> [Reduce, String]
+      def higher_production_precedence_result(reduce_action)
+        [reduce_action, "shift/reduce conflict resolved by higher production precedence"]
+      end
+
+      #: (state_id: Integer, lookahead: Symbol, existing_action: Shift | Reduce | Accept, new_action: Shift | Reduce | Accept, resolved_action: Shift | Reduce | Accept | nil, message: String) -> ConflictReport
+      def build_conflict_report(
+        state_id:,
+        lookahead:,
+        existing_action:,
+        new_action:,
+        resolved_action:,
+        message:
+      )
+        ConflictReport.new(
+          state_id: state_id,
+          lookahead: lookahead,
+          existing_action: existing_action,
+          new_action: new_action,
+          resolved_action: resolved_action,
+          message: message
+        )
+      end
+    end
+  end
+end