dendroid 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e94a9721000d8e9a45184107ec3488a3dad0c92337507c6753d4cbfa973400fd
-  data.tar.gz: 03bbe70d73b5e12de42b5dca4f008f1850fb9efcc4272115e5123c7397984f4a
+  metadata.gz: '06667077966c902b083c8e73debebc0808bbc0952243712d19a34f26f9d0c1ba'
+  data.tar.gz: 56e29eb75f509f37212d9bc384c139b6e903b730308fa320e84dc4f352c93f2e
 SHA512:
-  metadata.gz: 8dde1d9509f2d713db092e5730a1c37f1aaab2a1a58b45cb46c3e28011e672d6c27d9e630262d96a5e5597de35b9278aab8b6e2b87934bf4840e024eee0d6bea
-  data.tar.gz: d927b08bf68f6c2a128c92c4724a533991799acf207cd13c381d4abea4cbbf8b340de17771c0a41c351bed3a0d6ac2cd523990d1c0bb699824ce14b9ccd97fe6
+  metadata.gz: e135fc4c2ce34cf54d226d6ed82e188174d99220645abb127877b8d7a97ea77bbce77f8b8a731c390b362e592f961f758078c1af8618c339e41b6564052f1bf3
+  data.tar.gz: 8b30951295517fbf46fa2a1560b4e27dbae13b101cff1841142b641711b4be6696cb50e16333e03dbcb472fa4803380a8e706c85ddab69837db148b69f8ffae4

data/.rubocop.yml

@@ -2,9 +2,21 @@ Layout/EndOfLine:
   Enabled: true
   EnforcedStyle: lf
 
+Metrics/AbcSize:
+  Enabled: true
+  Max: 25
+
 Metrics/BlockLength:
   Enabled: true
-  Max: 50
+  Max: 75
+
+Metrics/ClassLength:
+  Enabled: true
+  Max: 200
+
+Metrics/MethodLength:
+  Enabled: true
+  Max: 20
 
 Naming/MethodParameterName:
   Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.0.7] - 2023-10-30
+### Added
+- Class `BaseGrmBuilder` and its spec file
+
+## [0.0.6] - 2023-10-30
+### Added
+- Class `Grammar` and its spec file
+
 ## [0.0.5] - 2023-10-28
 ### Added
 - Class `Choice` and its spec file

