antelope 0.0.1 → 0.1.0

data/lib/antelope/ace/scanner/second.rb

@@ -8,7 +8,7 @@ module Antelope
       # identifier followed by a colon; the body consists of "parts",
       # an "or", a "prec", and/or a "block".  The part may consist
       # of any alphabetical characters.  An or is just a vertical bar
-      # (`|`).  A prec is a presidence declaraction, which is `%prec `
+      # (`|`).  A prec is a precedence declaraction, which is `%prec `
       # followed by any alphabetical characters.  A block is a `{`,
       # followed by code, followed by a terminating `}`.  Rules _may_
       # be terminated by a semicolon, but this is optional.
@@ -100,7 +100,7 @@ module Antelope
           end
         end
 
-        # Attempts to scan a presidence definition.  A presidence
+        # Attempts to scan a precedence definition.  A precedence
         # definition is "%prec " followed by a terminal or nonterminal.
         #
         # @return [Boolean] if it matched.

data/lib/antelope/ace/token.rb

@@ -145,7 +145,7 @@ module Antelope
         self.class.new(name, @value)
       end
 
-      # Generates a hashs for this class.
+      # Generates a hash for this class.
       #
       # @note This is not intended for use.  It is only defined to be
       #   compatible with Hashs (and by extension, Sets).

data/lib/antelope/ace.rb

@@ -2,7 +2,7 @@ require "antelope/ace/errors"
 require "antelope/ace/scanner"
 require "antelope/ace/compiler"
 require "antelope/ace/token"
-require "antelope/ace/presidence"
+require "antelope/ace/precedence"
 require "antelope/ace/grammar"
 
 module Antelope
@@ -42,7 +42,7 @@ module Antelope
   # `<content>` is code to be used in the output file upon matching
   # the specific rule.
   #
-  # The thid part consists of a body, which is copied directly into
+  # The third part consists of a body, which is copied directly into
   # the output.
   module Ace
 

data/lib/antelope/cli.rb

@@ -0,0 +1,33 @@
+require "thor"
+
+module Antelope
+  class CLI < Thor
+
+    class_option :verbose, default: false, type: :boolean
+
+    option :type, default: nil, type: :string,
+      desc: "The type of generator to use"
+    desc "compile FILE [FILE]*", "compile the given files"
+    def compile(*files)
+      files.each do |file|
+        compile_file(file)
+      end
+    end
+
+    private
+
+    def compile_file(file)
+      puts "Compiling #{file}... "
+
+      grammar = Ace::Grammar.from_file(file)
+      grammar.generate(options)
+
+    rescue => e
+      $stderr.puts "Error while compiling: #{e.class}: #{e.message}"
+
+      if options[:verbose]
+        $stderr.puts e.backtrace[0..10].map { |_| "\t#{_}" }
+      end
+    end
+  end
+end

data/lib/antelope/errors.rb

@@ -0,0 +1,6 @@
+module Antelope
+
+  # Every error in antelope inherits this error class.
+  class Error < StandardError
+  end
+end

data/lib/antelope/generation/constructor/first.rb

@@ -1,18 +1,38 @@
 module Antelope
   module Generation
     class Constructor
+
+      # Contains the methods to construct first sets for tokens.
       module First
 
+        # Initialize.
         def initialize
           @firstifying = []
           super
         end
 
+        # Constructs the first set for a given token.  This is how
+        # the method should behave:
+        #
+        #     FIRST(ε)  == []  # if ϵ is the epsilon token
+        #     FIRST(x)  == [x] # if x is a terminal
+        #     FIRST(αβ) == if nullable?(α)
+        #       FIRST(α) U FIRST(β)
+        #     else
+        #       FIRST(α)
+        #     end
+        #     FIRST(A)  == FIRST(a_1) U FIRST(a_2) U ... U FIRST(a_n)
+        #       # if A is a nonterminal and a_1, a_2, ..., a_3 are all
+        #       # of the right-hand sides of its productions.
+        #
+        # @param token [Ace::Token, Array<Ace::Token>]
+        # @return [Set<Ace::Token::Terminal>]
+        # @see #first_array
         def first(token)
           case token
           when Ace::Token::Nonterminal
             firstifying(token) do
