rusa 0.1.0

data/sig/generated/rusa/grammar/grammar.rbs

@@ -0,0 +1,103 @@
+# Generated from lib/rusa/grammar/grammar.rb with RBS::Inline
+
+module Rusa
+  module Grammar
+    # Grammar keeps the normalized internal representation of the DSL.
+    class Grammar
+      AUGMENTED_START: ::Symbol
+
+      END_OF_INPUT: ::Symbol
+
+      attr_accessor start_symbol: Symbol?
+
+      attr_reader terminals: Hash[Symbol, TerminalSymbol]
+
+      attr_reader nonterminals: Hash[Symbol, NonterminalSymbol]
+
+      attr_reader productions: Array[Production]
+
+      attr_reader precedences: Hash[Symbol, Precedence]
+
+      attr_reader skip_patterns: Array[Regexp]
+
+      attr_reader warnings: Array[String]
+
+      # : () -> void
+      def initialize: () -> void
+
+      # : (Symbol | String, String | Regexp) -> TerminalSymbol
+      def add_terminal: (Symbol | String, String | Regexp) -> TerminalSymbol
+
+      # : (Symbol | String) -> NonterminalSymbol
+      def add_nonterminal: (Symbol | String) -> NonterminalSymbol
+
+      # : (Production) -> Production
+      def add_production: (Production) -> Production
+
+      # : (Regexp) -> Regexp
+      def add_skip_pattern: (Regexp) -> Regexp
+
+      # : (Symbol | String, Integer, Symbol) -> Precedence
+      def set_precedence: (Symbol | String, Integer, Symbol) -> Precedence
+
+      # : (Symbol | String) -> Precedence?
+      def precedence_for: (Symbol | String) -> Precedence?
+
+      # : (Symbol | String) -> Array[Production]
+      def productions_for: (Symbol | String) -> Array[Production]
+
+      # : () -> self
+      def augment!: () -> self
+
+      # : () -> self
+      def validate!: () -> self
+
+      # : () -> Symbol
+      def augmented_start: () -> Symbol
+
+      # : () -> Production
+      def augmented_production: () -> Production
+
+      # : () -> Hash[Symbol, TerminalSymbol | NonterminalSymbol]
+      def symbols: () -> Hash[Symbol, TerminalSymbol | NonterminalSymbol]
+
+      # : (Symbol | String) -> bool
+      def terminal?: (Symbol | String) -> bool
+
+      # : (Symbol | String) -> bool
+      def nonterminal?: (Symbol | String) -> bool
+
+      # : () -> String
+      def dump: () -> String
+
+      private
+
+      # : (Symbol) -> String
+      def duplicate_nonterminal_message: (Symbol) -> String
+
+      # : () -> Symbol
+      def required_start_symbol: () -> Symbol
+
+      # : () -> Array[Symbol]
+      def undefined_symbols: () -> Array[Symbol]
+
+      # : (Production) -> Array[Symbol]
+      def undefined_symbols_in: (Production) -> Array[Symbol]
+
+      # : (Symbol) -> bool
+      def defined_symbol?: (Symbol) -> bool
+
+      # : () -> Array[String]
+      def unreachable_warnings: () -> Array[String]
+
+      # : () -> Array[Production]
+      def reindex_productions!: () -> Array[Production]
+
+      # : () -> Array[Symbol]
+      def unreachable_nonterminals: () -> Array[Symbol]
+
+      # : (Symbol, Array[Symbol]) -> Array[Symbol]
+      def next_reachable_nonterminals: (Symbol, Array[Symbol]) -> Array[Symbol]
+    end
+  end
+end

data/sig/generated/rusa/grammar/precedence.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/rusa/grammar/precedence.rb with RBS::Inline
+
+module Rusa
+  module Grammar
+    # Operator precedence metadata used to resolve parser conflicts.
+    class Precedence
+      attr_reader level: Integer
+
+      attr_reader associativity: Symbol
+
+      # : (Integer, Symbol) -> void
+      def initialize: (Integer, Symbol) -> void
+
+      # : (Object) -> bool
+      def ==: (Object) -> bool
+
+      alias eql? ==
+
+      # : () -> Integer
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/generated/rusa/grammar/rule.rbs