data/lib/dendroid/grm_dsl/base_grm_builder.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require_relative '..\syntax\terminal'
+require_relative '..\syntax\non_terminal'
+require_relative '..\syntax\symbol_seq'
+require_relative '..\syntax\production'
+require_relative '..\syntax\choice'
+require_relative '..\syntax\grammar'
+
+module Dendroid
+  # This module contains classes that define Domain-Specific Language specialized
+  # in grammar definition.
+  module GrmDSL
+    # Builder GoF pattern: Builder builds a complex object.
+    #   here the builder creates a grammar from simpler objects
+    #   (symbols and production rules)
+    #   and using a step by step approach.
+    class BaseGrmBuilder
+      # @return [Symbol] one of: :declaring, :building, :complete
+      attr_reader :state
+
+      # @return [Hash{String, Dendroid::Syntax::GrmSymbol}] The mapping of grammar symbol names
+      #   to the matching grammar symbol object.
+      attr_reader :symbols
+
+      # @return [Array<Dendroid::Syntax::Rule>] The list of rules of the grammar
+      attr_reader :rules
+
+      # Creates a new grammar builder object.
+      # @param aBlock [Proc] code block used to build the grammar.
+      # @example Building a tiny English grammar
+      #   builder = Rley::Syntax::GrammarBuilder.new do
+      #     declare_terminals('n', 'v', 'adj', 'det')
+      #     rule 'S' => 'NP VP'
+      #     rule 'VP' => 'v NP'
+      #     rule 'NP' => ['det n', 'adj NP']
+      #   end
+      #   # Now with `builder`, let's create the grammar
+      #   tiny_eng = builder.grammar
+      def initialize(&aBlock)
+        @symbols = {}
+        @rules = []
+        @state = :declaring
+
+        if block_given?
+          instance_exec(&aBlock)
+          grammar_complete!
+        end
+      end
+
+      # Add the given terminal symbols to the grammar of the language
+      # @param terminalSymbols [String, Terminal] 1..* terminal symbols.
+      # @return [void]
+      def declare_terminals(*terminalSymbols)
+        err_msg = "Terminal symbols may only be declared in state :declaring, current state is: #{state}"
+        raise StandardError, err_msg unless state == :declaring
+
+        new_symbs = build_symbols(Dendroid::Syntax::Terminal, terminalSymbols)
+        symbols.merge!(new_symbs)
+      end
+
+      # Add a production rule in the grammar given one
+      # key-value pair of the form: String => String.
+      #   Where the key is the name of the non-terminal appearing in the
+      #   left side of the rule.
+      #   When the value is a String, it is a sequence of grammar symbol names separated by space.
+      #   When the value is an array of String, the elements represent an alternative rhs
+      # The rule is created and inserted in the grammar.
+      # @example
+      #   builder.rule('sentence' => 'noun_phrase verb_phrase')
+      #   builder.rule('noun_phrase' => ['noun', 'adj noun'])
+      # @param productionRuleRepr [Hash{String, String|Array<String>}]
+      #   A Hash-based representation of a production.
+      # @return [Dendroid::Syntax::Rule] The created Production or Choice instance
+      def rule(productionRuleRepr)
+        raise Exception, "Cannot add a production rule in state :complete" if state == :complete
+        @state = :building
+
+        if productionRuleRepr.is_a?(Hash)
+          head_name = productionRuleRepr.keys.first
+          if symbols.include? head_name
+            err_msg = "Terminal symbol '#{head_name}' may not be on left-side of a rule."
+            raise StandardError, err_msg if symbols[head_name].is_a?(Dendroid::Syntax::Terminal)
+          else
+            symbols.merge!(build_symbols(Dendroid::Syntax::NonTerminal, [head_name]))
+          end
+          lhs = symbols[head_name]
+          raw_rhs = productionRuleRepr.values.first
+
+          if raw_rhs.is_a? String
+            new_prod = Dendroid::Syntax::Production.new(lhs, build_symbol_seq(raw_rhs))
+          else
+            rhs = raw_rhs.map { |raw| build_symbol_seq(raw) }
+            new_prod = Dendroid::Syntax::Choice.new(lhs, rhs)
+          end
+          rules << new_prod
+          new_prod
+        end
+      end
+
+      # A method used to notify the builder that the grammar is complete
+      #   (i.e. all rules were entered).
+      def grammar_complete!
+        @state = :complete
+      end
+
+      # Generate the grammar according to the specifications.
+      # @return [Dendroid::Syntax::Grammar]
+      def grammar
+        terminals = symbols.values.select(&:terminal?)
+        grm = Dendroid::Syntax::Grammar.new(terminals)
+        rules.each { |prod| grm.add_rule(prod) }
+        grm.complete!
+        grm
+      end
+
+      private
+
+      def build_symbol_seq(raw_symbols)
+        symb_array = []
+        raw_stripped = raw_symbols.strip
+        return Dendroid::Syntax::SymbolSeq.new([]) if raw_stripped.empty?
+
+        symbol_names = raw_stripped.split(/(?: |\t)+/)
+        symbol_names.each do |symb_name|
+          if symbols.include? symb_name
+            symb_array << symbols[symb_name]
+          else
+            symbols.merge!(build_symbols(Dendroid::Syntax::NonTerminal, [symb_name]))
+            symb_array << symbols[symb_name]
+          end
+        end
+
+        Dendroid::Syntax::SymbolSeq.new(symb_array)
+      end
+
+      # Add the given grammar symbols.
+      # @param aClass [Class] The class of grammar symbols to instantiate.
+      # @param theSymbols [Array] array of elements are treated as follows:
+      #   if the element is already a grammar symbol, then it added as is,
+      #   otherwise it is considered as the name of a grammar symbol
+      # of the specified class to build.
+      def build_symbols(aClass, theSymbols)
+        symbs = {}
+        theSymbols.each do |s|
+          new_symbol = build_symbol(aClass, s)
+          symbs[new_symbol.name] = new_symbol
+          symbs[s] = new_symbol
+        end
+
+        symbs
+      end
+
+      # If the argument is already a grammar symbol object then it is
+      # returned as is. Otherwise, the argument is treated as a name
+      # for a new instance of the given class.
+      # @param aClass [Class] The class of grammar symbols to instantiate
+      # @param aSymbolArg [GrmSymbol-like or String]
+      # @return [Array] list of grammar symbols
+      def build_symbol(aClass, aSymbolArg)
+        if aSymbolArg.is_a?(Dendroid::Syntax::GrmSymbol)
+          aSymbolArg
+        else
+          aClass.new(aSymbolArg)
+        end
+      end
+    end # class
+  end # module
+end # module

