sequitur 0.1.03 → 0.1.05

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Mzg2M2MwZDY5M2M1Zjc5MGZlOWI5MTMwM2ExNTc3YWZlMWI4MjliZA==
+    MjI4NGQ0MTJmZjkyYzVlZDg0MTA3MTExMDU1NGI2MzRiODcyMTg1ZA==
   data.tar.gz: !binary |-
-    OTY4NzRlYjJmMGU1Nzc4ZDdiZmNkYWFiNzRmMWU3OThiMmExNDNkYg==
+    YWFjNTY5ZWJmZjI0YWIwZWE5ZjRkOTU3NzA2ZDMwZjBjYjFkMmE3Mg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    Y2M3Mjg1ZTFkYzEzNWI0YWYwMmIxMGIzZGE5ZjZmZmE4NmRjMDQ3NGE3Nzhl
-    YTZiMjM1ZWM1OTRiODAwMmE0NDg0NWI1MzYyZGQ1Y2RiMTAzNWMwMzFjNzE1
-    OGVkYmNlYzBmMjlhYmI3NDZkZTZjYWNjY2VkZTk2MzQxNWQ4OGY=
+    OWNlODIxNjAzMTlhYzhhZjA5NWY4NTJlYjkxNjY1ZjMwYjU4YzZkMDU5ZDJi
+    M2JlNjNlMGM4ZTNkY2FkZGM0Njc2NTNiYTIyM2Q0Y2YyNTk2MjU5YWFkOWEz
+    NTE0ZjM0NjQ2NDdjMjhkYzNkMGNkN2M1OWZlMmUzZWZiMWZkMjM=
   data.tar.gz: !binary |-
-    MTNiNjhlYTNhNGU1NjY4ZTUwNzkzNWRiYzllMDA5MjczYmFhMzE3MDJiZDI3
-    NWUzYzIyNTJlMDYzZTUxOWFmOTM0MzE3MDU3YTJiMTgzMTVkN2QyMGU5ZDFi
-    MmU0ZTMxZjYwMzNkZjFmNGVhMGU4M2E1ZTQ5YTliMDg4NmNlZGQ=
+    YTk1MjgzMzcxYWUwNmI2NDY3MDc3YmU5NTYxMjJkOTljY2EzOGRhYjI4ZWUw
+    ZDA1ZTYzMWJjYmQwMmMyMjU0ZTJmNTIzZjZjMWY4NGZhNmE4MDE0MTVkODBk
+    NThmODRiMzM3MTk5NGE2MTExMGMyZGFhYTgxNDBlZGIwZGRmZDE=

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+### 0.1.05 / 2014-09-28
+* [CHANGE] File `README.md`: added badge from inch-ci.org (documentation quality).
+
+### 0.1.04 / 2014-09-28
+* [CHANGE] All methods are now documented (YARD reports 100% coverage).
+
 ### 0.1.03 / 2014-09-21
 * [CHANGE] Class `Sequitur::SequiturGrammar` Code refactoring: cleaner and simpler implementation the algorithm.
 * [CHANGE] Class `Sequitur::Digram`. Added new method `repeating?` that tells whether digram members are the same.

data/README.md

