rdoc-f95 0.0.1

data/lib/rdoc-f95/options.rb

@@ -0,0 +1,745 @@
+# We handle the parsing of options, and subsequently as a singleton
+# object to be queried for option values
+
+require "rdoc-f95/ri/paths"
+require 'optparse'
+require "pathname"
+
+class RDocF95::Options
+
+  ##
+  # Should the output be placed into a single file
+
+  attr_reader :all_one_file
+
+  ##
+  # Character-set
+
+  attr_reader :charset
+
+  ##
+  # URL of stylesheet
+
+  attr_reader :css
+
+  ##
+  # Should diagrams be drawn
+
+  attr_reader :diagram
+
+  ##
+  # Files matching this pattern will be excluded
+
+  attr_accessor :exclude
+
+  ##
+  # Additional attr_... style method flags
+
+  attr_reader :extra_accessor_flags
+
+  ##
+  # Pattern for additional attr_... style methods
+
+  attr_accessor :extra_accessors
+
+  ##
+  # Should we draw fileboxes in diagrams
+
+  attr_reader :fileboxes
+
+  ##
+  # The list of files to be processed
+
+  attr_accessor :files
+
+  ##
+  # Scan newer sources than the flag file if true.
+
+  attr_reader :force_update
+
+  ##
+  # Description of the output generator (set with the <tt>-fmt</tt> option)
+
+  attr_accessor :generator
+
+  ##
+  # The case of names of classes or modules or methods are ignored
+  attr_reader :ignore_case
+
+  ##
+  # Formatter to mark up text with
+
+  attr_accessor :formatter
+  
+  ##
+  # image format for diagrams
+
+  attr_reader :image_format
+
+  ##
+  # Include line numbers in the source listings
+
+  attr_reader :include_line_numbers
+
+  ##
+  # Should source code be included inline, or displayed in a popup
+
+  attr_accessor :inline_source
+
+  ##
+  # 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
+
+  ##
+  # TeX formatted formula is converted to MathML
+  attr_reader :mathml
+
+  ##
+  # Merge into classes of the same name when generating ri
+
+  attr_reader :merge
+
+  ##
+  # The name of the output directory
+
+  attr_accessor :op_dir
+
+  ##
+  # The name to use for the output
+
+  attr_accessor :op_name
+
+  ##
+  # Are we promiscuous about showing module contents across multiple files
+
+  attr_reader :promiscuous
+
+  ##
+  # Array of directories to search for files to satisfy an :include:
+
+  attr_reader :rdoc_include
+
+  ##
+  # Include private and protected methods in the output
+
+  attr_accessor :show_all
+
+  ##
+  # Include the '#' at the front of hyperlinked instance method names
+
+  attr_reader :show_hash
+
+  ##
+  # The number of columns in a tab
+
+  attr_reader :tab_width
+
+  ##
+  # template to be used when generating output
+
+  attr_reader :template
+
+  ##
+  # Template class for file generation
+  #--
+  # HACK around dependencies in lib/rdoc-f95/generator/html.rb
+
+  attr_accessor :template_class # :nodoc:
+
+  ##
+  # Documentation title
+
+  attr_reader :title
+
+  ##
+  # Verbosity, zero means quiet
+
+  attr_accessor :verbosity
+
+  ##
+  # URL of web cvs frontend
+
+  attr_reader :webcvs
+
+  def initialize(generators = {}) # :nodoc:
+    @op_dir = "doc"
+    @op_name = nil
+    @show_all = false
+    @main_page = nil
+    @merge = false
+    @exclude = []
+    @generators = generators
+    @generator_name = 'html'
+    @generator = @generators[@generator_name]
+    @rdoc_include = []
+    @title = nil
+    @template = nil
+    @template_class = 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
+    @verbosity = 1
+
+    @mathml = false
+    @ignore_case = false
+
+    @css = nil
+    @webcvs = nil
+
+    @charset = 'utf-8'
+  end
+
+  ##
+  # Parse command line options.
+
+  def parse(argv)
+    accessors = []
+
+    opts = OptionParser.new do |opt|
+      opt.program_name = File.basename $0
+      opt.version = RDocF95::VERSION
+      opt.release = nil
+      opt.summary_indent = ' ' * 4
+      opt.banner = <<-EOF
+Usage: #{opt.program_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.
+
+  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).
+
+  - XHTML output is the same as HTML. 
+
+  - 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.
+      EOF
+
+#      opt.separator nil  # 1.8.2 doesn't work
+      opt.separator "Options:"
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--accessor=ACCESSORS", "-A", Array,
+             "A comma separated list of additional class",
+             "methods that should be treated like",
+             "'attr_reader' and friends.",
+             " ",
+             "Option may be repeated.",
+             " ",
+             "Each accessorname may have '=text'",
+             "appended, in which case that text appears",
+             "where the r/w/rw appears for normal.",
+             "accessors") do |value|
+        value.each do |accessor|
+          if accessor =~ /^(\w+)(=(.*))?$/
+            accessors << $1
+            @extra_accessor_flags[$1] = $3
+          end
+        end
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--all", "-a",
+             "Include all methods (not just public) in",
+             "the output.") do |value|
+        @show_all = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--charset=CHARSET", "-c",
+             "Specifies the output HTML character-set.") do |value|
+        @charset = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--debug", "-D",
+             "Displays lots on internal stuff.") do |value|
+        $DEBUG_RDOC = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--diagram", "-d",
+             "Generate diagrams showing modules and",
+             "classes. You need dot V1.8.6 or later to",
+             "use the --diagram option correctly. Dot is",
+             "available from http://graphviz.org") do |value|
+        check_diagram
+        @diagram = true
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--exclude=PATTERN", "-x", Regexp,
+             "Do not process files or directories",
+             "matching PATTERN.") do |value|
+        @exclude << value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--extension=NEW=OLD", "-E",
+             "Treat files ending with .new as if they",
+             "ended with .old. Using '-E cgi=rb' will",
+             "cause xxx.cgi to be parsed as a Ruby file.") do |value|
+        new, old = value.split(/=/, 2)
+
+        unless new and old then
+          raise OptionParser::InvalidArgument, "Invalid parameter to '-E'"
+        end
+
+        unless RDocF95::ParserFactory.alias_extension old, new then
+          raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E"
+        end
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--fileboxes", "-F",
+             "Classes are put in boxes which represents",
+             "files, where these classes reside. Classes",
+             "shared between more than one file are",
+             "shown with list of files that are sharing",
+             "them. Silently discarded if --diagram is",
+             "not given.") do |value|
+        @fileboxes = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--force-update", "-U",
+             "Forces rdoc to scan all sources even if",
+             "newer than the flag file.") do |value|
+        @force_update = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys,
+             "Set the output formatter.") do |value|
+        @generator_name = value.downcase
+        setup_generator
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      image_formats = %w[gif png jpg jpeg]
+      opt.on("--image-format=FORMAT", "-I", image_formats,
+             "Sets output image format for diagrams. Can",
+             "be #{image_formats.join ', '}. If this option",
+             "is omitted, png is used. Requires",
+             "diagrams.") do |value|
+        @image_format = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--include=DIRECTORIES", "-i", Array,
+             "set (or add to) the list of directories to",
+             "be searched when satisfying :include:",
+             "requests. Can be used more than once.") do |value|
+        @rdoc_include.concat value.map { |dir| dir.strip }
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--inline-source", "-S",
+             "Show method source code inline, rather than",
+             "via a popup link.") do |value|
+        @inline_source = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--line-numbers", "-N",
+             "Include line numbers in the source code.") do |value|
+        @include_line_numbers = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--main=NAME", "-m",
+             "NAME will be the initial page displayed.") do |value|
+        @main_page = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--merge", "-M",
+             "When creating ri output, merge previously",
+             "processed classes into previously",
+             "documented classes of the same name.") do |value|
+        @merge = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--one-file", "-1",
+             "Put all the output into a single file.") do |value|
+        @all_one_file = value
+        @inline_source = value if value
+        @template = 'one_page_html'
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--op=DIR", "-o",
+             "Set the output directory.") do |value|
+        if @css && ! (%r{^(https?:/)?/} =~ @css)
+          @css = relative_str(File.join(value, "."),
+                              relative_str(File.join(@op_dir.split("/").fill(".."), ".."), @css))
+        end
+        @op_dir = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--opname=NAME", "-n",
+             "Set the NAME of the output. Has no effect",
+             "for HTML.") do |value|
+        @op_name = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--promiscuous", "-p",
+             "When documenting a file that contains a",
+             "module or class also defined in other",
+             "files, show all stuff for that module or",
+             "class in each files page. By default, only",
+             "show stuff defined in that particular file.") do |value|
+        @promiscuous = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--quiet", "-q",
+             "Don't show progress as we parse.") do |value|
+        @verbosity = 0
+      end
+
+      opt.on("--verbose", "-v",
+             "Display extra progress as we parse.") do |value|
+        @verbosity = 2
+      end
+
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--ri", "-r",
+             "Generate output for use by `ri`. The files",
+             "are stored in the '.rdoc' directory under",
+             "your home directory unless overridden by a",
+             "subsequent --op parameter, so no special",
+             "privileges are needed.") do |value|
+        @generator_name = "ri"
+        @op_dir = RDocF95::RI::Paths::HOMEDIR
+        setup_generator
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--ri-site", "-R",
+             "Generate output for use by `ri`. The files",
+             "are stored in a site-wide directory,",
+             "making them accessible to others, so",
+             "special privileges are needed.") do |value|
+        @generator_name = "ri"
+        @op_dir = RDocF95::RI::Paths::SITEDIR
+        setup_generator
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--ri-system", "-Y",
+             "Generate output for use by `ri`. The files",
+             "are stored in a site-wide directory,",
+             "making them accessible to others, so",
+             "special privileges are needed.  This",
+             "option is intended to be used during Ruby",
+             "installation.") do |value|
+        @generator_name = "ri"
+        @op_dir = RDocF95::RI::Paths::SYSDIR
+        setup_generator
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--show-hash", "-H",
+             "A name of the form #name in a comment is a",
+             "possible hyperlink to an instance method",
+             "name. When displayed, the '#' is removed",
+             "unless this option is specified.") do |value|
+        @show_hash = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--style=URL", "-s",
+             "Specifies the URL of a separate stylesheet.") do |value|
+        if %r{^(https?:/)?/} =~ value
+          @css = value
+        else
+          @css = relative_str(File.join(@op_dir, "."), value)
+        end
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of tab characters.") do |value|
+        @tab_width = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--template=NAME", "-T",
+             "Set the template used when generating",
+             "output.") do |value|
+        @template = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--title=TITLE", "-t",
+             "Set TITLE as the title for HTML output.") do |value|
+        @title = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--webcvs=URL", "-W",
+             "Specify a URL for linking to a web frontend",
+             "to CVS. If the URL contains a '\%s', the",
+             "name of the current file will be",
+             "substituted; if the URL doesn't contain a",
+             "'\%s', the filename will be appended to it.") do |value|
+        @webcvs = value
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--mathml", "-l",
+             "TeX formatted formula is converted to MathML.", 
+             "You need mathml.rb V0.8 or later to use the --mathml", 
+             "option correctly. mathml.rb V0.8 is available from", 
+             "http://www.hinet.mydns.jp/files/math_ml-0.8.0.tar.gz") do |value|
+        check_mathml
+        @mathml = true
+        @generator_name = 'xhtml'
+        @template = @generator_name
+        setup_generator
+      end
+
+#      opt.separator nil  # 1.8.2 doesn't work
+
+      opt.on("--ignore-case", "-C",
+             "The case of names of classes or modules", 
+             "or methods are ignored.") do |value|
+        @ignore_case = true
+      end
+    end
+
+    argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
+
+    opts.parse! argv
+
+    @files = argv.dup
+
+    @rdoc_include << "." if @rdoc_include.empty?
+
+    if @exclude.empty? then
+      @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? then
+      re = '^(' + accessors.map { |a| Regexp.quote a }.join('|') + ')$'
+      @extra_accessors = Regexp.new re
+    end
+
+  rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
+    puts opts
+    puts
+    puts e
+    exit 1
+  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
+
+  ##
+  # Don't display progress as we process the files
+
+  def quiet
+    @verbosity.zero?
+  end
+
+  def quiet=(bool)
+    @verbosity = bool ? 0 : 1
+  end
+
+  private
+
+  ##
+  # Set up an output generator for the format in @generator_name
+
+  def setup_generator
+    @generator = @generators[@generator_name]
+
+    unless @generator then
+      raise OptionParser::InvalidArgument, "Invalid output formatter"
+    end
+
+    if @generator_name == "xml" then
+      @all_one_file = true
+      @inline_source = true
+    end
+  end
+
+  # Check that the right version of 'dot' is available.  Unfortunately this
+  # doesn't work correctly under Windows NT, so we'll bypass the test under
+  # Windows.
+
+  def check_diagram
+    return if RUBY_PLATFORM =~ /mswin|cygwin|mingw|bccwin/
+
+    ok = false
+    ver = nil
+
+    IO.popen "dot -V 2>&1" do |io|
+      ver = io.read
+      if ver =~ /dot.+version(?:\s+gviz)?\s+(\d+)\.(\d+)/ then
+        ok = ($1.to_i > 1) || ($1.to_i == 1 && $2.to_i >= 8)
+      end
+    end
+
+    unless ok then
+      if ver =~ /^dot.+version/ then
+        $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
+    end
+  end
+
+  ##
+  # Check that the right version of 'mathml.rb' is available.
+
+  def check_mathml
+    not_found = true
+    fpath = ""
+    $LOAD_PATH.each{ |lpath|
+      ["mathml.rb", "math_ml.rb"].each { |ml|
+        fpath = File.join(lpath, ml)
+        if File.exist?(fpath)
+          not_found = false
+          break
+        end
+      }
+      break unless not_found
+    }
+
+    if not_found
+      $stderr.puts <<-"EOT"
+You need the 'mathml.rb' to convert TeX to MathML.
+(see http://www.hinet.mydns.jp/~hiraku/hiki/, but only JAPANESE.
+ You can download 'mathml.rb' directly from 
+ http://www.hinet.mydns.jp/files/math_ml-0.8.0.tar.gz)
+
+EOT
+      exit
+    end
+
+    contents = File.open(fpath, "r") {|f| f.read}
+    num = 1
+    if !(contents =~ /^\s*module\s+MathML/) ||
+        !(contents =~ /^\s*module\s+LaTeX/) ||
+        !(contents =~ /^\s*class\s+Parser/) ||
+        !(contents =~ /^\s*def\s+parse/)
+      $stderr.puts <<-"EOT"
+You need the 'mathml.rb' V0.8 or later to use.
+(see http://www.hinet.mydns.jp/~hiraku/hiki/, but only JAPANESE.
+ You can download 'mathml.rb' directly from 
+ http://www.hinet.mydns.jp/files/math_ml-0.8.0.tar.gz)
+
+EOT
+
+      exit
+    end
+  end
+
+  ##
+  # Return relative path
+
+  def relative_str(from, target)
+    from_dir     = File.dirname(from)
+    target_dir   = File.dirname(target)
+    target_base  = File.basename(target)
+
+    from_ab_path   = Pathname.new(File.expand_path(from_dir))
+    target_ab_path = Pathname.new(File.expand_path(target_dir))
+
+    target_re_path = target_ab_path.relative_path_from(from_ab_path)
+
+    result = target_re_path.to_s + "/" + target_base
+
+    return result
+  end
+
+  ##
+  # Check that the files on the command line exist
+
+  def check_files
+    @files.each do |f|
+      stat = File.stat f
+      raise RDocF95::Error, "file '#{f}' not readable" unless stat.readable?
+    end
+  end
+
+end