rattler 0.5.0 → 0.6.0

data/lib/rattler/parsers/attributed_sequence.rb

@@ -0,0 +1,50 @@
+require 'rattler/parsers'
+
+module Rattler::Parsers
+
+  # +AttributedSequence+ combines one or more parsers with a semantic action
+  # and matches the parser in sequence and applies the action to the captured
+  # results.
+  class AttributedSequence < Parser
+    include Sequencing
+
+    # @private
+    def self.parsed(results, *_) #:nodoc:
+      op, action = results
+      (op + [action]).reduce(:>>)
+    end
+
+    # Parse each parser in sequence, and if they all succeed return the result
+    # of applying the semantic action to the captured results.
+    #
+    # @param (see Match#parse)
+    #
+    # @return the result of applying the semantic action to the captured
+    #   results of each parser, or +false
+    def parse(scanner, rules, scope = ParserScope.empty)
+      result = false
+      backtracking(scanner) do
+        if scope = parse_children(scanner, rules, scope.nest) {|r| result = r }
+          yield scope if block_given?
+          result
+        end
+      end
+    end
+
+    # (see Parser#capturing?)
+    def capturing?
+      children.last.capturing?
+    end
+
+    # (see Parser#capturing_decidable?)
+    def capturing_decidable?
+      false
+    end
+
+    # (see Sequence#capture_count)
+    def capture_count
+      @capture_count ||= children[0...-1].count {|_| _.capturing? }
+    end
+
+  end
+end

data/lib/rattler/parsers/back_reference.rb

@@ -1,42 +1,47 @@
-#
-# = rattler/parsers/back_reference.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +BackReference+ matches the labeled result of an earlier match.
-  #
-  # @author Jason Arhart
-  #
   class BackReference < Parser
 
+    # @param [Symbol,String] ref_label the label referencing the earlier match
+    # @return [BackReference] a new parser that matches the value an earlier
+    #   match whose result is labeled by +ref_label+
     def self.[](ref_label)
       self.new(:ref_label => ref_label.to_sym)
     end
 
+    # @private
     def self.parsed(results, *_)
       self[results.first[1..-1]]
     end
 
-    def parse(scanner, rules, scope={})
+    # If the earlier referenced match result appears again at the parse
+    # position, match that string, otherwise return a false value.
+    #
+    # @param (see Match#parse)
+    #
+    # @return the matched string, or +nil+
+    def parse(scanner, rules, scope = ParserScope.empty)
       scanner.scan Regexp.compile(Regexp.escape scope[ref_label])
     end
 
+    # @param [ParserScope] scope the scope of captured results
+    # return [String] ruby code for a +Regexp+ that matches the earlier
+    #   referenced match result
     def re_expr(scope)
       "/#{re_source scope}/"
     end
 
+    # @param [ParserScope] scope the scope of captured results
+    # return [String] the source of a +Regexp+ that matches the earlier
+    #   referenced match result
     def re_source(scope)
       '#{' + Regexp.escape(scope[ref_label].to_s) + '}'
     end
 
-    # @param (see Parser#with_ws)
-    # @return (see Parser#with_ws)
+    # (see Parser#with_ws)
     def with_ws(ws)
       ws.skip & self
     end

data/lib/rattler/parsers/choice.rb

@@ -1,19 +1,10 @@
-#
-# = rattler/parsers/choice.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Choice+ combines two or more parsers and matches by trying each one in
   # order until one succeeds and returning that result.
-  #
-  # @author Jason Arhart
-  #
   class Choice < Parser
     include Combining
 
@@ -24,10 +15,10 @@ module Rattler::Parsers
 
     # Try each parser in order until one succeeds and return that result.
     #
-    # @param (see Parser#parse_labeled)
+    # @param (see Match#parse)
     #
     # @return the result of the first parser that matches, or +false+
-    def parse(scanner, rules, scope = {})
+    def parse(scanner, rules, scope = ParserScope.empty)
       for child in children
         if r = child.parse(scanner, rules, scope)
           return r
@@ -36,6 +27,14 @@ module Rattler::Parsers
       false
     end
 
+    # (see Parser#capturing_decidable?)
+    def capturing_decidable?
+      @capturing_decidable ||=
+        children.all? {|_| _.capturing_decidable? } and
+        ( children.all? {|_| _.capturing? } or
+          children.none? {|_| _.capturing? } )
+    end
+
     # Return a new parser that tries this parser first and if it fails tries
     # +other+.
     #

data/lib/rattler/parsers/combinator_parser.rb

