rattler 0.5.0 → 0.6.0

data/lib/rattler/{back_end → compiler}/ruby_generator.rb

@@ -1,22 +1,13 @@
-#
-# = rattler/back_end/ruby_generator.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-require 'rattler/back_end'
+require 'rattler/compiler'
 require 'stringio'
 
-module Rattler::BackEnd
-  #
+module Rattler::Compiler
+
   # A +RubyGenerator+ is used to generate well-formatted ruby code. It keeps
   # track of the indent level and has various methods for adding code, all of
   # which return +self+ to allow method chaining.
-  #
-  # @author Jason Arhart
-  #
   class RubyGenerator
-    
+
     # Create a new +RubyGenerator+ with the given options, yield it to the
     # block, and return the code generated by the block.
     #
@@ -30,7 +21,7 @@ module Rattler::BackEnd
       yield generator
       generator.code
     end
-    
+
     # Create a new +RubyGenerator+ with the given options.
     #
     # @option options [Integer] :indent_level (0) the initial indent level
@@ -41,7 +32,7 @@ module Rattler::BackEnd
       @indent_level = options[:indent_level] || 0
       @io = options[:io] || StringIO.new
     end
-    
+
     # Add arbirtrary code.
     #
     # @param [String] s the code to add
@@ -51,7 +42,7 @@ module Rattler::BackEnd
       @io << s
       self
     end
-    
+
     # Add the appropriate amount of space to indent the start of a line.
     #
     # @return [self]
@@ -59,7 +50,7 @@ module Rattler::BackEnd
       @io << ('  ' * @indent_level)
       self
     end
-    
+
     # Add a line break followed by the appropriate amount of space to indent
     # the start of a line.
     #
@@ -68,7 +59,7 @@ module Rattler::BackEnd
       @io.puts
       start_line
     end
-    
+
     # Increase the indent level and start a new line for the given block.
     #
     # @return [self]
@@ -79,7 +70,7 @@ module Rattler::BackEnd
       @indent_level -= 1
       self
     end
-    
+
     # Append the given string after code generated in the given block.
     #
     # @return [self]
@@ -87,7 +78,7 @@ module Rattler::BackEnd
       yield
       self << s
     end
-    
+
     # Append +before+, followed by the code generated in the given block,
     # followed by +after+.
     #
@@ -99,7 +90,7 @@ module Rattler::BackEnd
       self << before
       suffix(after) { yield }
     end
-    
+
     # Generate a multiline indented block with the code generated in the
     # given block, opening the block with +before+ and closing it with
     # +after+.
@@ -113,7 +104,7 @@ module Rattler::BackEnd
       indent { yield }
       newline << after
     end
-    
+
     # Add a separator or newlines or both in between code generated in the
     # given block for each element in +enum+. Newlines, are always added
     # after the separator.
@@ -142,7 +133,7 @@ module Rattler::BackEnd
       end
       self
     end
-    
+
     # Add +sep+ followed by a newline in between code generated in the given
     # block for each element in +enum+.
     #
@@ -153,13 +144,13 @@ module Rattler::BackEnd
     def intersperse_nl(enum, sep)
       intersperse(enum, :sep => sep, :newline => true) {|_| yield _ }
     end
-    
+
     # Return the generated code.
     #
     # @return [String] the generated code
     def code
       @io.string
     end
-    
+
   end
 end

data/lib/rattler/parsers.rb

@@ -1,22 +1,13 @@
-#
-# = rattler/parsers.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
 require 'rattler'
 
 module Rattler
-  #
+
   # The +Parsers+ module defines the basic parsers and combinators used to
-  # compose more complex parsers.
-  #
-  # @author Jason Arhart
-  #
+  # compose recursive descent parsers.
   module Parsers
-
     autoload :Parser, 'rattler/parsers/parser'
     autoload :CombinatorParser, 'rattler/parsers/combinator_parser'
+    autoload :Grammar, 'rattler/parsers/grammar'
     autoload :RuleSet, 'rattler/parsers/rule_set'
     autoload :Rule, 'rattler/parsers/rule'
     autoload :Match, 'rattler/parsers/match'
@@ -29,36 +20,24 @@ module Rattler
     autoload :Disallow, 'rattler/parsers/disallow'
     autoload :Eof, 'rattler/parsers/eof'
     autoload :ESymbol, 'rattler/parsers/e_symbol'