@@ -0,0 +1,35 @@
+# Generated from lib/rusa/grammar/rule.rb with RBS::Inline
+
+module Rusa
+  module Grammar
+    # Production rules connect one nonterminal with a sequence of symbols.
+    class Production
+      attr_accessor id: Integer?
+
+      attr_accessor lhs: Symbol
+
+      attr_accessor rhs: Array[Symbol]
+
+      attr_accessor action: Proc?
+
+      attr_accessor context_precedence: Symbol?
+
+      attr_accessor action_source: String?
+
+      # : (Symbol | String, Array[Symbol | String], ?Proc?, ?context_precedence: Symbol | String?, ?action_source: String?) -> void
+      def initialize: (Symbol | String, Array[Symbol | String], ?Proc?, ?context_precedence: Symbol | String?, ?action_source: String?) -> void
+
+      # : (Grammar) -> Symbol?
+      def precedence_token: (Grammar) -> Symbol?
+
+      # : (Grammar) -> Precedence?
+      def precedence: (Grammar) -> Precedence?
+
+      # : () -> bool
+      def empty?: () -> bool
+
+      # : () -> String
+      def to_s: () -> String
+    end
+  end
+end

data/sig/generated/rusa/grammar/symbol.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/rusa/grammar/symbol.rb with RBS::Inline
+
+module Rusa
+  module Grammar
+    # Terminal symbols are matched by the generated tokenizer.
+    class TerminalSymbol
+      attr_reader name: Symbol
+
+      attr_reader pattern: Regexp
+
+      # : (Symbol | String, String | Regexp) -> void
+      def initialize: (Symbol | String, String | Regexp) -> void
+
+      # : () -> bool
+      def terminal?: () -> bool
+
+      # : () -> bool
+      def nonterminal?: () -> bool
+
+      # : (Object) -> bool
+      def ==: (Object) -> bool
+
+      alias eql? ==
+
+      # : () -> Integer
+      def hash: () -> Integer
+    end
+
+    # Nonterminal symbols are expanded by grammar productions.
+    class NonterminalSymbol
+      attr_reader name: Symbol
+
+      # : (Symbol | String) -> void
+      def initialize: (Symbol | String) -> void
+
+      # : () -> bool
+      def terminal?: () -> bool
+
+      # : () -> bool
+      def nonterminal?: () -> bool
+
+      # : (Object) -> bool
+      def ==: (Object) -> bool
+
+      alias eql? ==
+
+      # : () -> Integer
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/generated/rusa/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/rusa/version.rb with RBS::Inline
+
+module Rusa
+  VERSION: ::String
+end

data/sig/generated/rusa.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/rusa.rb with RBS::Inline
+
+module Rusa
+  # : () { (Grammar::DSL) [self: Grammar::DSL] -> void } -> Grammar::Grammar
+  def self.grammar: () { (Grammar::DSL) [self: Grammar::DSL] -> void } -> Grammar::Grammar
+end

data/test/test_automaton.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class AutomatonTest < Minitest::Test
+  def test_builds_lr0_states_for_balanced_parens_grammar
+    grammar = Rusa.grammar do
+      token :LPAREN, "("
+      token :RPAREN, ")"
+      token :ID, "id"
+
+      start :s
+
+      rule :s do
+        alt(:LPAREN, :s, :RPAREN)
+        alt(:ID)
+      end
+    end
+
+    automaton = Rusa::Analysis::Automaton.new(grammar)
+
+    assert_equal 6, automaton.states.length
+    assert_equal({ s: 1, LPAREN: 2, ID: 3 }, automaton.transitions[0])
+    assert automaton.states.any? { |state| state.items.any? { |item| item.to_s == "s -> LPAREN s · RPAREN" } }
+    assert automaton.states.any? { |state| state.items.any? { |item| item.to_s == "s -> ID ·" } }
+  end
+end