@@ -1,15 +1,16 @@
-#
-# = rattler/parsers/rule_set.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
+
+  # +CombinatorParser+ is a runtime parser that parses using the parse rules
+  # directly instead of using match methods generated from the parse rules
   class CombinatorParser < Rattler::Runtime::Parser
 
+    # @param [Symbol] start_rule the initial rule to use for parsing
+    # @param [RuleSet] rule_set the set of rules to use for parsing
+    #
+    # @return [Class] a subclass of +CombinatorParser+ that uses the given
+    #   start rule and rule set and can be instantiated with only a source
     def self.as_class(start_rule, rule_set)
       new_class = Class.new(self)
       new_class.send :define_method, :initialize do |source|
@@ -18,12 +19,19 @@ module Rattler::Parsers
       new_class
     end
 
+    # Create a new +CombinatorParser+ to parse +source+ using +rule_set+ and
+    # starting with +start_rule+
+    #
+    # @param [String] source the source to parse
+    # @param [Symbol] start_rule the initial rule to use for parsing
+    # @param [RuleSet] rule_set the set of rules to use for parsing
     def initialize(source, start_rule, rule_set)
       super source
       @start_rule = start_rule
       @rule_set = rule_set
     end
 
+    # (see Rattler::Runtime::RecursiveDescentParser#__parse__)
     def __parse__
       @start_rule.parse(@scanner, @rule_set)
     end

data/lib/rattler/parsers/combining.rb

@@ -1,18 +1,24 @@
-#
-# = rattler/parsers/combining.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 module Rattler::Parsers
-  # @private
-  module Combining #:nodoc:
 
+  # +Combining+ describes a parser that is a combination of other parsers.
+  module Combining
+
+    # (see Parser#capturing?)
     def capturing?
       @capturing ||= any? {|child| child.capturing? }
     end
 
+    # (see Parser#capturing_decidable?)
+    def capturing_decidable?
+      @capturing_decidable ||= all? {|child| child.capturing_decidable? }
+    end
+
+    # (see Parser#semantic?)
+    def semantic?
+      @semantic = any? {|child| child.semantic? }
+    end
+
+    # (see Parser#with_ws)
     def with_ws(ws)
       self.class.new(children.map {|_| _.with_ws(ws) }, attrs)
     end

data/lib/rattler/parsers/disallow.rb

@@ -1,26 +1,19 @@
-#
-# = rattler/parsers/disallow.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Disallow+ decorates a parser and succeeds if the decorated parser fails
-  # and vice versa.
-  #
+  # and fails if the parser succeeds and never consumes any input (zero-width
+  # negative lookahead).
   class Disallow < Predicate
 
-    # Succeed and return +true+ if and only if decorated parser fails.  Never
+    # Succeed and return +true+ if and only if decorated parser fails. Never
     # consumes any input.
     #
     # @param (see Parser#parse_labeled)
     #
     # @return [Boolean] +true+ if the decorated parser fails
-    def parse(scanner, rules, scope = {})
+    def parse(scanner, rules, scope = ParserScope.empty)
       pos = scanner.pos
       result = !child.parse(scanner, rules, scope)
       scanner.pos = pos

data/lib/rattler/parsers/e_symbol.rb

@@ -1,19 +1,9 @@
-#
-# = rattler/parsers/e_symbol.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 require 'singleton'
 
 module Rattler::Parsers
-  #
+
   # +ESymbol+ always succeeds without advancing.
-  #
-  # @author Jason Arhart
-  #
   class ESymbol < Parser
     include Atomic
     include Singleton
@@ -32,13 +22,14 @@ module Rattler::Parsers
 
     # Return +true+ without advancing
     #
-    # @param (see Parser#parse)
+    # @param (see Match#parse)
     #
-    # @return true
-    def parse(scanner, rules, scope = {})
+    # @return [Boolean] +true+
+    def parse(*_)
       true
     end
 
+    # (see Parser#capturing?)
     def capturing?
       false
     end

data/lib/rattler/parsers/eof.rb

@@ -1,20 +1,10 @@
-#
-# = rattler/parsers/eof.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 require 'singleton'
 
 module Rattler::Parsers
-  #
+
   # +Eof+ succeeds if there is no more input to parse.
-  #
-  # @author Jason Arhart
-  #
-  class Eof < Predicate
+  class Eof < Parser
     include Atomic
     include Singleton
 
@@ -32,12 +22,17 @@ module Rattler::Parsers
 
     # Return +true+ if there is no more input to parse
     #
-    # @param (see Parser#parse_labeled)
+    # @param (see Match#parse)
     #
