rley 0.5.05 → 0.5.06

data/lib/rley.rb

@@ -4,7 +4,7 @@
 
 require_relative './rley/constants'
 require_relative './rley/syntax/grammar_builder'
-require_relative './rley/tokens/token'
+require_relative './rley/lexical/token'
 require_relative './rley/parser/gfg_earley_parser'
 require_relative './rley/parser/parse_tree_builder'
 require_relative './rley/parse_tree_visitor'

data/lib/rley/{parser → base}/base_parser.rb

@@ -1,21 +1,23 @@
 require_relative '../syntax/grammar'
 require_relative 'grm_items_builder' # Use mix-in module
-require_relative 'parse_tracer'
+
 
 
 module Rley # This module is used as a namespace
-  module Parser # This module is used as a namespace
+  module Base # This module is used as a namespace
     # Abstract class for Earley parser.
     class BaseParser
       include GrmItemsBuilder # Mix-in for creating dotted items of grammar
 
       # The grammar of the language.
+      # @return [Syntax::Grammar]
       attr_reader(:grammar)
 
       # The dotted items/rules for the productions of the grammar
       attr_reader(:dotted_items)
 
-
+      # Constructor.
+      # @param [Syntax::Grammar] The grammar of the language.
       def initialize(aGrammar)
         @grammar = aGrammar
         @dotted_items = build_dotted_items(grammar) # Method from mixin

data/lib/rley/{parser → base}/dotted_item.rb

@@ -1,30 +1,33 @@
 module Rley # This module is used as a namespace
-  # A dotted item is a parse state for a given production/grammar rule
-  # It partitions the rhs of the rule in two parts.
-  # The left part consists of the symbols in the rules that are matched
-  # by the input tokens.
-  # The right part consists of symbols that are predicted to match the
-  # input tokens.
-  # The terminology stems from the traditional way to visualize the partition
-  # by using a fat dot character as a separator between the left and right
-  # parts
-  # An item with the dot at the beginning (i.e. before any rhs symbol)
-  #  is called a predicted item.
-  # An item with the dot at the end (i.e. after all rhs symbols)
-  #  is called a reduce item.
-  # An item with a dot in front of a terminal is called a shift item.
-  module Parser # This module is used as a namespace
+  module Base # This module is used as a namespace
+    # A dotted item is a parse state for a given production/grammar rule
+    # It partitions the rhs of the rule in two parts.
+    # The left part consists of the symbols in the rules that are matched
+    # by the input tokens.
+    # The right part consists of symbols that are predicted to match the
+    # input tokens.
+    # The terminology stems from the traditional way to visualize the partition
+    # by using a fat dot character as a separator between the left and right
+    # parts
+    # An item with the dot at the beginning (i.e. before any rhs symbol)
+    #  is called a predicted item.
+    # An item with the dot at the end (i.e. after all rhs symbols)
+    #  is called a reduce item.
+    # An item with a dot in front of a terminal is called a shift item.
     class DottedItem
       # Production rule
+      # @return [Syntax::Production]
       attr_reader(:production)
 
       # Index of the next symbol (from the rhs) after the 'dot'.
       # If the dot is at the end of the rhs (i.e.) there is no next
       # symbol, then the position takes the value -1.
       # It the rhs is empty, then the position is -2
+      # @return [Integer]
       attr_reader(:position)
 
-      # @param aProduction
+      # @param aProduction [Syntax::Production]
+      # @param aPosition [Integer] Position of the dot in rhs of production.
       def initialize(aProduction, aPosition)
         @production = aProduction
         @position = valid_position(aPosition)
@@ -46,6 +49,7 @@ module Rley # This module is used as a namespace
       end
 
       # Return true if the dot position is at the start of the rhs.
+      # @return [Boolean]
       def at_start?()
         return position.zero? || position == -2
       end
@@ -55,17 +59,20 @@ module Rley # This module is used as a namespace
       alias predicted_item? at_start?
 
       # A dotted item is called a reduce item if the dot is at the end.
+      # @return [Boolean]
       def reduce_item?()
         return position < 0 # Either -1 or -2
       end
 
       # The non-terminal symbol that is on the left-side of the production
+      # @return [Syntax::NonTerminal]
       def lhs()
         return production.lhs
       end
 
       # Return the symbol before the dot.
       # nil is returned if the dot is at the start of the rhs
+      # @return [Syntax::GrmSymbol, NilClass]
       def prev_symbol()
         before_position = prev_position
         result = if before_position.nil?
