sequitur 0.1.23 → 0.1.25

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

@@ -0,0 +1,89 @@
+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
+      # @return [Integer] Current indentation level
+      attr_accessor indentation: 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 _ [DynamicGrammar]
+      def before_grammar: (DynamicGrammar _) -> 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 _ [Production]
+      def before_production: (Production _) -> 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] _) -> 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 _ [Object]
+      def before_terminal: (untyped _) -> untyped
+
+      # 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: (untyped _) -> 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 _ [Production] a production occurring in the rhs
+      def before_non_terminal: (Production _) -> untyped
+
+      # 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: (untyped _) -> untyped
+
+      # 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: (::Array[untyped] _) -> untyped
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit
+      # of a production
+      # @param _ [Production]
+      def after_production: (Production _) -> untyped
+
+      # Method called by a GrammarVisitor to which the formatter subscribed.
+      # Notification of a visit event: the visitor completed the visit
+      # of a grammar
+      # @param _ [DynamicGrammar]
+      def after_grammar: (DynamicGrammar _) -> untyped
+
+      private
+
+      def indent: () -> Integer
+
+      def dedent: () -> Integer
+
+      def output_event: (Symbol anEvent, Integer indentationLevel) -> nil
+    end
+  end
+end

data/sig/lib/sequitur/production.rbs

@@ -0,0 +1,120 @@
+module Sequitur
+  # In a context-free grammar, a production is a rule in which
+  # its left-hand side (LHS) consists solely of a non-terminal symbol
+  # and the right-hand side (RHS) consists of a sequence of symbols.
+  # The symbols in RHS can be either terminal or non-terminal symbols.
+  # 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.
+  # Implementation note: the object id of the production is taken as its LHS.
+  class Production
+    # @return [Sequitur::SymbolSequence] The right-hand side (rhs)
+    #   consists of a sequence of grammar symbols
+    attr_reader rhs: untyped
+
+    # @return [Integer] The reference count (= how times other productions reference this one)
+    attr_reader refcount: untyped
+
+    # @return [Array<Sequitur::Digram>] The sequence of digrams appearing in the RHS
+    attr_reader digrams: untyped
+
+    # Constructor.
+    # Build a production with an empty RHS.
+    def initialize: () -> void
+
+    # Identity testing.
+    # @param other [Production, ProductionRef] another production or production reference.
+    # @return [TrueClass, FalseClass] true when the receiver and other are the same.
+    def ==: ((Production | ProductionRef) other) -> bool
+
+    # Is the rhs empty?
+    # @return [TrueClass, FalseClass] true if the rhs has no members.
+    def empty?: () -> bool
+
+    # Increment the reference count by one.
+    # @return [Integer]
+    def incr_refcount: () -> Integer
+
+    # Decrement the reference count by one.
+    # @return [Integer]
+    def decr_refcount: () -> Integer
+
+    # Select the references to production appearing in the rhs.
+    # @return [Array<ProductionRef>]
+    def references: () -> Array[Sequitur::ProductionRef]
+
+    # Look in the rhs all the references to a production passed a argument.
+    # @param a_prod [Production, ProductionRef] The production to search for.
+    # @return [Array<ProductionRef>]
+    def references_of: ((Production | ProductionRef) a_prod) -> Array[ProductionRef]
+
+    # Enumerate the digrams appearing in the right-hand side (rhs)
+    # @return [Array<Sequitur::Digram>] the list of digrams found in rhs of this production.
+    def recalc_digrams: () -> Array[Sequitur::Digram]
+
+    # Does the rhs have exactly one digram only (= 2 symbols)?
+    # @return [TrueClass, FalseClass] true when the rhs contains exactly two symbols.
+    def single_digram?: () -> bool
+
+    # 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
+    # @return [TrueClass, FalseClass] true when the digram occurs twice in rhs.
+    def repeated_digram?: () -> bool
+
+    # Retrieve the last digram appearing in the RHS (if any).
+    # @return [Sequitur::Digram, NilClass] last digram in the rhs otherwise nil.
+    def last_digram: () -> (nil | Sequitur::Digram)
+
+    # 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: () -> ::String
+
+    # Add a (grammar) symbol at the end of the RHS.
+    # @param aSymbol [Object] A (grammar) symbol to add.
+    def append_symbol: (untyped aSymbol) -> untyped
+
+    # Clear the right-hand side.
+    # Any referenced production has its reference counter decremented.
+    def clear_rhs: () -> untyped
+
+    # Find all the positions where the digram occurs in the rhs
+    # @param symb1 [Object] first symbol of the digram
+    # @param symb2 [Object] second symbol of the digram
+    # @return [Array<Integer>] 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: (untyped symb1, untyped symb2) -> Array[Integer]
+
+    # 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, ProductionRef] a production that
+    #   consists exactly of one digram (= 2 symbols).
+    def reduce_step: ((Production | ProductionRef) another) -> untyped
+
+    # Replace every occurrence of 'another' production in self.rhs by
+    #   the symbols in the rhs of 'another'.
+    # @param another [Production, 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: ((Production | ProductionRef) another) -> untyped
+
+    # Part of the 'visitee' role in Visitor design pattern.
+    # @param aVisitor[Sequitur::GrammarVisitor]
+    def accept: (Sequitur::GrammarVisitor aVisitor) -> untyped
+  end
+end