-    # @return true if there is no more input to parse
-    def parse(scanner, rules, scope = {})
+    # @return [Boolean] +true+ if there is no more input to parse
+    def parse(scanner, *_)
       scanner.eos?
     end
 
+    # (see Parser#capturing?)
+    def capturing?
+      false
+    end
+
   end
 end

data/lib/rattler/parsers/fail.rb

@@ -1,32 +1,23 @@
-#
-# = rattler/parsers/fail.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Fail+ is a parser that always fails. It can be used to define more useful
   # error messages.
-  #
-  # @author Jason Arhart
-  #
   class Fail < Parser
-    
+
     # @private
     def self.parsed(results, *_) #:nodoc:
-      keyword, message_expr = results
-      message = eval(message_expr)
+      keyword, arg_expr = results
+      arg = eval(arg_expr)
       case keyword
-      when 'fail'       then self[:expr, message]
-      when 'fail_rule'  then self[:rule, message]
-      when 'fail_parse' then self[:parse, message]
+      when 'fail'       then self[:expr, arg]
+      when 'fail_rule'  then self[:rule, arg]
+      when 'fail_parse' then self[:parse, arg]
+      when 'expected'   then self[:expr, arg.to_sym]
       end
     end
-    
+
     # Create a new parser that always fails with +message+. The +type+ should
     # be one of <tt>:expr</tt>, <tt>:rule</tt> or <tt>:parse</tt>, indicating
     # to simply fail, to cause its parse rule to fail, or to cause the entire
@@ -38,24 +29,23 @@ module Rattler::Parsers
     def self.[](type, message)
       self.new(:type => type, :message => message)
     end
-    
+
     # Always return +false+. The parser code generated for this parser should
     # use +message+ as the failure message, and should cause its parse rule
     # to fail if +type+ is <tt>:rule</tt> or cause the entire parse to fail
-    # +type+ is <tt>:parse</tt>
+    # if +type+ is <tt>:parse</tt>
     #
-    # @param (see Parser#parse_labeled)
+    # @param (see Match#parse)
     #
     # @return false
-    def parse(scanner, rules, labeled = {})
+    def parse(*_)
       false
     end
-    
-    # Always +false+
-    # @return false
+
+    # @return +false+
     def capturing?
       false
     end
-    
+
   end
 end

data/lib/rattler/{grammar → parsers}/grammar.rb

@@ -1,16 +1,8 @@
-#
-# = rattler/grammar/grammar.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-require 'rattler/grammar'
+require 'rattler/parsers'
+
+module Rattler::Parsers
 
-module Rattler::Grammar
-  #
   # +Grammar+ represents a parsed grammar
-  #
-  # @author Jason Arhart
   class Grammar < Rattler::Util::Node
 
     # The name of the default parser base class
@@ -32,35 +24,38 @@ module Rattler::Grammar
 
     # @param rules [RuleSet] the parse rules that define the parser
     #
-    # @option opts [String] start_rule (rules.first)
+    # @option opts [String] start_rule (rules.first.name)
     # @option opts [String] grammar_name (nil)
     # @option opts [String] parser_name (nil)
     # @option opts [String] base_name (Rattler::Runtime::RecursiveDescentParser)
     # @option opts [Array<String>] requires ([])
     # @option opts [Array<String>] includes ([])
     def initialize(rules, opts={})
-      super @@default_opts.merge(opts)
-
-      case attrs[:start_rule]
-      when Symbol then attrs[:start_rule] = rules[start_rule]
-      when nil    then attrs[:start_rule] = rules.first
-      end
+      start_rule =
+        opts[:start_rule] || rules.start_rule || (rules.first && rules.first.name)
 
-      @rules = rules.with_attrs(:start_rule => start_rule.name)
+      super rules.with_attrs(:start_rule => start_rule),
+        @@default_opts.merge(:start_rule => start_rule).merge(opts)
 
       attrs[:name] ||= grammar_name || parser_name
     end
 
-    attr_reader :rules
+    alias_method :rules, :child
 
+    # @param [Symbol] name the name of a parse rule in the grammar
+    # @return [Rule] the parse rule referenced by +name+
     def rule(name)
       rules[name]
     end
 
+    # @return [Analysis] a static analysis of the grammar rules
     def analysis
       rules.analysis
     end
 
+    # @param [RuleSet] new_rules
+    # @return [Grammar] a new grammar with the parse rules replaced by
+    #   +new_rules+
     def with_rules(new_rules)
       self.class.new new_rules, attrs
     end