rubymacros 0.1.0

data/COPYING.LGPL

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions. 
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version. 
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/Manifest.txt

@@ -0,0 +1,21 @@
+COPYING.LGPL
+Manifest.txt
+README.txt
+rubymacros.vpj
+Rakefile
+test/test_form.rb
+test/test_expand.rb
+lib/macro.rb
+lib/macro/form.rb
+lib/macro/version.rb
+example/andand.rb
+example/assert.rb
+example/assert_wrap.rb
+example/__dir__.rb
+example/__dir___wrap.rb
+example/loop.rb
+example/loop_wrap.rb
+example/simple.rb
+example/simple_wrap.rb
+example/with.rb
+example/with_wrap.rb

data/README.txt

@@ -0,0 +1,119 @@
+= RubyMacros
+* http://rubymacros.rubyforge.org
+* http://rubyforge.org/projects/rubymacros
+
+== DESCRIPTION:
+RubyMacros is a lisp-like macro pre-processor for Ruby. More than just a 
+purely textual substitution scheme, RubyMacros can manipulate and morph 
+Ruby parse trees (in the form of RedParse Nodes) at parse time in just about 
+any way you see fit. 
+
+Macros are programmed in ruby itself. And since parse trees are represented 
+in RedParse format, they're easier to use (programatically) and more object-
+oriented than other available ruby parsetree formats. (RedParse Node format 
+is actually designed to be straightforward to use and to represent the 
+structure of ruby source code very closely.)
+
+== Benefits:
+ * Powerful and easy metaprogramming
+ * Create better DSLs
+ * Manipulate syntax trees to suit yourself
+ * Access local variables and other caller context unavailable to methods
+ * Macros as inline methods: should be slightly faster than equivalent methods
+
+== Drawbacks:
+Although in theory already as powerful as lisp macros, the current 
+implementation has a number of problems which added together make it merely 
+a proof of concept or toy at this point:
+ * pre-processing is very, very slow (because of RedParse)
+ * macro calls must be inside some sort of method;
+ * straight out macro calls at the top level won't work
+ * macros can't have blocks or receivers
+ * some ruby syntax is unsupported in files using macros
+ * files using macros must be loaded via Macro.require;
+ * Kernel#require will not recognize macros
+ * RedParse Node tree format will be changing slightly
+ * macros cannot be scoped
+ * no variable (or other) hygiene
+
+== Requirements:
+  RubyMacros requires RedParse.
+
+== Install:
+  gem install rubymacros
+
+== Examples:
+  macro simple(a,b) 
+    :(^a+^b) 
+  end
+  def simple_user
+    p simple(1,2)  #prints 3
+  end
+
+  #loop as a macro, should be a bit faster than the #loop method
+  macro loop(body)
+    :(while true
+        ^body
+      end
+    )
+  end
+
+  #for more examples, see the examples/ directory
+
+== New Syntax:
+I have invented 3 new syntactical constructions in order to allow reasonably
+easy to use macros. Macros themselves look just like methods except that 
+'macro' instead of 'def' is used to start the macro definition off. A form 
+literal is an expression surrounded by ':(' and ')'. The form escape operator 
+is '^'. '^' is a unary operator of fairly high precedence.
+
+== Forms and Form Escapes:
+Forms are an essential adjunct to macros. Forms represent quoted source 
+code, which has been parsed but not evaled yet. When a form literal is 
+executed, it returns a RedParse::Node representing the parse tree for the 
+enclosed source code. Within a form literal, a ^, used as a unary operator, 
+will escape the expression it controls, so that instead of being part of the
+form's data, it is executed at the same time as the form literal, and the 
+result of an escaped expression (which should be a Node) is interpolated
+into the form at that point. The whole effect is much like that of string
+interpolations (#{}) inside string literals.
+
+== How Macros Work
+Typically, macros return a single form literal, which contains form escape 
+expressions within it which make use of the macro's parameters. However, 
+macro bodies may contain anything at all; more complicated macros will 
+likely not contain any forms. (Likewise, form literals may be used outside 
+macros, but the utility of doing so may be minimal.)
+
+At parse time (well, really at method definition time, but in effect it's 
+much the same thing) method bodies are scanned for callsites which have the 
+names of known macros. When such a call is found, it is expanded as follows. 
+The parsetrees for the arguments to the callsite are passed as arguments to 
+the macro. The macro is expected to return a parsetree, which replaces the 
+macro callsite in the parsetree which contained it. 
+
+
+
+== Known Problems
+ * need to insert extra parens around form params and macro texts
+ * a variety of parsetrees are kept around forever for no good reason
+ * a few warnings and disabled tests in unit tests
+ * however, huge rediculous piles of RedParse warnings when running 'rake test'
+
+== License:
+Copyright (C) 2008  Caleb Clausen
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+

data/Rakefile

@@ -0,0 +1,26 @@
+# Copyright (C) 2008  Caleb Clausen
+# Distributed under the terms of Ruby's license.
+require 'rubygems'
+require 'hoe'
+require 'lib/macro/version.rb'
+ 
+ 
+   readme=open("README.txt")
+   readme.readline("\n== DESCRIPTION:")
+   readme.readline("\n\n")
+   desc=readme.readline("\n\n")
+ 
+   hoe=Hoe.new("rubymacros", Macro::VERSION) do |_|
+     _.author = "Caleb Clausen"
+     _.email = "rubymacros-owner @at@ inforadical .dot. net"
+     _.url = ["http://rubymacros.rubyforge.org/", "http://rubyforge.org/projects/rubymacros/"]
+     _.extra_deps << ['redparse', '>= 0.8.0']
+     _.test_globs=["test/*"]
+     _.description=desc
+     _.summary=desc[/\A[^.]+\./]
+#     _.spec_extras={:bindir=>''}
+     _.rdoc_pattern=/\A(README\.txt|lib\/.*\.rb)\Z/
+     _.remote_rdoc_dir="/"
+   end
+
+

data/example/__dir__.rb

@@ -0,0 +1,7 @@
+macro __DIR__
+  :(File.dirname(__FILE__))
+end
+
+def diruser
+  p __DIR__
+end

data/example/__dir___wrap.rb

@@ -0,0 +1,4 @@
+require 'macro'
+Macro.require 'example/__dir__.rb'
+
+diruser

data/example/andand.rb

@@ -0,0 +1,3 @@
+macro andand(a,b)
+  :(^a and ^b)
+end

data/example/assert.rb

@@ -0,0 +1,42 @@
+#this file uses macros! won't parse in normal ruby
+$Debug=1
+if $Debug
+  macro assert(cond)
+    if RedParse::OpNode===cond and /\A[=!]=\Z/===cond.op
+      left,op,right=*cond
+      :(fail 'expected '+^left.unparse({})+"(==#{^left}) to be "+
+             ^op+" "+^right.unparse({})+"(==#{^right})" unless ^cond)    
+    else
+      :(fail "expected #{:(^^cond)}, but was not true" unless ^cond)
+    end
+  end
+else
+  macro assert(cond)
+  end
+end
+
+
+#assert_equal... bah, who needs it?
+
+def test_assert
+  a=1 
+  b=2
+
+  assert a     #ok
+  assert a!=b  #ok
+
+  begin
+    assert(a==b) #oops, fails. msg="expected a(==1) to be == b(==2)"
+  rescue Exception=>e
+    assert("expected a(==1) to be == b(==2)"== e.message) #better be ok
+  else fail
+  end
+
+  begin
+    assert(nil) #oops, fails. msg="expected nil, but was not true"
+  rescue Exception=>e
+    assert("expected nil, but was not true"== e.message) #better be ok
+    #ok, that message didn't make a lot of sense...
+  else fail
+  end
+end

data/example/assert_wrap.rb

@@ -0,0 +1,4 @@
+require 'macro'
+Macro.require 'example/assert'
+
+test_assert

data/example/loop.rb

@@ -0,0 +1,23 @@
+=begin doesn't work yet
+macro loop(&body)
+  :(while true
+     ^body
+  )
+end
+=end
+
+macro loop(body)
+  :(while true
+     ^body
+    end
+  )
+end
+
+def loop_user
+  i=0
+  loop(
+    p i
+    i+=1
+    break if i>=10
+  )
+end

data/example/loop_wrap.rb

@@ -0,0 +1,4 @@
+require 'macro'
+Macro.require 'example/loop.rb'
+
+loop_user

data/example/simple.rb

@@ -0,0 +1,4 @@
+macro simple(a,b) :(^a+^b) end
+def simple_user
+  p simple(1,2)
+end

data/example/simple_wrap.rb

@@ -0,0 +1,4 @@
+require 'macro'
+Macro.require 'example/simple'
+
+simple_user

data/example/with.rb

@@ -0,0 +1,56 @@
+=begin doesn't work yet
+
+#change the default receiver within the block from self to new_default
+macro with(new_default,&block)
+  block.walk{|parent,i,subi,node|
+    if RedParse::CallNode===node and node.receiver.nil?
+      node.receiver=new_default
+    end
+    true
+  }
+  return block
+end
+
+#used like this:
+class Foo
+  def bar
+    @quux=999
+    p with "baz" do
+      [
+        @quux,  #=>999, not nil
+        size   #=>3, not 99
+      ]
+    end
+  end
+
+  def size; 99 end
+end
+Foo.new.bar
+
+
+=end
+
+#change the default receiver within the block from self to new_default
+macro with(new_default,block)
+  block.walk{|parent,i,subi,node|
+    if RedParse::CallNode===node and node.receiver.nil?
+      node.receiver=new_default
+    end
+    true
+  }  
+  return block
+end
+
+#used like this:
+class Foo
+  def bar
+    @quux=999
+    p with "baz", [
+      @quux,  #=>999, not nil
+      size   #=>3, not 99
+    ]
+  end
+
+  def size; 99 end
+end
+Foo.new.bar

data/example/with_wrap.rb

@@ -0,0 +1,3 @@
+require 'macro'
+Macro.require 'example/with'
+

data/lib/macro/form.rb

@@ -0,0 +1,146 @@
+=begin
+    rubymacros - a macro preprocessor for ruby
+    Copyright (C) 2008  Caleb Clausen
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+=end
+
+#warn '$LOAD_PATH hacked up to include latest redparse'
+#$: << "../redparse/lib"
+
+require "redparse"
+require "macro"
+class Macro
+  class FormNode < RedParse::ValueNode
+    param_names :text
+    def initialize(colon,text)
+      if RedParse::VarLikeNode===text 
+        @transform=HashLiteralNode[]
+        super text
+        return
+      end
+
+      fail unless ParenedNode===text && text.size==1 
+      text=text.body
+
+      super text
+      rebuild_transform
+    end
+
+    def rebuild_transform
+      @transform=HashLiteralNode[]
+      @parameters=[]
+
+      walkers=proc{|rcvr,wraplayers| #curry
+        rcvr.walk{|*args| 
+         node=args.last
+         case node
+         when FormParameterNode
+           target=node.wraplevel
+           fail if wraplayers > target
+           if wraplayers==target #skip this parameter if it doesn't have enough wrappers
+             @parameters << node #remember parameter (and implicitly, location)
+
+             nil# and stop further recursion
+           else 
+             true
+           end
+         when FormNode
+           #walk form with same walker we're using now, except an extra layer of form parameters
+           #must be present for them to be considered 'our' parameters
+           walkers[node.text,wraplayers+1]
+           nil #don't recurse in this node again, we just did it
+         else true
+         end
+        } if rcvr.respond_to? :walk
+      }
+      walkers[text,1]
+
+      @parameters.each{|orig_escd| 
+        escd=orig_escd
+        escd=escd.val while FormParameterNode===escd
+        @transform.push LiteralNode[orig_escd.__id__], escd
+      }    
+
+      return self
+    end
+
+    def each_parameter(&block)
+      @parameters.each(&block) if @parameters
+    end
+
+    def deep_copy transform={}
+      super(transform).rebuild_transform
+    end
+
+    def unparse o
+      ":("+text.unparse(o)+")"
+    end
+
+    def reify transform
+      transform.each_pair{|k,v|
+        transform[k]=Macro.quote(v) unless Node===v or VarNameToken===v
+      }
+      deep_copy(transform)
+    end
+
+    def parsetree
+      parses_like.parsetree
+    end
+
+
+
+    module ::Macro::Names
+      COUNT=[0]
+      def self.request form 
+        result="Number_#{COUNT[0]+=1}"
+        const_set result, form
+        return result
+      end
+    end
+
+    #CallSiteNode=RedParse::CallSiteNode
+    #ConstantNode=RedParse::ConstantNode
+    def parses_like
+      CallSiteNode[CallSiteNode[ConstantNode[nil,"Macro","Names",formname], "reify", [@transform],nil,nil], "text", nil,nil,nil]
+      #:(::Macro::Names::^(formname).reify.text)
+    end
+    
+    def formname
+      @formname ||= ::Macro::Names.request(self)
+    end
+  end
+
+
+  class FormParameterNode < RedParse::ValueNode #not to appear in final parsetree?
+      param_names :val
+
+      def initialize(*args)
+        super(args.last)    
+      end
+
+      def unparse o
+        "^"+val.unparse(o)      
+      end
+
+      def wraplevel
+        return val.wraplevel+1 if FormParameterNode===val
+        return 1
+      end
+
+      def inspect
+         val.unparse({})
+      end
+  end
+end

data/lib/macro/version.rb

@@ -0,0 +1,22 @@
+=begin
+    rubymacros - a macro preprocessor for ruby
+    Copyright (C) 2008  Caleb Clausen
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+=end
+
+
+class Macro
+  VERSION="0.1.0"
+end