@@ -79,12 +86,14 @@ module Rley # This module is used as a namespace
 
       # Return the symbol after the dot.
       # nil is returned if the dot is at the end
+      # @return [Syntax::GrmSymbol, NilClass]
       def next_symbol()
         return position < 0 ? nil : production.rhs[position]
       end
 
       # Calculate the position of the dot if were moved by
       # one step on the left.
+      # @return [Integer]
       def prev_position()
         case position
           when -2, 0
@@ -100,6 +109,8 @@ module Rley # This module is used as a namespace
 
       # Return true if this dotted item has a dot one place
       # to the right compared to the dotted item argument.
+      # @param another [DottedItem]
+      # @return [Boolean]
       def successor_of?(another)
         return false if production != another.production
         to_the_left = prev_position

data/lib/rley/{parser → base}/grm_items_builder.rb

@@ -1,10 +1,12 @@
 require_relative 'dotted_item'
 
 module Rley # This module is used as a namespace
-  module Parser # This module is used as a namespace
+  module Base # This module is used as a namespace
     # Mix-in module. Builds the dotted items for a given grammar
     module GrmItemsBuilder
-      # Build an array of dotted items from the productions in passed grammar.
+      # Build an array of dotted items from the productions of passed grammar.
+      # @param [Syntax::Grammar]
+      # @return [Array<DottedItem>]
       def build_dotted_items(aGrammar)
         items = []
         aGrammar.rules.each do |prod|

data/lib/rley/constants.rb

@@ -3,7 +3,7 @@
 
 module Rley # Module used as a namespace
   # The version number of the gem.
-  Version = '0.5.05'.freeze
+  Version = '0.5.06'.freeze
 
   # Brief description of the gem.
   Description = "Ruby implementation of the Earley's parsing algorithm".freeze

data/lib/rley/formatter/base_formatter.rb

@@ -4,6 +4,7 @@ module Rley # This module is used as a namespace
     # Superclass for parse tree formatters.
     class BaseFormatter
       # The IO output stream in which the formatter's result will be sent.
+      # @return [IO] The output stream for the formatter.
       attr_reader(:output)
 
       # Constructor.

data/lib/rley/gfg/item_vertex.rb

@@ -4,25 +4,29 @@ require_relative 'vertex'
 
 module Rley # This module is used as a namespace
   module GFG # This module is used as a namespace
-    # TODO: modify definition
-    # Represents a specialized vertex in a grammar flow graph
-    # that is associated to a given dotted item.
+    # Specialization of Vertex class. Represents a 
+    # vertex in a grammar flow graph associated to a given dotted item.
     # Responsibilities (in addition to inherited ones):
     # - Know its related non-terminal symbol
     class ItemVertex < Vertex
       # Link to the dotted item object
+      # @return [DottedItem] The corresponding dotted item      
       attr_reader :dotted_item
 
       # Optional link to a "shortcut" edge.
       # Applicable only if the dotted expects a non-terminal symbol.
+      # @return [ShortcutEdge] Optional "shortcut" edge
       attr_reader :shortcut
 
+      # Constructor.
+      # @param aDottedItem [DottedItem] the corresponding dotted item.
       def initialize(aDottedItem)
         super()
         @dotted_item = aDottedItem
       end
 
       # Set the "shortcut" edge.
+      # @param aShortcut [ShortcutEdge] the "shortcut" edge.
       def shortcut=(aShortcut)
         unless aShortcut.kind_of?(ShortcutEdge)
           raise StandardError, 'Invalid shortcut argument'
@@ -41,26 +45,33 @@ module Rley # This module is used as a namespace
         @shortcut = aShortcut
       end
 
+      # The label of this vertex.
+      # It is the same as the label of the corresponding dotted item.
+      # @return [String] Label for this vertex
       def label()
         return dotted_item.to_s
       end
 
       # Returns true if the dotted item has a dot at the end of the production.
+      # @return [Boolean]
       def complete?()
         return dotted_item.reduce_item?
       end
 
-      # Return the symbol before the dot else nil.
+      # Return the symbol before the dot.
+      # @return [Syntax::GrmSymbol, NilClass] Previous symbol otherwise nil.
       def prev_symbol()
         return dotted_item.prev_symbol
       end
 
-      # Return the symbol after the dot else nil.
+      # Return the symbol after the dot.
+      # @return [Syntax::GrmSymbol, NilClass] Next grammar symbol otherwise nil.      
       def next_symbol()
         return dotted_item.next_symbol
       end
 
       # Return the non-terminal symbol at the left-hand side of the production