data/lib/dendroid/syntax/grammar.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Dendroid
+  module Syntax
+    # A grammar specifies the syntax of a language.
+    #   Formally, a grammar has:
+    #   * One start symbol,
+    #   * One or more other production rules,
+    #   * Each production has a rhs that is a sequence of grammar symbols.
+    #   * Grammar symbols are categorized into:
+    #     -terminal symbols
+    #     -non-terminal symbols
+    class Grammar
+      # The list of grammar symbols in the language.
+      # @return [Array<Dendroid::Syntax::GrmSymbol>] The terminal and non-terminal symbols.
+      attr_reader :symbols
+
+      # The list of production rules for the language.
+      # @return [Array<Dendroid::Syntax::Rule>] Array of rules for the grammar.
+      attr_reader :rules
+
+      # A Hash that maps symbol names to their grammar symbols
+      # @return [Hash{String => Dendroid::Syntax::GrmSymbol}]
+      attr_reader :name2symbol
+
+      # TODO: make nonterminal - rules one-to-one
+      # A Hash that maps symbol names to their grammar symbols
+      # @return [Hash{Dendroid::Syntax::GrmSymbol => Dendroid::Syntax::Rule}]
+      attr_reader :nonterm2productions
+
+      # Constructor.
+      # @param terminals [Array<Dendroid::Syntax::Terminal>]
+      def initialize(terminals)
+        @symbols = []
+        @name2symbol = {}
+        add_terminals(terminals)
+      end
+
+      # Add a rule to the grammar
+      # @param rule [Dendroid::Syntax::Rule]
+      def add_rule(rule)
+        if @rules.nil?
+          @rules = []
+          @nonterm2productions = {}
+        end
+        # TODO: add test for duplicate productions
+        if nonterm2productions[rule.head]&.include? rule
+          raise StandardError, "Production rule '#{production}' appears more than once in the grammar."
+        end
+        add_symbol(rule.head)
+        rule.nonterminals.each { |nonterm| add_symbol(nonterm) }
+        rules << rule
+        nonterm2productions[rule.head] = [] unless nonterm2productions.include? rule.head
+        nonterm2productions[rule.head] << rule
+      end
+
+      # Return the start symbol for the language
+      # @return [Dendroid::Syntax::NonTerminal]
+      def start_symbol
+        rules.first.lhs
+      end
+
+      # A event method to notify the grammar that all grammar rules
+      # have been entered. The grammar, in turn, reacts by validating the
+      # production rules.
+      def complete!
+        validate
+        analyze
+      end
+
+      private
+
+      # rubocop: disable Metrics/AbcSize
+      # rubocop: disable Metrics/BlockNesting
+      # rubocop: disable Metrics/MethodLength
+      # rubocop: disable Metrics/PerceivedComplexity
+      def add_terminals(terminals)
+        terminals.each { |term| add_symbol(term) }
+      end
+
+      def add_symbol(symb)
+        return if name2symbol.include? symb.name
+
+        symbols.push(symb)
+        name2symbol[symb.name] = symb
+        name2symbol[symb.name.to_s] = symb
+      end
+
+      def validate
+        at_least_one_terminal
+        are_terminals_referenced?
+        are_nonterminals_rewritten?
+        are_symbols_productive?
+        are_symbols_reachable?
+      end
+
+      def analyze
+        mark_nullable_symbols
+      end
+
+      # Does the grammar contain at least one terminal symbol?
+      def at_least_one_terminal
+        found = symbols.any?(&:terminal?)
+
+        unless found
+          err_msg = "Grammar doesn't contain any terminal symbol."
+          raise StandardError, err_msg
+        end
+      end
+
+      # Does every terminal symbol appear at least once
+      # in a rhs of a production rule?
+      def are_terminals_referenced?
+        all_terminals = Set.new(symbols.select(&:terminal?))
+        terms_in_rhs = rules.reduce(Set.new) do |collected, prd|
+          found = prd.terminals
+          collected.merge(found)
+        end
+        check_ok = all_terminals == terms_in_rhs
+        unless check_ok
+          unused_terms = all_terminals.difference(terms_in_rhs)
+          text = unused_terms.map(&:name).join("', '")
+          err_msg = "Terminal symbols '#{text}' never appear in production rules."
+          raise StandardError, err_msg
+        end
+
+        check_ok
+      end
+
+      def are_nonterminals_rewritten?
+        all_nonterminals = Set.new(symbols.reject(&:terminal?))
+
+        symbs_in_lhs = rules.reduce(Set.new) do |collected, prd|
+          collected.add(prd.head)
+        end
+        check_ok = all_nonterminals == symbs_in_lhs
+        unless check_ok
+          undefined_nterms = all_nonterminals.difference(symbs_in_lhs)
+          text = undefined_nterms.map(&:name).join("', '")
+          err_msg = "Non-terminal symbols '#{text}' never appear in head of any production rule."
+          raise StandardError, err_msg
+        end
+
+        check_ok
+      end
+
+      def are_symbols_reachable?
+        unreachable = unreachable_symbols
+        return true if unreachable.empty?
+
+        text = unreachable.to_a.map(&:name).join("', '")
+        err_msg = "Symbols '#{text}' are unreachable from start symbol."
+        raise StandardError, err_msg
+      end
+
+      def are_symbols_productive?
+        non_productive = mark_non_productive_symbols
+        return true if non_productive.empty?
+
+        text = non_productive.to_a.map(&:name).join("', '")
+        err_msg = "Symbols '#{text}' are non-productive."
+        raise StandardError, err_msg
+      end
+
+      # Are all symbols reachable from start symbol?
+      def unreachable_symbols
+        backlog = [start_symbol]
+        set_reachable = Set.new(backlog.dup)
+
+        begin
+          reachable_sym = backlog.pop
+          prods = nonterm2productions[reachable_sym]
+          prods.each do |prd|
+            # prd.body.members.each do |member|
+            prd.rhs_symbols.each do |member|
+              unless member.terminal? || set_reachable.include?(member)
+                backlog.push(member)
+              end
+              set_reachable.add(member)
+            end
+          end
+        end until backlog.empty?
+
+        all_symbols = Set.new(symbols)
+        unreachable = all_symbols - set_reachable
+      end
+
+      def mark_non_productive_symbols
+        prod_count = rules.size
+        backlog = Set.new(0...prod_count)
+        rules.each_with_index do |prd, i|
+          backlog.delete(i) if prd.productive?
+        end
+        until backlog.empty?
+          size_before = backlog.size
+          to_remove = []
+          backlog.each do |i|
+            prd = rules[i]
+            to_remove << i if prd.productive?
+          end
+          break if to_remove.empty?
+
+          backlog.subtract(to_remove)
+        end
+
+        backlog.each { |i| rules[i].non_productive }
+        non_productive = symbols.reject(&:productive?)
+        non_productive.each { |symb| symb.productive = false }
+        non_productive
+      end
+
+      def mark_nullable_symbols
+        nullable_found = false
+        sym2seqs = {}
+
+        nonterm2productions.each_pair do |sym, prods|
+          if prods.any?(&:empty?)
+            sym.nullable = nullable_found = true
+          else
+            sym2seqs[sym] = prods.map(&:rhs).flatten
+          end
+        end
+
+        if nullable_found
+          backlog = {} # { SymbolSequence => [Integer, Symbol] }
+          sym2seqs.each do |sym, seqs|
+            seqs.each { |sq| backlog[sq] = [0, sym] }
+          end
+
+          begin
+            seqs_done = []
+            backlog.each_pair do |sq, (elem_index, lhs)|
+              member = sq.members[elem_index]
+              if member.terminal?
+                seqs_done << sq # stop with this sequence: it is non-nullable
+                backlog[sq] = [-1, lhs]
+              elsif member.nullable?
+                if elem_index == sq.size - 1
+                  seqs_done << sq # end of sequence reached...
+                  backlog[sq] = [-1, lhs]
+                  lhs.nullable = true
+                else
+                  backlog[sq] = [elem_index + 1, lhs]
+                end
+              end
+            end
+            seqs_done.each do |sq|
+              if backlog.include? sq
+                (_, lhs) = backlog[sq]
+                if lhs.nullable?
+                  to_drop = sym2seqs[lhs]
+                  to_drop.each { |seq| backlog.delete(seq) }
+                else
+                  backlog.delete(sq)
+                end
+              end
+            end
+          end until backlog.empty? || seqs_done.empty?
+        end
+
+        symbols.each do |sym|
+          next if sym.terminal?
+
+          sym.nullable = false if sym.nullable.nil?
+        end
+      end
+      # rubocop: enable Metrics/AbcSize
+      # rubocop: enable Metrics/BlockNesting
+      # rubocop: enable Metrics/MethodLength
+      # rubocop: enable Metrics/PerceivedComplexity
+    end # class
+  end # module
+end # module

