rattler 0.5.0 → 0.6.0

data/lib/rattler/runtime/packrat_parser.rb

@@ -1,20 +1,10 @@
-#
-# = rattler/runtime/packrat_parser.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 
 module Rattler::Runtime
-  #
+
   # A +PackratParser+ is a recursive descent parser that memoizes the results
   # of applying nonterminal rules so that each rule method is invoked at most
   # once at a given parse position.
-  #
-  # @author Jason Arhart
-  #
   class PackratParser < RecursiveDescentParser
 
     # Create a new packrat parser to parse +source+.
@@ -24,49 +14,45 @@ module Rattler::Runtime
     #
     def initialize(source, options={})
       super
-      @memo = Hash.new {|h, rule_name| h[rule_name] = {} }
+      @memo = Hash.new {|h, match_method_name| h[match_method_name] = {} }
     end
 
     protected
 
-    # Apply a rule by dispatching to the method associated with the given rule
-    # name, which is named by <tt>"match_#{rule_name}"<tt>, and if the match
-    # fails set a parse error. The result of applying the rule is memoized
-    # so that the rule method is invoked at most once at a given parse
-    # position.
+    # Apply a rule by dispatching to the given match method. The result of
+    # applying the rule is memoized so that the match method is invoked at most
+    # once at a given parse position.
     #
     # @param (see RecursiveDescentParser#apply)
     # @return (see RecursiveDescentParser#apply)
     #
-    def apply(rule_name)
+    def apply(match_method_name)
       start_pos = @scanner.pos
-      if m = memo(rule_name, start_pos)
-        recall m, rule_name
+      if m = memo(match_method_name, start_pos)
+        recall m, match_method_name
       else
-        m = inject_fail rule_name, start_pos
-        save m, eval_rule(rule_name)
+        m = inject_fail match_method_name, start_pos
+        save m, eval_rule(match_method_name)
       end
     end
 
-    alias_method :memoize, :apply
-
     alias_method :eval_rule, :send
 
     private
 
     # @private
-    def memo(rule_name, start_pos) #:nodoc:
-      @memo[rule_name][start_pos]
+    def memo(match_method_name, start_pos) #:nodoc:
+      @memo[match_method_name][start_pos]
     end
 
     # @private
-    def inject_memo(rule_name, start_pos, result, end_pos) #:nodoc:
-      @memo[rule_name][start_pos] = MemoEntry.new(result, end_pos)
+    def inject_memo(match_method_name, start_pos, result, end_pos) #:nodoc:
+      @memo[match_method_name][start_pos] = MemoEntry.new(result, end_pos)
     end
 
     # @private
-    def inject_fail(rule_name, fail_pos) #:nodoc:
-      @memo[rule_name][fail_pos] = MemoEntry.new(false, fail_pos)
+    def inject_fail(match_method_name, fail_pos) #:nodoc:
+      @memo[match_method_name][fail_pos] = MemoEntry.new(false, fail_pos)
     end
 
     # @private
@@ -76,7 +62,7 @@ module Rattler::Runtime
     end
 
     # @private
-    def recall(m, rule_name) #:nodoc:
+    def recall(m, match_method_name) #:nodoc:
       @scanner.pos = m.end_pos
       m.result
     end

data/lib/rattler/runtime/parse_failure.rb

@@ -1,20 +1,10 @@
-#
-# = rattler/runtime/parse_failure.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 
 module Rattler::Runtime
-  #
+
   # A +ParseFailure+ represents a position and explanation of a failed parse.
-  #
-  # @author Jason Arhart
-  #
   class ParseFailure
-    
+
     # Create a new parse error object.
     #
     # @overload initialize(source, pos)
@@ -46,39 +36,39 @@ module Rattler::Runtime
       end
       @lc = Rattler::Util::LineCounter.new(source)
     end
-    
+
     attr_reader :pos, :message
-    
-    # Return the (1-based) column number where the parse error occurred.
-    # @return [Integer] the column number where the parse error occurred.
+
+    # @return [Integer] the (1-based) column number where the parse error
+    #   occurred
     def column
       @lc.column(pos)
     end
-    
-    # Return the (1-based) line number where the parse error occurred.
-    # @return [Integer] the line number where the parse error occurred.
+
+    # @return [Integer] the (1-based) line number where the parse error
+    #   occurred
     def line
       @lc.line(pos)
     end