data/sig/lib/sequitur/production_ref.rbs

@@ -0,0 +1,73 @@
+module Sequitur
+  # A production reference is a grammar symbol that may appear in the right-hand
+  # side of a production P1 and that refers to a production P2.
+  # Every time a production P2 appears in the left-hand side of
+  # production P1, this is implemented by inserting a production reference to P2
+  # 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
+    # @return [Sequitur::Production] Link to the production to reference.
+    attr_reader production: Sequitur::Production
+
+    # Constructor
+    # @param target [Production, ProductionRef]
+    #   The production that is being referenced.
+    def initialize: ((Production | ProductionRef) target) -> void
+
+    # 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: (ProductionRef orig) -> void
+
+    # Emit the text representation of a production reference.
+    # @return [String]
+    def to_s: () -> String
+
+    alias to_string to_s
+
+    # 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.
+    # @param other [Production, ProductionRef]
+    # @return [TrueClass, FalseClass]
+    def ==: ((Production | ProductionRef) other) -> bool
+
+    # Produce a hash value.
+    #   A reference has no identity on its own,
+    #   the method returns the hash value of the
+    #   referenced production
+    # @return [Integer] the hash value
+    def hash: () -> Integer
+
+    # Make this reference point to the given production.
+    # @param aProduction [Production, ProductionRef] the production
+    #   to refer to
+    def bind_to: ((Production | ProductionRef) aProduction) -> (nil | untyped)
+
+    # Clear the reference to the target production.
+    def unbind: () -> nil
+
+    # Check that the this object doesn't refer to any production.
+    # @return [TrueClass, FalseClass] true when this object doesn't
+    #   point to a production.
+    def unbound?: () -> bool
+
+    # Part of the 'visitee' role in the Visitor design pattern.
+    # @param aVisitor [Sequitur::GrammarVisitor] the visitor
+    def accept: (Sequitur::GrammarVisitor aVisitor) -> untyped
+  end
+end

data/sig/lib/sequitur/sequitur_grammar.rbs

@@ -0,0 +1,55 @@
+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: (untyped anEnum) -> void
+
+    private
+
+    # Struct used for internal purposes
+    CollisionDiagnosis: untyped
+
+    # 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: () -> untyped
+
+    # 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: () -> untyped
+
+    # 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: (untyped aDiagnosis) -> untyped
+
+    # Return a production that is used less than twice in the grammar.
+    def detect_useless_production: () -> untyped
+
+    # 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: (untyped prod_index) -> untyped
+
+    # Create a new production that will have the symbols from digram
+    # as its rhs members.
+    def build_production_for: (untyped aDigram) -> untyped
+  end
+end

data/sig/lib/sequitur/symbol_sequence.rbs

@@ -0,0 +1,83 @@
+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
+    attr_reader symbols: Array[untyped]
+
+    # Create an empty sequence
+    def initialize: () -> void
+
+    # Copy constructor invoked by dup or clone methods.
+    # @param orig [SymbolSequence]
+    def initialize_copy: (untyped orig) -> untyped
+
+    # Clear the symbol sequence.
+    def clear: () -> untyped
+
+    # Tell whether the sequence is empty.
+    # @[true / false] true only if the sequence has no symbol in it.
+    def empty?: () -> untyped
+
+    # Count the number of elements in the sequence.
+    #  @[Fixnum] the number of elements
+    def size: () -> untyped
+
+    # Append a grammar symbol at the end of the sequence.
+    # @param aSymbol [Object] The symbol to append.
+    def <<: (untyped aSymbol) -> (nil | untyped)
+
+    # Retrieve the element from the sequence at given position.
+    # @param anIndex [Fixnum] A zero-based index of the element to access.
+    def []: (untyped anIndex) -> untyped
+
+    # Equality testing.
+    # @param other [SymbolSequence or Array] the other other sequence
+    #   to compare to.
+    # @true when an item from self equals the corresponding
+    #   item from 'other'
+    def ==: (untyped other) -> untyped
+
+    # Select the references to production appearing in the rhs.
+    # @[Array of ProductionRef]
+    def references: () -> untyped
+
+    # Select the references of the given production appearing in the rhs.
+    # @param aProduction [Production]
+    # @[Array of ProductionRef]
+    def references_of: (untyped aProduction) -> untyped
+
+    # Emit a text representation of the symbol sequence.
+    # Text is of the form: space-separated sequence of symbols.
+    # @[String]
+    def to_string: () -> untyped
+
+    # Insert at position the elements from another sequence.
+    # @param position [Fixnum] A zero-based index of the symbols to replace.
+    # @param another [SymbolSequence] A production with a two-elements rhs
+    #   (a single digram).
+    def insert_at: (untyped position, untyped another) -> untyped
+
+    # 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 [Integer] the position of a two symbol sequence to be replaced
+    #   by the production
+    # @param aProduction [Production, ProductionRef] a production that
+    #   consists exactly of one digram (= 2 symbols).
+    def reduce_step: (Integer index, (Production | ProductionRef) aProduction) -> untyped
+
+    # Remove the element at given position
+    # @param position [Integer] a zero-based index.
+    def delete_at: (untyped position) -> untyped
+
+    # Part of the 'visitee' role in Visitor design pattern.
+    # @param aVisitor[GrammarVisitor]
+    def accept: (untyped aVisitor) -> untyped
+
+    private
+
+    def invalidate_refs: () -> untyped
+  end
+end

