Rdoc Hooks !

[Vincent Fourmond]

--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)--

 

[Eric Hodel]

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.

Please post this to the rdoc tracker on rubyforge.

It will only get lost here.