sexp_builder 0.1

data/COPYING

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Magnus Holm
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software,
+and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+  
+The above copyright notice and this permission notice shall be 
+included in all copies or substantial portions of the Software.
+   
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.rdoc

@@ -0,0 +1,259 @@
+= SexpBuilder
+
+SexpBuilder is an alternative to SexpProcessor which allows you to match and
+rewrite S-expressions based on recursive descent SexpPaths. You probably want
+to read http://github.com/adamsanderson/sexp_path before you proceed.
+
+SexpBuilder works on any S-expressions, but all of these examples uses Ruby's
+S-expressions as given from ParseTree and RubyParser.
+
+== Synopsis
+  
+  # Inherit SexpBuilder:
+  class Andand < SexpBuilder
+    
+    ## Rules
+    #
+    # Rules are simply snippets of SexpPath which can refer to each other
+    # and itself. They are basically method definition, so they can take 
+    # arguments too.
+    
+    # This matches foo.andand:     
+    rule :andand_base do
+      s(:call,          # a method call
+        _ % :receiver,  # the receiver
+        :andand,        # the method name
+        s(:arglist))    # the arguments
+    end
+    
+    # This matches foo.andand.bar
+    rule :andand_call do
+      s(:call,         # a method call
+        andand_base,   # foo.andand
+        _ % :name,     # the method name
+        _ % :args)     # the arguments
+    end
+    
+    # This matches foo.andand.bar { |args| block }
+    rule :andand_iter do
+      s(:iter,           # a block
+        andand_call,     # the method call
+        _ % :blockargs,  # the arguments passed to the block
+        _ % :block)      # content of the block
+    end
+    
+    ## Rewriters
+    #
+    # Rewriters take one or more rules and defines replacements when they 
+    # match. The data-object from SexpPath is given as an argument.
+    
+    # This will rewrite:
+    #
+    #   foo.andand.bar     => (tmp = foo) && tmp.bar
+    #   foo.andand.bar { } => (tmp = foo) && tmp.bar { }
+    # 
+    rewrite :andand_call, :andand_iter do |data|
+      # get a tmpvar (see below for definition)
+      tmp = tmpvar
+      
+      # tmp = foo
+      assign = s(:lasgn, tmp, process(data[:receiver]))
+      
+      # tmp.bar
+      call   = s(:call, s(:lasgn, tmp), data[:name], process(data[:args]))
+      
+      # tmp.bar { }
+      if data[:block]
+        call = s(:iter,
+                 call,
+                 process(data[:blockargs]),
+                 process(data[:block]))
+      end
+      
+      # (tmp = foo) && tmp.bar
+      s(:and,
+        assign,
+        call)
+    end
+    
+    ## Other methods
+    
+    def initialize
+      @tmp = 0
+      super           # don't forget to call super!
+    end
+    
+    # Generates a random variable.
+    def tmpvar
+      "__andand_#{@tmp += 1}".to_sym
+    end
+  end
+  
+  # instantiate a new processor 
+  processor = Andand.new
+
+  # foo.andand.bar
+  example =
+  s(:call,
+   s(:call, s(:call, nil, :foo, s(:arglist)), :andand, s(:arglist)),
+   :bar,
+   s(:arglist))
+   
+  # process it
+  result = processor.process(example)
+  pp result
+ 
+  # s(:and,
+  #  s(:lasgn, :__andand_1, s(:call, nil, :foo, s(:arglist))),
+  #  s(:call, s(:lasgn, :__andand_1), :bar, s(:arglist)))
+  
+  # BONUS: turn it into Ruby with Ruby2Ruby
+  require 'ruby2ruby'
+ 
+  ruby = Ruby2Ruby.new.process(result)
+  puts ruby
+ 
+  # (__andand_1 = foo and (__andand_1).bar)
+  
+== More
+
+SexpBuilder has four different concepts:
+
+* Matchers
+* Rules
+* Rewriters
+* Contexts
+ 
+=== Matchers
+
+A matcher is a bit of Ruby code which can be used in your rules. The
+expression it should match is passed in, and it should return a true-ish value
+if it matches. The matcher will be evaluated under the instantiated processor,
+so you can use other instance methods and instance variables too.
+  
+  class Example < SexpBuilder
+    matcher :five_arguments do |exp|
+      self             # => the instance of Example
+      exp.length == 6  # the first will always be :arglist 
+    end
+    
+    rule :magic_call do
+      s(:call,          # a method call
+        nil,            # no receiver
+        :MAGIC!,        # method name
+        five_arguments) # our matcher
+    end
+  end
+  
+=== Rules
+
+You've heard it before, but let's repeat: Rules are simply snippets of
+SexpPath which can refer to each other and itself. They are basically method
+definition, so they can take arguments too.
+
+The rule will be evaluated under a special scope, but if you really need it
+you can access the instantiated processor using `instance`. You should however
+move any specific Ruby code into a matcher and let the rules simply contain
+other rules and matchers.
+
+  class Example < SexpBuilder
+    # Matches any number.
+    rule :number do |capture_as|
+      # Doesn't make very much sense to take an argument here,
+      # it's just an example
+      s(:lit, _ % capture_as)
+    end
+    
+    # Matches a sequence of plusses: 1 + 2 + 3
+    rule :plus_sequence do
+      s(:call,               # a method call
+         number(:number) |   # the receiver can be a number
+         plus_sequence,      # or a sequence   
+        :+,
+        s(:arglist,
+         number(:number) |   # the argument can be a number
+         plus_sequence       # or a sequence
+    end
+  end
+  
+=== Rewriters
+
+Rewriters take one or more rules and defines replacements when they match. The
+data-object from SexpPath is given as an argument. If you want some of the
+sub-expressions matched too, you'll have to call process yourself.
+
+  class Example < SexpBuilder
+    
+    # We want to rewrite the plus_sequence above
+    rewrite :plus_sequence do |data|
+      # sum the numbers
+      sum = data[:number].inject { |all, one| all + one }
+      # return a new number
+      s(:lit, sum)
+    end
+    
+    rewrite :something_else do |data|
+      # process the block in case it also needs to be rewritten
+      block = process(data[:block])
+      do_funky_stuff(block)
+    end
+  end
+  
+=== Contexts
+
+Contexts allows you to group a set of rewriters together. It will inherit the
+parents rules and matchers.
+
+  class Example < SexpBuilder
+    # Matches a class definition
+    rule :class_def do
+      s(:class,
+        _ % :name,
+        _ % :parent,
+        _ % :content)
+    end
+    
+    rewrite :class_def do |data|
+      # NOTICE: we use process_class to enter the class-context.
+      content = process_class(data[:content])
+      do_funky_stuff(content)
+    end
+
+    # Only for stuff inside a class:
+    context :class do
+      rule :method_definition do
+        s(:defn,
+          _ % :name,
+          _ % :args,
+          _ % :content)
+      end
+      
+      rewrite :method_definition do |data|
+        # this will continue processing in the class-context.
+        # use process_main to enter the main context again.
+        content = process(data[:content])
+        do_funky_stuff(content)
+      end
+    end
+    
+  end
+  
+If you subclass your processor, it will also enter a new context:
+
+  class ModuleContext < Example
+    # use process_module to enter this context.
+  end
+  
+By default it takes the last part of the name, removes "Context" or "Builder"
+at the end and turns it into snake case. If needed, you can easily override
+this yourself (remember to turn it into a writable method name though):
+
+  def Example.context_name(mod)
+    "context#{rand(10)}"
+  end
+  
+== License
+
+See COPYING for legal information. It's a MIT license which allows you to do
+pretty much what you want with it, and *please* do!
+    

data/examples/andand.rb

@@ -0,0 +1,67 @@
+class Andand < SexpBuilder
+  
+  # This matches foo.andand:     
+  rule :andand_base do
+    s(:call,          # a method call
+      _ % :receiver,  # the receiver
+      :andand,        # the method name
+      s(:arglist))    # the arguments
+  end
+  
+  # This matches foo.andand.bar
+  rule :andand_call do
+    s(:call,         # a method call
+      andand_base,   # foo.andand
+      _ % :name,     # the method name
+      _ % :args)     # the arguments
+  end
+  
+  # This matches foo.andand.bar { |args| block }
+  rule :andand_iter do
+    s(:iter,           # a block
+      andand_call,     # the method call
+      _ % :blockargs,  # the arguments passed to the block
+      _ % :block)      # content of the block
+  end
+  
+  # This will rewrite:
+  #
+  #   foo.andand.bar     => (tmp = foo) && tmp.bar
+  #   foo.andand.bar { } => (tmp = foo) && tmp.bar { }
+  # 
+  rewrite :andand_call, :andand_iter do |data|
+    # get a tmpvar (see below for definition)
+    tmp = tmpvar
+    
+    # tmp = foo
+    assign = s(:lasgn, tmp, process(data[:receiver]))
+    
+    # tmp.bar
+    call   = s(:call, s(:lasgn, tmp), data[:name], process(data[:args]))
+    
+    # tmp.bar { }
+    if data[:block]
+      call = s(:iter,
+               call,
+               process(data[:blockargs]),
+               process(data[:block]))
+    end
+    
+    # (tmp = foo) && tmp.bar
+    s(:and,
+      assign,
+      call)
+  end
+  
+  ## Other methods
+  
+  def initialize
+    @tmp = 0
+    super           # don't forget to call super!
+  end
+  
+  # Generates a random variable.
+  def tmpvar
+    "__andand_#{@tmp += 1}".to_sym
+  end
+end

data/lib/sexp_builder.rb

@@ -0,0 +1,100 @@
+require 'forwardable'
+require 'thread'
+require 'sexp_path'
+
+class SexpBuilder
+  VERSION = "0.1"
+  
+  autoload :Context,      'sexp_builder/context'
+  autoload :QueryBuilder, 'sexp_builder/query_builder'
+  attr_reader :context, :scope
+  
+  # Initializes the builder. If you redefine this in your subclass,
+  # it's important to call +super()+.
+  def initialize
+    @context = self.class.current_context
+    @main = @context.main_context
+    @scope = []
+    @rewriters = {}
+    @query_builders = {}
+  end
+  
+  # Process +sexp+ under the current context.
+  def process(sexp, options = {})
+    @scope.unshift(sexp.sexp_type)
+
+    rewriters.each do |query, method|
+      if data = query.satisfy?(sexp, QueryBuilder::Data.new)
+        return method.call(SexpPath::SexpResult.new(sexp, data))
+      end
+    end
+    
+    # If none of the rewriters matched, process the children:
+    sexp.inject(Sexp.new) do |memo, exp|
+      memo << if exp.is_a?(Sexp)
+        process(exp)
+      else
+        exp
+      end
+    end
+  ensure
+    @scope.shift     
+  end
+  
+  # Process +sexp+ under the top context.
+  def process_main(sexp, options = {})
+    prev, @context = @context, @main
+    process(sexp, options)
+  ensure
+    @context = prev
+  end
+  
+  # Returns an array in the format of:
+  #
+  #   [<SexpPath::Matcher> rule, <Method> rewriter] 
+  def rewriters(context = @context)
+    @rewriters[context] ||= context.rewriters.map do |rule|
+      [query_builder(context).send(rule), method("rewrite_#{rule}")]
+    end
+  end
+  
+  # Returns the query builder for a given context.
+  def query_builder(context = @context)
+    @query_builders[context] ||= QueryBuilder.make(context, self)
+  end
+  
+  class << self
+    extend Forwardable
+    # The Context which this builder will process under.
+    attr_accessor :current_context
+    # Delegates various methods to the current_context.
+    def_delegators :@current_context, :context, :matcher, :rule, :rewrite
+    
+    # Sets up the +current_context+.
+    def inherited(mod)
+      if self == SexpBuilder
+        mod.current_context = Context.new(mod)
+      else
+        mod.current_context = current_context.context(context_name(mod))
+      end
+    end
+    
+    # Turns a module into a context name:
+    #
+    # * FooBar        => foo_bar
+    # * FooBarContext => foo_bar
+    # * FooBarBuilder => foo_bar
+    def context_name(mod)
+      name = mod.name
+      name = name.split("::").last
+      name.gsub!(/(Context|Builder)$/, '')
+      name.scan(/.[^A-Z]+/).map { |part| part.downcase }.join("_")
+    end
+    
+    # Generates a temporary id.
+    def tmpid
+      @tmpid ||= 0
+      @tmpid += 1
+    end
+  end
+end

data/lib/sexp_builder/context.rb

@@ -0,0 +1,168 @@
+class SexpBuilder
+  class Context
+    attr_reader :parent, :builder, :query_scope, :contexts, :rewriters
+    
+    def initialize(builder, parent = nil)
+      @builder = builder
+      @parent = parent
+      
+      @contexts  = {}
+      @rewriters = []
+      
+      @query_scope = Module.new do
+        include parent.query_scope if parent
+      end
+    end
+    
+    # Returns the top-most context.
+    def main_context
+      if @parent
+        @parent.main_context
+      else
+        self
+      end
+    end
+    
+    # Defines or finds a sub-context, and evalutes the block under it. If you
+    # want to process something under this context, you would have to call
+    # <tt>process_{name}</tt>.
+    def context(name, &blk)
+      context = define_context(name.to_sym)
+      context.instance_eval(&blk) if blk
+      context
+    end
+    
+    # Defines a matcher. A matcher is a bit of Ruby code which can be used in
+    # your rules. The expression it should match is passed in, and it should
+    # return a true-ish value if it matches. The matcher will be evaluated
+    # under the instatiated processor, so you can use other instance methods
+    # and instance variables too.
+    #
+    #   matcher :five_arguments do |exp|
+    #     self             # => the instance of Example
+    #     exp.length == 6  # the first will always be :arglist
+    #   end
+    # 
+    # Under the hood, this will define:
+    # 
+    # * The block as +matcher_five_arguments+ on the builder.
+    # * +five_arguments+, which will invoke the matcher, on the query scope.
+    def matcher(name, &blk)
+      method_name = "matcher_#{name}"
+      define(method_name, &blk)
+      
+      define_query_scope(name) do
+        block do |exp|
+          instance.send(method_name, exp)
+        end
+      end
+    end
+    
+    # Defines a rule. Rules are simply snippets of SexpPath which can refer to
+    # each other and itself. They can also take arguments too.
+    # 
+    #   # Matches any number.
+    #   rule :number do |capture_as|
+    #     # Doesn't make very much sense to take an argument here,
+    #     # it's just an example
+    #     s(:lit, _ % capture_as)
+    #   end
+    #
+    #   # Matches a sequence of plusses: 1 + 2 + 3
+    #   rule :plus_sequence do
+    #     s(:call,               # a method call
+    #        number(:number) |   # the receiver can be a number
+    #        plus_sequence,      # or a sequence   
+    #       :+,
+    #       s(:arglist,
+    #        number(:number) |   # the argument can be a number
+    #        plus_sequence       # or a sequence
+    #   end
+    # 
+    # Under the hood, this will define:
+    # 
+    # * The blocks as +real_number+ and +real_plus_sequence+ on the 
+    #   query_scope.
+    # * +number+ and +plus_sequence+ which wraps the methods above as 
+    #   QueryBuilder::Deferred.
+    def rule(name, &blk)
+      real_name = "real_#{name}"
+      define_query_scope(real_name, &blk)
+      define_query_scope(name) do |*args|
+        QueryBuilder::Deferred.new(self, real_name, args, name)
+      end
+    end
+    
+    # Defines a rewriter. Rewriters take one or more rules and defines
+    # replacements when they match. The data-object from SexpPath is given as
+    # an argument. If you want some of the sub-expressions matched too, you'll
+    # have to call process() yourself.
+    #
+    #   rewrite :plus_sequence do |data|
+    #     # sum the numbers
+    #     sum = data[:number].inject { |all, one| all + one }
+    #     # return a new number
+    #     s(:lit, sum)
+    #   end
+    # 
+    # Under the hood, this will define:
+    # 
+    # * The block as +rewrite_plus_sequence+.
+    # * And @rewriters will now include :plus_sequence.
+    # 
+    # You can also give this several rules, or none if you want it to match
+    # every single Sexp.
+    #
+    # == Context shortcut
+    #
+    #   rewrite :foo, :in => :bar do
+    #     ...
+    #   end
+    # 
+    # Is the same as:
+    #
+    #   context :bar do
+    #     rewrite :foo do
+    #       ...
+    #     end
+    #   end
+    def rewrite(*rules, &blk)
+      options = rules.last.is_a?(Hash) ? rules.pop : {}
+      rules << :wild if rules.empty?
+      
+      return context(options[:in]).rewrite(*rules, &blk) if options[:in]
+      
+      rules.each do |rule|
+        @rewriters << rule
+        define("rewrite_#{rule}", &blk)
+      end
+    end
+    
+    private
+    
+    def define_context(name)
+      @contexts[name] ||= begin      
+        context = Context.new(@builder, self)
+        
+        define("process_#{name}") do |*args|
+          begin
+            prev, @context = @context, context
+            process(*args)
+          ensure
+            @context = prev
+          end
+        end                  
+        
+        context
+      end
+    end
+    
+    def define_query_scope(name, &blk)
+      @query_scope.send(:define_method, name, &blk)
+    end
+    
+    def define(name, &blk)
+      @builder.send(:define_method, name, &blk)
+    end
+  end
+end

data/lib/sexp_builder/query_builder.rb

@@ -0,0 +1,65 @@
+class SexpBuilder
+  class QueryBuilder < SexpPath::SexpQueryBuilder
+    class Data < Hash
+      def []=(key, value)
+        if current = self[key]
+          if current.class == Array
+            current << value
+          else
+            super(key, [current, value])
+          end
+        else
+          super
+        end
+      end
+    end
+    
+    class Scope < SexpPath::Matcher::Base
+      def initialize(type, instance)
+        @type = type
+        @instance = instance
+      end
+      
+      def satisfy?(o, data={})
+        if @instance.scope[1..-1].include?(@type)
+          capture_match o, data
+        end
+      end
+    end
+    
+    class Deferred < SexpPath::Matcher::Base
+      def initialize(receiver, name, args, real_name)
+        @receiver = receiver
+        @name = name
+        @args = args
+        @real_name = real_name.to_s
+      end
+      
+      def satisfy?(o, data={})
+        @receiver.send(@name, *@args).satisfy?(o, data)
+      end
+      
+      def inspect
+        "rule(:#{@real_name})" 
+      end
+    end
+    
+    class << self
+      attr_accessor :instance
+      
+      def make(context, instance)
+        query_builder = Class.new(QueryBuilder) { extend context.query_scope }
+        query_builder.instance = instance
+        query_builder
+      end
+      
+      def scope(type)
+        Scope.new(type, instance)
+      end
+      
+      def block(&blk)
+        SexpPath::Matcher::Block.new(&blk)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: sexp_builder
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- Magnus Holm
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-25 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: sexp_path
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: judofyr@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- COPYING
+- README.rdoc
+- examples/andand.rb
+- lib/sexp_builder.rb
+- lib/sexp_builder/context.rb
+- lib/sexp_builder/query_builder.rb
+has_rdoc: true
+homepage: http://dojo.rubyforge.org/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Easily to match and rewrite S-expressions
+test_files: []
+