rattler 0.5.0 → 0.6.0

data/lib/rattler/parsers/parser_scope.rb

@@ -0,0 +1,88 @@
+require 'rattler/parsers'
+
+module Rattler::Parsers
+
+  # +ParserScope+ represents the scope of bindings and captures in a parse
+  # sequence.
+  class ParserScope
+
+    # @return [ParserScope] an empty scope as a singleton
+    def self.empty
+      @empty ||= self.new
+    end
+
+    # @param [Hash] bindings labeled bindings
+    # @param [Array] captures captured parse results
+    # @param [Boolean] captures_decidable whether the list of captured parse
+    #   results can be known statically
+    def initialize(bindings={}, captures=[], captures_decidable=true)
+      @bindings = bindings
+      @captures = captures
+      @captures_decidable = captures_decidable
+    end
+
+    attr_reader :bindings, :captures
+
+    # @param [Hash] new_bindings bindings to add or replace the current
+    #   bindings
+    # @return [ParserScope] a new scope with additional bindings
+    def bind(new_bindings)
+      self.class.new(@bindings.merge(new_bindings), @captures, @captures_decidable)
+    end
+
+    # @param new_captures captures to add to the current captures
+    # @return [ParserScope] a new scope with additional captures
+    def capture(*new_captures)
+      self.class.new(@bindings, @captures + new_captures, @captures_decidable)
+    end
+
+    # Create a new scope with this scope as the outer scope. The new scope
+    # inherits this scope's bindings, but not its captures.
+    #
+    # @return [ParserScope] a new scope with this scope as the outer scope
+    def nest
+      self.class.new(@bindings, [], @captures_decidable)
+    end
+
+    # @param [ParserScope] other another scope
+    # @return [ParserScope] a new scope with bindings the other scope
+    def merge(other)
+      bind(other.bindings)
+    end
+
+    # @return [ParserScope] a new scope with captures_decidable +false+
+    def with_undecidable_captures
+      if captures_decidable?
+        self.class.new(@bindings, @captures, false)
+      else
+        self
+      end
+    end
+
+    # @return whether the list of captured parse results can be known
+    #   statically
+    def captures_decidable?
+      @captures_decidable
+    end
+
+    # @param [Symbol] name a binding name
+    # @return whether the scope has a binding for +name+
+    def has_name?(name)
+      @bindings.has_key?(name)
+    end
+
+    # Run the block once for each binding
+    # @yield [name, value] the binding name and value
+    # @return self#bindings
+    def each_binding
+      @bindings.each {|name, value| yield name, value }
+    end
+
+    # @param [Symbol] name a binding name
+    # @return the value bound to +name+ in the scope
+    def [](name)
+      @bindings[name]
+    end
+
+  end
+end

data/lib/rattler/parsers/predicate.rb

@@ -1,24 +1,26 @@
-#
-# = rattler/parsers/predicate.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  # @private
-  class Predicate < Parser #:nodoc:
+
+  # A +Predicate+ is a parser that either succeeds or fails and never consumes
+  # any input or captures any parse results.
+  class Predicate < Parser
     include Combining
 
-    def self.parsed(results, *_)
+    # @private
+    def self.parsed(results, *_) #:nodoc:
       self[results.first]
     end
 
+    # (see Parser#capturing?)
     def capturing?
       false
     end
 
+    # (see Parser#capturing_decidable?)
+    def capturing_decidable?
+      true
+    end
+
   end
 end

data/lib/rattler/parsers/repeat.rb

