sequitur 0.1.03 → 0.1.05

data/lib/sequitur/grammar_visitor.rb

@@ -1,80 +1,98 @@
 module Sequitur # Module for classes implementing the Sequitur algorithm
 
 # A visitor class dedicated in the visit of Grammar.
-
 class GrammarVisitor
+  # Link to the grammar to visit
   attr_reader(:grammar)
-  
+
+  # List of objects that subscribed to the visit event notification.
   attr_reader(:subscribers)
-  
-  # Constructor.
-  # [aGrammar] a DynamicGrammar-like instance.
+
+  # Build a visitor for the given grammar.
+  # @param aGrammar [DynamicGrammar-like] the grammar to visit.
   def initialize(aGrammar)
     @grammar = aGrammar
     @subscribers = []
   end
-  
+
   public
-  
-  # Add a subscriber to the list.
+
+  # Add a subscriber for the visit event notification.
+  # @param aSubscriber [Object]
   def subscribe(aSubscriber)
     subscribers << aSubscriber
   end
-  
+
+  # Remove the given object from the subscription list.
+  # The object won't be notified of visit events.
+  # @param aSubscriber [Object]
   def unsubscribe(aSubscriber)
     subscribers.delete_if { |entry| entry == aSubscriber }
   end
-  
+
   # The signal to start the visit.
   def start()
-    grammar.send(:accept, self)
+    grammar.accept(self)
   end
 
-  
+
+  # Visit event. The visitor is about to visit the grammar.
+  # @param aGrammar [DynamicGrammar-like] the grammar to visit.
   def start_visit_grammar(aGrammar)
     broadcast(:before_grammar, aGrammar)
   end
-  
 
+
+  # Visit event. The visitor is about to visit the given production.
+  # @param aProduction [Production] the production to visit.
   def start_visit_production(aProduction)
     broadcast(:before_production, aProduction)
     broadcast(:before_rhs, aProduction.rhs)
   end
 
-
+  # Visit event. The visitor is visiting the 
+  # given reference production (= non-terminal symbol).
+  # @param aProdRef [ProductionRef] the production reference to visit.
   def visit_prod_ref(aProdRef)
     production = aProdRef.production
     broadcast(:before_non_terminal, production)
     broadcast(:after_non_terminal, production)
   end
 
+  # Visit event. The visitor is visiting the 
+  # given terminal symbol.
+  # @param aTerminal [Object] the terminal to visit.
   def visit_terminal(aTerminal)
     broadcast(:before_terminal, aTerminal)
     broadcast(:after_terminal, aTerminal)
-  end 
-
+  end
 
+  # Visit event. The visitor has completed its visit of the given production.
+  # @param aProduction [Production] the production to visit.
   def end_visit_production(aProduction)
     broadcast(:after_rhs, aProduction.rhs)
     broadcast(:after_production, aProduction)
 
-  end  
-  
-  
+  end
+
+  # Visit event. The visitor has completed the visit of the grammar.
+  # @param aGrammar [DynamicGrammar-like] the grammar to visit.
   def end_visit_grammar(aGrammar)
     broadcast(:after_grammar, aGrammar)
   end
-  
-  private
 
+  private
+  # Send a notification to all subscribers.
+  # @param msg [Symbol] event to notify
+  # @param args [Array] arguments of the notification.
   def broadcast(msg, *args)
     subscribers.each do |a_subscriber|
       next unless a_subscriber.respond_to?(msg)
       a_subscriber.send(msg, *args)
     end
   end
-  
-  
+
+
 end # class
 
 end # module

data/lib/sequitur/production.rb

@@ -11,7 +11,7 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
 # The rule stipulates that the LHS is equivalent to the RHS,
 # in other words every occurrence of the LHS can be substituted to
 # corresponding RHS.
-# The object id of the production is taken as its LHS.
+# Implementation note: the object id of the production is taken as its LHS.
 class Production
   # The right-hand side (rhs) consists of a sequence of grammar symbols
   attr_reader(:rhs)
@@ -22,7 +22,8 @@ class Production
   # The sequence of digrams appearing in the RHS
   attr_reader(:digrams)
 
-  # Constructor. Build a production with an empty RHS.
+  # Constructor. 
+  # Build a production with an empty RHS.
   def initialize()
     clear_rhs
     @refcount = 0