@@ -6,6 +6,7 @@ _Ruby gem implementing the Sequitur algorithm_
 [![Build Status](https://travis-ci.org/famished-tiger/Sequitur.svg?branch=master)](https://travis-ci.org/famished-tiger/Sequitur)
 [![Gem Version](https://badge.fury.io/rb/sequitur.svg)](http://badge.fury.io/rb/sequitur)
 [![Dependency Status](https://gemnasium.com/famished-tiger/Sequitur.png)](https://gemnasium.com/famished-tiger/Sequitur)
+[![Inline docs](http://inch-ci.org/github/famished-tiger/Sequitur.svg?branch=master)](http://inch-ci.org/github/famished-tiger/Sequitur)
 
 
 ### What is the Sequitur algorithm? ###

data/lib/sequitur.rb

@@ -10,12 +10,12 @@ require_relative './sequitur/formatter/base_text'
 
 module Sequitur
 
-  # Convenience method. Builds a Sequitur-generated grammar based
-  # on the sequence of input tokens
+  # Build a Sequitur-generated grammar based on the sequence of input tokens.
+  #
   # @param tokens [StringOrEnumerator] 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.
-  # Returns a SequiturGrammar instance.
+  #   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

data/lib/sequitur/constants.rb

@@ -3,22 +3,22 @@
 
 module Sequitur # Module used as a namespace
   # The version number of the gem.
-  Version = '0.1.03'
+  Version = '0.1.05'
 
   # Brief description of the gem.
   Description = 'Ruby implementation of the Sequitur algorithm'
 
   # Constant Sequitur::RootDir contains the absolute path of Sequitur's
-  # root directory. Note: it also ends with a slash character.
+  # start directory. Note: it also ends with a slash character.
   unless defined?(RootDir)
     # The initialisation of constant RootDir is guarded in order
     # to avoid multiple initialisation (not allowed for constants)
 
-    # The root folder of Sequitur.
+    # The start folder of Sequitur.
     RootDir = begin
       require 'pathname' # Load Pathname class from standard library
-      rootdir = Pathname(__FILE__).dirname.parent.parent.expand_path
-      rootdir.to_s + '/' # Append trailing slash character to it
+      startdir = Pathname(__FILE__).dirname.parent.parent.expand_path
+      startdir.to_s + '/' # Append trailing slash character to it
     end
   end
 end # module

data/lib/sequitur/digram.rb

@@ -3,24 +3,28 @@
 module Sequitur # Module for classes implementing the Sequitur algorithm
 
 # 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 grammar (production) rule. Each symbol in a digram 
+# 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.
+  #   The two symbols should respond to the :hash message.
   attr_reader(:symbols)
   
-  # An unique Hash key of the digram
+  # An unique hash key of the digram
   attr_reader(:key)
   
   # The production in which the digram occurs
   attr_reader(: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 [StringOrSymbol] First element of the digram
   # @param symbol2 [StringOrSymbol] Second element of the digram
   # @param aProduction [Production] Production in which the RHS 
-  # the sequence symbol1 symbol2 appears.
+  #   the sequence symbol1 symbol2 appears.
   def initialize(symbol1, symbol2, aProduction)
     @symbols = [symbol1, symbol2]
     @key = "#{symbol1.hash.to_s(16)}:#{symbol2.hash.to_s(16)}" 
@@ -28,12 +32,15 @@ class Digram
   end
   
   # Equality testing.
-  # Returns true when keys of both digrams are equal
+  #   true iff keys of both digrams are equal, false otherwise
+  # @param other [Digram] another to compare with
+  # @return [true/false]
   def ==(other)
     return key == other.key
   end
   
-  # Return true when the digram consists of twice the same symbols
+  # Does the digram consists of twice the same symbols?
+  # @return [true/false] true when symbols.first == symbols.last
   def repeating?()
     return symbols[0] == symbols[1]
   end

data/lib/sequitur/dynamic_grammar.rb

@@ -3,9 +3,17 @@ require_relative 'grammar_visitor'
 
 module Sequitur # Module for classes implementing the Sequitur algorithm
 
+# 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
-  # Link to the root - start - production.
-  attr_reader(:root)
+  # Link to the start production.
+  attr_reader(:start)
 
   # The set of production rules of the grammar
   attr_reader(:productions)
@@ -15,10 +23,10 @@ class DynamicGrammar
 
 
   # Constructor.
-  # Build a grammar with one empty rule as start/root rule
+  # Build a grammar with one empty rule as start/start rule.
   def initialize()
-    @root = Production.new
-    @productions = [ root ]
+    @start = Production.new
+    @productions = [ start ]
     @trace = false
   end
 
@@ -26,6 +34,7 @@ class DynamicGrammar
 
   # Emit a text representation of the grammar.
   # Each production rule is emitted per line.
+  # @return [String]
   def to_string()
     rule_text = productions.map(&:to_string).join("\n")
     return rule_text
@@ -33,16 +42,18 @@ class DynamicGrammar
 
 
   # Add a given production to the grammar.
+  # @param aProduction [Production]
   def add_production(aProduction)
     # TODO: remove output
     puts "Adding #{aProduction.object_id}" if trace
     puts aProduction.to_string if trace
-    check_rhs_of(aProduction) # TODO: configurable check
     productions << aProduction
   end
 
 
-  # Remove a production from the grammar
+  # Remove a production with given index from the grammar
+  # @param anIndex [Fixnum]
+  # @return [Production] the production removed from the grammar.
   def remove_production(anIndex)
     puts "Before production removal #{productions[anIndex].object_id}" if trace
     puts to_string if trace
@@ -56,55 +67,38 @@ class DynamicGrammar
 
 
   # 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(aToken)
-    append_symbol_to(root, aToken)
+    append_symbol_to(start, aToken)
   end
 
-  # Part of the 'visitee' role.
-  # [aVisitor] a GrammarVisitor instance
+  # Part of the 'visitee' role in the Visitor design pattern.
+  #   A visitee is expected to accept the visit from a visitor object
+  # @param aVisitor [GrammarVisitor] the visitor object
   def accept(aVisitor)
     aVisitor.start_visit_grammar(self)
+    
+    # Let's proceed with the visit of productions
     productions.each { |prod| prod.accept(aVisitor) }
+    
     aVisitor.end_visit_grammar(self)
   end
 
   # Factory method. Returns a visitor for this grammar.
+  # @return [GrammarVisitor]
   def visitor()
     return GrammarVisitor.new(self)
   end
 
   protected
-
+  
+  # Append a given symbol to the rhs of passed production.
+  # @param aProduction [Production]
+  # @param aSymbol [Object]
   def append_symbol_to(aProduction, aSymbol)
     aProduction.append_symbol(aSymbol)
   end
-
-
-  # Check that every production reference in rhs is
-  # pointing to a production of the grammar
-  def check_rhs_of(aProduction)
-    aProduction.references.each do |symb|
-      referenced_prod = symb.production
-      next if productions.include?(referenced_prod)
-
-      msg = "Production #{aProduction.object_id} refers to"
-      msg << " production #{referenced_prod.object_id}"
-      msg << ' that is not part of the grammar.'
-      fail StandardError, msg
-    end
-  end
-
-
-  # Visitor pattern.
-  # A visitee is expected to accept the visit from a visitor object
-  def accept(aVisitor)
-    aVisitor.start_visit_grammar(self)
-
-    # Let's proceed with the visit of productions
-    productions.each { |a_prod| a_prod.accept(aVisitor) }
-
-    aVisitor.end_visit_grammar(self)
-  end
 end # class
 
 end # module

data/lib/sequitur/formatter/base_formatter.rb

@@ -1,4 +1,6 @@
 module Sequitur
+
+  # Namespace dedicated to grammar formatters.
   module Formatter
   
     # Superclass for grammar formatters.
@@ -7,7 +9,8 @@ module Sequitur
       attr(:output)
 
       # Constructor.
-      # [anIO] an output IO where the formatter's result will be placed.
+      # @param anIO [IO] an output IO where the formatter's result will 
+      # be placed.
       def initialize(anIO)
         @output = anIO
       end
@@ -16,6 +19,7 @@ module Sequitur
       
       # Given a grammar or a grammar visitor, perform the visit
       # and render the visit events in the output stream.
+      # @param aGrmOrVisitor [DynamicGrammar or GrammarVisitor]
       def render(aGrmOrVisitor)
         if aGrmOrVisitor.kind_of?(GrammarVisitor)
           a_visitor = aGrmOrVisitor

data/lib/sequitur/formatter/base_text.rb

@@ -2,60 +2,86 @@ require_relative 'base_formatter'
 
 module Sequitur
   module Formatter
-  
+
     # A formatter class that can render a dynamic grammar in plain text.
-    # Synopsis:
-    # 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)
+    # @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
 
       # Constructor.
-      # [anIO]
+      # @param anIO [IO] The output stream to which the rendered grammar
+      # is written.
       def initialize(anIO)
         super(anIO)
         @prod_lookup = {}
       end
 
       public
-      
+
+      # 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-like object]
       def before_grammar(aGrammar)
         aGrammar.productions.each_with_index do |a_prod, index|
           prod_lookup[a_prod] = index
         end
       end
 
+      # 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 [aProduction]
       def before_production(aProduction)
         p_name = prod_name(aProduction)
         output.print p_name
       end
 
+      # 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(_)
         output.print ' :'
       end
 
+      # 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(aSymbol)
         output.print " #{aSymbol}"
       end
 
-
+      # 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(aProduction)
         p_name = prod_name(aProduction)
         output.print " #{p_name}"
       end
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor complete the visit 
+      # of a production
       def after_production(_)
         output.print ".\n"
       end
 
       private
       
+      # Read accessor of the production lookup
       def prod_lookup()
         return @prod_lookup
       end
-      
+
+      # Generate a name of a given production.
+      # @param aProduction [Production] 
       def prod_name(aProduction)
         prod_index = prod_lookup[aProduction]
         name = (prod_index == 0) ? 'start' : "P#{prod_index}"

data/lib/sequitur/formatter/debug.rb

@@ -3,11 +3,22 @@ require_relative 'base_formatter'
 
 module Sequitur
   module Formatter
+
+    # A formatter class that can render the notification events
+    # from a grammar visitor
+    # @example
+    #   some_grammar = ... # Points to a DynamicGrammar-like object
+    #   # Output the result to the standard console output
+    #   formatter = Sequitur::Formatter::Debug.new(STDOUT)
+    #   # Render the visit notifications
+    #   formatter.run(some_grammar.visitor)
     class Debug < BaseFormatter
+      # Current indentation level
       attr(:indentation)
 
       # Constructor.
-      # [anIO]
+      # @param anIO [IO] The output stream to which the rendered grammar
+      # is written.
       def initialize(anIO)
         super(anIO)
         @indentation = 0
@@ -15,47 +26,85 @@ module Sequitur
 
       public
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor is about to visit a grammar
+      # @param _ [DynamicGrammar-like object]
       def before_grammar(_)
         output_event(__method__, indentation)
         indent
       end
 
+      # 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]
       def before_production(_)
         output_event(__method__, indentation)
         indent
       end
 
+      # 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(_)
         output_event(__method__, indentation)
         indent
       end
 
+      # 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 _ [Object]
       def before_terminal(_)
         output_event(__method__, indentation)
       end
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit of
+      # a terminal symbol from the rhs of a production
+      # @param _ [Object]
       def after_terminal(_)
         output_event(__method__, indentation)
       end
 
+      # 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 _ [Production] a production occurring in the rhs
       def before_non_terminal(_)
         output_event(__method__, indentation)
       end
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit of
+      # a non-terminal symbol from the rhs of a production.
+      # @param _ [Object]
       def after_non_terminal(_)
         output_event(__method__, indentation)
       end
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit of
+      # the rhs of a production
+      # @param _ [Array]
       def after_rhs(_)
         dedent
         output_event(__method__, indentation)
       end
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit
+      # of a production
       def after_production(_)
         dedent
         output_event(__method__, indentation)
       end
 
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit
+      # of a grammar
       def after_grammar(_)
         dedent
         output_event(__method__, indentation)