Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Ruby > Rdoc Hooks !

Reply
Thread Tools

Rdoc Hooks !

 
 
Vincent Fourmond
Guest
Posts: n/a
 
      11-26-2006
--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)--

 
Reply With Quote
 
 
 
 
Eric Hodel
Guest
Posts: n/a
 
      11-28-2006
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 - http://www.velocityreviews.com/forums/(E-Mail Removed) - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com



 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Any hooks in rdoc ? Vincent Fourmond Ruby 4 11-15-2006 08:11 PM
rdoc: how to add readme.rdoc as index.html? Iwan van der Kleyn Ruby 1 04-26-2005 12:37 PM
[RDOC] Using a template causes rdoc not to document some classes Daniel Berger Ruby 1 11-02-2004 08:23 PM
rdoc bug (and rdoc bug tracker site is down) Brian Schröder Ruby 5 09-18-2004 02:08 PM
rdoc: how to generate rdoc & ri documentation of standard library? Andreas Schwarz Ruby 6 01-01-2004 03:09 AM



Advertisments