data/lib/dendroid/syntax/grm_symbol.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Dendroid
+  # The namespace for all classes used to build a grammar.
   module Syntax
     # Abstract class for grammar symbols.
     # A grammar symbol is an element that appears in grammar rules.

data/spec/dendroid/grm_dsl/base_grm_builder_spec.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative '..\..\spec_helper'
+require_relative '..\..\..\lib\dendroid\grm_dsl\base_grm_builder'
+
+describe Dendroid::GrmDSL::BaseGrmBuilder do
+  # Builds ingredients for a grammar inspired from https://en.wikipedia.org/wiki/Earley_parser
+  subject do
+    instance = described_class.new
+    instance.declare_terminals('PLUS', 'STAR', 'INTEGER')
+    instance
+  end
+
+  context 'Initialization:' do
+    it 'is initialized with an optional code block' do
+      expect { described_class.new }.not_to raise_error
+    end
+
+    it 'is in "declaring" state by default' do
+      expect(described_class.new.state).to eq(:declaring)
+    end
+
+    it 'has no grammar symbol by default' do
+      expect(described_class.new.symbols).to be_empty
+    end
+
+    it 'has no production rule by default' do
+      expect(described_class.new.rules).to be_empty
+    end
+  end # context
+
+  context 'Provided services:' do
+    it 'builds declared terminal symbols' do
+      instance = described_class.new
+      terminals = %w[PLUS STAR INTEGER]
+      instance.declare_terminals(*terminals)
+      expect(instance.symbols.size).to eq(2 * terminals.size)
+      expect(instance.symbols[:PLUS]).to be_kind_of(Dendroid::Syntax::Terminal)
+      expect(instance.symbols['PLUS']).to eq(instance.symbols[:PLUS])
+      expect(instance.symbols[:PLUS].name).to eq(:PLUS)
+      expect(instance.symbols[:STAR]).to be_kind_of(Dendroid::Syntax::Terminal)
+      expect(instance.symbols['STAR']).to eq(instance.symbols[:STAR])
+      expect(instance.symbols[:STAR].name).to eq(:STAR)
+      expect(instance.symbols[:INTEGER]).to be_kind_of(Dendroid::Syntax::Terminal)
+      expect(instance.symbols['INTEGER']).to eq(instance.symbols[:INTEGER])
+      expect(instance.symbols[:INTEGER].name).to eq(:INTEGER)
+      expect(instance.state).to eq(:declaring)
+    end
+
+    it 'builds production rules' do
+      subject.rule('p' => 's')
+      expect(subject.state).to eq(:building)
+
+      # Undeclared symbols in production represent non-terminals
+      expect(subject.symbols['p']).to be_kind_of(Dendroid::Syntax::NonTerminal)
+      expect(subject.symbols['s']).to be_kind_of(Dendroid::Syntax::NonTerminal)
+
+      expect(subject.rules.size).to eq(1)
+      expect(subject.rules.first.to_s).to eq('p => s')
+    end
+
+    it 'builds a grammar' do
+      subject.rule('p' => 's')
+      subject.rule('s' => ['s PLUS m', 'm'])
+      subject.rule('m' => ['m STAR t', 't'])
+      subject.rule('t' => 'INTEGER')
+      subject.grammar_complete!
+
+      grm = subject.grammar
+      expect(grm).to be_kind_of(Dendroid::Syntax::Grammar)
+      (terms, nonterms) = grm.symbols.partition(&:terminal?)
+      expect(terms.map(&:name)).to eq(%i[PLUS STAR INTEGER])
+      expect(nonterms.map(&:name)).to eq(%i[p s m t])
+      grammar_rules = [
+        'p => s',
+        's => s PLUS m | m',
+        'm => m STAR t | t',
+        't => INTEGER'
+      ]
+      expect(subject.rules.map(&:to_s)).to eq(grammar_rules)
+    end
+
+    it 'provides a simple DSL' do
+      instance = described_class.new do
+        declare_terminals('PLUS', 'STAR', 'INTEGER')
+        rule('p' => 's')
+        rule('s' => ['s PLUS m', 'm'])
+        rule('m' => ['m STAR t', 't'])
+        rule('t' => 'INTEGER')
+      end
+
+      grm = instance.grammar
+      expect(grm).to be_kind_of(Dendroid::Syntax::Grammar)
+      (terms, nonterms) = grm.symbols.partition(&:terminal?)
+      expect(terms.map(&:name)).to eq(%i[PLUS STAR INTEGER])
+      expect(nonterms.map(&:name)).to eq(%i[p s m t])
+      grammar_rules = [
+        'p => s',
+        's => s PLUS m | m',
+        'm => m STAR t | t',
+        't => INTEGER'
+      ]
+      expect(instance.rules.map(&:to_s)).to eq(grammar_rules)
+    end
+  end # context
+end # describe

