rubymacros 0.1.1 → 0.1.2

data/History.txt

@@ -0,0 +1,16 @@
+=== 0.1.2 / 2009-04-26
+
+* 7 minor enhancements
+  * lots of nice comments added, thanks to Paul Brannan and Tatsuji Kawai
+  * Paul fixed the weird rdoc failure too!
+  * incorrect warning removed
+  * Value changed to Expr in parse rules
+  * hack to get 'rake test' to stay in 1 process (to keep netbeans happy)
+  * in test_form.rb, don't test deep_copy on nil forms
+  * all files should be world-readable now
+
+=== 0.1.0 / 2008-10-24
+
+* 1 major enhancement
+  * Birthday!
+

data/Manifest.txt

@@ -1,6 +1,7 @@
 COPYING.LGPL
 Manifest.txt
 README.txt
+History.txt
 rubymacros.vpj
 Rakefile
 test/test_form.rb
@@ -19,3 +20,6 @@ example/simple.rb
 example/simple_wrap.rb
 example/with.rb
 example/with_wrap.rb
+example/linenum.rb
+example/linenum_user.rb
+example/linenum_wrap.rb

data/Rakefile

@@ -4,7 +4,18 @@ require 'rubygems'
 require 'hoe'
 require 'lib/macro/version.rb'
  
- 
+
+if $*==["test"]
+  #hack to get 'rake test' to stay in one process
+  #which keeps netbeans happy
+  $:<<"lib"
+  $:<<"../redparse/lib" #hack hack hack
+  require 'redparse'
+  require "test/test_all.rb"
+  Test::Unit::AutoRunner.run
+  exit
+end
+
    readme=open("README.txt")
    readme.readline("\n== DESCRIPTION:")
    readme.readline("\n\n")
@@ -19,7 +30,7 @@ require 'lib/macro/version.rb'
      _.description=desc
      _.summary=desc[/\A[^.]+\./]
 #     _.spec_extras={:bindir=>''}
-     _.rdoc_pattern=/\A(README\.txt|lib\/.*\.rb)\Z/
+#     _.rdoc_pattern=/\A(README\.txt|lib\/.*\.rb)\Z/
      _.remote_rdoc_dir="/"
    end
 

data/example/linenum.rb

@@ -0,0 +1,18 @@
+macro __DIR__
+  :(File.dirname(__FILE__))
+end
+
+macro foo
+  :(
+    "just an example, to take up several lines,"+
+    "so that line numbers might be messed up"
+  )
+end
+
+def user_of_foo
+  foo
+end
+
+def linenumuser
+  p __LINE__ #should print 17
+end

data/example/linenum_user.rb

@@ -0,0 +1,7 @@
+SCRIPT_LINES__={}
+require 'example/linenum_wrap.rb'
+
+p SCRIPT_LINES__.keys.grep(/linenum/).each{|k|
+  p k
+  puts SCRIPT_LINES__[k]
+}

data/example/linenum_wrap.rb

@@ -0,0 +1,4 @@
+require 'macro'
+Macro.require 'example/linenum.rb'
+
+linenumuser

data/lib/macro/form.rb

@@ -22,15 +22,25 @@
 require "redparse"
 require "macro"
 class Macro
+  # The syntax node for forms
   class FormNode < RedParse::ValueNode
     param_names :text
+
+    # Create a new form node.  The user should normally not call this
+    # function.  Form nodes are created by the parser.
+    #
+    # +colon+:: A colon token
+    # +text+::  A ParenedNode or VarLikeNode
+    #
     def initialize(colon,text)
+      # Certain node types need to be quoted
       if RedParse::VarLikeNode===text 
         @transform=HashLiteralNode[]
         super text
         return
       end
 
+      # Sanity check - make sure this is a valid ParenedNode
       fail unless ParenedNode===text && text.size==1 
       text=text.body
 
@@ -38,7 +48,10 @@ class Macro
       rebuild_transform
     end
 
+    # Initialize the transform and create all the form escapes that are
+    # used in this form
     def rebuild_transform
+      # TODO: this method needs to be better documented/refactored
       @transform=HashLiteralNode[]
       @parameters=[]
 
@@ -76,18 +89,37 @@ class Macro
       return self
     end
 
+    # Iterate over all the parameters in this form
+    #
+    # +block+:: the block to call for each parameter
+    #
     def each_parameter(&block)
       @parameters.each(&block) if @parameters
     end
 
+    # Make a deep copy of this form
+    #
+    # +transform+:: TODO
+    #
     def deep_copy transform={}
       super(transform).rebuild_transform
     end
 
+    # Performs the reverse of a parse operation (turns the node into a
+    # string)
+    #
+    # +o+:: a list of options for unparse
+    #
     def unparse o
       ":("+text.unparse(o)+")"
     end
 
