ruby/lib/rdoc/options.rb

# 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

  # 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

  # 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

  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 lots on internal stuff" ],

      [ "--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." ],

      [ "--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"],

      [ "--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  RDoc'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 'rdoc --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...]

          Files are parsed, and the information they contain
          collected, before any output is produced. This allows cross
          references between all files to be resolved. 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

      @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 "--one-file"      then @all_one_file  = 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 "--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 ||= "RDoc Documentation"
  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\s+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