-    autoload :DispatchAction, 'rattler/parsers/dispatch_action'
-    autoload :DirectAction, 'rattler/parsers/direct_action'
-    autoload :SemanticAssert, 'rattler/parsers/semantic_assert'
-    autoload :SemanticDisallow, 'rattler/parsers/semantic_disallow'
-    autoload :SideEffect, 'rattler/parsers/side_effect'
+    autoload :SemanticAction, 'rattler/parsers/semantic_action'
+    autoload :NodeAction, 'rattler/parsers/node_action'
+    autoload :Semantic, 'rattler/parsers/semantic'
+    autoload :AttributedSequence, 'rattler/parsers/attributed_sequence'
     autoload :Token, 'rattler/parsers/token'
     autoload :Skip, 'rattler/parsers/skip'
+    autoload :Super, 'rattler/parsers/super'
     autoload :Label, 'rattler/parsers/label'
     autoload :BackReference, 'rattler/parsers/back_reference'
     autoload :Fail, 'rattler/parsers/fail'
-    autoload :ParserDSL, 'rattler/parsers/parser_dsl'
     autoload :Predicate, 'rattler/parsers/predicate'
     autoload :Atomic, 'rattler/parsers/atomic'
     autoload :Combining, 'rattler/parsers/combining'
-    autoload :MatchJoining, 'rattler/parsers/match_joining'
+    autoload :Sequencing, 'rattler/parsers/sequencing'
+    autoload :ParserScope, 'rattler/parsers/parser_scope'
     autoload :ActionCode, 'rattler/parsers/action_code'
-    autoload :EffectCode, 'rattler/parsers/effect_code'
-    autoload :AssertCode, 'rattler/parsers/assert_code'
-    autoload :DisallowCode, 'rattler/parsers/disallow_code'
     autoload :NodeCode, 'rattler/parsers/node_code'
-
-    class <<self
-      # Define parse rules with the given block
-      #
-      # @return [Rules] a set of parse rules
-      #
-      def define(&block)
-        ParserDSL.rules(&block)
-      end
-    end
-
+    autoload :Analysis, 'rattler/parsers/analysis'
   end
+
 end

data/lib/rattler/parsers/action_code.rb

@@ -1,16 +1,14 @@
-#
-# = rattler/parsers/action_code.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  # @private
+
+  # +ActionCode+ defines abstract ruby code with variables that can be bound
+  # to captured parse results to produce concrete ruby code for semantic
+  # actions.
   class ActionCode #:nodoc:
 
+    # @param [String] code ruby code with optional block parameters and free
+    #   variables and block parameters that can bound to captured parse results
     def initialize(code)
       if md = /\A\s*\|([^|]*)\|(.*)\Z/.match(code)
         @param_names = md[1].split(',').map {|_| _.strip }
@@ -23,14 +21,25 @@ module Rattler::Parsers
 
     attr_reader :param_names, :body
 
-    def bind(scope, bind_args)
-      bind_in body, scope, bind_args
+    # Bind parameters and variables in the code to parse results in +scope+
+    #
+    # @param [ParserScope] scope the scope of captured parse results
+    # @return [String] concrete ruby code with the parameters and variables
+    #   bound to the captured parse results
+    def bind(scope)
+      bind_in body, scope
     end
 
-    def scoped_bindings(scope, bind_args)
-      to_bindings(scope).merge(arg_bindings(bind_args))
+    # @param [ParserScope] scope the scope of captured parse results
+    # @return [Hash] matchers for variables in the ruby code associated with
+    #   replacement values
+    def scoped_bindings(scope)
+      to_bindings(scope.bindings).merge(arg_bindings(scope.captures))
     end
 
+    # @param [Array] args captured parse results as arguments to the ruby code
+    # @return [Hash] matchers for parameters in the ruby code associated with
+    #   +args+ as replacements values
     def arg_bindings(args)
       if param_names.count > args.count
         raise ArgumentError, 'more parameter names than arguments'
@@ -46,12 +55,12 @@ module Rattler::Parsers
       bindings
     end
 
-    def bind_in(code, scope, bind_args)
+    def bind_in(code, scope)
       new_code = code.dup
-      unless param_names.include? '_' or scope.has_key? '_'
-        bind_blanks!(new_code, bind_args)
+      unless param_names.include? '_' or scope.has_name? '_'
+        bind_blanks!(new_code, scope.captures)
       end
-      scoped_bindings(scope, bind_args).each do |k, v|
+      scoped_bindings(scope).each do |k, v|
         next unless k and v
         new_code.gsub!(k, v.to_s)
       end

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

@@ -1,42 +1,50 @@
-#
-# = rattler/grammar/grammar.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-require 'rattler/grammar'
+require 'rattler/parsers'
 require 'set'
 
-module Rattler::Grammar
-  class Analysis
+module Rattler::Parsers
 
-    include Rattler::Parsers
+  # +Analysis+ represents a static analysis of a set of parse rules.
+  class Analysis
 
+    # @param [RuleSet] rules the rule set to analyze
     def initialize(rules)
       @rules = rules
       @references = {}
       @left_references = {}
       @direct_references = {}
       @direct_left_references = {}