-              productions = parser.productions[token.name]
+              productions = grammar.productions[token.name]
               productions.map { |prod|
                 first(prod[:items]) }.inject(Set.new, :+)
             end
@@ -29,17 +49,31 @@ module Antelope
 
         private
 
-        def first_array(token)
-          token.dup.delete_if { |tok| @firstifying.include?(tok) }.
-          each_with_index.take_while do |tok, i|
+        # Determines the FIRST set of an array of tokens.  First, it
+        # removes any terminals we are finding the FIRST set for;
+        # then, it determines which tokens we have to find the FIRST
+        # sets for (since some tokens may be nullable).  We then add
+        # those sets to our set.
+        #
+        # @param tokens [Array<Ace::Token>]
+        # @return [Set<Ace::Token>]
+        def first_array(tokens)
+          tokens.dup.delete_if { |_| @firstifying.include?(_) }.
+          each_with_index.take_while do |token, i|
             if i.zero?
               true
             else
-              nullable?(token[i - 1])
+              nullable?(tokens[i - 1])
             end
-          end.map(&:first).map { |tok| first(tok) }.inject(Set.new, :+)
+          end.map(&:first).map { |_| first(_) }.inject(Set.new, :+)
         end
 
+        # Helps keep track of the nonterminals we're finding FIRST
+        # sets for. This helps prevent recursion.
+        #
+        # @param tok [Ace::Token::Nonterminal]
+        # @yield once.
+        # @return [Set<Ace::Token>]
         def firstifying(tok)
           @firstifying << tok
           out = yield

data/lib/antelope/generation/constructor/follow.rb

@@ -1,44 +1,102 @@
 module Antelope
   module Generation
     class Constructor
+
+      # Contains the methods to find the FOLLOW sets of nonterminals.
       module Follow
 
+        # Initialize.
         def initialize
           @follows = {}
           super
         end
 
+        # Returns the FOLLOW set of the given token.  If the given
+        # token isn't a nonterminal, it raises an error.  It then
+        # generates the FOLLOW set for the given token, and then
+        # caches it.
+        #
+        # @return [Set<Ace::Token>]
+        # @see Constructor#incorrect_argument!
+        # @see #generate_follow_set
         def follow(token)
-
-          if token.nonterminal?
-            token = token.name
-          elsif token.is_a? Symbol
-          else
-            incorrect_argument! token, Ace::Token::Nonterminal, Symbol
+          unless token.is_a? Ace::Token::Nonterminal
+            incorrect_argument! token, Ace::Token::Nonterminal
           end
 
