ruby-core

Hi,

attached is patch for rdoc to capture execution output of the file it
is given.  This is most useful for grabbing the help or usage
information from a script.

to run rdoc in a directory and capture the help information for only
files containing 'optparse'
and place that information below the beginning rdoc documentation,
with 'Usage' formatted as a header use the following:

rdoc -C arg=--help,header=Usage,pos=bottom,trigger="(require|load).*optparse"

Greg

Attachments (2)

options_capture_output.diff (2.99 KB, text/x-diff)

--- options.rb	2006-09-24 19:35:56.437500000 -0500
+++ options_capture_output.rb	2006-09-24 19:35:33.906250000 -0500
@@ -94,6 +94,9 @@
   # scan newer sources than the flag file if true.
   attr_reader :force_update
 
+  # -C --capture_output
+  attr_reader :capture_output
+
   module OptionList
 
     OPTION_LIST = [
@@ -110,6 +113,21 @@
       [ "--charset",       "-c",   "charset",
         "specifies HTML character-set" ],
 
+      [ "--capture-output", "-C",  "option1[,option2]",
+        "capture output from executing file to be documented\n"+
+        "available options (comma seperated):\n"+
+        "args=arg1[:arg2...]\n"+
+        "  colon seperated arguments given to file\n" +
+        "  'args=--help' captures help information\n" +
+        "pos=top|bottom|override (default = bottom)\n" +
+        "  placement of output in relation to current rdoc header\n" +
+        "trigger=pattern1[:pattern2...]\n" +
+        "  only capture output if pattern is detected\n" +
+        "  'trigger=optparse'\n" +
+        "header=header1[:header2...]\n" +
+        "  treat first instance of text as a header\n" +
+        "  'header=Usage' substitutes 'Usage' for '==Usage'"],
+
       [ "--debug",         "-D",   nil,
         "displays lots on internal stuff" ],
 
@@ -371,6 +389,7 @@
       @extra_accessor_flags = {}
       @promiscuous = false
       @force_update = false
+      @capture_output = nil
 
       @css = nil
       @webcvs = nil
@@ -418,6 +437,31 @@
             end
           end
 
+        when "--capture-output"
+          @capture_output = {}
+          arg.split(/,/).each do |ar|
+            if ar =~/(\w).*\=(.+)/
+              case $1
+                when 'a' then @capture_output[:args] = $2.split(/:/)
+                when 'p'
+                  @capture_output[:position] = case $2[0,1]
+                    when 'b' then :bottom
+                    when 't' then :top
+                    when 'o' then :override
+                    else     raise OptionList.error("Invalid Argument: #$2 in #{ar}")
+                  end
+                when 't'
+                  @capture_output[:trigger] = Regexp.new("(#{$2.split(/:/).join(')|(')})")
+                when 'h'
+                  @capture_output[:headers] = $2.split(/:/)
+                else
+                  raise OptionList.error("Invalid Argument: #$1 in #{ar}")
+              end
+            else
+              raise OptionList.error("Invalid Argument: #{a} in #{ar}")
+            end
+          end
+
         when "--diagram"
           check_diagram
           @diagram = true
@@ -425,7 +469,7 @@
         when "--fileboxes"
           @fileboxes = true if @diagram
 
-	when "--fmt"
+        when "--fmt"
           @generator_name = arg.downcase
           setup_generator(generators)
 
@@ -473,10 +517,10 @@
         when "--force-update"
           @force_update = true
 
-	when "--version"
-	  puts VERSION_STRING
-	  exit
-	end
+        when "--version"
+          puts VERSION_STRING
+          exit
+        end
 
       end

rdoc_capture_output.diff (2.97 KB, text/x-diff)

--- rdoc.rb	2006-09-24 16:09:08.812500000 -0500
+++ rdoc_mine.rb	2006-09-24 17:15:34.656250000 -0500
@@ -203,6 +203,64 @@
       normalized_file_list(options, Dir.glob(File.join(dir, "*")), false, options.exclude)
     end
 
+    # to run rdoc in a directory and capture the help infromation for only files containing 'optparse'
+    # and to place that information below the beginning rdoc documentation,
+    # with 'Usage' formatted as a header, use the following:
+    # rdoc -C arg=--help,header=Usage,pos=bot,trigger="(require|load).*optparse"
+    def capture_output(filename, content, options)
+
+      # determine the start and finish of the rdoc header documentation
+      # then we can place the help_doc before, after, or overriding it
+      rdoc_start, rdoc_finish = nil, nil
+      content = content.to_a
+      return nil unless content.each_with_index do |line, index|
+        next if index == 0 and line =~ /^#\!/
+
+        if rdoc_start.nil?
+          rdoc_start = index if line =~ /^#/ 
+
+        elsif rdoc_finish.nil?
+          if line =~ /^[^#]/
+            rdoc_finish = index
+            break true unless options[:trigger]
+          end
+
+        elsif line =~ options[:trigger]
+          break true
+        end
+      end
+
+      # hack to fix a bug that I don't know why it occurs:
+      # there is no special rdoc formatting applied if there are spaces between the '#' and the text.
+      # remove one white space character
+      content[rdoc_start...rdoc_finish] = content[rdoc_start...rdoc_finish].map{|line| line.sub(/^#\s/, '#') }
+
+      # command to capture output from file.  Do not chomp the output.
+      command = "ruby #{filename} #{ options[:args] ? options[:args].join(' ') : '' }"
+
+      # remove one space for previously mentioned bug
+      # find given headers and insert '==' to make them appear as headers
+      if options[:headers]
+        headers = options[:headers]
+
+        help_doc = %x{ #{command} }.map do |line|
+          headers.reject! do |header|
+            line = "==#$1" << ($` or '') << "\n"   if line =~ /\s*(#{header})/
+          end
+
+          line.sub(/^\s?/, '#')
+        end
+
+      else
+        help_doc = %x{ #{command} }.map{ |line| line.sub(/^\s?/, '#') }
+      end
+
+      case options[:position] # default is :bottom
+        when :top      then (content[0...rdoc_start] + help_doc + content[rdoc_start..-1]).to_s
+        when :override then (help_doc + content[rdoc_finish..-1]).to_s
+        else                (content[0...rdoc_finish] + help_doc + content[rdoc_finish..-1]).to_s
+      end
+    end
 
     # Parse each file on the command line, recursively entering
     # directories
@@ -221,6 +279,8 @@
         
         content = File.open(fn, "r") {|f| f.read}
 
+        content = capture_output(fn, content, options.capture_output) if options.capture_output
+
         top_level = TopLevel.new(fn)
         parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
         file_info << parser.scan

Thread

Prev Next

In This Thread

Prev Next