sequitur 0.1.23 → 0.1.25

data/lib/sequitur/sequitur_grammar.rb

@@ -2,155 +2,153 @@
 
 require_relative 'dynamic_grammar'
 
-
 module Sequitur # Module for classes implementing the Sequitur algorithm
-# Specialization of the DynamicGrammar class.
-# A Sequitur grammar is a context-free grammar that is entirely built
-# from a sequence of input tokens through the Sequitur algorithm.
-class SequiturGrammar < DynamicGrammar
-  # Build the grammar from an enumerator of tokens.
-  # @param anEnum [Enumerator] an enumerator that will iterate
-  #   over the input tokens.
-  def initialize(anEnum)
-    super()
-    # Make start production compliant with utility rule
-    2.times { start.incr_refcount }
-
-    # Read the input sequence and apply the Sequitur algorithm
-    anEnum.each do |a_token|
-      add_token(a_token)
-      enforce_rules
+  # Specialization of the DynamicGrammar class.
+  # A Sequitur grammar is a context-free grammar that is entirely built
+  # from a sequence of input tokens through the Sequitur algorithm.
+  class SequiturGrammar < DynamicGrammar
+    # Build the grammar from an enumerator of tokens.
+    # @param anEnum [Enumerator] an enumerator that will iterate
+    #   over the input tokens.
+    def initialize(anEnum)
+      super()
+      # Make start production compliant with utility rule
+      2.times { start.incr_refcount }
+
+      # Read the input sequence and apply the Sequitur algorithm
+      anEnum.each do |a_token|
+        add_token(a_token)
+        enforce_rules
+      end
     end
-  end
-
-  private
-
-  # Struct used for internal purposes
-  CollisionDiagnosis = Struct.new(
-    :collision_found, # true if collision detected
-    :digram, # The digram involved in a collision
-    :productions) # The productions where the digram occurs
-
-
-
-  # Assuming that a new input token was added to the start production,
-  # enforce the digram unicity and rule utility rules
-  # begin
-  #   if a digram D occurs twice in the grammar then
-  #     add a production P : D (if not already there)
-  #     replace both Ds with R (reduction step).
-  #   end
-  #   if a production P : RHS in referenced only once then
-  #     replace P by its RHS (derivation step)
-  #     remove P from grammar
-  #   end
-  #  end until digram unicity and rule utility are met
-  def enforce_rules
-    loop do
-      unicity_diagnosis = detect_collision if unicity_diagnosis.nil?
-      restore_unicity(unicity_diagnosis) if unicity_diagnosis.collision_found
-
-      prod_index = detect_useless_production
-      restore_utility(prod_index) unless prod_index.nil?
-
-      unicity_diagnosis = detect_collision
-      prod_index = detect_useless_production
-      break unless unicity_diagnosis.collision_found || !prod_index.nil?
+
+    private
+
+    # Struct used for internal purposes
+    CollisionDiagnosis = Struct.new(
+      :collision_found, # true if collision detected
+      :digram, # The digram involved in a collision
+      :productions # The productions where the digram occurs
+    )
+
+    # Assuming that a new input token was added to the start production,
+    # enforce the digram unicity and rule utility rules
+    # begin
+    #   if a digram D occurs twice in the grammar then
+    #     add a production P : D (if not already there)
+    #     replace both Ds with R (reduction step).
+    #   end
+    #   if a production P : RHS in referenced only once then
+    #     replace P by its RHS (derivation step)
+    #     remove P from grammar
+    #   end
+    #  end until digram unicity and rule utility are met
+    def enforce_rules
+      loop do
+        unicity_diagnosis = detect_collision if unicity_diagnosis.nil?
+        restore_unicity(unicity_diagnosis) if unicity_diagnosis.collision_found
+
+        prod_index = detect_useless_production
+        restore_utility(prod_index) unless prod_index.nil?
+
+        unicity_diagnosis = detect_collision
+        prod_index = detect_useless_production
+        break unless unicity_diagnosis.collision_found || !prod_index.nil?
+      end
     end
-  end
-
-  # Check whether a digram is used twice in the grammar.
-  # Return an empty Hash if each digram appears once.
-  # Otherwise return a Hash with a pair of the form: digram => [Pi, Pk]
-  # Where Pi, Pk are two productions where the digram occurs.
-  def detect_collision
-    diagnosis = CollisionDiagnosis.new(false)
-    found_so_far = {}
-    productions.each do |a_prod|
-      prod_digrams = a_prod.digrams
-      prod_digrams.each do |a_digr|
-        its_key = a_digr.key
-        if found_so_far.include? its_key
-          orig_digr = found_so_far[its_key]
-          # Disregard sequence like a a a
-          if (orig_digr.production == a_prod) && a_digr.repeating? &&
-             (orig_digr == a_digr)
-            next
-          end
 