@@ -31,6 +32,9 @@ class Production
 
   public
 
+  # Identity testing.
+  # @param other [] another production or production reference.
+  # @return true when the receiver and other are the same.
   def ==(other)
     return true if object_id == other.object_id
 
@@ -45,33 +49,40 @@ class Production
 
 
   # Is the rhs empty?
+  # @ return true if the rhs has no members.
   def empty?
     return rhs.empty?
   end
 
+  # Increment the reference count by one.
   def incr_refcount()
     @refcount += 1
   end
 
+  # Decrement the reference count by one.
   def decr_refcount()
     fail StandardError, 'Internal error' if @refcount == 0
     @refcount -= 1
   end
 
 
-  # Return the set of references to production appearing in the rhs.
+  # Select the references to production appearing in the rhs.
+  # @return [Array of ProductionRef]
   def references()
     return rhs.select { |symb| symb.is_a?(ProductionRef) }
   end
 
-  # Return the set of references to a given production
+  # Look in the rhs all the references to a production passed a argument.
+  # aProduction [aProduction or ProductionRef] The production to search for.
+  # @return [Array] the array of ProductionRef to the passed production
   def references_of(aProduction)
     refs = references
     return refs.select { |a_ref| a_ref == aProduction }
   end
 
 
-  # Return the list digrams found in rhs of this production.
+  # Enumerate the digrams appearing in the right-hand side (rhs)
+  # @return [Array] the list of digrams found in rhs of this production.
   def recalc_digrams()
     return [] if rhs.size < 2
 
@@ -84,6 +95,7 @@ class Production
 
 
   # Does the rhs have exactly one digram only (= 2 symbols)?
+  # @return [true/false] true when the rhs contains exactly two symbols.
   def single_digram?
     return rhs.size == 2
   end
@@ -92,7 +104,8 @@ class Production
   # Detect whether the last digram occurs twice
   # Assumption: when a digram occurs twice in a production then it must occur
   # at the end of the rhs
-  def repeated_digram?
+  # @return [true/false] true when the digram occurs twice in rhs.
+  def repeated_digram?()
     return false if rhs.size < 3
 
     my_digrams = digrams
@@ -102,7 +115,8 @@ class Production
     return !same_key_found.nil?
   end
 
-  # Return the last digram appearing in the RHS.
+  # Retrieve the last digram appearing in the RHS (if any).
+  # @return [Digram] last digram in the rhs otherwise nil.
   def last_digram()
     result = digrams.empty? ? nil : digrams.last
     return result
@@ -113,6 +127,7 @@ class Production
   # Emit a text representation of the production rule.
   # Text is of the form:
   # object id of production : rhs as space-separated sequence of symbols.
+  # @return [String]
   def to_string()
     rhs_text = rhs.map do |elem|
       case elem
@@ -125,6 +140,7 @@ class Production
   end
 
   # Add a (grammar) symbol at the end of the RHS.
+  # @param aSymbol [Object] A (grammar) symbol to add.
   def append_symbol(aSymbol)
     case aSymbol
       when Production
@@ -145,22 +161,27 @@ class Production
   end
 
   # Clear the right-hand side.
-  # Any referenced production has its back reference counter decremented
+  # Any referenced production has its reference counter decremented.
   def clear_rhs()
     if rhs
       refs = references
-      refs.each { |a_ref| a_ref.unbind }
+      refs.each(&:unbind)
     end
     @rhs = []
   end
 
   # Find all the positions where the digram occurs in the rhs
-  # Synopsis:
-  # Given the production p -> a b c a b a b d
-  # Then p.positions_of(a, b) should returns [0, 3, 5]
-  # Caution: "overlapping" digrams shouldn't be counted
-  # Given the production p -> a a b a a a c d
-  # Then p.positions_of(a, a) should returns [0, 3]
+  # @param symb1 [Object] first symbol of the digram
+  # @param symb2 [Object] second symbol of the digram
+  # @return [Array] the list of indices where the digram occurs in rhs.
+  # @example
+  #   # Given the production p : a b c a b a b d
+  #   #Then ...
+  #   p.positions_of(a, b) # => [0, 3, 5]
+  #   # Caution: "overlapping" digrams shouldn't be counted
+  #   # Given the production p : a a b a a a c d
+  #   # Then ... 
+  #   p.positions_of(a, a) # => [0, 3]
   def positions_of(symb1, symb2)
 
     # Find the positions where the digram occur in rhs
