Rdoc Hooks !

Discussion in 'Ruby' started by Vincent Fourmond, Nov 26, 2006.

  1. --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 :mad: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)--
     
    Vincent Fourmond, Nov 26, 2006
    #1
    1. Advertising

  2. Vincent Fourmond

    Eric Hodel Guest

    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://blog.segment7.net
    This implementation is HODEL-HASH-9600 compliant

    http://trackmap.robotcoop.com
     
    Eric Hodel, Nov 28, 2006
    #2
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Andreas Schwarz
    Replies:
    6
    Views:
    254
    Randy W. Sims
    Jan 1, 2004
  2. Brian Schröder
    Replies:
    5
    Views:
    141
    Dave Thomas
    Sep 18, 2004
  3. Daniel Berger
    Replies:
    1
    Views:
    144
    Dave Thomas
    Nov 2, 2004
  4. Iwan van der Kleyn

    rdoc: how to add readme.rdoc as index.html?

    Iwan van der Kleyn, Apr 26, 2005, in forum: Ruby
    Replies:
    1
    Views:
    237
    Stefan Lang
    Apr 26, 2005
  5. Vincent Fourmond

    Any hooks in rdoc ?

    Vincent Fourmond, Nov 10, 2006, in forum: Ruby
    Replies:
    4
    Views:
    101
    Gregory Brown
    Nov 15, 2006
Loading...

Share This Page