data/spec/dendroid/syntax/grammar_spec.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative '..\..\spec_helper'
+require_relative '..\..\..\lib\dendroid\syntax\terminal'
+require_relative '..\..\..\lib\dendroid\syntax\non_terminal'
+require_relative '..\..\..\lib\dendroid\syntax\symbol_seq'
+require_relative '..\..\..\lib\dendroid\syntax\production'
+require_relative '..\..\..\lib\dendroid\syntax\choice'
+require_relative '..\..\..\lib\dendroid\syntax\grammar'
+
+describe Dendroid::Syntax::Grammar do
+  let(:int_symb) { build_terminal('INTEGER') }
+  let(:plus_symb) { build_terminal('PLUS') }
+  let(:star_symb) { build_terminal('STAR') }
+  let(:p_symb) { build_nonterminal('p') }
+  let(:s_symb) { build_nonterminal('s') }
+  let(:m_symb) { build_nonterminal('m') }
+  let(:t_symb) { build_nonterminal('t') }
+  let(:all_terminals) { [int_symb, plus_symb, star_symb] }
+
+  subject { described_class.new(all_terminals) }
+
+  def build_terminal(name)
+    Dendroid::Syntax::Terminal.new(name)
+  end
+
+  def build_nonterminal(name)
+    Dendroid::Syntax::NonTerminal.new(name)
+  end
+
+  def build_symbol_seq(symbols)
+    Dendroid::Syntax::SymbolSeq.new(symbols)
+  end
+
+  def build_production(lhs, symbols)
+    Dendroid::Syntax::Production.new(lhs, build_symbol_seq(symbols))
+  end
+
+  def build_choice(lhs, sequences)
+    Dendroid::Syntax::Choice.new(lhs, sequences.map { |arr| build_symbol_seq(arr) })
+  end
+
+  def build_all_rules
+    rule1 = build_production(p_symb, [s_symb]) # p => s
+    rule2 = build_choice(s_symb, [[s_symb, plus_symb, m_symb], [m_symb]]) # s => s + m | m
+    rule3 = build_choice(m_symb, [[m_symb, star_symb, t_symb], [t_symb]]) # m => m * t
+    rule4 = build_production(t_symb, [int_symb]) # t => INTEGER
+    [rule1, rule2, rule3, rule4]
+  end
+
+  context 'Initialization:' do
+    it 'is initialized with an array of terminal symbols' do
+      expect { described_class.new(all_terminals) }.not_to raise_error
+    end
+
+    it 'knows its terminal symbols' do
+      expect(subject.symbols).to eq(all_terminals)
+    end
+
+    it 'ignores about productions after initialization' do
+      expect(subject.rules).to be_nil
+    end
+
+    it 'maps a terminal name to one GrmSymbol object' do
+      expect(subject.name2symbol.values.uniq.size).to eq(all_terminals.size)
+      expect(subject.name2symbol.values.size).to eq(2 * all_terminals.size)
+      expect(subject.name2symbol[:PLUS]).to eq(plus_symb)
+      expect(subject.name2symbol['PLUS']).to eq(plus_symb)
+    end
+  end # context
+
+  context 'Adding productions:' do
+    it 'allows the addition of one production rule' do
+      rule = build_production(p_symb, [s_symb])
+      expect { subject.add_rule(rule) }.not_to raise_error
+      expect(subject.rules.size).to eq(1)
+      expect(subject.rules.first).to eq(rule)
+    end
+
+    it 'allows the addition of multiple production rules' do
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      expect(subject.rules.size).to eq(4)
+      expect(subject.rules.first).to eq(rules.first)
+      expect(subject.rules.last).to eq(rules.last)
+    end
+
+    it 'updates the set of symbols when adding production rules' do
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      [p_symb, s_symb, m_symb, t_symb].each do |symb|
+        expect(subject.symbols.include?(symb)).to be_truthy
+      end
+    end
+
+    it 'maps name of every non-terminal to its related GrmSymbol' do
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      [[:p, p_symb],
+       ['p', p_symb],
+       [:s, s_symb],
+       ['s', s_symb],
+       [:m, m_symb],
+       ['m', m_symb],
+       [:t, t_symb],
+       [:t, t_symb]].each do |(name, symb)|
+        expect(subject.name2symbol[name]).to eq(symb)
+      end
+    end
+
+    it 'maps every non-terminal to its defining productions' do
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      %i[p s m t].each do |symb_name|
+        symb = subject.name2symbol[symb_name]
+        expected_prods = subject.rules.select { |prd| prd.head == symb }
+        related_prods = subject.nonterm2productions[symb]
+        expect(related_prods).to eq(expected_prods)
+      end
+    end
+  end # context
+
+  context 'Grammar completion:' do
+    it 'detects and marks nullable symbols (I)' do
+      # Case: grammar without nullable symbols
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      subject.complete!
+      expect(subject.symbols.none?(&:nullable?)).to be_truthy
+    end
+
+    it 'detects and marks nullable symbols (II)' do
+      # Case: grammar with only nullable symbols
+      # Grammar inspired for paper "Practical Earley Parser"
+      terminal_a = build_terminal('a')
+      nterm_s_prime = build_nonterminal("S'")
+      nterm_s = build_nonterminal('S')
+      nterm_a = build_nonterminal('A')
+      nterm_e = build_nonterminal('E')
+
+      instance = described_class.new([terminal_a])
+      instance.add_rule(build_production(nterm_s_prime, [nterm_s]))
+      instance.add_rule(build_production(nterm_s, [nterm_a, nterm_a, nterm_a, nterm_a]))
+      instance.add_rule(build_choice(nterm_a, [[terminal_a], [nterm_e]]))
+      instance.add_rule(build_production(nterm_e, []))
+
+      instance.complete!
+      all_nonterminals = subject.symbols.reject(&:terminal?)
+      expect(all_nonterminals.all?(&:nullable?)).to be_truthy
+    end
+
+    it 'detects unreachable symbols' do
+      # Case: grammar without unreachable symbols
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      expect(subject.send(:unreachable_symbols)).to be_empty
+
+      # Let add's unreachable symbols
+      zed_symb = build_nonterminal('Z')
+      question_symb = build_nonterminal('?')
+      bad_rule = build_production(zed_symb, [zed_symb, question_symb, int_symb]) # Z => Z ? INTEGER
+      subject.add_rule(bad_rule)
+      unreachable = subject.send(:unreachable_symbols)
+      expect(unreachable).not_to be_empty
+      expect(unreachable).to eq(Set.new([zed_symb, question_symb]))
+    end
+
+    it 'detects non-productive symbols' do
+      # Case: grammar without non-productive symbols
+      rules = build_all_rules
+      rules.each { |rl| subject.add_rule(rl) }
+      expect(subject.send(:mark_non_productive_symbols)).to be_empty
+      expect(t_symb).to be_productive
+      expect(p_symb).to be_productive
+
+      # Grammar with non-productive symbols
+      term_a = build_terminal('a')
+      term_b = build_terminal('b')
+      term_c = build_terminal('c')
+      term_d = build_terminal('d')
+      term_e = build_terminal('e')
+      term_f = build_terminal('f')
+      nterm_A = build_nonterminal('A')
+      nterm_B = build_nonterminal('B')
+      nterm_C = build_nonterminal('C')
+      nterm_D = build_nonterminal('D')
+      nterm_E = build_nonterminal('E')
+      nterm_F = build_nonterminal('F')
+      nterm_S = build_nonterminal('S')
+      instance = described_class.new([term_a, term_b, term_c, term_d, term_e, term_f])
+      instance.add_rule(build_choice(nterm_S, [[nterm_A, nterm_B], [nterm_D, nterm_E]]))
+      instance.add_rule(build_production(nterm_A, [term_a]))
+      instance.add_rule(build_production(nterm_B, [term_b, nterm_C]))
+      instance.add_rule(build_production(nterm_C, [term_c]))
+      instance.add_rule(build_production(nterm_D, [term_d, nterm_F]))
+      instance.add_rule(build_production(nterm_E, [term_e]))
+      instance.add_rule(build_production(nterm_F, [term_f, nterm_D]))
+      nonproductive = instance.send(:mark_non_productive_symbols)
+      expect(nonproductive).not_to be_empty
+      expect(nonproductive).to eq([nterm_D, nterm_F])
+    end
+  end # context
+end # describe