-    
+
     # Return a string representation of the parse error suitable for showing
     # to the user, e.g. "parse error at line 17, column 42: expr expected"
     #
-    # @return [String] a string representation of the parse error suitable for showing
-    #   to the user
+    # @return [String] a string representation of the parse error suitable for
+    #   showing to the user
     def to_s
       message ? "#{intro_str}:\n #{message}" : intro_str
     end
-    
+
     private
-    
+
     def intro_str
       "parse error #{pos_str}"
     end
-    
+
     def pos_str
       "at line #{line}, column #{column}"
     end
-    
+
   end
 end

data/lib/rattler/runtime/parse_node.rb

@@ -1,21 +1,11 @@
-#
-# = rattler/runtime/parse_node.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 
 module Rattler::Runtime
-  #
+
   # +ParseNode+ is intended as s a convenient class to use as a parsing
   # result type.
-  #
-  # @author Jason Arhart
-  #
   class ParseNode < Rattler::Util::Node
-    
+
     # Create a parse node from the results of a parsing expression.
     #
     # @param [Array] children the children of the parse node
@@ -26,7 +16,7 @@ module Rattler::Runtime
     def self.parsed(children, attrs={})
       self.new(children, attrs.reject {|_, val| val.nil? })
     end
-    
+
     # Access the parse node's children.
     #
     # @overload [](index)
@@ -55,13 +45,13 @@ module Rattler::Runtime
         super
       end
     end
-    
+
     # Return a hash associating labels with the labeled children
     # @return [Hash] a hash associating labels with the labeled children
     def labeled
       attrs.fetch(:labeled, {})
     end
-    
+
     # Return +true+ if the node has the same value as +other+, i.e. +other+
     # is an instance of the same class and has equal children and attributes
     # and the children are labeled the same.
@@ -71,16 +61,16 @@ module Rattler::Runtime
       super &&
       self.labeled == other.labeled
     end
-    
+
     # Allow labeled children to be accessed as methods.
     def method_missing(symbol, *args)
       (args.empty? and labeled.has_key?(symbol)) ? labeled[symbol] : super
     end
-    
+
     # @private
     def respond_to?(symbol) #:nodoc:
       super || labeled.has_key?(symbol)
     end
-    
+
   end
 end

data/lib/rattler/runtime/parser.rb

@@ -1,19 +1,9 @@
-#
-# = rattler/runtime/parser.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 require 'strscan'
 
 module Rattler::Runtime
-  #
+
   # +Parser+ is the base class for all parsers in the Rattler framework.
-  #
-  # @author Jason Arhart
-  #
   class Parser < Rattler::Util::Node
 
     # Parse +source+ and raise a {SyntaxError} if the parse fails.
@@ -38,15 +28,14 @@ module Rattler::Runtime
     # Create a new parser to parse +source+.
     #
     # @param [String] source the source to parse
-    # @option options [Int] :tab_size (8) tab size to use to calculate column
-    #   numbers
+    # @option options [Integer] :tab_size (8) tab size to use to calculate
+    #   column numbers
     def initialize(source, options={})
       @source = source
       @scanner = StringScanner.new(source)
       @tab_size = options[:tab_size]
     end
 
-    # The source that this parser parses
     # @return [String] the source that this parser parses
     attr_reader :source
 
@@ -84,15 +73,14 @@ module Rattler::Runtime
       parse_fully or raise_error
     end
 
-    # The current parse position
-    # @return [Integer] the current parse position
+    # @return [Fixnum] the current parse position
     def pos
       @scanner.pos
     end
 
     # Set the current parse position
     # @param [Integer] n the new parse position
-    # @return [Integer] n
+    # @return [Fixnum] the new parse position
     def pos=(n)
       @scanner.pos = n
     end
@@ -167,7 +155,7 @@ module Rattler::Runtime
     # Register a parse failure
     #
     # @param [Integer] position the position of the failure
-    # @param [String, Symbol] a failure message or rule name or +nil+
+    # @param [String, Symbol] message a failure message or rule name or +nil+
     #
     # @return [false]
     def register_failure(position, message)

data/lib/rattler/runtime/parser_helper.rb

@@ -1,19 +1,12 @@
-#
-# = rattler/runtime/parser_helper.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 
 module Rattler::Runtime
   # @private
   module ParserHelper #:nodoc:
-    
+
     def select_captures(results)
-      results.reject {|_| _ == true }
+      results.reject {|_| _.equal? true }
     end
-    
+
   end
 end

data/lib/rattler/runtime/recursive_descent_parser.rb

@@ -1,24 +1,20 @@
-#
-# = rattler/runtime/recursive_descent_parser.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 
 module Rattler::Runtime
-  #
+
   # +RecursiveDescentParser+ is the base class for any recursive descent
   # parsers. It supports unlimited backtracking, which may result in rules
   # being applied to the same source many times. It is usually preferable to
   # use {PackratParser}, which memoizes parse results.
-  #
-  # @author Jason Arhart
-  #
   class RecursiveDescentParser < Parser
     include ParserHelper
-    include Rattler::Grammar::GrammarDSL
+
+    class <<self
+      private
+      def grammar(source)
+        Rattler.compile(self, source)
+      end
+    end
 
     # Create a new recursive descent parser to parse +source+.
     #
@@ -30,22 +26,25 @@ module Rattler::Runtime
       @rule_method_names = Hash.new {|h, name| h[name] = :"match_#{name}" }
     end
 
-    # Apply a rule by dispatching to the method associated with +rule_name+
-    # which is named by <tt>"match_#{rule_name}"<tt>, and if the match fails
-    # register a parse failure.
-    #
-    # @param (see #apply)
-    # @return (see #apply)
+    # Attempt to match the source by applying the named parse rule and return
+    # the result. If the rule is successfully matched the result is "thruthy".
+    # If the rules captures parse results, the captured results are returned,
+    # otherwise the result is +true+. If the rule fails to match, the result
+    # may be +false+ or +nil+.
     #
+    # @param [Symbol] rule_name the name of the parse rule.
+    # @return the result of applying the parse rule.
     def match(rule_name)
-      send @rule_method_names[rule_name] or fail { rule_name }
+      send @rule_method_names[rule_name]
     end
 
-    def method_missing(symbol, *args)
+    # @private
+    def method_missing(symbol, *args) #:nodoc:
       (symbol == :start_rule) ? :start : super
     end
 
-    def respond_to?(symbol)
+    # @private
+    def respond_to?(symbol) #:nodoc:
       super or (symbol == :start_rule)
     end
 
@@ -59,8 +58,12 @@ module Rattler::Runtime
       match start_rule
     end
 
-    def apply(rule_method_name)
-      send rule_method_name
+    # Apply a rule by directly dispatching to the given match method.
+    #
+    # @param [Symbol] match_method_name the name of the match method.
+    # @return the result of applying the parse rule.
+    def apply(match_method_name)
+      send match_method_name
     end
 
   end

data/lib/rattler/runtime/syntax_error.rb

@@ -1,17 +1,7 @@
-#
-# = rattler/runtime/syntax_error.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/runtime'
 
 module Rattler::Runtime
   # +SyntaxError+ is raised by {Parser#raise_error} to indicate a failed parse.
-  #
-  # @author Jason Arhart
-  #
   class SyntaxError < RuntimeError
   end
 end

data/lib/rattler/util.rb

@@ -1,9 +1,3 @@
-#
-# = rattler/util.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 require 'rattler'
 
 module Rattler
@@ -12,6 +6,8 @@ module Rattler
     autoload :LineCounter, 'rattler/util/line_counter'
     autoload :Node, 'rattler/util/node'
     autoload :ParserSpecHelper, 'rattler/util/parser_spec_helper'
+    autoload :ParserCLI, 'rattler/util/parser_cli'
+    autoload :GrammarCLI, 'rattler/util/grammar_cli'
     autoload :GraphViz, 'rattler/util/graphviz'
   end
 end

data/lib/rattler/util/grammar_cli.rb

@@ -0,0 +1,19 @@
+require 'rattler/util'
+
+module Rattler::Util
+
+  # +GrammarCLI+ defines a command line interface for generated grammars.
+  class GrammarCLI < ParserCLI
+
+    # Create a new command line interface for the given grammar module
+    #
+    # @param [Module] grammar_module the grammar module to run the command line
+    #   interface for
+    def initialize(grammar_module)
+      parser_class = Class.new(Rattler::Runtime::ExtendedPackratParser)
+      parser_class.module_eval { include grammar_module }
+      super(parser_class)
+    end
+
+  end
+end