From: Vincent Fourmond <vincent.fourmond@9online.fr>
Date: 2006-11-27T06:46:23+09:00
Subject: Rdoc Hooks !

--Boundary_(ID_M4Zc99jQ4xgeZeCvncFatQ)
Content-type: text/plain; charset=ISO-8859-1
Content-transfer-encoding: 7BIT


  Hello all !

  Not so long ago, I posted a question about hooks in rdoc. It appeared
that there are none, and that I was welcome to create some. So I did.
The attached patch (against 1.8.5) does the job for me.

  Here is the principle: the --hook option allows rdoc to require some
files. The files should contain statements of the like

RDoc::Hook.hook(/def_delegators/) do |name, args, comment, context, mod|
  return unless mod.document_self
  to = args.shift
  for a in args
    meth = RDoc::Alias.new("", a, "#{to}.#{a}", comment)
    context.add_alias(meth)
  end
end

  This code declares a hook for things like

# A nice comment
def_delegators :@some_stuff, :some_method, :some_other_method

  The block is called with

name = "def_delegators"
args = ["@some_stuff", "some_method", "some_other_method"]
comment = "# A nice comment"
context = ??? # An object representing the class/module currently processed
mod = ??? # We're interested basically only in the document_self attribute.

  This syntax should be pretty flexible for all meta-programming
purposes. I did my best to keep the modifications to the code as little
as possible, it really shouldn't break anything.

  It would be cool if some people could test this code. I would then
forward the patch to ruby-code.

  Thanks !

	Vince

-- 
Vincent Fourmond, PhD student
http://vincent.fourmond.neuf.fr/

--Boundary_(ID_M4Zc99jQ4xgeZeCvncFatQ)
Content-type: text/plain; name=rdoc-hooks.diff
Content-transfer-encoding: 7BIT
Content-disposition: inline; filename=rdoc-hooks.diff

diff -Naur /usr/lib/ruby/1.8/rdoc/hooks.rb rdoc/hooks.rb
--- /usr/lib/ruby/1.8/rdoc/hooks.rb	1970-01-01 01:00:00.000000000 +0100
+++ rdoc/hooks.rb	2006-11-26 21:16:54.000000000 +0100
@@ -0,0 +1,63 @@
+# hooks.rb, by Vincent Fourmond: implementation of hooks in rdoc parsing
+
+module RDoc
+
+  # This class is used to implement hooks for rdoc parsing.
+  # An instance of this class is a hook, the class itself can be
+  # used to represent all the hooks.
+  class Hook
+    
+    attr_reader :what, :code
+
+    def initialize(what, code)
+      @what = what
+      @code = code
+    end
+
+    # Returns true if this hook should handle the name given
+    def is_mine?(name)
+      return name =~ what
+    end
+
+    # Processes the current element found. If #is_mine? 'biniou', then
+    # when rdoc encouters the following code:
+    #
+    #  # A nice comment for the biniou
+    #  biniou :foo, "bar", "and some other stuff", Integer
+    #
+    # #process is called with:
+    # * _name_ = :foo
+    # * _args_ = ["bar", "and some other stuff", "Integer"]
+    # * _comment_ = "# A nice comment for the biniou\n"
+    # * _context_ : the current "parent element".
+    # * _modifiers_ : the modifiers. You'll be interested
+    #   mainly in the _document_self_ and
+    #   _force_documentation_ elements.
+    #
+    # #process forwards the call to the block code.
+    def process(name, args, comment, context, modifiers)
+      code.call(name, args, comment, context, modifiers)
+    end
+
+
+    # Now, class methods.
+    @@hooks = []
+
+    # Registers a hook. 
+    def self.hook(what, &code)
+      @@hooks << Hook.new(what, code)
+    end
+
+    # Returns the hook associated with the given name, or
+    # returns false.
+    def self.hook?(name)
+      for hook in @@hooks
+        if hook.is_mine?(name)
+          return hook
+        end
+      end
+      return false
+    end
+
+  end
+end
diff -Naur /usr/lib/ruby/1.8/rdoc/options.rb rdoc/options.rb
--- /usr/lib/ruby/1.8/rdoc/options.rb	2004-11-20 16:02:56.000000000 +0100
+++ rdoc/options.rb	2006-11-26 20:32:57.000000000 +0100
@@ -143,6 +143,12 @@
       [ "--help-output",   "-O",   nil,
         "explain the various output options" ],
 
+
+      [ "--hook",          "-G",   "file name",
+        "Requires the given file. It can be used to \n" +
+        "setup hooks for meta-programming practices"
+      ],
+
       [ "--image-format",  "-I",   "gif/png/jpg/jpeg",
         "Sets output image format for diagrams. Can\n" +
         "be png, gif, jpeg, jpg. If this option is\n" +
@@ -410,6 +416,10 @@
             end
           end
 
+        # Code for hooks
+        when "--hook"
+          require arg
+
         when "--diagram"
           check_diagram
           @diagram = true
diff -Naur /usr/lib/ruby/1.8/rdoc/parsers/parse_rb.rb rdoc/parsers/parse_rb.rb
--- /usr/lib/ruby/1.8/rdoc/parsers/parse_rb.rb	2006-10-30 09:06:59.000000000 +0100
+++ rdoc/parsers/parse_rb.rb	2006-11-26 22:16:40.000000000 +0100
@@ -22,6 +22,9 @@
 
 require "rdoc/parsers/parserfactory"
 
+# For rdoc hooks
+require 'rdoc/hooks'
+
 $TOKEN_DEBUG = $DEBUG
 
 # Definitions of all tokens involved in the lexical analysis
@@ -1693,6 +1696,21 @@
               if container.document_self
 	        parse_alias(container, single, tk, comment)
 	      end
+            else
+              # We check if a hook correspond to that item
+              if hook = Hook.hook?(tk.name)
+                # Now, we build up arguments for the hook
+                begin
+                  args = parse_symbol_arg
+                  tmp = CodeObject.new
+                  read_documentation_modifiers(tmp, ATTR_MODIFIERS)
+                  # Process the hook.
+                  hook.process(tk.name, args, comment, container, tmp)
+                rescue Exception
+                  puts "A problem was found with the hook for #{tk.name}"
+                  raise
+                end
+              end
             end
 	  end
 	  

--Boundary_(ID_M4Zc99jQ4xgeZeCvncFatQ)--