+      # @return [Syntax::GrmSymbol] The non-terminal symbol at left side of production.
       def lhs()
         return dotted_item.lhs
       end

data/lib/rley/gfg/non_terminal_vertex.rb

@@ -2,14 +2,19 @@ require_relative 'vertex'
 
 module Rley # This module is used as a namespace
   module GFG # This module is used as a namespace
+    # Abstract class.
     # Represents a specialized vertex in a grammar flow graph 
     # that is associated to a given non-terminal symbol and
     # that may have in-degree or out-degree > 1
     # Responsibilities (in addition to inherited ones):
     # - Know its related non-terminal symbol
     class NonTerminalVertex < Vertex
+      # The non-terminal symbol associated to the vertex
+      # @return [Syntax::NonTerminal]
       attr_reader :non_terminal
       
+      # Constructor to specialize in subclasses.
+      # @param [Syntax::NonTerminal]
       def initialize(aNonTerminal)
         super()
         @non_terminal = aNonTerminal

data/lib/rley/gfg/vertex.rb

@@ -6,11 +6,10 @@ module Rley # This module is used as a namespace
     # - To know its label
     class Vertex
       # The edges linking the successor vertices to this one.
-      # @!attribute [r] edges
       # @return [Array<Edge>] The edge(s) linking this vertex to successor(s)
       attr_reader :edges
       
-      # Constructor to override.
+      # Constructor to extend in subclasses.
       def initialize()
         @edges = []
       end

data/lib/rley/lexical/token.rb

@@ -0,0 +1,31 @@
+module Rley # This module is used as a namespace
+  module Lexical # This module is used as a namespace
+    # In Rley, a (lexical) token is an object created by a lexer (tokenizer)
+    # and passed to the parser. Such token an object is created when a lexer
+    # detects that a sequence of characters(a lexeme) from the input stream
+    # is an instance of a terminal grammar symbol.
+    # Say, that in a particular language, the lexeme 'foo' is an occurrence
+    # of the terminal symbol IDENTIFIER. Then the lexer will return a Token
+    # object that states the fact that 'foo' is indeed an IDENTIFIER. Basically,
+    # a Token is a pair (lexeme, terminal): it asserts that a given lexeme 
+    # is an instance of given terminal symbol.
+    class Token
+      # The sequence of character(s) from the input stream that is an occurrence
+      # of the related terminal symbol.
+      # @return [String] Input substring that is an instance of the terminal.
+      attr_reader(:lexeme)
+      
+      # @return [Syntax::Terminal] Terminal symbol corresponding to the lexeme.
+      attr_reader(:terminal)
+
+      # Constructor.
+      # @param theLexeme [String] the lexeme (= piece of text from input)
+      # @param aTerminal [Syntax::Terminal] The terminal symbol corresponding to the lexeme.
+      def initialize(theLexeme, aTerminal)
+        @lexeme = theLexeme
+        @terminal = aTerminal
+      end
+    end # class
+  end # module
+end # module
+# End of file

data/lib/rley/{tokens → lexical}/token_range.rb

@@ -1,5 +1,5 @@
 module Rley # This module is used as a namespace
-  module Tokens # This module is used as a namespace
+  module Lexical # This module is used as a namespace
     # A token range (also called an extent) represents an interval 
     # of token positions that is matched by a given grammar symbol.
     # For instance consider the expression E: 3 + 11,
@@ -10,17 +10,23 @@ module Rley # This module is used as a namespace
     # token range can be temporarily undefined (= set to nil)
     class TokenRange
       # The index of the lower bound of token range
+      # @return [Integer]
       attr_reader(:low)
 
       # The index of the upper bound of token range
+      # @return [Integer]
       attr_reader(:high)
 
-      # @param aRangeRep [Hash]
+      # Constructor
+      # @param aRangeRep [Hash] A hash with keys :low and :high
       def initialize(aRangeRep)
         assign_low(aRangeRep)
         assign_high(aRangeRep)
       end
 
+      # Test for equality of ranges.
+      # @param other [TokenRange, Range, Hash, Array<Integer>]
+      # @return [Boolean]
       def ==(other)
         return true if object_id == other.object_id
 

data/lib/rley/parser/gfg_earley_parser.rb

@@ -1,11 +1,11 @@
-require_relative 'base_parser'
+require_relative '../base/base_parser'
 require_relative '../gfg/grm_flow_graph'
 require_relative 'gfg_parsing'
 
 module Rley # This module is used as a namespace
   module Parser # This module is used as a namespace
     # Implementation of a parser that uses the Earley parsing algorithm.