@@ -176,11 +197,12 @@ class Production
   end
 
 
-  # Substitute in self all occurrences of the digram that
-  # appears in the rhs of the other production
-  # Pre-condition:
-  # another has a rhs with exactly one digram (= a two-symbol sequence).
-  def replace_digram(another)
+  # 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 another [Production or ProductionRef] a production that
+  #   consists exactly of one digram (= 2 symbols).
+  def reduce_step(another)
     (symb1, symb2) = another.rhs
     pos = positions_of(symb1, symb2).reverse
 
@@ -199,14 +221,17 @@ class Production
     recalc_digrams
   end
 
-  # Replace every occurrence of 'another' production in rhs by
-  # the rhs of 'another'.
-  # Given the production p_A -> a p_B b p_B c
-  # And the production p_B -> x y
-  # Then the call p_A.replace_production(p_B)
-  # Modifies p_A as into:
-  # p_A -> a x y b x y c
-  def replace_production(another)
+  # Replace every occurrence of 'another' production in self.rhs by
+  #   the symbols in the rhs of 'another'.
+  # @param another [Production or ProductionRef] a production that
+  #   consists exactly of one digram (= 2 symbols).
+  # @example Synopsis
+  # # Given the production p_A : a p_B b p_B c
+  # # And the production p_B : x y
+  # # Then...
+  # p_A.derive_step(p_B)
+  # #Modifies p_A as into: p_A -> a x y b x y c
+  def derive_step(another)
     (0...rhs.size).to_a.reverse.each do |index|
       next unless rhs[index] == another
 
@@ -223,8 +248,8 @@ class Production
   end
 
 
-  # Part of the 'visitee' role.
-  # [aVisitor] a GrammarVisitor instance
+  # Part of the 'visitee' role in Visitor design pattern.
+  # @param aVisitor[GrammarVisitor]
   def accept(aVisitor)
     aVisitor.start_visit_production(self)
 

data/lib/sequitur/production_ref.rb

@@ -9,24 +9,40 @@ module Sequitur # Module for classes implementing the Sequitur algorithm
 # in the appropriate position in the RHS of P1.
 # In the literature, production references are also called non terminal
 # symbols
+# @example
+#   # Given a production rule...
+#   prod = Sequitur::Production.new
+#   puts prod.refcount # outputs 0
+#   # ... Build a reference to it
+#   ref = Sequitur::ProductionRef.new(prod)
+#   # ... Production reference count is updated...
+#   puts prod.refcount # outputs 1
 class ProductionRef
 
-  # Link to the production to reference
+  # Link to the production to reference.
   attr_reader(:production)
 
   # Constructor
-  # [target] The production that is being referenced.
+  # @param target [Production or ProductionRef]
+  #   The production that is being referenced.
   def initialize(target)
     bind_to(target)
   end
-  
-  # Copy constructor invoked by dup or clone methods
+
+  # Copy constructor invoked by dup or clone methods.
+  # @param orig [ProductionRef]
+  # @example
+  #   prod = Sequitur::Production.new
+  #   ref = Sequitur::ProductionRef.new(prod)
+  #   copy_ref = ref.dup
+  #   puts prod.refcount # outputs 2
   def initialize_copy(orig)
     @production = nil
     bind_to(orig.production)
   end
 
-  # Return the text representation of a production reference.
+  # Emit the text representation of a production reference.
+  # @return [String]
   def to_s()
     return "#{production.object_id}"
   end
@@ -35,9 +51,11 @@ class ProductionRef
 
 
   # Equality testing.
-  # A production ref is equal to another one when its
-  # refers to the same production or when it is compared to
-  # the production it refers to.
+  #   A production ref is equal to another one when its
+  #   refers to the same production or when it is compared to
+  #   the production it refers to.
+  # @param other [ProductionRef]
+  # @return [true / false]
   def ==(other)
     return true if object_id == other.object_id
 
@@ -50,42 +68,48 @@ class ProductionRef
     return result
   end
 