-          diagnosis.digram = orig_digr
-          diagnosis.productions = [orig_digr.production, a_prod]
-          diagnosis.collision_found = true
-          break
-        else
-          found_so_far[its_key] = a_digr
+    # Check whether a digram is used twice in the grammar.
+    # Return an empty Hash if each digram appears once.
+    # Otherwise return a Hash with a pair of the form: digram => [Pi, Pk]
+    # Where Pi, Pk are two productions where the digram occurs.
+    def detect_collision
+      diagnosis = CollisionDiagnosis.new(false)
+      found_so_far = {}
+      productions.each do |a_prod|
+        prod_digrams = a_prod.digrams
+        prod_digrams.each do |a_digr|
+          its_key = a_digr.key
+          if found_so_far.include? its_key
+            orig_digr = found_so_far[its_key]
+            # Disregard sequence like a a a
+            if (orig_digr.production == a_prod) && a_digr.repeating? &&
+               (orig_digr == a_digr)
+              next
+            end
+
+            diagnosis.digram = orig_digr
+            diagnosis.productions = [orig_digr.production, a_prod]
+            diagnosis.collision_found = true
+            break
+          else
+            found_so_far[its_key] = a_digr
+          end
         end
+        break if diagnosis.collision_found
       end
-      break if diagnosis.collision_found
+
+      diagnosis
     end
 
-    return diagnosis
-  end
-
-  # When a collision diagnosis indicates that a given
-  # digram d occurs twice in the grammar
-  # Then create a new production that will have
-  # the symbols of d as its rhs members.
-  def restore_unicity(aDiagnosis)
-    prods = aDiagnosis.productions
-    if prods.any?(&:single_digram?)
-      (simple, compound) = prods.partition(&:single_digram?)
-      compound[0].reduce_step(simple[0])
-    else
-      # Create a new production with the digram's symbols as its
-      # sole rhs members.
-      new_prod = build_production_for(aDiagnosis.digram)
-      prods[0].reduce_step(new_prod)
-      prods[1].reduce_step(new_prod) unless prods[1] == prods[0]
+    # When a collision diagnosis indicates that a given
+    # digram d occurs twice in the grammar
+    # Then create a new production that will have
+    # the symbols of d as its rhs members.
+    def restore_unicity(aDiagnosis)
+      prods = aDiagnosis.productions
+      if prods.any?(&:single_digram?)
+        (simple, compound) = prods.partition(&:single_digram?)
+        compound[0].reduce_step(simple[0])
+      else
+        # Create a new production with the digram's symbols as its
+        # sole rhs members.
+        new_prod = build_production_for(aDiagnosis.digram)
+        prods[0].reduce_step(new_prod)
+        prods[1].reduce_step(new_prod) unless prods[1] == prods[0]
+      end
     end
-  end
-
-  # Return a production that is used less than twice in the grammar.
-  def detect_useless_production
-    useless = productions.index { |prod| prod.refcount < 2 }
-    useless = nil if useless&.zero?
-
-    return useless
-  end
-
-  # Given the passed production P is referenced only once.
-  # Then replace P by its RHS where it is referenced.
-  # And delete P
-  def restore_utility(prod_index)
-    # Retrieve useless prod from its index
-    useless_prod = productions[prod_index]
-
-    # Retrieve production referencing useless one
-    referencing = nil
-    productions.reverse_each do |a_prod|
-      # Next line assumes non-recursive productions
-      next if a_prod == useless_prod
-
-      refs = a_prod.references_of(useless_prod)
-      next if refs.empty?
-
-      referencing = a_prod
-      break
+
+    # Return a production that is used less than twice in the grammar.
+    def detect_useless_production
+      useless = productions.index { |prod| prod.refcount < 2 }
+      useless = nil if useless&.zero?
+
+      useless
     end
 
-    referencing.derive_step(useless_prod)
-    remove_production(prod_index)
-  end
+    # Given the passed production P is referenced only once.
+    # Then replace P by its RHS where it is referenced.
+    # And delete P
+    def restore_utility(prod_index)
+      # Retrieve useless prod from its index
+      useless_prod = productions[prod_index]
+
+      # Retrieve production referencing useless one
+      referencing = nil
+      productions.reverse_each do |a_prod|
+        # Next line assumes non-recursive productions
+        next if a_prod == useless_prod
+
+        refs = a_prod.references_of(useless_prod)
+        next if refs.empty?
+
+        referencing = a_prod
+        break
+      end
+
+      referencing.derive_step(useless_prod)
+      remove_production(prod_index)
+    end
 
