From 2ef9c50c6e405717d06362787c4549ca4f1c6485 Mon Sep 17 00:00:00 2001 From: drbrain Date: Mon, 20 Dec 2010 03:22:49 +0000 Subject: Import RDoc 3 git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30249 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/rdoc/options.rb | 459 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 368 insertions(+), 91 deletions(-) (limited to 'lib/rdoc/options.rb') diff --git a/lib/rdoc/options.rb b/lib/rdoc/options.rb index 90415f0aa4..810f7fac0a 100644 --- a/lib/rdoc/options.rb +++ b/lib/rdoc/options.rb @@ -8,9 +8,41 @@ require 'rdoc/ri/paths' class RDoc::Options ## - # Character-set + # The deprecated options. + + DEPRECATED = { + '--accessor' => 'support discontinued', + '--diagram' => 'support discontinued', + '--help-output' => 'support discontinued', + '--image-format' => 'was an option for --diagram', + '--inline-source' => 'source code is now always inlined', + '--merge' => 'ri now always merges class information', + '--one-file' => 'support discontinued', + '--op-name' => 'support discontinued', + '--opname' => 'support discontinued', + '--promiscuous' => 'files always only document their content', + '--ri-system' => 'Ruby installers use other techniques', + } - attr_reader :charset + ## + # Template option validator for OptionParser + + Template = nil + + ## + # Character-set for HTML output. #encoding is preferred over #charset + + attr_accessor :charset + + ## + # If true, RDoc will not write any files. + + attr_accessor :dry_run + + ## + # Encoding of output where. This is set via --encoding. + + attr_accessor :encoding if Object.const_defined? :Encoding ## # Files matching this pattern will be excluded @@ -22,10 +54,21 @@ class RDoc::Options attr_accessor :files + ## + # Create the output even if the output directory does not look + # like an rdoc output directory + + attr_accessor :force_output + ## # Scan newer sources than the flag file if true. - attr_reader :force_update + attr_accessor :force_update + + ## + # Formatter to mark up text with + + attr_accessor :formatter ## # Description of the output generator (set with the -fmt option) @@ -33,9 +76,21 @@ class RDoc::Options attr_accessor :generator ## - # Formatter to mark up text with + # Loaded generator options. Used to prevent --help from loading the same + # options multiple times. - attr_accessor :formatter + attr_accessor :generator_options + + ## + # Old rdoc behavior: hyperlink all words that match a method name, + # even if not preceded by '#' or '::' + + attr_accessor :hyperlink_all + + ## + # Include line numbers in the source code + + attr_accessor :line_numbers ## # Name of the file, class or module to display in the initial index page (if @@ -43,45 +98,55 @@ class RDoc::Options attr_accessor :main_page + ## + # If true, only report on undocumented files + + attr_accessor :coverage_report + ## # The name of the output directory attr_accessor :op_dir ## - # Is RDoc in pipe mode? + # The OptionParser for this instance - attr_accessor :pipe + attr_accessor :option_parser ## - # Array of directories to search for files to satisfy an :include: + # Is RDoc in pipe mode? - attr_reader :rdoc_include + attr_accessor :pipe ## - # Include private and protected methods in the output? + # Array of directories to search for files to satisfy an :include: - attr_accessor :show_all + attr_accessor :rdoc_include ## # Include the '#' at the front of hyperlinked instance method names - attr_reader :show_hash + attr_accessor :show_hash ## # The number of columns in a tab - attr_reader :tab_width + attr_accessor :tab_width ## # Template to be used when generating output - attr_reader :template + attr_accessor :template + + ## + # Directory the template lives in + + attr_accessor :template_dir ## # Documentation title - attr_reader :title + attr_accessor :title ## # Verbosity, zero means quiet @@ -91,29 +156,88 @@ class RDoc::Options ## # URL of web cvs frontend - attr_reader :webcvs + attr_accessor :webcvs + + ## + # Minimum visibility of a documented method. One of +:public+, + # +:protected+, +:private+. May be overridden on a per-method + # basis with the :doc: directive. + + attr_accessor :visibility def initialize # :nodoc: require 'rdoc/rdoc' - @op_dir = nil - @show_all = false - @main_page = nil + @dry_run = false @exclude = [] - @generators = RDoc::RDoc::GENERATORS - @generator = RDoc::Generator::Darkfish + @force_output = false + @force_update = true + @generator = nil @generator_name = nil + @generator_options = [] + @generators = RDoc::RDoc::GENERATORS + @hyperlink_all = false + @line_numbers = false + @main_page = nil + @coverage_report = false + @op_dir = nil + @pipe = false @rdoc_include = [] - @title = nil - @template = nil @show_hash = false + @stylesheet_url = nil @tab_width = 8 - @force_update = true + @template = nil + @template_dir = nil + @title = nil @verbosity = 1 - @pipe = false - + @visibility = :protected @webcvs = nil - @charset = 'utf-8' + if Object.const_defined? :Encoding then + @encoding = Encoding.default_external + @charset = @encoding.to_s + else + @charset = 'UTF-8' + end + end + + ## + # Check that the files on the command line exist + + def check_files + @files.delete_if do |file| + if File.exist? file then + if File.readable? file then + false + else + warn "file '#{file}' not readable" + + true + end + else + warn "file '#{file}' not found" + + true + end + end + end + + ## + # Ensure only one generator is loaded + + def check_generator + if @generator then + raise OptionParser::InvalidOption, + "generator already set to #{@generator_name}" + end + end + + ## + # Set the title, but only if not already set. Used to set the title + # from a source file, so that a title set from the command line + # will have the priority. + + def default_title=(string) + @title ||= string end ## @@ -122,7 +246,10 @@ class RDoc::Options def parse(argv) ignore_invalid = true + argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT'] + opts = OptionParser.new do |opt| + @option_parser = opt opt.program_name = File.basename $0 opt.version = RDoc::VERSION opt.release = nil @@ -139,6 +266,14 @@ Usage: #{opt.program_name} [options] [names...] How RDoc generates output depends on the output formatter being used, and on the options you give. + Options can be specified via the RDOCOPT environment variable, which + functions similar to the RUBYOPT environment variable for ruby. + + $ export RDOCOPT="--show-hash" + + will make rdoc show hashes in method links by default. Command-line options + always will override those in RDOCOPT. + - Darkfish creates frameless HTML output by Michael Granger. - ri creates ri data files @@ -156,14 +291,44 @@ Usage: #{opt.program_name} [options] [names...] opt.banner << " - #{parser}: #{regexp.join ', '}\n" end + opt.banner << "\n The following options are deprecated:\n\n" + + name_length = DEPRECATED.keys.sort_by { |k| k.length }.last.length + + DEPRECATED.sort_by { |k,| k }.each do |name, reason| + opt.banner << " %*1$2$s %3$s\n" % [-name_length, name, reason] + end + + opt.accept Template do |template| + template_dir = template_dir_for template + + unless template_dir then + warn "could not find template #{template}" + nil + else + [template, template_dir] + end + end + opt.separator nil - opt.separator "Parsing Options:" + opt.separator "Parsing options:" opt.separator nil + if Object.const_defined? :Encoding then + opt.on("--encoding=ENCODING", "-e", Encoding.list.map { |e| e.name }, + "Specifies the output encoding. All files", + "read will be converted to this encoding.", + "Preferred over --charset") do |value| + @encoding = Encoding.find value + @charset = @encoding.to_s # may not be valid value + end + + opt.separator nil + end + opt.on("--all", "-a", - "Include all methods (not just public) in", - "the output.") do |value| - @show_all = value + "Synonym for --visibility=private.") do |value| + @visibility = :private end opt.separator nil @@ -207,20 +372,41 @@ Usage: #{opt.program_name} [options] [names...] end opt.separator nil - opt.separator "Generator Options:" + + 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("--charset=CHARSET", "-c", - "Specifies the output HTML character-set.") do |value| - @charset = value + opt.on("--visibility=VISIBILITY", "-V", RDoc::VISIBILITIES, + "Minimum visibility to document a method.", + "One of 'public', 'protected' (the default)", + "or 'private'. Can be abbreviated.") do |value| + @visibility = value + end + + opt.separator nil + opt.separator "Common generator options:" + opt.separator nil + + opt.on("--force-output", "-O", + "Forces rdoc to write the output files,", + "even if the output directory exists", + "and does not seem to have been created", + "by rdoc.") do |value| + @force_output = value end opt.separator nil generator_text = @generators.keys.map { |name| " #{name}" }.sort - opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys, + opt.on("-f", "--fmt=FORMAT", "--format=FORMAT", @generators.keys, "Set the output formatter. One of:", *generator_text) do |value| + check_generator + @generator_name = value.downcase setup_generator end @@ -236,9 +422,11 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil - opt.on("--main=NAME", "-m", - "NAME will be the initial page displayed.") do |value| - @main_page = value + opt.on("--[no-]coverage-report", "--[no-]dcov", "-C", + "Prints a report on undocumented items.", + "Does not generate files.") do |value| + @coverage_report = value + @force_update = true if value end opt.separator nil @@ -250,6 +438,51 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil + opt.on("-d", + "Deprecated --diagram option.", + "Prevents firing debug mode", + "with legacy invocation.") do |value| + end + + opt.separator nil + opt.separator 'HTML generator options:' + opt.separator nil + + opt.on("--charset=CHARSET", "-c", + "Specifies the output HTML character-set.", + "Use --encoding instead of --charset if", + "available.") do |value| + @charset = value + end + + opt.separator nil + + opt.on("--hyperlink-all", "-A", + "Generate hyperlinks for all words that", + "correspond to known methods, even if they", + "do not start with '#' or '::' (legacy", + "behavior).") do |value| + @hyperlink_all = value + end + + opt.separator nil + + opt.on("--main=NAME", "-m", + "NAME will be the initial page displayed.") do |value| + @main_page = value + end + + opt.separator nil + + opt.on("--[no-]line-numbers", "-N", + "Include line numbers in the source code.", + "By default, only the number of the first", + "line is displayed, in a leading comment.") do |value| + @line_numbers = value + 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", @@ -260,17 +493,12 @@ Usage: #{opt.program_name} [options] [names...] opt.separator nil - 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("--template=NAME", "-T", + opt.on("--template=NAME", "-T", Template, "Set the template used when generating", - "output.") do |value| - @template = value + "output. The default depends on the", + "formatter used.") do |(template, template_dir)| + @template = template + @template_dir = template_dir end opt.separator nil @@ -292,11 +520,7 @@ Usage: #{opt.program_name} [options] [names...] end opt.separator nil - - opt.on("-d", "--diagram", "Prevents -d from tripping --debug") - - opt.separator nil - opt.separator "ri Generator Options:" + opt.separator "ri generator options:" opt.separator nil opt.on("--ri", "-r", @@ -305,6 +529,8 @@ Usage: #{opt.program_name} [options] [names...] "your home directory unless overridden by a", "subsequent --op parameter, so no special", "privileges are needed.") do |value| + check_generator + @generator_name = "ri" @op_dir ||= RDoc::RI::Paths::HOMEDIR setup_generator @@ -317,22 +543,30 @@ Usage: #{opt.program_name} [options] [names...] "are stored in a site-wide directory,", "making them accessible to others, so", "special privileges are needed.") do |value| + check_generator + @generator_name = "ri" @op_dir = RDoc::RI::Paths::SITEDIR setup_generator end opt.separator nil - opt.separator "Generic Options:" + opt.separator "Generic options:" opt.separator nil + opt.on("--[no-]dry-run", + "Don't write any files") do |value| + @dry_run = value + end + opt.on("-D", "--[no-]debug", "Displays lots on internal stuff.") do |value| $DEBUG_RDOC = value end opt.on("--[no-]ignore-invalid", - "Ignore invalid options and continue.") do |value| + "Ignore invalid options and continue", + "(default true).") do |value| ignore_invalid = value end @@ -342,38 +576,70 @@ Usage: #{opt.program_name} [options] [names...] end opt.on("--verbose", "-v", - "Display extra progress as we parse.") do |value| + "Display extra progress as RDoc parses") do |value| @verbosity = 2 end + opt.on("--help", + "Display this help") do + RDoc::RDoc::GENERATORS.each_key do |generator| + setup_generator generator + end + + puts opt.help + exit + end + opt.separator nil end - argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT'] - ignored = [] + setup_generator 'darkfish' if + argv.grep(/\A(-f|--fmt|--format|-r|-R|--ri|--ri-site)\b/).empty? + + deprecated = [] + invalid = [] begin opts.parse! argv rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e - if ignore_invalid then - ignored << e.args.join(' ') - retry + if DEPRECATED[e.args.first] then + deprecated << e.args.first + elsif %w[--format --ri -r --ri-site -R].include? e.args.first then + raise else - $stderr.puts opts - $stderr.puts - $stderr.puts e - exit 1 + invalid << e.args.join(' ') end + + retry + end + + unless @generator then + @generator = RDoc::Generator::Darkfish + @generator_name = 'darkfish' end if @pipe and not argv.empty? then @pipe = false - ignored << '-p (with files)' + invalid << '-p (with files)' end - unless ignored.empty? or quiet then - $stderr.puts "invalid options: #{ignored.join ', '}" - $stderr.puts '(invalid options are ignored)' + unless quiet then + deprecated.each do |opt| + $stderr.puts 'option ' << opt << ' is deprecated: ' << DEPRECATED[opt] + end + + unless invalid.empty? then + invalid = "invalid options: #{invalid.join ', '}" + + if ignore_invalid then + $stderr.puts invalid + $stderr.puts '(invalid options are ignored)' + else + $stderr.puts opts + $stderr.puts invalid + exit 1 + end + end end @op_dir ||= 'doc' @@ -392,15 +658,10 @@ Usage: #{opt.program_name} [options] [names...] # If no template was specified, use the default template for the output # formatter - @template ||= @generator_name - 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 + unless @template then + @template = @generator_name + @template_dir = template_dir_for @template + end end ## @@ -410,30 +671,46 @@ Usage: #{opt.program_name} [options] [names...] @verbosity.zero? end - def quiet=(bool) + ## + # Set quietness to +bool+ + + def quiet= bool @verbosity = bool ? 0 : 1 end - private - ## - # Set up an output generator for the format in @generator_name + # Set up an output generator for the named +generator_name+. + # + # If the found generator responds to :setup_options it will be called with + # the options instance. This allows generators to add custom options or set + # default options. - def setup_generator - @generator = @generators[@generator_name] + def setup_generator generator_name = @generator_name + @generator = @generators[generator_name] unless @generator then - raise OptionParser::InvalidArgument, "Invalid output formatter" + raise OptionParser::InvalidArgument, + "Invalid output formatter #{generator_name}" end + + return if @generator_options.include? @generator + + @generator_name = generator_name + @generator_options << @generator + + @generator.setup_options self if @generator.respond_to? :setup_options end ## - # Check that the files on the command line exist + # Finds the template dir for +template+ - def check_files - @files.each do |f| - stat = File.stat f rescue next - raise RDoc::Error, "file '#{f}' not readable" unless stat.readable? + def template_dir_for template + template_path = File.join 'rdoc', 'generator', 'template', template + + $LOAD_PATH.map do |path| + File.join File.expand_path(path), template_path + end.find do |dir| + File.directory? dir end end -- cgit v1.2.3