sequitur 0.1.00 → 0.1.01

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZDAyNmJiYjE4YTQzNWMxZDI0ZWU2NTJhMGZiMTBiMmI0ZDg5MTBkOA==
+    NTQ5ODkzODJlYjNmZDBiODNiZTdiZTE4ZDFlNTljYWFhMTg5MzExYw==
   data.tar.gz: !binary |-
-    MzI2YzIxMmZkYjExYTk1Yjc4ZTk0MDg0ZjczYjUxNDI4YWNkMWMxZg==
+    YzZkNWE1MTdhZTBiMWZmOTI1ZDhhMDJkM2QxYTU3ZDAxZDExZjk5MQ==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NzEwYTk3ZGFhOGU5ZDZkMWRlMWVmZWU5MDQxOTQ0YTk5ZDIzMGM4YjY1ODAw
-    NjQyYmU0ODEwZTRhYzM4ZjVmMWQ3ZDgyNjdiNDkzNjMyZmExZjFmN2Q0MTk3
-    ODE4NTQwYjBiZGQ5M2QyY2JlZTczMzIzMWI0YjUwYzVmNzkyNjg=
+    YWVmZTE0YWQ4MmEyMTI4YTFjYmU2MTZkYTZhOGUwZTM4YTZmMDQ2OTliMDky
+    NjVmMjdkYmVkMGY3MGEzMDBlM2RjMzNlODMzZDQ3NGY4NzRmNzNkNjNlOTI2
+    ZGFlMTkxMTNmZjA0MTI2MjM0MzhkMjM4MjUwMzg0ZDk5NDU0YTU=
   data.tar.gz: !binary |-
-    MTYxOWNiMjg5MzRhY2JlOTdmYjJjZmI0YjVkYzA1MmIxMmY5NjQ4NDY2Zjc1
-    NWJlY2MyY2Q4ZWE2OTFmZGFiZWU1YjZkMjNmMzYzY2ZmYmM2MTE3MWVjODNj
-    ZDBlNzA3M2VjNmI3NTJhNTk5NGY0OGY4ODFlOGJhZDY1MDMyZmU=
+    MTNhOGQyOWNlNTQ4Y2RiOTcyYjU3ZDM3MGZmZGEzYjY2NjFkM2RiZmI3ZTZl
+    ZmRiM2JiNzU0MGVkMDUzYTVjM2M4MmM3MWQwYTgyNmQzYjA0MTdhNWI4Mjg2
+    ODAwYTc4M2JjZGQyOTUzOGM4MjA5MzZhYThlMmM5MWNjYjJhZmQ=

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+### 0.1.01 / 2014-09-17
+* [NEW] Added new `BaseFormatter` superclass. Sample formatters are inheriting from this one.  
+* [CHANGE] File `README.me`: added a brief intro to the Sequitur algorithm, expanded the Ruby examples 
+* [CHANGE] Private method `BaseText#prod_name` production name doesn't contain an underscore.
+* [CHANGE] Formatter class `BaseText` now inherits from `BaseFormatter`
+* [CHANGE] Formatter class `Debug` now inherits from `BaseFormatter`
+
+
 ### 0.1.00 / 2014-09-16
 * [CHANGE] Version number bumped. Added grammar rendering through specialized formatters.
 

data/README.md

@@ -9,43 +9,105 @@ _Ruby gem implementing the Sequitur algorithm_
 
 
 ### What is the Sequitur algorithm? ###