data/version.txt

@@ -1 +1 @@
-0.0.5
+0.0.7

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dendroid
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Dimitri Geshef
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-28 00:00:00.000000000 Z
+date: 2023-10-30 00:00:00.000000000 Z
 dependencies: []
 description: WIP. A Ruby implementation of a Earley parser
 email: famished.tiger@yahoo.com
@@ -23,15 +23,19 @@ files:
 - Rakefile
 - bin/dendroid
 - dendroid.gemspec
-- lib/dendroid/dendroid.rb
+- lib/dendroid.rb
+- lib/dendroid/grm_dsl/base_grm_builder.rb
 - lib/dendroid/syntax/choice.rb
+- lib/dendroid/syntax/grammar.rb
 - lib/dendroid/syntax/grm_symbol.rb
 - lib/dendroid/syntax/non_terminal.rb
 - lib/dendroid/syntax/production.rb
 - lib/dendroid/syntax/rule.rb
 - lib/dendroid/syntax/symbol_seq.rb
 - lib/dendroid/syntax/terminal.rb
+- spec/dendroid/grm_dsl/base_grm_builder_spec.rb
 - spec/dendroid/syntax/choice_spec.rb
+- spec/dendroid/syntax/grammar_spec.rb
 - spec/dendroid/syntax/grm_symbol_spec.rb
 - spec/dendroid/syntax/non_terminal_spec.rb
 - spec/dendroid/syntax/production_spec.rb