-  # Create a new production that will have the symbols from digram
-  # as its rhs members.
-  def build_production_for(aDigram)
-    new_prod = Production.new
-    aDigram.symbols.each { |sym| new_prod.append_symbol(sym) }
-    add_production(new_prod)
+    # Create a new production that will have the symbols from digram
+    # as its rhs members.
+    def build_production_for(aDigram)
+      new_prod = Production.new
+      aDigram.symbols.each { |sym| new_prod.append_symbol(sym) }
+      add_production(new_prod)
 
-    return new_prod
-  end
-end # class
+      new_prod
+    end
+  end # class
 end # module
 # End of file

data/lib/sequitur/symbol_sequence.rb

@@ -4,7 +4,7 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
   # Represents a sequence (concatenation) of grammar symbols
   # as they appear in rhs of productions
   class SymbolSequence
-    # The sequence of symbols itself
+    # @return [Array] The sequence of symbols itself
     attr_reader(:symbols)
 
     # Create an empty sequence
@@ -31,15 +31,15 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
     end
 
     # Tell whether the sequence is empty.
-    # @return [true / false] true only if the sequence has no symbol in it.
+    # @[true / false] true only if the sequence has no symbol in it.
     def empty?
-      return symbols.empty?
+      symbols.empty?
     end
 
     # Count the number of elements in the sequence.
-    #  @return [Fixnum] the number of elements
+    #  @[Fixnum] the number of elements
     def size
-      return symbols.size
+      symbols.size
     end
 
     # Append a grammar symbol at the end of the sequence.
@@ -55,58 +55,55 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
     # Retrieve the element from the sequence at given position.
     # @param anIndex [Fixnum] A zero-based index of the element to access.
     def [](anIndex)
-      return symbols[anIndex]
+      symbols[anIndex]
     end
 
     # Equality testing.
-    # @param other [SymbolSequence or Array] the other other sequence
+    # @param other [SymbolSequence, Array] the other other sequence
     #   to compare to.
-    # @return true when an item from self equals the corresponding
+    # @return [TrueClass, FalseClass] true when an item from self equals the corresponding
     #   item from 'other'
     def ==(other)
-      return true if object_id == other.object_id
+      true if object_id == other.object_id
 
-      same = case other
-               when SymbolSequence
-                 symbols == other.symbols
-               when Array
-                 symbols == other
-               else
-                 false
-             end
-
-      return same
+      case other
+      when SymbolSequence
+        symbols == other.symbols
+      when Array
+        symbols == other
+      else
+        false
+      end
     end
 
     # Select the references to production appearing in the rhs.
-    # @return [Array of ProductionRef]
+    # @[Array of ProductionRef]
     def references
       @memo_references ||= symbols.select { |symb| symb.is_a?(ProductionRef) }
-      return @memo_references
+      @memo_references
     end
 
     # Select the references of the given production appearing in the rhs.
     # @param aProduction [Production]
-    # @return [Array of ProductionRef]
+    # @[Array of ProductionRef]
     def references_of(aProduction)
-      return [] if references.empty?
+      [] if references.empty?
 
-      result = references.select { |a_ref| a_ref == aProduction }
-      return result
+      references.select { |a_ref| a_ref == aProduction }
     end
 
     # Emit a text representation of the symbol sequence.
     # Text is of the form: space-separated sequence of symbols.
-    # @return [String]
+    # @[String]
     def to_string
       rhs_text = symbols.map do |elem|
         case elem
-          when String then "'#{elem}'"
-          else elem.to_s
+        when String then "'#{elem}'"
+        else elem.to_s
         end
       end
 
-      return rhs_text.join(' ')
+      rhs_text.join(' ')
     end
 
     # Insert at position the elements from another sequence.
@@ -122,9 +119,9 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
     # Given that the production P passed as argument has exactly 2 symbols
     #   in its rhs s1 s2, substitute in the rhs of self all occurrences of
     #   s1 s2 by a reference to P.
-    # @param index [Fixnum] the position of a two symbol sequence to be replaced
+    # @param index [Integer] the position of a two symbol sequence to be replaced
     #   by the production
