diff options
Diffstat (limited to 'lib/rdoc/options.rb')
| -rw-r--r-- | lib/rdoc/options.rb | 422 |
1 files changed, 107 insertions, 315 deletions
diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb index 2b069f4265..e4616f2aed 100644 --- a/lib/rdoc/options.rb +++ b/lib/rdoc/options.rb @@ -1,15 +1,11 @@ -# We handle the parsing of options, and subsequently as a singleton -# object to be queried for option values - -require "rdoc/ri/paths" require 'optparse' -class RDoc::Options +require 'rdoc/ri/paths' - ## - # Should the output be placed into a single file +## +# RDoc::Options handles the parsing and storage of options - attr_reader :all_one_file +class RDoc::Options ## # Character-set @@ -17,36 +13,11 @@ class RDoc::Options 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 @@ -67,45 +38,20 @@ class RDoc::Options 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 ## - # 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 + # Is RDoc in pipe mode? - attr_reader :promiscuous + attr_accessor :pipe ## # Array of directories to search for files to satisfy an :include: @@ -113,7 +59,7 @@ class RDoc::Options attr_reader :rdoc_include ## - # Include private and protected methods in the output + # Include private and protected methods in the output? attr_accessor :show_all @@ -128,18 +74,11 @@ class RDoc::Options attr_reader :tab_width ## - # template to be used when generating output + # Template to be used when generating output attr_reader :template ## - # Template class for file generation - #-- - # HACK around dependencies in lib/rdoc/generator/html.rb - - attr_accessor :template_class # :nodoc: - - ## # Documentation title attr_reader :title @@ -154,34 +93,24 @@ class RDoc::Options attr_reader :webcvs - def initialize(generators = {}) # :nodoc: - @op_dir = "doc" - @op_name = nil + def initialize # :nodoc: + require 'rdoc/rdoc' + @op_dir = nil @show_all = false @main_page = nil - @merge = false @exclude = [] - @generators = generators - @generator_name = 'html' - @generator = @generators[@generator_name] + @generators = RDoc::RDoc::GENERATORS + @generator = RDoc::Generator::Darkfish + @generator_name = nil @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 + @force_update = true @verbosity = 1 + @pipe = false - @css = nil @webcvs = nil @charset = 'utf-8' @@ -191,7 +120,7 @@ class RDoc::Options # Parse command line options. def parse(argv) - accessors = [] + ignore_invalid = true opts = OptionParser.new do |opt| opt.program_name = File.basename $0 @@ -210,44 +139,26 @@ Usage: #{opt.program_name} [options] [names...] 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). + - Darkfish creates frameless HTML output by Michael Granger. + - ri creates ri data files - - 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. + RDoc understands the following file formats: - - .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 - opt.separator "Options:" - opt.separator nil + parsers = Hash.new { |h,parser| h[parser] = [] } - 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 + RDoc::Parser.parsers.each do |regexp, parser| + parsers[parser.name.sub('RDoc::Parser::', '')] << regexp.source + end + + parsers.sort.each do |parser, regexp| + opt.banner << " - #{parser}: #{regexp.join ', '}\n" end opt.separator nil + opt.separator "Parsing Options:" + opt.separator nil opt.on("--all", "-a", "Include all methods (not just public) in", @@ -257,31 +168,6 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil - opt.on("--charset=CHARSET", "-c", - "Specifies the output HTML character-set.") do |value| - @charset = value - end - - opt.separator nil - - opt.on("--debug", "-D", - "Displays lots on internal stuff.") do |value| - $DEBUG_RDOC = value - end - - opt.separator nil - - 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 - opt.on("--exclude=PATTERN", "-x", Regexp, "Do not process files or directories", "matching PATTERN.") do |value| @@ -300,25 +186,13 @@ Usage: #{opt.program_name} [options] [names...] raise OptionParser::InvalidArgument, "Invalid parameter to '-E'" end - unless RDoc::ParserFactory.alias_extension old, new then + unless RDoc::Parser.alias_extension old, new then raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E" end end opt.separator nil - 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 - opt.on("--force-update", "-U", "Forces rdoc to scan all sources even if", "newer than the flag file.") do |value| @@ -327,45 +201,37 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil - opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys, - "Set the output formatter.") do |value| - @generator_name = value.downcase - setup_generator + opt.on("--pipe", + "Convert RDoc on stdin to HTML") do + @pipe = true end opt.separator nil - - 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 "Generator Options:" opt.separator nil - 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 } + opt.on("--charset=CHARSET", "-c", + "Specifies the output HTML character-set.") do |value| + @charset = value end opt.separator nil - opt.on("--inline-source", "-S", - "Show method source code inline, rather than", - "via a popup link.") do |value| - @inline_source = value + generator_text = @generators.keys.map { |name| " #{name}" }.sort + + opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys, + "Set the output formatter. One of:", *generator_text) do |value| + @generator_name = value.downcase + setup_generator end opt.separator nil - opt.on("--line-numbers", "-N", - "Include line numbers in the source code.") do |value| - @include_line_numbers = value + 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 @@ -377,62 +243,61 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil - opt.on("--merge", "-M", - "When creating ri output, merge previously", - "processed classes into previously", - "documented classes of the same name.") do |value| - @merge = value + opt.on("--output=DIR", "--op", "-o", + "Set the output directory.") do |value| + @op_dir = value end opt.separator nil - 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' + 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 - opt.on("--op=DIR", "-o", - "Set the output directory.") do |value| - @op_dir = value + opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger, + "Set the width of tab characters.") do |value| + @tab_width = value end opt.separator nil - opt.on("--opname=NAME", "-n", - "Set the NAME of the output. Has no effect", - "for HTML.") do |value| - @op_name = value + opt.on("--template=NAME", "-T", + "Set the template used when generating", + "output.") do |value| + @template = value end opt.separator nil - 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 + opt.on("--title=TITLE", "-t", + "Set TITLE as the title for HTML output.") do |value| + @title = value end opt.separator nil - opt.on("--quiet", "-q", - "Don't show progress as we parse.") do |value| - @verbosity = 0 + 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.on("--verbose", "-v", - "Display extra progress as we parse.") do |value| - @verbosity = 2 - end + opt.separator nil + opt.on("-d", "--diagram", "Prevents -d from tripping --debug") opt.separator nil + opt.separator "ri Generator Options:" + opt.separator nil opt.on("--ri", "-r", "Generate output for use by `ri`. The files", @@ -441,7 +306,7 @@ Usage: #{opt.program_name} [options] [names...] "subsequent --op parameter, so no special", "privileges are needed.") do |value| @generator_name = "ri" - @op_dir = RDoc::RI::Paths::HOMEDIR + @op_dir ||= RDoc::RI::Paths::HOMEDIR setup_generator end @@ -458,74 +323,49 @@ Usage: #{opt.program_name} [options] [names...] end opt.separator nil - - 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 = RDoc::RI::Paths::SYSDIR - setup_generator - end - - opt.separator nil - - 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 "Generic Options:" opt.separator nil - opt.on("--style=URL", "-s", - "Specifies the URL of a separate stylesheet.") do |value| - @css = value + opt.on("-D", "--[no-]debug", + "Displays lots on internal stuff.") do |value| + $DEBUG_RDOC = value end - opt.separator nil - - opt.on("--tab-width=WIDTH", "-w", OptionParser::DecimalInteger, - "Set the width of tab characters.") do |value| - @tab_width = value + opt.on("--[no-]ignore-invalid", + "Ignore invalid options and continue.") do |value| + ignore_invalid = value end - opt.separator nil - - opt.on("--template=NAME", "-T", - "Set the template used when generating", - "output.") do |value| - @template = value + opt.on("--quiet", "-q", + "Don't show progress as we parse.") do |value| + @verbosity = 0 end - opt.separator nil - - opt.on("--title=TITLE", "-t", - "Set TITLE as the title for HTML output.") do |value| - @title = value + opt.on("--verbose", "-v", + "Display extra progress as we parse.") do |value| + @verbosity = 2 end opt.separator nil - - 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 end argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT'] - opts.parse! argv + begin + opts.parse! argv + rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e + if ignore_invalid and not quiet then + $stderr.puts e + $stderr.puts '(invalid options are ignored)' + else + $stderr.puts opts + $stderr.puts + $stderr.puts e + exit 1 + end + end + @op_dir ||= 'doc' @files = argv.dup @rdoc_include << "." if @rdoc_include.empty? @@ -542,18 +382,6 @@ Usage: #{opt.program_name} [options] [names...] # 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 ## @@ -586,42 +414,6 @@ Usage: #{opt.program_name} [options] [names...] 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 ## @@ -629,7 +421,7 @@ Usage: #{opt.program_name} [options] [names...] def check_files @files.each do |f| - stat = File.stat f + stat = File.stat f rescue next raise RDoc::Error, "file '#{f}' not readable" unless stat.readable? end end |