-          @follows.fetch(token) do
-            @follows[token] = Set.new
-            set = Set.new
-
-            parser.productions.each do |key, value|
-              value.each do |production|
-                items = production[:items]
-                positions = items.each_with_index.
-                  find_all { |t, _| t.name == token }.
-                  map(&:last).map(&:succ)
-                positions.map { |pos| first(items[pos..-1]) }.
-                  inject(set, :merge)
-                positions.each do |pos|
-                  if pos == items.size || nullable?(items[pos..-1])
-                    set.merge follow(Ace::Token::Nonterminal.new(key))
-                  end
-                end
+          @follows.fetch(token) { generate_follow_set(token) }
+        end
+
+        private
+
+        # Generates the FOLLOW set for the given token.  It finds the
+        # positions at which the token appears in the grammar, and
+        # sees what could possibly follow it.  For example, given the
+        # following production:
+        #
+        #     A -> aBz
+        #
+        # With `a` and `z` being any combination of terminals and
+        # nonterminals, and we're trying to find the FOLLOW set of
+        # `B` we add the FIRST set of `z` to the FOLLOW set of `B`:
+        #
+        #     FOLLOW(B) = FOLLOW(B) ∪ FIRST(z)
+        #
+        # In the case that `B` is at the end of a production, like so:
+        #
+        #     A -> aB
+        #
+        # or
+        #
+        #     A -> aBw
+        #
+        # (with `w` being nullable) We also add the FOLLOW set of `A`
+        # to `B`:
+        #
+        #     FOLLOW(B) = FOLLOW(B) ∪ FOLLOW(A)
+        #
+        # In case this operation is potentially recursive, we make
+        # sure to set the FOLLOW set of `B` to an empty set (since we
+        # cache the result of a FOLLOW set, the empty set will be
+        # returned).
+        #
+        # @param token [Ace::Token::Nonterminal]
+        # @return [Set<Ace::Token>]
+        # @see First#first
+        # @see Nullable#nullable?
+        def generate_follow_set(token)
+          # Set it to the empty set so we don't end up recursing.
+          @follows[token] = Set.new
+
+          # This is going to be the output set.
+          set = Set.new
+
+          productions.each do |rule|
+            items = rule.right
+
+            # Find all of the positions within the rule that our token
+            # occurs, and then increment that position by one.
+            positions = items.each_with_index.
+              find_all { |t, _| t == token }.
+              map(&:last).map(&:succ)
+
+            # Find the FIRST set of every item after our token, and
+            # put that in our set.
+            positions.map { |pos| first(items[pos..-1]) }.
+              inject(set, :merge)
+
+            positions.each do |pos|
+              # If we're at the end of the rule...
+              if pos == items.size || nullable?(items[pos..-1])
+                # Then add the FOLLOW set of the left-hand side to our
+                # set.
+                set.merge follow(rule.left)
               end
             end
-
-            @follows[token] = set
           end
+
+          # Replace the cached empty set with our filled set.
+          @follows[token] = set
         end
       end
     end

data/lib/antelope/generation/constructor/nullable.rb

@@ -1,17 +1,33 @@
 module Antelope
   module Generation
     class Constructor
+
+      # Contains the methods to determine if an object is nullable.
       module Nullable
 
+        # Initialize.
         def initialize
-          @nullifying = []
+          @nullifying = Set.new
         end
 
+        # Determine if a given token is nullable.  This is how the
+        # method should behave:
+        #
+        #     nullable?(ϵ) == true  # if ϵ is the epsilon token
+        #     nullable?(x) == false # if x is a terminal
+        #     nullable?(αβ) == nullable?(α) && nullable?(β)
+        #     nullable?(A) == nullable?(a_1) || nullable?(a_2) || ... nullable?(a_n)
+        #       # if A is a nonterminal and a_1, a_2, ..., a_n are all
+        #       # of the right-hand sides of its productions
+        #
+        # @param token [Ace::Token, Array<Ace::Token>] the token to
+        #    check.
+        # @return [Boolean] if the token can reduce to ϵ.
         def nullable?(token)
           case token
           when Ace::Token::Nonterminal
             nullifying(token) do
-              productions = parser.productions[token.name]
+              productions = grammar.productions[token.name]
               !!productions.any? { |prod| nullable?(prod[:items]) }
             end
           when Array
@@ -28,6 +44,12 @@ module Antelope
 
         private
 
+        # Helps keep track of the nonterminals we're checking for
+        # nullability.  This helps prevent recursion.
+        #
+        # @param tok [Ace::Token::Nonterminal]
+        # @yield once.
+        # @return [Boolean]
         def nullifying(tok)
           @nullifying << tok
           out = yield

data/lib/antelope/generation/constructor.rb

@@ -2,36 +2,56 @@ require "set"
 require "antelope/generation/constructor/nullable"
 require "antelope/generation/constructor/first"
 require "antelope/generation/constructor/follow"
-require "antelope/generation/constructor/lookahead"
 
 module Antelope
   module Generation
+
+    # Constructs the lookahead sets for all of the rules in the
+    # grammar.
     class Constructor
 
       include Nullable
       include First
       include Follow
-      include Lookahead
 
-      attr_reader :parser
+      # The grammar.
+      #
+      # @return [Ace::Grammar]
+      attr_reader :grammar
+
       attr_reader :productions
 