-    # @param aProduction [Production or ProductionRef] a production that
+    # @param aProduction [Production, ProductionRef] a production that
     #   consists exactly of one digram (= 2 symbols).
     def reduce_step(index, aProduction)
       if symbols[index].is_a?(ProductionRef)
@@ -144,7 +141,7 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
     end
 
     # Remove the element at given position
-    # @param position [Fixnum] a zero-based index.
+    # @param position [Integer] a zero-based index.
     def delete_at(position)
       invalidate_refs if symbols[position].is_a?(ProductionRef)
       symbols.delete_at(position)

data/lib/sequitur.rb

@@ -9,22 +9,22 @@ require_relative './sequitur/sequitur_grammar'
 require_relative './sequitur/formatter/debug'
 require_relative './sequitur/formatter/base_text'
 
-
+# Namespace for the classes of sequitur gem.
 module Sequitur
   # Build a Sequitur-generated grammar based on the sequence of input tokens.
   #
-  # @param tokens [StringOrEnumerator] The input sequence of input tokens.
+  # @param tokens [String, Enumerator] The input sequence of input tokens.
   #   Can be a sequence of characters (i.e. a String) or an Enumerator.
   #   Tokens returned by enumerator should respond to the :hash message.
   # @return [SequiturGrammar] a grammar that encodes the input.
   def self.build_from(tokens)
     input_sequence = case tokens
-                       when String then tokens.chars
-                       when Enumerator then tokens
-                       else tokens.to_enum
+                     when String then tokens.chars
+                     when Enumerator then tokens
+                     else tokens.to_enum
                      end
 
-    return SequiturGrammar.new(input_sequence)
+    SequiturGrammar.new(input_sequence)
   end
 end # module
 

data/sig/lib/sequitur/constants.rbs

@@ -0,0 +1,10 @@
+module Sequitur
+  # @return [String] The version number of the gem.
+  Version: String
+
+  # @return [String] Brief description of the gem.
+  Description: String
+
+  # @return [String] The start folder of Sequitur.
+  RootDir: String
+end

data/sig/lib/sequitur/digram.rbs

@@ -0,0 +1,37 @@
+module Sequitur
+  # In linguistics, a digram is a sequence of two letters.
+  # In Sequitur, a digram is a sequence of two consecutive symbols that
+  # appear in a production rule. Each symbol in a digram
+  # can be a terminal or not.
+  class Digram
+    # The sequence of two consecutive grammar symbols.
+    # @return [Array<String, Symbol>] The two symbols should respond to the :hash message.
+    attr_reader symbols: Array<String|Symbol>
+
+    # @return [String] An unique hash key of the digram
+    attr_reader key: String
+
+    # @return [Sequitur::Production] The production in which the digram occurs
+    attr_reader production: Sequitur::Production
+
+    # Constructor.
+    # A digram represents a sequence of two symbols
+    # (that appears in a rhs of a production).
+    # Terminal symbols must respond to the :hash message.
+    # @param symbol1 [String, Symbol] First element of the digram
+    # @param symbol2 [String, Symbol] Second element of the digram
+    # @param aProduction [Sequitur::Production] Production in which the RHS
+    #   the sequence symbol1 symbol2 appears.
+    def initialize: ((String | Symbol) symbol1, (String | Symbol) symbol2, Sequitur::Production aProduction) -> void
+
+    # Equality testing.
+    #   true iff keys of both digrams are equal, false otherwise
+    # @param other [Sequitur::Digram] another to compare with
+    # @return [TrueClass, FalseClass]
+    def ==: (Sequitur::Digram other) -> bool
+
+    # Does the digram consists of twice the same symbols?
+    # @return [TrueClass, FalseClass] true when symbols.first == symbols.last
+    def repeating?: () -> bool
+  end
+end

data/sig/lib/sequitur/dynamic_grammar.rbs