-    class GFGEarleyParser < BaseParser
+    class GFGEarleyParser < Base::BaseParser
       # The Grammar Flow graph for the given grammar
       attr_reader :gf_graph
 

data/lib/rley/parser/parse_tree_builder.rb

@@ -1,4 +1,4 @@
-require_relative '../tokens/token_range'
+require_relative '../lexical/token_range'
 require_relative '../syntax/terminal'
 require_relative '../syntax/non_terminal'
 require_relative '../gfg/end_vertex'
@@ -166,7 +166,7 @@ module Rley # This module is used as a namespace
       # Create a raw node with given range
       # and push it on top of stack.
       def push_raw_node(aRange, aSymbol)
-        raw_node = CSTRawNode.new(Tokens::TokenRange.new(aRange), aSymbol)
+        raw_node = CSTRawNode.new(Lexical::TokenRange.new(aRange), aSymbol)
         stack.push(raw_node)
       end
 

data/lib/rley/ptree/parse_tree_node.rb

@@ -1,4 +1,4 @@
-require_relative '../tokens/token_range'
+require_relative '../lexical/token_range'
 
 module Rley # This module is used as a namespace
   module PTree # This module is used as a namespace
@@ -11,7 +11,7 @@ module Rley # This module is used as a namespace
 
       def initialize(aSymbol, aRange)
         @symbol = aSymbol
-        @range = Tokens::TokenRange.new(aRange)
+        @range = Lexical::TokenRange.new(aRange)
       end
 
       # Assign a value from given range to each  undefined range bound

data/lib/rley/sppf/sppf_node.rb

@@ -1,4 +1,4 @@
-require_relative '../tokens/token_range'
+require_relative '../lexical/token_range'
 
 module Rley # This module is used as a namespace
   module SPPF # This module is used as a namespace
@@ -10,7 +10,7 @@ module Rley # This module is used as a namespace
       attr_reader(:range)
       
       def initialize(aRange)
-        @range = Tokens::TokenRange.new(aRange)
+        @range = Lexical::TokenRange.new(aRange)
       end
       
       # Return the origin (= lower bound of the range 

data/lib/rley/syntax/grammar.rb

@@ -14,15 +14,19 @@ module Rley # This module is used as a namespace
     class Grammar
       # A non-terminal symbol that represents all the possible strings
       # in the language.
+      # @return [NonTerminal] Start symbol of the grammar.
       attr_reader(:start_symbol)
 
       # The list of production rules for the language.
+      # @return [Array<Production>] Array of productions for the grammar.
       attr_reader(:rules)
 
       # The list of grammar symbols in the language.
+      # @return [Array<GrmSymbol>] The terminal and non-terminal symbols.
       attr_reader(:symbols)
 
-      # A Hash with pairs of the kind: symbol name => grammar symbol
+      # A Hash that maps symbol names to their grammar symbols
+      # @return [Hash{String => GrmSymbol}] 
       attr_reader(:name2symbol)
 
       # @param theProductions [Array<Production>] productions of the grammar.

data/lib/rley/syntax/grammar_builder.rb

@@ -1,8 +1,8 @@
 require 'set'
-require_relative 'verbatim_symbol'
-require_relative 'literal'
 require_relative 'terminal'
 require_relative 'non_terminal'
+require_relative 'literal'
+require_relative 'verbatim_symbol'
 require_relative 'production'
 require_relative 'grammar'
 

data/lib/rley/syntax/terminal.rb

@@ -7,7 +7,7 @@ module Rley # This module is used as a namespace
     class Terminal < GrmSymbol
       
       # Constructor.
-      # aName [String] The name of the grammar symbol.
+      # @param aName [String] The name of the grammar symbol.
       def initialize(aName)
         super(aName)
         self.generative = true

data/spec/rley/{parser → base}/dotted_item_spec.rb

@@ -5,10 +5,10 @@ require_relative '../../../lib/rley/syntax/non_terminal'
 require_relative '../../../lib/rley/syntax/production'
 
 # Load the class under test
-require_relative '../../../lib/rley/parser/dotted_item'
+require_relative '../../../lib/rley/base/dotted_item'
 
 module Rley # Open this namespace to avoid module qualifier prefixes
-  module Parser # Open this namespace to avoid module qualifier prefixes
+  module Base # Open this namespace to avoid module qualifier prefixes
     describe DottedItem do
       # Factory method. Builds a production with given left-hand side (LHS)
       # and given RHS (right-hand side)