data/sig/lib/sequitur.rbs

@@ -0,0 +1,9 @@
+module Sequitur
+  # Build a Sequitur-generated grammar based on the 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: ((String | ::Enumerator[untyped]) tokens) -> SequiturGrammar
+end

data/spec/sequitur/digram_spec.rb

@@ -5,38 +5,40 @@ require_relative '../spec_helper'
 # Load the class under test
 require_relative '../../lib/sequitur/digram'
 
-module Sequitur # Re-open the module to get rid of qualified names
-describe Digram do
+describe Sequitur::Digram do
   let(:two_symbols) { %i[b c] }
   let(:production) { double('sample-production') }
+  def make_digram(symb1, symb2, production)
+    Sequitur::Digram.new(symb1, symb2, production)
+  end
 
   context 'Standard creation & initialization:' do
     it 'should be created with 3 arguments' do
-      instance = Digram.new(:b, :c, production)
+      instance = make_digram(:b, :c, production)
 
       expect(instance.symbols).to eq(two_symbols)
       expect(instance.production).to eq(production)
     end
 
     it 'should return the production that it refers to' do
-      instance = Digram.new(:b, :c, production)
+      instance = make_digram(:b, :c, production)
       expect(instance.production).to eq(production)
     end
 
     it 'should whether its symbols are the same' do
-       instance1 = Digram.new(:a, :a, production)
-       expect(instance1).to be_repeating
+      instance1 = make_digram(:a, :a, production)
+      expect(instance1).to be_repeating
 
-       instance1 = Digram.new(:a, :b, production)
-       expect(instance1).not_to be_repeating
+      instance1 = make_digram(:a, :b, production)
+      expect(instance1).not_to be_repeating
     end
   end # context
 
   context 'Provided services:' do
     it 'should compare itself to another digram' do
-      instance1 = Digram.new(:a, :b, production)
-      same = Digram.new(:a, :b, production)
-      different = Digram.new(:b, :c, production)
+      instance1 = make_digram(:a, :b, production)
+      same = make_digram(:a, :b, production)
+      different = make_digram(:b, :c, production)
 
       expect(instance1).to eq(instance1)
       expect(instance1).to eq(same)
@@ -45,6 +47,5 @@ describe Digram do
     end
   end # context
 end # describe
-end # module
 
 # End of file

data/spec/sequitur/dynamic_grammar_spec.rb

@@ -5,14 +5,13 @@ require_relative '../spec_helper'
 # Load the class under test
 require_relative '../../lib/sequitur/dynamic_grammar'
 
-module Sequitur # Re-open the module to get rid of qualified names
-describe DynamicGrammar do
+describe Sequitur::DynamicGrammar do
   # Factory method. Build a production with the given sequence
   # of symbols as its rhs.
   def build_production(*symbols)
-    prod = Production.new
+    prod = Sequitur::Production.new
     symbols.each { |symb| prod.append_symbol(symb) }
-    return prod
+    prod
   end
 
   let(:p_a) { build_production(:a) }
@@ -20,10 +19,9 @@ describe DynamicGrammar do
   let(:p_c) { build_production(:c) }
   let(:p_bc) { build_production(p_b, p_c) }
 
-
   context 'Creation & initialization:' do
     it 'should be created without parameter' do
-      expect { DynamicGrammar.new }.not_to raise_error
+      expect { Sequitur::DynamicGrammar.new }.not_to raise_error
     end
 
     it 'should have an empty start/start production' do
@@ -33,7 +31,6 @@ describe DynamicGrammar do
     end
   end # context
 
-
   context 'Adding productions to the grammar:' do
     it 'should add a simple production' do
       subject.add_production(p_a)
@@ -60,7 +57,6 @@ describe DynamicGrammar do
     end
   end # context
 
-
   context 'Removing a production from the grammar:' do
     it 'should remove an existing production' do
       subject.add_production(p_a) # index = 1
@@ -91,7 +87,7 @@ describe DynamicGrammar do
   context 'Visiting:' do
     it 'should return a visitor' do
       expect { subject.visitor }.not_to raise_error
-      expect(subject.visitor).to be_kind_of(GrammarVisitor)
+      expect(subject.visitor).to be_kind_of(Sequitur::GrammarVisitor)
     end
 
     it 'should accept a visitor' do
@@ -133,7 +129,6 @@ describe DynamicGrammar do
     end
   end # context
 
-
   context 'Generating a text representation of itself:' do
     it 'should generate a text representation when empty' do
       expectation = "#{subject.start.object_id} : ."
@@ -141,6 +136,5 @@ describe DynamicGrammar do
     end
   end # context
 end # describe
-end # module
 
 # End of file