Asp Forum - Rdoc Hooks ! - comp.lang.ruby

Vincent Fourmond

11/26/2006 9:46:00 PM

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.fourmon...
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

3 Answers

Eric Hodel

11/28/2006 11:08:00 AM

On Nov 26, 2006, at 1346 , Vincent Fourmond wrote:

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

--
Eric Hodel - drbrain@segment7.net - http://blog.se...
This implementation is HODEL-HASH-9600 compliant

http://trackmap.rob...

suzeeq

1/5/2012 2:49:00 AM

Barry Margolin wrote:
> In article <je304l$csm$1@dont-email.me>, suzeeq <suzee@imbris.com>
> wrote:
>
>> Patty Winter wrote:
>>> I thought "The Finder" was going to replace "Bones" for a couple
>>> of months, but both The Futon Critic and Zap2It are showing a new
>>> episode of "Bones" next week, just before the premiere of "The Finder."
>>>
>>> But...I can't find out what's happening on Jan. 19 or 26. Those dates
>>> aren't available in Zap2It yet. TFC shows new eps of "The Finder" on
>>> those dates, but so far lists neither new eps or repeats of "Bones."
>>>
>>> Yes, I did look at Fox's website; it only mentions two hours of reruns
>>> of "Bones" this Thursday; no future information.
>>>
>>> I doubt that Fox would put on one new episode and then back out to
>>> repeats again, so I'm guessing that, indeed, "Bones" is returning
>>> next week after all.
>> Yeah, for some reason they were going to show this last episode before
>> the break to Finders back in November, but decided to hold it over until
>> January. This week is a repeat, next week is the new episode. And none
>> of the TV guides have information more than 2 weeks out, so you have to
>> wait until Friday to see what's happening week after next.
>
> Wasn't the original plan to rerun the episode that introduced the Finder
> as the lead-in to the Finder premiere?

Could be, and they did that one a couple weeks ago.

Michael Black

1/5/2012 4:45:00 AM

comp.lang.ruby

Rdoc Hooks !

Vincent Fourmond

Eric Hodel

suzeeq

Michael Black

x Login to ForumsZone