testdoc 0.0.2

data/lib/testdoc/testdocoptions.rb

@@ -0,0 +1,607 @@
+# We handle the parsing of options, and subsequently as a singleton
+# object to be queried for option values
+
+require "rdoc/ri/ri_paths"
+
+class Options
+
+  require 'singleton'
+  require 'getoptlong'
+
+  include Singleton
+
+  # files matching this pattern will be excluded
+  attr_accessor :exclude
+
+  # the name of the output directory
+  attr_accessor :op_dir
+
+  # the name to use for the output
+  attr_reader :op_name
+
+  # include private and protected methods in the
+  # output
+  attr_accessor :show_all
+
+  # name of the file, class or module to display in
+  # the initial index page (if not specified
+  # the first file we encounter is used)
+  attr_accessor :main_page
+
+  # merge into classes of the name name when generating ri
+  attr_reader :merge
+
+
+
+  # merge into classes of the name name when generating ri
+  attr_reader :text
+
+
+  # Don't display progress as we process the files
+  attr_reader :quiet
+
+  # description of the output generator (set with the <tt>-fmt</tt>
+  # option
+  attr_accessor :generator
+
+  # and the list of files to be processed
+  attr_reader :files
+
+  # array of directories to search for files to satisfy an :include:
+  attr_reader :rdoc_include
+
+  attr_reader :debug
+  attr_accessor :debug
+
+  # title to be used out the output
+  attr_writer :title
+
+  # template to be used when generating output
+  attr_reader :template
+
+  # should diagrams be drawn
+  attr_reader :diagram
+
+  # should we draw fileboxes in diagrams
+  attr_reader :fileboxes
+
+  # include the '#' at the front of hyperlinked instance method names
+  attr_reader :show_hash
+
+  # image format for diagrams
+  attr_reader :image_format
+
+  # character-set
+  attr_reader :charset
+
+  # should source code be included inline, or displayed in a popup
+  attr_reader :inline_source
+
+  # should the output be placed into a single file
+  attr_reader :all_one_file
+
+  # the number of columns in a tab
+  attr_reader :tab_width
+
+  # include line numbers in the source listings
+  attr_reader :include_line_numbers
+
+  # pattern for additional attr_... style methods
+  attr_reader :extra_accessors
+  attr_reader :extra_accessor_flags
+
+  # URL of stylesheet
+  attr_reader :css
+
+  # URL of web cvs frontend
+  attr_reader :webcvs
+
+  # Are we promiscuous about showing module contents across
+  # multiple files
+  attr_reader :promiscuous
+
+  # scan newer sources than the flag file if true.
+  attr_reader :force_update
+
+  module OptionList
+
+    OPTION_LIST = [
+#       [ "--accessor",      "-A",   "accessorname[,..]",
+#         "comma separated list of additional class methods\n" +
+#         "that should be treated like 'attr_reader' and\n" +
+#         "friends. Option may be repeated. Each accessorname\n" +
+#         "may have '=text' appended, in which case that text\n" +
+#         "appears where the r/w/rw appears for normal accessors."],
+
+#       [ "--all",           "-a",   nil,
+#         "include all methods (not just public)\nin the output" ],
+
+#       [ "--charset",       "-c",   "charset",
+#         "specifies HTML character-set" ],
+
+       [ "--debug",         "-D",   nil,
+         "displays testplan in compact format" ],
+
+#       [ "--diagram",       "-d",   nil,
+#         "Generate diagrams showing modules and classes.\n" +
+#         "You need dot V1.8.6 or later to use the --diagram\n" +
+#         "option correctly. Dot is available from\n"+
+#         "http://www.research.att.com/sw/tools/graphviz/" ],
+
+#       [ "--exclude",       "-x",   "pattern",
+#         "do not process files or directories matching\n" +
+#         "pattern. Files given explicitly on the command\n" +
+#         "line will never be excluded." ],
+
+#       [ "--extension",     "-E",   "new=old",
+#         "Treat files ending with .new as if they ended with\n" +
+#         ".old. Using '-E cgi=rb' will cause xxx.cgi to be\n" +
+#         "parsed as a Ruby file"],
+
+#       [ "--fileboxes",     "-F",   nil,
+#         "classes are put in boxes which represents\n" +
+#         "files, where these classes reside. Classes\n" +
+#         "shared between more than one file are\n" +
+#         "shown with list of files that sharing them.\n" +
+#         "Silently discarded if --diagram is not given\n" +
+#         "Experimental." ],
+
+#       [ "--force-update",  "-U",   nil,
+#         "forces to scan all sources even if newer than\n" +
+#         "the flag file." ],
+
+       [ "--fmt",           "-f",   "format name",
+         "set the output formatter (see below)" ],
+
+       [ "--help",          "-h",   nil,
+         "you're looking at it" ],
+
+#       [ "--help-output",   "-O",   nil,
+#         "explain the various output options" ],
+
+#       [ "--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" +
+#         "omitted, png is used. Requires --diagram." ],
+
+#       [ "--include",       "-i",   "dir[,dir...]",
+#         "set (or add to) the list of directories\n" +
+#         "to be searched when satisfying :include:\n" +
+#         "requests. Can be used more than once." ],
+
+#       [ "--inline-source", "-S",   nil,
+#         "Show method source code inline, rather\n" +
+#         "than via a popup link" ],
+
+#       [ "--line-numbers", "-N", nil,
+#         "Include line numbers in the source code" ],
+
+#       [ "--main",          "-m",   "name",
+#         "'name' will be the initial page displayed" ],
+
+       [ "--merge",         "-M",   nil,
+         "when creating ri output, merge processed classes\n" +
+         "into previously documented classes of the name name"],
+
+       [ "--text",         "-x",   nil,
+         "text output to stdout instead of html"],
+
+#       [ "--one-file",      "-1",   nil,
+#         "put all the output into a single file" ],
+
+#       [ "--op",            "-o",   "dir",
+#         "set the output directory" ],
+
+#       [ "--opname",       "-n",    "name",
+#         "Set the 'name' of the output. Has no\n" +
+#         "effect for HTML." ],
+
+#       [ "--promiscuous",   "-p",   nil,
+#         "When documenting a file that contains a module\n" +
+#         "or class also defined in other files, show\n" +
+#         "all stuff for that module/class in each files\n" +
+#         "page. By default, only show stuff defined in\n" +
+#         "that particular file." ],
+
+      [ "--quiet",         "-q",   nil,
+        "don't show progress as we parse" ],
+
+#       [ "--ri",            "-r",   nil,
+#        "generate output for use by 'ri.' The files are\n" +
+#        "stored in the '.rdoc' directory under your home\n"+
+#        "directory unless overridden by a subsequent\n" +
+#        "--op parameter, so no special privileges are needed." ],
+
+#       [ "--ri-site",       "-R",   nil,
+#        "generate output for use by 'ri.' The files are\n" +
+#        "stored in a site-wide directory, making them accessible\n"+
+#        "to others, so special privileges are needed." ],
+
+#       [ "--ri-system",     "-Y",   nil,
+#        "generate output for use by 'ri.' The files are\n" +
+#        "stored in a system-level directory, making them accessible\n"+
+#        "to others, so special privileges are needed. This option\n"+
+#        "is intended to be used during Ruby installations" ],
+
+#       [ "--show-hash",     "-H",   nil,
+#         "A name of the form #name in a comment\n" +
+#         "is a possible hyperlink to an instance\n" +
+#         "method name. When displayed, the '#' is\n" +
+#         "removed unless this option is specified" ],
+
+#       [ "--style",         "-s",   "stylesheet url",
+#         "specifies the URL of a separate stylesheet." ],
+
+#       [ "--tab-width",     "-w",   "n",
+#         "Set the width of tab characters (default 8)"],
+
+#       [ "--template",      "-T",   "template name",
+#         "Set the template used when generating output" ],
+
+       [ "--title",         "-t",   "text",
+         "Set 'txt' as the title for the output" ],
+
+      [ "--version",       "-v",   nil,
+        "display TestDoc's version" ]
+
+#       [ "--webcvs",        "-W",   "url",
+#         "Specify a URL for linking to a web frontend\n" +
+#         "to CVS. If the URL contains a '\%s', the\n" +
+#         "name of the current file will be substituted;\n" +
+#         "if the URL doesn't contain a '\%s', the\n" +
+#        "filename will be appended to it." ],
+
+    ]
+
+    def OptionList.options
+      OPTION_LIST.map do |long, short, arg,|
+        [ long,
+          short,
+          arg ? GetoptLong::REQUIRED_ARGUMENT : GetoptLong::NO_ARGUMENT
+        ]
+      end
+    end
+
+
+    def OptionList.strip_output(text)
+      text =~ /^\s+/
+      leading_spaces = $&
+      text.gsub!(/^#{leading_spaces}/, '')
+      $stdout.puts text
+    end
+
+
+    # Show an error and exit
+
+    def OptionList.error(msg)
+      $stderr.puts
+      $stderr.puts msg
+      $stderr.puts "\nFor help on options, try 'testdoc --help'\n\n"
+      exit 1
+    end
+
+    # Show usage and exit
+
+    def OptionList.usage(generator_names)
+
+      puts
+      puts(VERSION_STRING)
+      puts
+
+      name = File.basename($0)
+      OptionList.strip_output(<<-EOT)
+          Usage:
+
+            #{name} [options]  [names...]
+
+          Generates test documentation from sourcecode comments.
+          These directives are extracted from the sourcecode:
+
+             # testplan: Title for testplan (Optional)
+             # test: What to test
+             # task: How to perform the test manually
+             # check: How to perform the check (Optional)
+
+          Directives can be multiline and have to be in the
+          correct order as shown above. If a name is a directory,
+          it is traversed. If no names are specified, all
+          Ruby files in the current directory (and subdirectories) are
+          processed.
+
+          Options:
+
+      EOT
+
+      OPTION_LIST.each do |long, short, arg, desc|
+        opt = sprintf("%20s", "#{long}, #{short}")
+        oparg = sprintf("%-7s", arg)
+        print "#{opt} #{oparg}"
+        desc = desc.split("\n")
+        if arg.nil? || arg.length < 7
+          puts desc.shift
+        else
+          puts
+        end
+        desc.each do |line|
+          puts(" "*28 + line)
+        end
+        puts
+      end
+
+#      puts "\nAvailable output formatters: " +
+#        generator_names.sort.join(', ') + "\n\n"
+
+#      puts "For information on where the output goes, use\n\n"
+#      puts "   rdoc --help-output\n\n"
+
+      exit 0
+    end
+
+    def OptionList.help_output
+      OptionList.strip_output(<<-EOT)
+      How RDoc generates output depends on the output formatter being
+      used, and on the options you give.
+
+      - HTML output is normally produced into a number of separate files
+        (one per class, module, and file, along with various indices).
+        These files will appear in the directory given by the --op
+        option (doc/ by default).
+
+      - XML output by default is written to standard output. If a
+        --opname option is given, the output will instead be written
+        to a file with that name in the output directory.
+
+      - .chm files (Windows help files) are written in the --op directory.
+        If an --opname parameter is present, that name is used, otherwise
+        the file will be called rdoc.chm.
+
+      For information on other RDoc options, use "rdoc --help".
+      EOT
+      exit 0
+    end
+  end
+
+  # Parse command line options. We're passed a hash containing
+  # output generators, keyed by the generator name
+
+  def parse(argv, generators)
+    old_argv = ARGV.dup
+    begin
+      ARGV.replace(argv)
+      @op_dir = "doc"
+      @op_name = nil
+      @show_all = false
+      @main_page = nil
+      @marge     = false
+      @exclude   = []
+      @quiet = false
+      @generator_name = 'html'
+      @generator = generators[@generator_name]
+      @rdoc_include = []
+      @title = nil
+      @template = nil
+      @diagram = false
+      @fileboxes = false
+      @show_hash = false
+      @image_format = 'png'
+      @inline_source = false
+      @all_one_file  = false
+      @tab_width = 8
+      @include_line_numbers = false
+      @extra_accessor_flags = {}
+      @promiscuous = false
+      @force_update = false
+
+      @css = nil
+      @webcvs = nil
+
+      @charset = case $KCODE
+                 when /^S/i
+                   'Shift_JIS'
+                 when /^E/i
+                   'EUC-JP'
+                 else
+                   'iso-8859-1'
+                 end
+
+      accessors = []
+
+      go = GetoptLong.new(*OptionList.options)
+      go.quiet = true
+
+      go.each do |opt, arg|
+        case opt
+#        when "--all"           then @show_all      = true
+#        when "--charset"       then @charset       = arg
+        when "--debug"         then $DEBUG         = true
+#        when "--exclude"       then @exclude       << Regexp.new(arg)
+#        when "--inline-source" then @inline_source = true
+#        when "--line-numbers"  then @include_line_numbers = true
+#        when "--main"          then @main_page     = arg
+        when "--merge"         then @merge         = true
+        when "--text"          then @text         = true
+#        when "--one-file"      then @all_one_file  = @inline_source = true
+#        when "--op"            then @op_dir        = arg
+#        when "--opname"        then @op_name       = arg
+#        when "--promiscuous"   then @promiscuous   = true
+        when "--quiet"         then @quiet         = true
+        when "--show-hash"     then @show_hash     = true
+        when "--style"         then @css           = arg
+        when "--template"      then @template      = arg
+        when "--title"         then @title         = arg
+        when "--webcvs"        then @webcvs        = arg
+
+        when "--accessor"
+          arg.split(/,/).each do |accessor|
+            if accessor =~ /^(\w+)(=(.*))?$/
+              accessors << $1
+              @extra_accessor_flags[$1] = $3
+            end
+          end
+
+        when "--diagram"
+          check_diagram
+          @diagram = true
+
+        when "--fileboxes"
+          @fileboxes = true if @diagram
+
+        when "--fmt"
+          @generator_name = arg.downcase
+          setup_generator(generators)
+
+        when "--help"
+          OptionList.usage(generators.keys)
+
+        when "--help-output"
+          OptionList.help_output
+
+        when "--image-format"
+          if ['gif', 'png', 'jpeg', 'jpg'].include?(arg)
+            @image_format = arg
+          else
+            raise GetoptLong::InvalidOption.new("unknown image format: #{arg}")
+          end
+
+        when "--include"
+          @rdoc_include.concat arg.split(/\s*,\s*/)
+
+        when "--ri", "--ri-site", "--ri-system"
+          @generator_name = "ri"
+          @op_dir = case opt
+                    when "--ri" then RI::Paths::HOMEDIR
+                    when "--ri-site" then RI::Paths::SITEDIR
+                    when "--ri-system" then RI::Paths::SYSDIR
+                    else fail opt
+                    end
+          setup_generator(generators)
+
+        when "--tab-width"
+          begin
+            @tab_width     = Integer(arg)
+          rescue
+            $stderr.puts "Invalid tab width: '#{arg}'"
+            exit 1
+          end
+
+        when "--extension"
+          new, old = arg.split(/=/, 2)
+          OptionList.error("Invalid parameter to '-E'") unless new && old
+          unless RDoc::ParserFactory.alias_extension(old, new)
+            OptionList.error("Unknown extension .#{old} to -E")
+          end
+
+        when "--force-update"
+          @force_update = true
+
+        when "--version"
+          puts VERSION_STRING
+          exit
+        end
+
+      end
+
+      @files = ARGV.dup
+
+      @rdoc_include << "." if @rdoc_include.empty?
+
+      if @exclude.empty?
+        @exclude = nil
+      else
+        @exclude = Regexp.new(@exclude.join("|"))
+      end
+
+      check_files
+
+      # If no template was specified, use the default
+      # template for the output formatter
+
+      @template ||= @generator_name
+
+      # Generate a regexp from the accessors
+      unless accessors.empty?
+        re = '^(' + accessors.map{|a| Regexp.quote(a)}.join('|') + ')$'
+        @extra_accessors = Regexp.new(re)
+      end
+
+    rescue GetoptLong::InvalidOption, GetoptLong::MissingArgument => error
+      OptionList.error(error.message)
+
+    ensure
+      ARGV.replace(old_argv)
+    end
+  end
+
+
+  def title
+    @title ||= "TestDoc"
+  end
+
+  # Set the title, but only if not already set. This means that a title set from
+  # the command line trumps one set in a source file
+
+  def title=(string)
+    @title ||= string
+  end
+
+
+  private
+
+  # Set up an output generator for the format in @generator_name
+  def setup_generator(generators)
+#     @generator = generators[@generator_name]
+#     if !@generator
+#       OptionList.error("Invalid output formatter")
+#     end
+
+    if @generator_name == "xml"
+      @all_one_file = true
+      @inline_source = true
+    end
+  end
+
+  # Check that the right version of 'dot' is available.
+  # Unfortuately this doesn't work correctly under Windows NT,
+  # so we'll bypass the test under Windows
+
+  def check_diagram
+    return if RUBY_PLATFORM =~ /win/
+
+    ok = false
+    ver = nil
+    IO.popen("dot -V 2>&1") do |io|
+      ver = io.read
+      if ver =~ /dot.+version(?:\s+gviz)?\s+(\d+)\.(\d+)/
+        ok = ($1.to_i > 1) || ($1.to_i == 1 && $2.to_i >= 8)
+      end
+    end
+    unless ok
+      if ver =~ /^dot.+version/
+        $stderr.puts "Warning: You may need dot V1.8.6 or later to use\n",
+          "the --diagram option correctly. You have:\n\n   ",
+          ver,
+          "\nDiagrams might have strange background colors.\n\n"
+      else
+        $stderr.puts "You need the 'dot' program to produce diagrams.",
+          "(see http://www.research.att.com/sw/tools/graphviz/)\n\n"
+        exit
+      end
+#      exit
+    end
+  end
+
+  # Check that the files on the command line exist
+
+  def check_files
+    @files.each do |f|
+      stat = File.stat f rescue error("File not found: #{f}")
+      error("File '#{f}' not readable") unless stat.readable?
+    end
+  end
+
+  def error(str)
+    $stderr.puts str
+    exit(1)
+  end
+
+end