data/test/test_code_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "test_helper"
+
+class CodeGeneratorTest < Minitest::Test
+  def test_generates_parser_from_file_backed_block_actions
+    Dir.mktmpdir do |dir|
+      grammar_path = File.join(dir, "calc.rb")
+      File.write(grammar_path, <<~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
+      RUBY
+
+      grammar = Rusa::CLI.new.send(:load_grammar, grammar_path)
+      table = Rusa::Analysis::LALRTable.new(grammar)
+      code = Rusa::Generator::CodeGenerator.new(grammar, table, class_name: "GeneratedCalcParser").generate
+      parser = build_parser("GeneratedCalcParser", code)
+
+      assert_equal [:add, 3, [:mul, 4, 5]], parser.parse("3 + 4 * 5")
+    end
+  end
+
+  def test_generates_compact_parser_from_action_strings
+    grammar = Rusa.grammar do
+      token :NUMBER,(/\d+/)
+      token :PLUS, "+"
+      skip(/\s+/)
+
+      left :PLUS
+      start :expr
+
+      rule :expr do
+        alt(:expr, :PLUS, :expr).action("[:add, _1, _3]")
+        alt(:NUMBER).action("_1.to_i")
+      end
+    end
+
+    table = Rusa::Analysis::LALRTable.new(grammar)
+    code = Rusa::Generator::CodeGenerator.new(
+      grammar,
+      table,
+      class_name: "CompactExprParser",
+      compact: true
+    ).generate
+    parser = build_parser("CompactExprParser", code)
+
+    assert_includes code, "Base64.decode64"
+    assert_equal [:add, [:add, 1, 2], 3], parser.parse("1 + 2 + 3")
+  end
+
+  private
+
+  def build_parser(class_name, code)
+    Object.send(:remove_const, class_name.to_sym) if Object.const_defined?(class_name, false)
+    Object.class_eval(code)
+    Object.const_get(class_name).new
+  end
+end

data/test/test_dsl.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class DslTest < Minitest::Test
+  def test_dsl_builds_grammar_and_augments_it
+    grammar = Rusa.grammar do
+      token :NUMBER,(/\d+/)
+      token :PLUS, "+"
+      skip(/\s+/)
+      left :PLUS
+
+      start :expr
+
+      rule :expr do
+        alt(:expr, :PLUS, :expr) { |l, _, r| [:add, l, r] }
+        alt(:NUMBER) { |n| n.to_i }
+      end
+    end
+
+    assert grammar.terminals.key?(:NUMBER)
+    assert grammar.terminals.key?(:PLUS)
+    assert grammar.nonterminals.key?(:expr)
+    assert grammar.nonterminals.key?(:"$start")
+    assert_equal 3, grammar.productions.length
+    assert_equal Rusa::Grammar::Precedence.new(1, :left), grammar.precedence_for(:PLUS)
+    assert_equal :expr, grammar.start_symbol
+    assert_equal 1, grammar.skip_patterns.length
+    assert_match(/\Alambda /, grammar.productions[1].action_source)
+  end
+
+  def test_keyword_literals_are_bounded_and_regexes_are_anchored
+    grammar = Rusa.grammar do
+      token :IF, "if"
+      token :IDENT,(/[a-z_]\w*/)
+      skip(/\s+/)
+      start :expr
+
+      rule :expr do
+        alt(:IDENT) { |value| value }
+      end
+    end
+
+    assert_equal "\\Aif\\b", grammar.terminals[:IF].pattern.source
+    assert_equal "\\A(?:[a-z_]\\w*)", grammar.terminals[:IDENT].pattern.source
+    assert_equal "\\A(?:\\s+)", grammar.skip_patterns.first.source
+  end
+
+  def test_action_capture_returns_nil_for_non_file_backed_proc
+    captured = Rusa::Grammar::ActionCapture.capture(eval("proc { |value| value }"))
+
+    assert_nil captured
+  end
+
+  def test_action_capture_does_not_swallow_unexpected_internal_errors
+    action = proc { |value| value }
+    action_capture = Rusa::Grammar::ActionCapture
+    singleton_class = action_capture.singleton_class
+    singleton_class.alias_method(:__extract_block_before_test__, :extract_block)
+    singleton_class.send(:remove_method, :extract_block)
+    singleton_class.define_method(:extract_block) { |_source| raise "boom" }
+
+    error = assert_raises(RuntimeError) do
+      action_capture.capture(action)
+    end
+
+    assert_equal "boom", error.message
+  ensure
+    if singleton_class.method_defined?(:extract_block)
+      singleton_class.send(:remove_method, :extract_block)
+    end
+    if singleton_class.method_defined?(:__extract_block_before_test__)
+      singleton_class.alias_method(:extract_block, :__extract_block_before_test__)
+      singleton_class.send(:remove_method, :__extract_block_before_test__)
+    end
+  end
+end

data/test/test_e2e.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "test_helper"
+
+class E2ETest < Minitest::Test
+  def test_cli_generates_calc_parser_and_parses_examples
+    Dir.mktmpdir do |dir|
+      output_path = File.join(dir, "calc_parser.rb")
+      status, = run_cli(
+        "generate",
+        "examples/calc.rb",
+        "-o",
+        output_path,
+        "--class",
+        "ExampleCalcParser"
+      )
+
+      assert_equal 0, status
+      parser = load_generated_parser("ExampleCalcParser", output_path)
+
+      assert_equal [:add, 1, 2], parser.parse("1 + 2")
+      assert_equal [:add, 1, [:mul, 2, 3]], parser.parse("1 + 2 * 3")
+      assert_equal [:mul, [:add, 1, 2], 3], parser.parse("(1 + 2) * 3")
+      assert_equal [:add, [:add, 1, 2], 3], parser.parse("1 + 2 + 3")
+    end
+  end
+
+  def test_generated_parser_reports_parse_and_lex_errors
+    Dir.mktmpdir do |dir|
+      output_path = File.join(dir, "calc_parser.rb")
+      run_cli(
+        "generate",
+        "examples/calc.rb",
+        "-o",
+        output_path,
+        "--class",
+        "ErrorCalcParser"
+      )
+      parser = load_generated_parser("ErrorCalcParser", output_path)
+
+      parse_error = assert_raises(ErrorCalcParser::ParseError) { parser.parse("1 + + 2") }
+      lex_error = assert_raises(ErrorCalcParser::ParseError) { parser.parse("1 @ 2") }
+
+      assert_includes parse_error.message, "line 1, column 5"
+      assert_includes lex_error.message, "Unexpected character"
+    end
+  end
+
+  def test_epsilon_grammar_parses_optional_prefix
+    Dir.mktmpdir do |dir|
+      grammar_path = File.join(dir, "optional.rb")
+      parser_path = File.join(dir, "optional_parser.rb")
+
+      File.write(grammar_path, <<~RUBY)
+        Rusa.grammar do
+          token :A, "a"
+          token :B, "b"
+          skip(/\\s+/)
+
+          start :s
+
+          rule :s do
+            alt(:a, :B) { |prefix, b| [prefix, b] }
+          end
+
+          rule :a do
+            alt(:A) { |a| a }
+            alt
+          end
+        end
+      RUBY
+
+      run_cli(
+        "generate",
+        grammar_path,
+        "-o",
+        parser_path,
+        "--class",
+        "OptionalParser"
+      )
+      parser = load_generated_parser("OptionalParser", parser_path)
+
+      assert_equal ["a", "b"], parser.parse("a b")
+      assert_equal [nil, "b"], parser.parse("b")
+    end
+  end
+
+  def test_report_command_prints_conflict_information
+    Dir.mktmpdir do |dir|
+      grammar_path = File.join(dir, "dangling_else.rb")
+      File.write(grammar_path, <<~RUBY)
+        Rusa.grammar do
+          token :IF, "if"
+          token :THEN, "then"
+          token :ELSE, "else"
+          token :ID,(/[a-z]+/)
+          skip(/\\s+/)
+
+          start :stmt
+
+          rule :stmt do
+            alt(:IF, :ID, :THEN, :stmt, :ELSE, :stmt)
+            alt(:IF, :ID, :THEN, :stmt)
+            alt(:ID)
+          end
+        end
+      RUBY
+
+      status, stdout = run_cli("report", grammar_path)
+
+      assert_equal 0, status
+      assert_includes stdout, "Conflict report:"
+      assert_includes stdout, "default shift"
+    end
+  end
+
+  private
+
+  def load_generated_parser(class_name, path)
+    Object.send(:remove_const, class_name.to_sym) if Object.const_defined?(class_name, false)
+    Object.class_eval(File.read(path), path)
+    Object.const_get(class_name).new
+  end
+
+  def run_cli(*argv)
+    status = nil
+    stdout, stderr = capture_io do
+      status = Rusa::CLI.new.run(argv)
+    end
+
+    [status, stdout, stderr]
+  end
+end

data/test/test_first_follow.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class FirstFollowTest < Minitest::Test
+  def test_expression_first_and_follow_sets
+    grammar = Rusa.grammar do
+      token :ID, "id"
+      token :PLUS, "+"
+      token :STAR, "*"
+      token :LPAREN, "("
+      token :RPAREN, ")"
+
+      start :e
+
+      rule :e do
+        alt(:e, :PLUS, :t)
+        alt(:t)
+      end
+
+      rule :t do
+        alt(:t, :STAR, :f)
+        alt(:f)
+      end
+
+      rule :f do
+        alt(:LPAREN, :e, :RPAREN)
+        alt(:ID)
+      end
+    end
+
+    first_follow = Rusa::Analysis::FirstFollow.new(grammar)
+
+    assert_equal Set[:LPAREN, :ID], first_follow.first_sets[:f]
+    assert_equal Set[:LPAREN, :ID], first_follow.first_sets[:t]
+    assert_equal Set[:LPAREN, :ID], first_follow.first_sets[:e]
+    assert_equal Set[:$end, :PLUS, :RPAREN], first_follow.follow_sets[:e]
+    assert_equal Set[:$end, :PLUS, :STAR, :RPAREN], first_follow.follow_sets[:t]
+    assert_equal Set[:$end, :PLUS, :STAR, :RPAREN], first_follow.follow_sets[:f]
+  end
+
+  def test_epsilon_productions_flow_through_sequence_first_sets
+    grammar = Rusa.grammar do
+      token :A, "a"
+      token :B, "b"
+
+      start :s
+
+      rule :s do
+        alt(:a, :b)
+      end
+
+      rule :a do
+        alt(:A)
+        alt
+      end
+
+      rule :b do
+        alt(:B)
+        alt
+      end
+    end
+
+    first_follow = Rusa::Analysis::FirstFollow.new(grammar)
+
+    assert_equal Set[:A, :B, Rusa::Analysis::FirstFollow::EMPTY], first_follow.first_sets[:s]
+    assert_equal Set[:B, :$end], first_follow.follow_sets[:a]
+    assert_equal Set[:$end], first_follow.follow_sets[:b]
+  end
+end

data/test/test_grammar_model.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class GrammarModelTest < Minitest::Test
+  def test_symbol_types_compare_by_name_and_type
+    number_a = Rusa::Grammar::TerminalSymbol.new(:NUMBER, /\d+/)
+    number_b = Rusa::Grammar::TerminalSymbol.new(:NUMBER, /\d+/)
+    expr = Rusa::Grammar::NonterminalSymbol.new(:expr)
+
+    assert_equal number_a, number_b
+    refute_equal number_a, expr
+    assert number_a.terminal?
+    refute number_a.nonterminal?
+    assert expr.nonterminal?
+    refute expr.terminal?
+  end
+
+  def test_production_uses_context_precedence_or_rightmost_terminal
+    grammar = Rusa::Grammar::Grammar.new
+    grammar.add_terminal(:PLUS, /\+/)
+    grammar.add_terminal(:STAR, /\*/)
+
+    plain = Rusa::Grammar::Production.new(:expr, [:expr, :PLUS, :expr, :STAR])
+    explicit = Rusa::Grammar::Production.new(:expr, [:MINUS, :expr], context_precedence: :UMINUS)
+
+    assert_equal :STAR, plain.precedence_token(grammar)
+    assert_equal :UMINUS, explicit.precedence_token(grammar)
+  end
+
+  def test_grammar_tracks_rules_and_validation
+    grammar = Rusa::Grammar::Grammar.new
+    grammar.add_terminal(:NUMBER, /\d+/)
+    grammar.add_terminal(:PLUS, /\+/)
+    grammar.start_symbol = :expr
+    grammar.add_nonterminal(:expr)
+    grammar.add_nonterminal(:unused)
+    grammar.add_production(Rusa::Grammar::Production.new(:expr, [:expr, :PLUS, :expr]))
+    grammar.add_production(Rusa::Grammar::Production.new(:expr, [:NUMBER]))
+
+    grammar.augment!
+    grammar.validate!
+
+    assert_equal 3, grammar.productions.length
+    assert_equal :expr, grammar.start_symbol
+    assert_includes grammar.warnings, "nonterminal unused is unreachable from expr"
+  end
+
+  def test_validation_raises_for_undefined_symbols
+    grammar = Rusa::Grammar::Grammar.new
+    grammar.add_terminal(:NUMBER, /\d+/)
+    grammar.start_symbol = :expr
+    grammar.add_nonterminal(:expr)
+    grammar.add_production(Rusa::Grammar::Production.new(:expr, [:NUMBER, :MISSING]))
+    grammar.augment!
+
+    error = assert_raises(Rusa::UndefinedSymbolError) { grammar.validate! }
+    assert_includes error.message, "MISSING"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "minitest/autorun"
+require "rusa"