+    # Called when the form is evaluated to ensure that the abstract form
+    # in the parse tree is a concrete form that can be modified (makes a
+    # copy of the form).
+    #
+    # +transform+:: the transform to use in the deep copy
+    #
     def reify transform
       transform.each_pair{|k,v|
         transform[k]=Macro.quote(v) unless Node===v or VarNameToken===v
@@ -95,6 +127,7 @@ class Macro
       deep_copy(transform)
     end
 
+    # Transform this node into a ParseTree parse tree
     def parsetree
       parses_like.parsetree
     end
@@ -103,6 +136,11 @@ class Macro
 
     module ::Macro::Names
       COUNT=[0]
+
+      # Sets up the mapping from a form name to a form literal
+      #
+      # +form+:: the name of the form
+      #
       def self.request form 
         result="Number_#{COUNT[0]+=1}"
         const_set result, form
@@ -112,35 +150,62 @@ class Macro
 
     #CallSiteNode=RedParse::CallSiteNode
     #ConstantNode=RedParse::ConstantNode
+
+    # Turn the form into something that is legal ruby (since :(..) is
+    # not legal ruby syntax).  Thus the form is changed from the syntax:
+    #
+    #   :(code)
+    #
+    # to:
+    #
+    #   RedParse::SomeNodeType[ some transform of code ]
+    #
     def parses_like
+      # TODO: either split this into mulitple lines or multiple methods
+      # possibly formname() should return the ConstantNode portion of
+      # the below expression (so that we have one "name" for the form
+      # instead of two representations of the same name)
       CallSiteNode[CallSiteNode[ConstantNode[nil,"Macro","Names",formname], "reify", [@transform],nil,nil], "text", nil,nil,nil]
       #:(::Macro::Names::^(formname).reify.text)
     end
     
+    # Lazily evaluate the name of the form and return it
     def formname
       @formname ||= ::Macro::Names.request(self)
     end
   end
 
 
-  class FormParameterNode < RedParse::ValueNode #not to appear in final parsetree?
-      param_names :val
+  # The syntax node for a form escape
+  class FormParameterNode < RedParse::ValueNode
+    param_names :val
 
-      def initialize(*args)
-        super(args.last)    
-      end
+    # Called by the parser to create a new form parameter node.
+    #
+    # +args+:: TODO
+    #
+    def initialize(*args)
+      super(args.last)    
+    end
 
-      def unparse o
-        "^"+val.unparse(o)      
-      end
+    # Performs the reverse of a parse operation (turns the node into a
+    # string)
+    #
+    # +o+:: a list of options for unparse
+    #
+    def unparse o
+      "^"+val.unparse(o)      
+    end
 
-      def wraplevel
-        return val.wraplevel+1 if FormParameterNode===val
-        return 1
-      end
+    # The number of carats (^) that occur in the escape.  Note that
+    # this method is recursive.
+    def wraplevel
+      return val.wraplevel+1 if FormParameterNode===val
+      return 1
+    end
 
-      def inspect
-         val.unparse({})
-      end
+    def inspect
+      val.unparse({})
+    end
   end
 end

data/lib/macro/version.rb

@@ -18,5 +18,5 @@
 
 
 class Macro
-  VERSION="0.1.1"
+  VERSION="0.1.2"
 end

data/lib/macro.rb

@@ -19,7 +19,6 @@
 #$:.unshift "../redparse/lib"
 #warn "$: hacked up to find latest redparse"
 
-warn "rubygems require disabled"
 require 'rubygems'
 require 'redparse'
 require "macro/form"
@@ -27,6 +26,13 @@ require "macro/version"
 
 warn "need to insert extra parens around form params and macro texts"
 
+class Object # :nodoc:
+  #as close as I can get to an empty binding (used below in Macro.eval)
+  def Object.new_binding() # :nodoc:
+    binding 
+  end
+end
+
 class Macro
   #import Node classes from RedParse
   RedParse::constants.each{|k| 
@@ -46,6 +52,9 @@ class Macro
 
   #like Kernel#require, but allows macros (and forms) as well.
   #c extensions (.dll,.so,etc) cannot be loaded via this method.
+  #
+  # +filename+:: the name of the feature to require
+  #
   def Macro.require(filename) 
     filename+='.rb' unless filename[/\.rb\Z/]
     return if $".include? filename 
@@ -53,12 +62,11 @@ class Macro
     load filename
   end
 
-  #as close as I can get to an empty binding
-  def Object.new_binding() # :nodoc:
-    binding 
-  end
-
   #like Kernel#load, but allows macros (and forms) as well.
+  #
+  # +filename+:: the name of the file to load
+  # +wrap+:: whether to wrap the loaded file in an anonymous module
+  #
   def Macro.load(filename,wrap=false)
     [''].concat($:).each{|pre|
       pre+="/" unless %r{(\A|/)\Z}===pre
@@ -78,6 +86,12 @@ class Macro
   #beware: default for second argument is currently broken.
   #best practice is to pass an explicit binding (see
   #Kernel#binding) for now.
+  #
+  # +code+:: a string of code to evaluate
+  # +binding+:: the binding in which to evaluate the code
+  # +file+:: the name of the file this code came from
+  # +line+:: the line number this code came from
+  #
   def Macro.eval(code,binding=nil,file="(eval)",line=1)
   #binding should default to Binding.of_caller, but byellgch
     
@@ -86,6 +100,16 @@ class Macro
     tree.eval binding||::Object.new_binding,file,line
   end
 
+  # A helper for Macro.eval which returns a RedParse tree for the given
+  # code string.
+  #
+  # +code+:: a string of code to evaluate
+  # +binding+:: the binding in which to evaluate the code
+  # +file+:: the name of the file this code came from
+  # +line+:: the line number this code came from
+  # +lvars+:: a list of local variables (empty unless called
+  # recursively)
+  #
   def Macro.parse(code,file="(eval)",line=1,lvars=[])
     if Binding===file or Array===file
       lvars=file
@@ -100,6 +124,10 @@ class Macro
   UNCOPYABLE= #Symbol|Numeric|true|false|nil|
              Module|Proc|IO|Method|UnboundMethod|Thread|Continuation
 
+  # Return a quoted node for the given scalar
+  #
+  # +obj+:: any object or node
+  #
   def Macro.quote obj
     #result=
     case obj
@@ -108,6 +136,8 @@ class Macro
       when String: 
         obj=obj.gsub(/['\\]/){|ch| '\\'+ch }
         StringNode[obj,{:@open=>"'", :@close=>"'"}]
+
+      # TODO: The following is dead code and should be removed
       else 
         #result=:(::Macro::QuotedStore[^QuotedStore.size])
         result=CallNode[ConstantNode[nil,"Macro","QuotedStore"],"[]",
@@ -123,6 +153,7 @@ class Macro
     end
   end
 
+  # TODO: dead code (only used by the dead else block above).
   def Macro.copy obj,seen={}
     result=seen[obj.__id__] 
     return result if result
@@ -152,6 +183,26 @@ class Macro
     return result
   end
 
+  # Create a node to postpone the macro (or method) definition until it
+  # is actually executed.  For example, in the following code:
+  #
+  #   if foo
+  #     macro bar
+  #       ...
+  #     end
+  #   else
+  #     macro bar
+  #       ...
+  #     end
+  #   end
+  #
+  # without postponing macro definition, the latter macro would always
+  # override the former.
+  #
+  # +node+::    the RedParse node for the entire method or macro defintion
+  #             that is being postponed
+  # +session+:: the context in which this macro is being processed
+  #
   def Macro.postpone node,session
       filename=session[:filename]
       unless session[:@modpath_unsure]
@@ -186,6 +237,13 @@ class Macro
     #beware: default for binding is currently broken.
     #best practice is to pass an explicit binding (see
     #Kernel#binding) for now.
+    #
+    # +binding+:: the binding in which to evaluate the node
+    # +file+::    for purpose of evaluation, the name of the file this node
+    #             came from
+    # +line+::    for purpose of evaluation, the line number this node came
+    #             from
+    #
     def eval(binding=nil,file=nil,line=nil)
       #binding should default to Binding.of_caller, but.... that's expensive
 
@@ -204,6 +262,12 @@ class Macro
       ::Kernel.eval unparsed, binding||::Object.new_binding,file||'(eval)',line||1
     end
 
+    # A helper for Macro.load and Macro.eval.  The source code for the
+    # node is saved to a file so that it can be viewed in the debugger.
+    #
+    # +name+:: the name of the file being loaded
+    # +wrap+:: whether to wrap the loaded file in an anonymous module
+    #
     def load(name='',wrap=false)
       expanded_tree=self    #Macro.expand(deep_copy,::Macro::GLOBALS)
 
@@ -233,7 +297,13 @@ class Macro
       return true
     end
 
+    # Convert this node to an S-expression
+    #
+    # +session+:: the context in which this macro is being processed
+    #
     def to_sexp session
+      # TODO: this (and all other functions similarly named) is possibly
+      # dead code
       self.class.name+"["+
         map{|param| call_to_sexp param,session }.join(", ")+
         ", {"+instance_variables.map{|iv| 
@@ -464,7 +534,7 @@ class Macro
         if old_modpath
           session[:@modpath]=old_modpath
         else
-          session[:@modpath].pop unwind
+          unwind.times{ session[:@modpath].pop }
         end
         session[:@namespace_type]=old_namespace_type
         session[:@modpath_unsure]=old_unsure
@@ -507,6 +577,10 @@ class Macro
        return parses_like,false #halt further recursion: already done where necessary
      end
 
+     # Convert this node to an S-expression
+     #
+     # +session+:: the context in which this macro is being processed
+     #
      def to_sexp session
        nest=session[:form_nest_level]
        session[:form_nest_level]=nest ? nest+1 : 2
@@ -523,6 +597,10 @@ class Macro
    end
 
    class FormParameterNode<ValueNode
+     # Convert this node to an S-expression
+     #
+     # +session+:: the context in which this macro is being processed
+     #
      def to_sexp session
        nest=session[:form_nest_level]||1
        carets=0
@@ -563,6 +641,11 @@ class Macro
     alias ensure_ ensures
     alias ensure ensures
 
+    # Performs the reverse of a parse operation (turns the node into a
+    # string)
+    #
+    # +o+:: a list of options for unparse
+    #
     def unparse o
       result="macro "
       result+=receiver.unparse(o)+'.' if receiver
@@ -591,10 +674,10 @@ class Macro
       [
         -[KW('macro'), KW(beginsendsmatcher).~.*, KW('end'), KW(/^(do|\{)$/).~.la]>>MisparsedNode
       ]+super+[
-        -[Op('^@'), Value, LowerOp]>>FormParameterNode,
+        -[Op('^@'), Expr, LowerOp]>>FormParameterNode,
         -[Op(':@'), (ParenedNode&-{:size=>1})|(VarLikeNode&-{:ident=>"nil"})]>>FormNode,
         -['macro', CallSiteNode, KW(';'),
-           Value.-, RescueNode.*, ElseNode.-, EnsureNode.-,
+           Expr.-, RescueNode.*, ElseNode.-, EnsureNode.-,
           'end'
          ]>>MacroNode,
       ]
@@ -602,6 +685,12 @@ class Macro
     def wants_semi_context
       super|KW('macro')
     end
+
+    # A regex for all the keywords that can be terminated with the 'end'
+    # keyword
+    #
+    # We use the base class's list, and add the 'macro' keyword to it.
+    #
     def beginsendsmatcher
       return @bem||=/#{super}|^macro$/ 
     end
@@ -609,6 +698,9 @@ class Macro
     def initialize(*args)
       super
       @lexer.enable_macros! if @lexer.respond_to? :enable_macros!
+
+      # Add ^ to the list of operators that could be either unary or
+      # binary
       @unary_or_binary_op=/^([\^:]|#@unary_or_binary_op)$/o
     end
   end

data/test/test_expand.rb

@@ -16,6 +16,10 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 =end
 
+# TODO: add a test for a method definition inside of a method definition
+# to ensure that the inner method definition is properly postponed
+
+
 
 require 'test/unit'
 require "macro"

data/test/test_form.rb

@@ -21,7 +21,7 @@ require "macro"
 require 'test/unit'
 require 'rubygems'
 require 'rubylexer'
-require "test/code/testcases" #from rubylexer
+require "rubylexer/test/testcases" #from rubylexer
 require 'pp'
 
 
@@ -30,7 +30,7 @@ class FormTest< Test::Unit::TestCase
 
   EXAMPLES.each_with_index{|x,i|
     next if /__END__/===x
-    if / \^[^\s]/===x and x.size>1000
+    if / \^[^\s]/===x #and x.size>1000
       while x['^']
         warn "disabling tests of '#{x[/^.*\^.*$/]}'"
         x[/^.*\^.*$/]=''
@@ -65,7 +65,7 @@ class FormTest< Test::Unit::TestCase
 
       assert_equal as_tree, as_form
 
-      assert_equal as_form, as_form.deep_copy
+      assert_equal as_form, as_form.deep_copy if as_form
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rubymacros
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - Caleb Clausen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-10-25 00:00:00 +01:00
+date: 2009-04-30 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.8.1
+        version: 1.12.2
     version: 
 description: 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.)
 email: rubymacros-owner @at@ inforadical .dot. net
@@ -41,10 +41,12 @@ extensions: []
 extra_rdoc_files: 
 - Manifest.txt
 - README.txt
+- History.txt
 files: 
 - COPYING.LGPL
 - Manifest.txt
 - README.txt
+- History.txt
 - rubymacros.vpj
 - Rakefile
 - test/test_form.rb
@@ -63,6 +65,9 @@ files:
 - example/simple_wrap.rb
 - example/with.rb
 - example/with_wrap.rb
+- example/linenum.rb
+- example/linenum_user.rb
+- example/linenum_wrap.rb
 has_rdoc: true
 homepage: http://rubymacros.rubyforge.org/
 post_install_message: 
@@ -86,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: rubymacros
-rubygems_version: 1.3.0
+rubygems_version: 1.3.1
 signing_key: 
 specification_version: 2
 summary: Macros are programmed in ruby itself.