ruby-core

The simplest command line would be
rdoc <file> -C arg=--help

file foo:
# ==Synopsis
# this is file foo
puts "This is the help message" if ARGV[0] == '--help'


Now your rdoc html file will display this from the browser:

Synopsis

this is foo

This is the help message



So this is not dependent on optparse at all.  I was giving the most
complex command to show all the options I built in, but there are
actually no required command.

It would be quite easy (and I would be willing) to add the option to
capture output from a different file, but is seems that you wouldn't
like to add another command line sub-option :)

I am not very familiar with gems and rake.
If there are other good solutions to achieve this functionality please
let me know of them.

Also, attached is newly updated rdoc.rb patch.

Greg Weber

Attachments (1)

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

--- /desktop/rdoc.rb	2006-09-26 21:51:35.609375000 -0500
+++ ./rdoc.rb	2006-09-27 07:37:11.437500000 -0500
@@ -203,6 +203,71 @@
       normalized_file_list(options, Dir.glob(File.join(dir, "*")), false, options.exclude)
     end
 
+    # --capture-output option: capture resulting output from script execution
+    # to run rdoc in a directory and capture the help infromation for only files containing 'optparse'
+    # and place that infromation below the current rdoc 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 content.to_s unless content.each_with_index do |line, index|
+        next if index == 0 and line =~ /^#\!/
+
+        if rdoc_start.nil?
+          break true unless line =~ /(^#)|(^\s*$)/
+          rdoc_start = index if $1
+
+        elsif rdoc_finish.nil?
+          if line =~ /^[^#]/
+            rdoc_finish = index
+            break true unless options[:trigger]
+          end
+
+        elsif line =~ options[:trigger]
+          break true
+        end
+      end
+
+      # in this case there is no rdoc header
+      if rdoc_start.nil? 
+        rdoc_start = rdoc_finish = 0
+      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
+      help_doc.unshift("#\n")
+
+      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 +286,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