dendroid 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a762fb52e0c8ff6116f41f481b5cb7346b99050d90f77c4e133da37a31dda3b3
-  data.tar.gz: ace142c5221c038eedaab8ea9882a3fbffa34cb424be08083ee722e9e5d8c6ca
+  metadata.gz: '06667077966c902b083c8e73debebc0808bbc0952243712d19a34f26f9d0c1ba'
+  data.tar.gz: 56e29eb75f509f37212d9bc384c139b6e903b730308fa320e84dc4f352c93f2e
 SHA512:
-  metadata.gz: 2746b3e1cd03e07e0045d7e41b54ed4c8a2f003df89ea45166fa0b66013f37aa9c1cf0044adc71bbe75d5958d99334b7f612d15c116954fe451f8e1e6756bfaa
-  data.tar.gz: 4917fd27358d80719b722c14a6df8636917ad827dfc29fb8201920b068393dba09dd2b9750d8b5946031a1d821bd6922c84dd27572b4a635e709faa4bfe31ceb
+  metadata.gz: e135fc4c2ce34cf54d226d6ed82e188174d99220645abb127877b8d7a97ea77bbce77f8b8a731c390b362e592f961f758078c1af8618c339e41b6564052f1bf3
+  data.tar.gz: 8b30951295517fbf46fa2a1560b4e27dbae13b101cff1841142b641711b4be6696cb50e16333e03dbcb472fa4803380a8e706c85ddab69837db148b69f8ffae4

data/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [0.0.7] - 2023-10-30
+### Added
+- Class `BaseGrmBuilder` and its spec file
 
 ## [0.0.6] - 2023-10-30
 ### Added

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/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

@@ -40,7 +40,6 @@ describe Dendroid::Syntax::Grammar do
     Dendroid::Syntax::Choice.new(lhs, sequences.map { |arr| build_symbol_seq(arr) })
   end
 
-  # rubocop: disable Metrics/AbcSize
   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
@@ -48,7 +47,6 @@ describe Dendroid::Syntax::Grammar do
     rule4 = build_production(t_symb, [int_symb]) # t => INTEGER
     [rule1, rule2, rule3, rule4]
   end
-  # rubocop: enable Metrics/AbcSize
 
   context 'Initialization:' do
     it 'is initialized with an array of terminal symbols' do

data/version.txt

@@ -1 +1 @@
-0.0.6
+0.0.7

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dendroid
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Dimitri Geshef
@@ -24,6 +24,7 @@ files:
 - bin/dendroid
 - dendroid.gemspec
 - 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
@@ -32,6 +33,7 @@ files:
 - 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