@@ -1,17 +1,18 @@
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Repeat+ decorates a parser with repeat counts to match repeatedly (up to
   # the upper bound, if given) and succeed if the decorated parser succeeds at
   # least as many times as specified by the lower bound.
-  #
-  # @author Jason Arhart
-  #
   class Repeat < Parser
     include Combining
 
-    def self.[](parser, lower_bound, upper_bound)
+    # @param [Parser] parser the parser to wrap and match with repeatedly
+    # @param [Integer] lower_bound the minimum number of times to match
+    # @param [Integer] upper_bound the maximum number of times to match
+    # @return [Repeat] a parser that decorates +parser+ and matches repeatedly
+    def self.[](parser, lower_bound, upper_bound = nil)
       self.new(parser, :lower_bound => lower_bound, :upper_bound => upper_bound)
     end
 
@@ -27,13 +28,13 @@ module Rattler::Parsers
     # +true+ if the wrapped parser is not <tt>capturing?</tt>.  Return +false+
     # if the lower bound is not reached.
     #
-    # @param (see Parser#parse_labeled)
+    # @param (see Match#parse)
     #
     # @return [Array, Boolean] an array containing the decorated parser's parse
     #   results, or +true+ if the decorated parser is not <tt>capturing?</tt>,
     #   or +false+ if the decorated parser does not succeed up to the lower
     #   bound.
-    def parse(scanner, rules, scope = {})
+    def parse(scanner, rules, scope = ParserScope.empty)
       a = []
       start_pos = scanner.pos
       while result = child.parse(scanner, rules, scope)
@@ -41,33 +42,39 @@ module Rattler::Parsers
         break if upper_bound? and a.size >= upper_bound
       end
       if a.size >= lower_bound
-        capturing? ? a : true
+        capturing? ? select_captures(a) : true
       else
         scanner.pos = start_pos
         false
       end
     end
 
+    # @return +true+ if the bounds define a zero-or-more
     def zero_or_more?
       lower_bound == 0 and not upper_bound?
     end
 
+    # @return +true+ if the bounds define a one-or-more parser
     def one_or_more?
       lower_bound == 1 and not upper_bound?
     end
 
+    # @return +true+ if the bounds define an optional (zero-or-one) parser
     def optional?
       lower_bound == 0 and upper_bound == 1
     end
 
+    # @return +true+ if there is a lower bound
     def lower_bound?
       lower_bound > 0
     end
 
+    # @return +true+ if there is an upper bound
     def upper_bound?
       not upper_bound.nil?
     end
 
+    # (see Parser#variable_capture_count?)
     def variable_capture_count?
       true
     end

data/lib/rattler/parsers/rule.rb

@@ -1,19 +1,9 @@
-#
-# = rattler/parsers/rule.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Rule+ is a binding for a parser that can be referenced by name from
   # another rule.
-  #
-  # @author Jason Arhart
-  #
   class Rule < Rattler::Util::Node
 
     # Create a new +Rule+.
@@ -28,26 +18,21 @@ module Rattler::Parsers
 
     alias_method :expr, :child
 
-    # Parse using +scanner+ and +rules+ and on success return the result, on
-    # failure return a false value.
+    # Parse using the rule body and on success return the result, on failure
+    # return a false value.
     #
-    # @param scanner (see Parser#parse_labeled)
-    # @param rules (see Parser#parse_labeled)
-    #
-    # @return (see Parser#parse_labeled)
-    def parse(scanner, rules, scope = {})
+    # @param (see Match#parse)
+    # @return (see Match#parse)
+    def parse(scanner, rules, scope = ParserScope.empty)
       catch(:rule_failed) do
         return expr.parse(scanner, rules, scope)
       end
       false
     end
 
-    def with_expr(new_expr)
-      Rule[name, new_expr, attrs]
-    end
+    alias_method :with_expr, :with_children
 
-    # @param (see Parser#with_ws)
-    # @return (see Parser#with_ws)
+    # (see Parser#with_ws)
     def with_ws(ws)
       self.with_expr expr.with_ws(ws)
     end

data/lib/rattler/parsers/rule_set.rb

@@ -1,20 +1,26 @@
-#
-# = rattler/parsers/rule_set.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
+
+  # +RuleSet+ encapsulates a set of parse rules that define a grammar and
+  # provides accessors to the rules by name.
   class RuleSet < Rattler::Util::Node
 
     # @private
     def self.parsed(results, *_) #:nodoc:
-      self.new(results)
+      self.new(results[0])
     end
 
+    # Create a +RuleSet+ instance.
+    #
+    # @overload initialize()
+    #   @return [RuleSet]
+    # @overload initialize(rule...)
+    #   @return [RuleSet]
+    # @overload initialize(attribute...)
+    #   @return [RuleSet]
+    # @overload initialize(rule..., attribute...)
+    #   @return [RuleSet]
     def initialize(*args)
       super
       @by_name = {}
@@ -23,14 +29,44 @@ module Rattler::Parsers
 
     alias_method :rules, :children
 
+    # @return [Symbol] the name of the rule to start parsing with
     def start_rule
       attrs[:start_rule]
     end
 
+    # @param [Symbol] name the name of a rule in the rule set
+    # @return [Rule] the rule with the given name in the rule set
     def rule(name)
-      @by_name[name]
+      @by_name[name] || inherited_rule(name)
+    end
+
+    # @param [Symbol] name the name of a rule in an inherited rule set
+    # @return [Rule] the rule with the given name in the inherited rule set
+    def inherited_rule(name)
+      includes.inject(nil) {|r,s| r || s.rule(name) }
+    end
+
+    # @return [Array<String>] a list of modules to be included in the parser
+    def includes
+      attrs[:includes] || []
     end
 
+    # Access the rule set's rules
+    #
+    # @overload [](rule_name)
+    #   @param [Symbol] name the name of a rule in the rule set
+    #   @return [Rule] the rule with the given name in the rule set
+    # @overload [](index)
+    #   @param [Integer] index index of the rule
+    #   @return the rule at +index+
+    # @overload [](start, length)
+    #   @param [Integer] start the index of the first rule
+    #   @param [Integer] length the number of rules to return
+    #   @return [Array] the rules starting at +start+ and continuing for
+    #     +length+ rules
+    # @overload [](range)
+    #   @param [Range] range the range of rules
+    #   @return [Array] the rules specified by +range+
     def [](*args)
       if args.length == 1 and args[0].is_a?(Symbol)
         rule(args[0])
@@ -39,24 +75,43 @@ module Rattler::Parsers
       end
     end
 
+    # @param [Hash] new_attrs a hash of attributes to merge with the existing
+    #   attributes
+    # @return [RuleSet] a new rule set with the same rules and the new
+    #   attributes merged
     def with_attrs(new_attrs)
       self.class.new(children, attrs.merge(new_attrs))
     end
 
+    # @param [Array<Rule>] new_rules the new list of rules to replace the
+    #   existing rules
+    # @return [RuleSet] a new rule set with a new list of rules and the same
+    #   attributes
     def with_rules(new_rules)
       self.class.new(new_rules, attrs)
     end
 
+    # @yield Run the block once for each rule
+    # @yieldparam [Rule] rule one rule in the rule set
+    # @yieldreturn [Rule] a rule to replace the one yielded to the block
+    # @return [RuleSet] a new rule set with the result of running the block
+    #   once for each rule
     def map_rules
-      self.with_rules rules.map {|_| yield _ }
+      self.with_rules rules.map {|rule| yield rule }
     end
 
+    # @yield Run the block as a predicate once for each rule
+    # @yieldparam [Rule] rule one rule in the rule set
+    # @yieldreturn [Boolean] +true+ to include the rule in the new rule set
+    # @return [RuleSet] a new rule set with the rules for which the block
+    #   returns +true+
     def select_rules
-      self.with_rules rules.select {|_| yield _ }
+      self.with_rules rules.select {|rule| yield rule }
     end
 
+    # @return [Analysis] a static analysis of the rules
     def analysis
-      @analysis ||= Rattler::Grammar::Analysis.new(self)
+      @analysis ||= Analysis.new(self)
     end
 
   end

data/lib/rattler/parsers/semantic.rb

@@ -0,0 +1,36 @@
+require 'rattler/parsers'
+
+module Rattler::Parsers
+
+  # +Semantic+ describes parsers that perform a semantic action
+  module Semantic
+
+    # @param [ParserScope] scope the scope of captures to bind in the code
+    # @return [String] ruby code that performs the action
+    def bind(scope)
+      bindable_code.bind(scope)
+    end
+
+    # @return an object that be bound to a parser scope to return ruby code
+    #   that performs the action
+    def bindable_code
+      @bindable_code ||= create_bindable_code
+    end
+
+    # @return +true+
+    def semantic?
+      true
+    end
+
+    private
+
+    def apply(scope)
+      code_bindings = {}
+      scope.each_binding {|k, v| code_bindings[k] = v.inspect }
+      code_captures = scope.captures.map {|_| _.inspect }
+      code_scope = ParserScope.new(code_bindings, code_captures)
+      eval(bind(code_scope))
+    end
+
+  end
+end

data/lib/rattler/parsers/semantic_action.rb

@@ -0,0 +1,39 @@
+module Rattler::Parsers
+
+  # +SemanticAction+ is a pseudo-parser that performs a semantic action by
+  # evaluating ruby code in the context of a parser scope.
+  class SemanticAction < Parser
+    include Semantic
+
+    # @private
+    def self.parsed(results, *_) #:nodoc:
+      self[results.first]
+    end
+
+    # @param [String] code ruby code that can be bound to a parser scope to
+    #   perform an action
+    # @return [SemanticAction] a pseudo-parser that performs a semantic action
+    def self.[](code)
+      self.new(:code => code.strip)
+    end
+
+    # Perform the semantic action in the context of +scope+
+    #
+    # @param (see Match#parse)
+    #
+    # @return the result of performing the semantic action in the context of
+    #   +scope+
+    def parse(scanner, rules, scope = ParserScope.empty)
+      apply scope
+    end
+
+    protected
+
+    # @return [ActionCode] an object that be bound to a parser scope to return
+    #   ruby code that performs the action
+    def create_bindable_code
+      ActionCode.new(code)
+    end
+
+  end
+end