-[Sequitur home](http://sequitur.info/)  
+The following are good entry points to learn about the algorithm:  
+[Sequitur algorithm home](http://sequitur.info/)  
 [Wikipedia](http://en.wikipedia.org/wiki/Sequitur_algorithm)  
 
-Sequitur is an algorithm that generates a set of rules representing a sequence of input tokens.  
-It detects repeated token patterns and can represent them in a compact way.
+### The theory in a nutshell ###
+Given a sequence of input tokens (say, characters), the Sequitur algorithm 
+will represent that input sequence as a set of rules. As the algorithm detects  
+automatically repeated token patterns, the resulting rule set can encode repetitions in the input
+in a very compact way.  
+Of interest is the fact that the algorithm runs in time linear in the length of the input sequence.
+
+**Can you give a simple example?**  
+Sure. Let's begin with a very basic case. Assume that 'abcabcabc' is our input string.
+Notice that it is the same as the text 'abc' repeated three times. The Sequitur algorithm captures
+this repetition and will generate the two following rules:
+
+```
+start : P1 P1 P1.  
+P1 : a b c.
+```
+
+In plain English:
+-The first rule (named start) always represents the whole input. Here, it indicates that the input
+is three time the pattern encoded by the rule called P1.
+-The second rule (named P1) represents the sequence a b c.
+
+**Can you give another example?**  
+Yep. Assume this time that the input is 'ababcabcdabcde'. 
+Then Sequitur algorithm will generate the rule set:  
+```
+start : P1 P2 P3 P3 e.  
+P1 : a b.  
+P2 : P1 c.  
+P3 : P2 d.   
+```
+
+Translated in plain English:  
+- Rule (start) tells that the input consists of the sequence of P_1 P_2 P_3 patterns followed by the letter e.  
+- Rule (P1) represents the sequence 'ab'.  
+- Rule (P2) represents the pattern encoded by P1 (thus 'ab') then 'c'.   
+In other words, it represents the string 'abc'.  
+- Rule (P3) represents the pattern encoded by P2 then d. It is thus equivalent to 'abcd'.  
+
+**What is it used for?**  
+Sequitur can be used:  
+- As a lossless data compression algorithm (especially for structured text containing
+repeated elements)  
+- To detect hierarchical structure in sequences (e.g. traces in program execution)
 
 
 ## Synopsis  
 
+**Time for a quick demo**
+
+The following Ruby snippet show how to apply Sequitur on the input string from the last example above. 
+
 ```ruby  
 
     require 'sequitur'  # Load the Sequitur library
 
-    input_sequence =  'abcabdabcabd'  # Let's analyze this string
+    input_sequence =  'ababcabcdabcde'  # Let's analyze this string
 
-    # The SEQUITUR algorithm will detect the repeated 'ab' pattern
-    # and will generate a context-free grammar that represents the input string
+    # Run the Sequitur algorithm which will result in a grammar (=rule set)
+    grammar = Sequitur.build_from(input_sequence)
+````
+
+The demo illustrates how easy it is to run the algorithm on a string. However, the next question is how
+can you make good use of the algorithm's result.  
+
+The very first natural step is to be able to print out the (grammar) rules.
+Here's how:
+ 
+
+```ruby  
+    require 'sequitur'
+    input_sequence =  'ababcabcdabcde'
     grammar = Sequitur.build_from(input_sequence)
 
     # To display the grammar rules on the console output
-    # We use a formatter
+    # We use a grammar formatter
     formatter = Sequitur::Formatter::BaseText.new(STDOUT)
 
     # Now render the rules. Each rule is displayed with the format:
     # rule_id : a_sequence_grammar_symbols.
     # Where: 
-    # - rule_id is either 'start' or a name like 'P_xxxx' (xxxx is a sequential number)
+    # - rule_id is either 'start' or a name like 'Pxxxx' (xxxx is a sequential number)
     # - a grammar symbol is either a terminal symbol 
     # (i.e. a character from the input) or a rule id
     formatter.render(grammar.visitor)
 
     # Rendered output is:
-    # start : P_2 P_2.
-    # P_1 : a b.
-    # P_2 : P_1 c P_1 d.
+    # start : P1 P2 P3 P3 e.
+    # P1 : a b.
+    # P2 : P1 c.
+    # P3 : P2 d.
 ```
 
+
+
 ### TODO: Add more documentation ###
 
 

data/lib/sequitur/constants.rb

@@ -3,7 +3,7 @@
 
 module Sequitur # Module used as a namespace
   # The version number of the gem.
-  Version = '0.1.00'
+  Version = '0.1.01'
 
   # Brief description of the gem.
   Description = 'Ruby implementation of the Sequitur algorithm'

data/lib/sequitur/formatter/base_formatter.rb

@@ -0,0 +1,33 @@
+module Sequitur
+  module Formatter
+  
+    # Superclass for grammar formatters.
+    class BaseFormatter
+      # The IO output stream in which the formatter's result will be sent.
+      attr(:output)
+
+      # Constructor.
+      # [anIO] an output IO where the formatter's result will be placed.
+      def initialize(anIO)
+        @output = anIO
+      end
+
+      public
+      
+      # Given a grammar or a grammar visitor, perform the visit
+      # and render the visit events in the output stream.
+      def render(aGrmOrVisitor)
+        aVisitor = if aGrmOrVisitor.kind_of?(GrammarVisitor)
+          aGrmOrVisitor
+        else
+          aGrmOrVisitor.visitor
+        end
+        
+        aVisitor.subscribe(self)
+        aVisitor.start()
+        aVisitor.unsubscribe(self)
+      end
+    
+    end # class
+  end # module
+end # module

data/lib/sequitur/formatter/base_text.rb

@@ -1,3 +1,5 @@
+require_relative 'base_formatter'
+
 module Sequitur
   module Formatter
   
@@ -8,23 +10,16 @@ module Sequitur
     # formatter = Sequitur::Formatter::BaseText.new(STDOUT)
     # Render the grammar (through a visitor)
     # formatter.run(some_grammar.visitor)
-    class BaseText
-      attr(:output)
+    class BaseText < BaseFormatter
 
       # Constructor.
       # [anIO]
       def initialize(anIO)
-        @output = anIO
+        super(anIO)
         @prod_lookup = {}
       end
 
       public
-
-      def render(aVisitor)
-        aVisitor.subscribe(self)
-        aVisitor.start()
-        aVisitor.unsubscribe(self)
-      end
       
       def before_grammar(aGrammar)
         aGrammar.productions.each_with_index do |a_prod, index|
@@ -63,7 +58,7 @@ module Sequitur
       
       def prod_name(aProduction)
         prod_index = prod_lookup[aProduction]
-        name = (prod_index == 0) ? 'start' : "P_#{prod_index}"
+        name = (prod_index == 0) ? 'start' : "P#{prod_index}"
         return name
       end
 

data/lib/sequitur/formatter/debug.rb

@@ -1,24 +1,20 @@
+require_relative 'base_formatter'
+
+
 module Sequitur
   module Formatter
-    class Debug
+    class Debug < BaseFormatter
       attr(:indentation)
-      attr(:output)
 
       # Constructor.
       # [anIO]
       def initialize(anIO)
+        super(anIO)
         @indentation = 0
-        @output = anIO
       end
 
       public
 
-      def render(aVisitor)
-        aVisitor.subscribe(self)
-        aVisitor.start()
-        aVisitor.unsubscribe(self)
-      end
-
       def before_grammar(_)
         output_event(__method__, indentation)
         indent

data/spec/sequitur/formatter/base_text_spec.rb

@@ -60,16 +60,29 @@ SNIPPET
       expect(destination.string).to eq(expectations)
     end
     
-    it 'should support events of a non-empty grammar' do
+    it 'should support visit events with an explicit visitor' do
       instance = BaseText.new(destination)
-      a_visitor = sample_grammar.visitor
+      a_visitor = sample_grammar.visitor  # Use visitor explicitly
       instance.render(a_visitor)
       expectations =<<-SNIPPET
 start :.
-P_1 : a.
-P_2 : b.
-P_3 : c.
-P_4 : P_2 P_3.
+P1 : a.
+P2 : b.
+P3 : c.
+P4 : P2 P3.
+SNIPPET
+      expect(destination.string).to eq(expectations)
+    end
+
+    it 'should support visit events without an explicit visitor' do
+      instance = BaseText.new(destination)
+      instance.render(sample_grammar)
+      expectations =<<-SNIPPET
+start :.
+P1 : a.
+P2 : b.
+P3 : c.
+P4 : P2 P3.
 SNIPPET
       expect(destination.string).to eq(expectations)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequitur
 version: !ruby/object:Gem::Version
-  version: 0.1.00
+  version: 0.1.01
 platform: ruby
 authors:
 - Dimitri Geshef
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-16 00:00:00.000000000 Z
+date: 2014-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -89,6 +89,7 @@ files:
 - lib/sequitur/constants.rb
 - lib/sequitur/digram.rb
 - lib/sequitur/dynamic_grammar.rb
+- lib/sequitur/formatter/base_formatter.rb
 - lib/sequitur/formatter/base_text.rb
 - lib/sequitur/formatter/debug.rb
 - lib/sequitur/grammar_visitor.rb