+      @has_super = {}
     end
 
+    # @param [Symbol] rule_name the name of a parse rule in the rule set
+    # @return +true+ if the rule referenced by +rule_name+ is non-recursive
     def regular?(rule_name)
       not recursive?(rule_name)
     end
 
+    # @param [Symbol] rule_name the name of a parse rule in the rule set
+    # @return +true+ if the rule referenced by +rule_name+ is recursive
     def recursive?(rule_name)
+      has_super? rule_name or
       referenced_from? rule_name, rule_name
     end
 
+    # @param [Symbol] rule_name the name of a parse rule in the rule set
+    # @return +true+ if the rule referenced by +rule_name+ is left-recursive
     def left_recursive?(rule_name)
       left_referenced_from? rule_name, rule_name
     end
 
+    # @param [Symbol] rule_name the name of a parse rule in the rule set
+    # @return +true+ if the rule referenced by +rule_name+ is referenced by any
+    #   other rule in the rule set
     def referenced?(rule_name)
       rule_name == @rules.start_rule or
       referenced_from? @rules.start_rule, rule_name
     end
 
+    private
+
     def referenced_from?(referencer, referencee)
       references_from(referencer).include? referencee
     end
@@ -45,7 +53,20 @@ module Rattler::Grammar
       left_references_from(referencer).include? referencee
     end
 
-    private
+    def has_super?(rule_name)
+      @has_super[rule_name] ||= expr_has_super?(@rules[rule_name].expr)
+    end
+
+    def expr_has_super?(expr)
+      case expr
+      when Super
+        true
+      when Rattler::Parsers::Parser
+        expr.any? {|_| expr_has_super? _ }
+      else
+        false
+      end
+    end
 
     def references_from(rule_name)
       @references[rule_name] ||= trace_references rule_name, :direct_references

data/lib/rattler/parsers/apply.rb

@@ -1,25 +1,11 @@
-#
-# = rattler/parsers/apply.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Apply+ parses by applying a referenced parse rule.
-  #
-  # @author Jason Arhart
-  #
   class Apply < Parser
 
-    # Create a new parser that parses by applying the parse rule referenced
-    # by +rule_name+.
-    #
-    # @param [Symbol] rule_name the name of the referenced rule
-    #
+    # @param [Symbol,String] rule_name the name of the referenced rule
     # @return [Apply] a new parser that parses by applying the rule
     #   referenced by +rule_name+
     def self.[](rule_name)
@@ -33,11 +19,16 @@ module Rattler::Parsers
 
     # Apply the parse rule referenced by the #rule_name.
     #
-    # @param (see Parser#parse_labeled)
+    # @param (see Match#parse)
     #
     # @return the result of applying the referenced parse rule
-    def parse(scanner, rules, scope = {})
-      (rule = rules[rule_name]) && rule.parse(scanner, rules)
+    def parse(scanner, rules, scope = ParserScope.empty)
+      (rule = rules[rule_name]) && rule.parse(scanner, rules, scope)
+    end
+
+    # (see Parser#capturing_decidable?)
+    def capturing_decidable?
+      false
     end
 
   end

data/lib/rattler/parsers/assert.rb

@@ -1,28 +1,18 @@
-#
-# = rattler/parsers/assert.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 require 'rattler/parsers'
 
 module Rattler::Parsers
-  #
+
   # +Assert+ decorates a parser and succeeds or fails like the decorated
-  # parser but never consumes any input.
-  #
-  # @author Jason Arhart
-  #
+  # parser but never consumes any input (zero-width positive lookahead).
   class Assert < Predicate
 
     # Succeed or fail like the decorated parser but do not consume any input
     # and return +true+ on success.
     #
-    # @param (see Parser#parse_labeled)
+    # @param (see Match#parse)
     #
     # @return [Boolean] +true+ if the decorated parser succeeds
-    def parse(scanner, rules, scope = {})
+    def parse(scanner, rules, scope = ParserScope.empty)
       pos = scanner.pos
       result = (child.parse(scanner, rules, scope) && true)
       scanner.pos = pos

data/lib/rattler/parsers/atomic.rb

@@ -1,16 +1,9 @@
-#
-# = rattler/parsers/atomic.rb
-#
-# Author:: Jason Arhart
-# Documentation:: Author
-#
-
 module Rattler::Parsers
-  # @private
+
+  # +Atomic+ describes a parser that is not a combination of other parsers.
   module Atomic #:nodoc:
 
-    # @param (see Parser#with_ws)
-    # @return (see Parser#with_ws)
+    # (see Parser#with_ws)
     def with_ws(ws)
       ws.skip & self
     end