-      def initialize(parser)
-        @parser      = parser
-        @productions = []
+      # Initialize.
+      #
+      # @param grammar [Ace::Grammar] the grammar.
+      def initialize(grammar)
+        @productions = Set.new
+        @grammar = grammar
         super()
       end
 
+      # Performs the construction.  First, it goes through every state
+      # and augments the state.  It then goes through every rule and
+      # augments it.
+      #
+      # @return [void]
+      # @see #augment_state
+      # @see #augment_rule
       def call
-        parser.states.each do |state|
+        grammar.states.each do |state|
           augment_state(state)
         end.each do |state|
           augment_rules(state)
         end
-
-        @productions
       end
 
+      # Augments the given state.  On every rule within that state
+      # that has a position of zero, it follows the rule throughout
+      # the DFA until the end; it marks every nonterminal it
+      # encounters with the transitions it took on that nonterminal.
+      #
+      # @param state [Recognizer::State] the state to augment.
+      # @return [void]
       def augment_state(state)
         state.rules.select { |x| x.position.zero? }.each do |rule|
           current_state = state
@@ -39,8 +59,6 @@ module Antelope
           rule.left.from = state
           rule.left.to   = state.transitions[rule.left.name]
 
-          states = [state]
-
           rule.right.each_with_index do |part, pos|
             transition = current_state.transitions[part.name]
             if part.nonterminal?
@@ -48,14 +66,22 @@ module Antelope
               part.to   = transition
             end
 
-            states.push(transition)
             current_state = transition
           end
 
-          productions << rule unless productions.include?(rule)
+          productions << rule
         end
       end
 
+      # Augments every final rule.  For every rule in the current
+      # state that has a position of zero, it follows the rule through
+      # the DFA until the ending state; it then modifies the ending
+      # state's lookahead set to be the FOLLOW set of the nonterminal
+      # it reduces to.
+      #
+      # @param state [Recognizer::State]
+      # @return [void]
+      # @see Follow#follow
       def augment_rules(state)
         state.rules.select { |x| x.position.zero? }.each do |rule|
           current_state = state

data/lib/antelope/generation/errors.rb

@@ -0,0 +1,15 @@
+module Antelope
+  module Generation
+
+    # Defines an error that can occur within the Generation module.
+    # All errors that are raised within the Generation module are
+    # subclasses of this.
+    class Error < Antelope::Error
+    end
+
+    # Used mainly in the {Tableizer}, this is raised when a conflict
+    # could not be resolved.
+    class UnresolvableConflictError < Error
+    end
+  end
+end

data/lib/antelope/generation/recognizer/rule.rb

@@ -1,26 +1,74 @@
 # encoding: utf-8
 
+require "securerandom"
+
 module Antelope
   module Generation
     class Recognizer
+
+      # Defines a rule.  A rule has a corresponding production, and a
+      # position in that production.  It also contains extra
+      # information for other reasons.
       class Rule
 
+        # The left-hand side of the rule.
+        #
+        # @return [Ace::Token::Nonterminal]
         attr_reader :left
+
+        # The right-hand side of the rule.
+        #
+        # @return [Ace::Token]
         attr_reader :right
+
+        # The current position inside of the rule.
+        #
+        # @return [Numeric]
         attr_reader :position
+
+        # The block to be executed on production match.
+        #
+        # @deprecated Use {Ace::Grammar::Production#block} instead.
+        # @return [String]
         attr_reader :block
+
+        # The lookahead set for this specific rule.  Contains nothing
+        # unless {#final?} returns true.
+        #
+        # @return [Set<Symbol>]
         attr_accessor :lookahead
+
+        # The id for this rule.  Initialy, this is set to a string of
+        # hexadecimal characters; after construction of all states,
+        # however, it is a number.
+        #
+        # @return [String, Numeric]
         attr_accessor :id
-        attr_accessor :presidence
+
+        # The precedence for this rule.
+        #
+        # @return [Ace::Precedence]
+        attr_accessor :precedence
+
+        # The associated production.
+        #
+        # @return [Ace::Grammar::Production]
         attr_reader :production
 
         include Comparable
 