-  # Generates a Fixnum value as hash value.
-  # As a reference has no identity on its own,
-  # the method returns the hash value of the
-  # referenced production
+  # Produce a hash value.
+  #   A reference has no identity on its own,
+  #   the method returns the hash value of the
+  #   referenced production
+  # @return [Fixnum] the hash value
   def hash()
     fail StandardError, 'Nil production' if production.nil?
     return production.hash
   end
-  
-  # Make this reference points to the given production
+
+  # Make this reference point to the given production.
+  # @param aProduction [Production or ProductionRef] the production
+  #   to refer to
   def bind_to(aProduction)
     return if aProduction == @production
-    
+
     production.decr_refcount if production
     unless aProduction.kind_of?(Production)
       fail StandardError, "Illegal production type #{aProduction.class}"
     end
-    @production = aProduction  
+    @production = aProduction
     production.incr_refcount
   end
 
-  # Clear the reference to the target production
+
+  # Clear the reference to the target production.
   def unbind()
     production.decr_refcount
     @production = nil
   end
 
   # Check that the this object doesn't refer to any production.
+  # @return [true / false] true when this object doesn't 
+  #   point to a production.
   def unbound?()
     return production.nil?
   end
-  
-  # Part of the 'visitee' role.
-  # [aVisitor]  a GrammarVisitor instance
+
+  # Part of the 'visitee' role in the Visitor design pattern.
+  # @param aVisitor [GrammarVisitor] the visitor
   def accept(aVisitor)
-    aVisitor.visit_prod_ref(self)  
+    aVisitor.visit_prod_ref(self)
   end
 
 end # class

data/lib/sequitur/sequitur_grammar.rb

@@ -3,13 +3,18 @@ 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
 
-  # Constructor. Build the grammar from an enumerator of tokens
+  # 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 { root.incr_refcount }
+    2.times { start.incr_refcount }
 
     # Read the input sequence and apply the Sequitur algorithm
     anEnum.each do |a_token|
@@ -18,10 +23,14 @@ class SequiturGrammar < DynamicGrammar
     end
   end
 
-  public
+  private
 
-
-CollisionDiagnosis = Struct.new(:collision_found, :digram, :productions)
+# 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,
@@ -37,7 +46,7 @@ CollisionDiagnosis = Struct.new(:collision_found, :digram, :productions)
   #   end
   #  end until digram unicity and rule utility are met
   def enforce_rules()
-    begin
+    loop do
       unicity_diagnosis = detect_collision if unicity_diagnosis.nil?
       restore_unicity(unicity_diagnosis) if unicity_diagnosis.collision_found
       
@@ -46,8 +55,8 @@ CollisionDiagnosis = Struct.new(:collision_found, :digram, :productions)
 
       unicity_diagnosis = detect_collision
       useless_prod = detect_useless_production
-      
-    end while unicity_diagnosis.collision_found || useless_prod
+      break unless unicity_diagnosis.collision_found || useless_prod
+    end
   end
 
   # Check whether a digram is used twice in the grammar.
@@ -88,15 +97,11 @@ CollisionDiagnosis = Struct.new(:collision_found, :digram, :productions)
   # Then create a new production that will have
   # the symbols of d as its rhs members.
   def restore_unicity(aDiagnosis)
-    return if aDiagnosis.nil?
-
     digr = aDiagnosis.digram
     prods = aDiagnosis.productions
     if prods.any?(&:single_digram?)
-      (simple, compound) = prods.partition do |a_prod|
-        a_prod.single_digram?
-      end
-      compound[0].replace_digram(simple[0])
+      (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.
@@ -104,9 +109,9 @@ CollisionDiagnosis = Struct.new(:collision_found, :digram, :productions)
       digr.symbols.each { |sym| new_prod.append_symbol(sym) }
       add_production(new_prod)
       if prods[0] == prods[1]
-        prods[0].replace_digram(new_prod)
+        prods[0].reduce_step(new_prod)
       else
-        prods.each { |a_prod| a_prod.replace_digram(new_prod) }
+        prods.each { |a_prod| a_prod.reduce_step(new_prod) }
       end
     end
   end
@@ -136,7 +141,7 @@ CollisionDiagnosis = Struct.new(:collision_found, :digram, :productions)
       break
     end
 
-    referencing.replace_production(useless_prod)
+    referencing.derive_step(useless_prod)
     remove_production(index)
   end