@@ -0,0 +1,58 @@
+module Sequitur
+  # A dynamic grammar is a context-free grammar that can be built incrementally.
+  #   Formally, a grammar has:
+  #   One start production
+  #   Zero or more other productions
+  #   Each production has a rhs that is a sequence of grammar symbols.
+  #   Grammar symbols are categorized into
+  #   -terminal symbols (i.e. String, Ruby Symbol,...)
+  #   -non-terminal symbols (i.e. ProductionRef)
+  class DynamicGrammar
+    # @return [Sequitur::Production] Link to the start production.
+    attr_reader start: Sequitur::Production
+
+    # @return [Array<Sequitur::Production>] The set of production rules of the grammar
+    attr_reader productions: Array[Sequitur::Production]
+
+    # @return [TrueClass, FalseClass] Trace the execution of the algorithm.
+    attr_accessor trace: bool
+
+    # Constructor.
+    # Build a grammar with one empty rule as start/start rule.
+    def initialize: () -> void
+
+    # Emit a text representation of the grammar.
+    # Each production rule is emitted per line.
+    # @return [String]
+    def to_string: () -> String
+
+    # Add a given production to the grammar.
+    # @param aProduction [Sequitur::Production]
+    # @return [Array<Sequitur::Production>]
+    def add_production: (Sequitur::Production aProduction) -> Array[Sequitur::Production]
+
+    # Remove a production with given index from the grammar
+    # @param anIndex [Integer]
+    # @return [Sequitur::Production] the production removed from the grammar.
+    def remove_production: (Integer anIndex) -> Sequitur::Production
+
+    # Add the given token to the grammar.
+    #   Append the token to the rhs of the start/start rule.
+    # @param aToken [Object] input token to add
+    def add_token: (untyped aToken) -> untyped
+
+    # Part of the 'visitee' role in the Visitor design pattern.
+    #   A visitee is expected to accept the visit from a visitor object
+    # @param aVisitor [Sequitur::GrammarVisitor] the visitor object
+    def accept: (Sequitur::GrammarVisitor aVisitor) -> untyped
+
+    # Factory method. Returns a visitor for this grammar.
+    # @return [Sequitur::GrammarVisitor]
+    def visitor: () -> Sequitur::GrammarVisitor
+
+    # Append a given symbol to the rhs of passed production.
+    # @param aProduction [Production]
+    # @param aSymbol [Object]
+    def append_symbol_to: (Production aProduction, untyped aSymbol) -> untyped
+  end
+end

data/sig/lib/sequitur/formatter/base_formatter.rbs

@@ -0,0 +1,20 @@
+module Sequitur
+  # Namespace dedicated to grammar formatters.
+  module Formatter
+    # Superclass for grammar formatters.
+    class BaseFormatter
+      # The IO output stream in which the formatter's result will be sent.
+      attr_accessor output: untyped
+
+      # Constructor.
+      # @param anIO [IO] an output IO where the formatter's result will
+      # be placed.
+      def initialize: (untyped anIO) -> void
+
+      # Given a grammar or a grammar visitor, perform the visit
+      # and render the visit events in the output stream.
+      # @param aGrmOrVisitor [DynamicGrammar, GrammarVisitor]
+      def render: ((DynamicGrammar | GrammarVisitor) aGrmOrVisitor) -> untyped
+    end
+  end
+end

data/sig/lib/sequitur/formatter/base_text.rbs

@@ -0,0 +1,62 @@
+module Sequitur
+  module Formatter
+    # A formatter class that can render a dynamic grammar in plain text.
+    # @example
+    #   some_grammar = ... # Points to a DynamicGrammar-like object
+    #   # Output the result to the standard console output
+    #   formatter = Sequitur::Formatter::BaseText.new(STDOUT)
+    #   # Render the grammar (through a visitor)
+    #   formatter.run(some_grammar.visitor)
+    class BaseText < BaseFormatter
+      attr_reader prod_lookup: ::Hash[Production, Integer]
+
+      # Constructor.
+      # @param anIO [IO] The output stream to which the rendered grammar
+      # is written.
+      def initialize: (IO anIO) -> void
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor is about to visit a grammar
+      # @param aGrammar [DynamicGrammar]
+      def before_grammar: (DynamicGrammar aGrammar) -> untyped
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor is about to visit
+      # a production
+      # @param aProduction [Production]
+      def before_production: (Production aProduction) -> untyped
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor is about to visit
+      # the rhs of a production
+      # @param _ [Array]
+      def before_rhs: (::Array[untyped] _)
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor is about to visit
+      # a terminal symbol from the rhs of a production
+      # @param aSymbol [Object]
+      def before_terminal: (untyped aSymbol) -> untyped
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor is about to visit
+      # a non-terminal (= an allusion to a production) in the rhs of a
+      # production
+      # @param aProduction [Production] a production occurring in the rhs
+      def before_non_terminal: (Production aProduction) -> untyped
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor complete the visit
+      # of a production
+      # @param _ [Production]
+      def after_production: (Production _) -> untyped
+
+      private
+
+      # Generate a name of a given production.
+      # @param aProduction [Production]
+      # @return [String]
+      def prod_name: (Production aProduction) -> String
+    end
+  end
+end