+        # Initialize the rule.
+        #
+        # @param production [Ace::Grammar::Production] the production
+        #   that this rule is based off of.
+        # @param position [Numeric] the position that this rule is in
+        #   the production.
+        # @param inherited [nil] do not use.
         def initialize(production, position, inherited = false)
-          @left       = production.label
+          @left       = production.label.dup
           @position   = position
           @lookahead  = Set.new
-          @presidence = production.prec
+          @precedence = production.prec
           @production = production
           @block      = production.block
           @id         = SecureRandom.hex
@@ -32,30 +80,69 @@ module Antelope
           end
         end
 
+        # Give a nice representation of the rule as a string.
+        #
+        # @return [String]
         def inspect
-          "#<#{self.class} id=#{id} left=#{left} right=[#{right.join(" ")}] position=#{position}>"
+          "#<#{self.class} id=#{id} left=#{left} " \
+            "right=[#{right.join(" ")}] position=#{position}>"
         end
 
+        # Give a nicer representation of the rule as a string.  Shows
+        # the id of the rule, the precedence, and the actual
+        # production; if the given argument is true, it will show a
+        # dot to show the position of the rule.
+        #
+        # @param dot [Boolean] show the current position of the rule.
+        # @return [String]
         def to_s(dot = true)
-          "#{id}/#{presidence.type.to_s[0]}#{presidence.level}: #{left} → #{right[0, position].join(" ")}#{" • " if dot}#{right[position..-1].join(" ")}"
+          "#{id}/#{precedence.type.to_s[0]}#{precedence.level}: " \
+            "#{left} → #{right[0, position].join(" ")}" \
+            "#{" • " if dot}#{right[position..-1].join(" ")}"
         end
 
+        # Returns the active token.  If there is no active token, it
+        # returns a blank {Ace::Token}.
+        #
+        # @return [Ace::Token]
         def active
           right[position] or Ace::Token.new(nil)
         end
 
+        # Creates the rule after this one by incrementing the position
+        # by one.  {#succ?} should be called to make sure that this
+        # rule exists.
+        #
+        # @return [Rule]
         def succ
           Rule.new(production, position + 1)
         end
 
+        # Checks to see if a rule can exist after this one; i.e. the
+        # position is not equal to the size of the right side of the
+        # rule.
+        #
+        # @return [Boolean]
         def succ?
-          right.size > (position)
+          right.size > position
         end
 
+        # Checks to see if this is the final rule, as in no rule can
+        # exist after this one; i.e. the position is equal to the
+        # size of the right side.
+        #
+        # @return [Boolean]
         def final?
           !succ?
         end
 
+        # Compares this rule to another object.  If the other object
+        # is not a rule, it delegates the comparison.  Otherwise, it
+        # converts both this and the other rule into arrays and
+        # compares the result.
+        #
+        # @param other [Object] the object to compare.
+        # @return [Numeric]
         def <=>(other)
           if other.is_a? Rule
             to_a <=> other.to_a
@@ -64,11 +151,12 @@ module Antelope
           end
         end
 
-        def without_transitions
-          @_without_transitions ||=
-            Rule.new(production, position)
-        end
-
+        # Fuzzily compares this object to another object.  If the
+        # other object is not a rule, it delegates the comparison.
+        # Otherwise, it fuzzily compares the left and right sides.
+        #
+        # @param other [Object] the object to compare.
+        # @return [Numeric]
         def ===(other)
           if other.is_a? Rule
             left === other.left and right.each_with_index.
@@ -78,12 +166,24 @@ module Antelope
           end
         end
 
+        # Generates a hash for this class.
+        #
+        # @note This is not intended for use.  It is only defined to be
+        #   compatible with Hashs (and by extension, Sets).
+        # @private
+        # @return [Object]
         def hash
           to_a.hash
         end
 
         alias_method :eql?, :==
 
+        # Creates an array representation of this class.
+        #
+        # @note This is not intended for use.  It is only defined to
+        #   make equality checking easier, and to create a hash.
+        # @private
+        # @return [Array<(Ace::Token::Nonterminal, Array<Ace::Token>, Numeric)>]
         def to_a
           [left, right, position]
         end