Class: RDoc::Options

Inherits:

Object

Object
RDoc::Options

show all

Defined in:

lib/rdoc/options.rb

Overview

RDoc::Options handles the parsing and storage of options

Constant Summary

DEPRECATED = The deprecated options.

{
  '--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',
}

Template = Template option validator for OptionParser

nil

Instance Attribute Summary (collapse)

- (Object) charset

Character-set for HTML output.
- (Object) coverage_report

If true, only report on undocumented files.
- (Object) dry_run

If true, RDoc will not write any files.
- (Object) encoding

Returns the value of attribute encoding.
- (Object) exclude

Files matching this pattern will be excluded.
- (Object) files

The list of files to be processed.
- (Object) force_output

Create the output even if the output directory does not look like an rdoc output directory.
- (Object) force_update

Scan newer sources than the flag file if true.
- (Object) formatter

Formatter to mark up text with.
- (Object) generator

Description of the output generator (set with the --fmt option).
- (Object) generator_options

Loaded generator options.
- (Object) hyperlink_all

Old rdoc behavior: hyperlink all words that match a method name, even if not preceded by '#' or '::'.
- (Object) line_numbers

Include line numbers in the source code.
- (Object) main_page

Name of the file, class or module to display in the initial index page (if not specified the first file we encounter is used).
- (Object) op_dir

The name of the output directory.
- (Object) option_parser

The OptionParser for this instance.
- (Object) pipe

Is RDoc in pipe mode?.
- (Object) rdoc_include

Array of directories to search for files to satisfy an :include:.
- (Object) show_hash

Include the '#' at the front of hyperlinked instance method names.
- (Object) tab_width

The number of columns in a tab.
- (Object) template

Template to be used when generating output.
- (Object) template_dir

Directory the template lives in.
- (Object) title

Documentation title.
- (Object) update_output_dir

Should RDoc update the timestamps in the output dir?.
- (Object) verbosity

Verbosity, zero means quiet.
- (Object) visibility

Minimum visibility of a documented method.
- (Object) webcvs

URL of web cvs frontend.

Instance Method Summary (collapse)

- (Object) check_files

Check that the files on the command line exist.
- (Object) check_generator

Ensure only one generator is loaded.
- (Object) default_title=(string)

Set the title, but only if not already set.
- (Object) finish

Completes any unfinished option setup business such as filtering for existent files, creating a regexp for #exclude and setting a default #template.
- (Object) generator_descriptions

Returns a properly-space list of generators and their descriptions.
- (Options) initialize constructor

:nodoc:.
- (Object) parse(argv)

Parses command line options.
- (Object) quiet

Don't display progress as we process the files.
- (Object) quiet=(bool)

Set quietness to bool.
- (Object) setup_generator(generator_name = @generator_name)

Set up an output generator for the named generator_name.
- (Object) template_dir_for(template)

Finds the template dir for template.

Constructor Details

- (`Options`) initialize

:nodoc:

# File 'lib/rdoc/options.rb', line 173

def initialize # :nodoc:
  require 'rdoc/rdoc'
  @dry_run = false
  @exclude = []
  @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 = []
  @show_hash = false
  @stylesheet_url = nil
  @tab_width = 8
  @template = nil
  @template_dir = nil
  @title = nil
  @update_output_dir = true
  @verbosity = 1
  @visibility = :protected
  @webcvs = nil

  if Object.const_defined? :Encoding then
    @encoding = Encoding.default_external
    @charset = @encoding.to_s
  else
    @charset = 'UTF-8'
  end
end

Instance Attribute Details

- (`Object`) charset

Character-set for HTML output. #encoding is preferred over #charset



35
36
37

# File 'lib/rdoc/options.rb', line 35

def charset
  @charset
end

- (`Object`) coverage_report

If true, only report on undocumented files



104
105
106

# File 'lib/rdoc/options.rb', line 104

def coverage_report
  @coverage_report
end

- (`Object`) dry_run

If true, RDoc will not write any files.



40
41
42

# File 'lib/rdoc/options.rb', line 40

def dry_run
  @dry_run
end

- (`Object`) encoding

Returns the value of attribute encoding



45
46
47

# File 'lib/rdoc/options.rb', line 45

def encoding
  @encoding
end

- (`Object`) exclude

Files matching this pattern will be excluded



50
51
52

# File 'lib/rdoc/options.rb', line 50

def exclude
  @exclude
end

- (`Object`) files

The list of files to be processed



55
56
57

# File 'lib/rdoc/options.rb', line 55

def files
  @files
end

- (`Object`) force_output

Create the output even if the output directory does not look like an rdoc output directory



61
62
63

# File 'lib/rdoc/options.rb', line 61

def force_output
  @force_output
end

- (`Object`) force_update

Scan newer sources than the flag file if true.



66
67
68

# File 'lib/rdoc/options.rb', line 66

def force_update
  @force_update
end

- (`Object`) formatter

Formatter to mark up text with



71
72
73

# File 'lib/rdoc/options.rb', line 71

def formatter
  @formatter
end

- (`Object`) generator

Description of the output generator (set with the --fmt option)



76
77
78

# File 'lib/rdoc/options.rb', line 76

def generator
  @generator
end

- (`Object`) generator_options

Loaded generator options. Used to prevent --help from loading the same options multiple times.



82
83
84

# File 'lib/rdoc/options.rb', line 82

def generator_options
  @generator_options
end

- (`Object`) hyperlink_all

Old rdoc behavior: hyperlink all words that match a method name, even if not preceded by '#' or '::'



88
89
90

# File 'lib/rdoc/options.rb', line 88

def hyperlink_all
  @hyperlink_all
end

- (`Object`) line_numbers

Include line numbers in the source code



93
94
95

# File 'lib/rdoc/options.rb', line 93

def line_numbers
  @line_numbers
end

- (`Object`) main_page

Name of the file, class or module to display in the initial index page (if not specified the first file we encounter is used)



99
100
101

# File 'lib/rdoc/options.rb', line 99

def main_page
  @main_page
end

- (`Object`) op_dir

The name of the output directory



109
110
111

# File 'lib/rdoc/options.rb', line 109

def op_dir
  @op_dir
end

- (`Object`) option_parser

The OptionParser for this instance



114
115
116

# File 'lib/rdoc/options.rb', line 114

def option_parser
  @option_parser
end

- (`Object`) pipe

Is RDoc in pipe mode?



119
120
121

# File 'lib/rdoc/options.rb', line 119

def pipe
  @pipe
end

- (`Object`) rdoc_include

Array of directories to search for files to satisfy an :include:



124
125
126

# File 'lib/rdoc/options.rb', line 124

def rdoc_include
  @rdoc_include
end

- (`Object`) show_hash

Include the '#' at the front of hyperlinked instance method names



129
130
131

# File 'lib/rdoc/options.rb', line 129

def show_hash
  @show_hash
end

- (`Object`) tab_width

The number of columns in a tab



134
135
136

# File 'lib/rdoc/options.rb', line 134

def tab_width
  @tab_width
end

- (`Object`) template

Template to be used when generating output



139
140
141

# File 'lib/rdoc/options.rb', line 139

def template
  @template
end

- (`Object`) template_dir

Directory the template lives in



144
145
146

# File 'lib/rdoc/options.rb', line 144

def template_dir
  @template_dir
end

- (`Object`) title

Documentation title



149
150
151

# File 'lib/rdoc/options.rb', line 149

def title
  @title
end

- (`Object`) update_output_dir

Should RDoc update the timestamps in the output dir?



154
155
156

# File 'lib/rdoc/options.rb', line 154

def update_output_dir
  @update_output_dir
end

- (`Object`) verbosity

Verbosity, zero means quiet



159
160
161

# File 'lib/rdoc/options.rb', line 159

def verbosity
  @verbosity
end

- (`Object`) visibility

Minimum visibility of a documented method. One of :public, :protected, :private. May be overridden on a per-method basis with the :doc: directive.



171
172
173

# File 'lib/rdoc/options.rb', line 171

def visibility
  @visibility
end

- (`Object`) webcvs

URL of web cvs frontend



164
165
166

# File 'lib/rdoc/options.rb', line 164

def webcvs
  @webcvs
end

Instance Method Details

- (`Object`) check_files

Check that the files on the command line exist

# File 'lib/rdoc/options.rb', line 212

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

- (`Object`) check_generator

Ensure only one generator is loaded

# File 'lib/rdoc/options.rb', line 233

def check_generator
  if @generator then
    raise OptionParser::InvalidOption,
      "generator already set to #{@generator_name}"
  end
end

- (`Object`) default_title=(string)

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.



245
246
247

# File 'lib/rdoc/options.rb', line 245

def default_title=(string)
  @title ||= string
end

- (`Object`) finish

Completes any unfinished option setup business such as filtering for existent files, creating a regexp for #exclude and setting a default #template.

# File 'lib/rdoc/options.rb', line 254

def finish
  @op_dir ||= 'doc'

  @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

  unless @template then
    @template     = @generator_name
    @template_dir = template_dir_for @template
  end

  self
end

- (`Object`) generator_descriptions

Returns a properly-space list of generators and their descriptions.

# File 'lib/rdoc/options.rb', line 281

def generator_descriptions
  lengths = []

  generators = RDoc::RDoc::GENERATORS.map do |name, generator|
    lengths << name.length

    description = generator::DESCRIPTION if
      generator.const_defined? :DESCRIPTION

    [name, description]
  end

  longest = lengths.max

  generators.sort.map do |name, description|
    if description then
      "  %-*s - %s" % [longest, name, description]
    else
      "  #{name}"
    end
  end.join "\n"
end

- (`Object`) parse(argv)

Parses command line options.

# File 'lib/rdoc/options.rb', line 307

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
    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.

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.

Available formatters:

#{generator_descriptions}

RDoc understands the following file formats:

    EOF

    parsers = Hash.new { |h,parser| h[parser] = [] }

    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.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 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",
           "Synonym for --visibility=private.") do |value|
      @visibility = :private
    end

    opt.separator nil

    opt.on("--exclude=PATTERN", "-x", Regexp,
           "Do not process files or directories",
           "matching PATTERN.") do |value|
      @exclude << value
    end

    opt.separator nil

    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 RDoc::Parser.alias_extension old, new then
        raise OptionParser::InvalidArgument, "Unknown extension .#{old} to -E"
      end
    end

    opt.separator nil

    opt.on("--[no-]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

    opt.on("--pipe",
           "Convert RDoc on stdin to HTML") do
      @pipe = true
    end

    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("--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("-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

    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 }
    end

    opt.separator nil

    opt.on("--[no-]coverage-report=[LEVEL]", "--[no-]dcov", "-C", Integer,
           "Prints a report on undocumented items.",
           "Does not generate files.") do |value|
      value = 0 if value.nil? # Integer converts -C to nil

      @coverage_report = value
      @force_update = true if value
    end

    opt.separator nil

    opt.on("--output=DIR", "--op", "-o",
           "Set the output directory.") do |value|
      @op_dir = value
    end

    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",
           "name. When displayed, the '#' is removed",
           "unless this option is specified.") do |value|
      @show_hash = value
    end

    opt.separator nil

    opt.on("--template=NAME", "-T", Template,
           "Set the template used when generating",
           "output. The default depends on the",
           "formatter used.") do |(template, template_dir)|
      @template     = template
      @template_dir = template_dir
    end

    opt.separator nil

    opt.on("--title=TITLE", "-t",
           "Set TITLE as the title for HTML output.") do |value|
      @title = value
    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

    opt.separator nil
    opt.separator "ri generator options:"
    opt.separator nil

    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|
      check_generator

      @generator_name = "ri"
      @op_dir ||= RDoc::RI::Paths::HOMEDIR
      setup_generator
    end

    opt.separator nil

    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|
      check_generator

      @generator_name = "ri"
      @op_dir = RDoc::RI::Paths::SITEDIR
      setup_generator
    end

    opt.separator nil
    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",
           "(default true).") do |value|
      ignore_invalid = value
    end

    opt.on("--quiet", "-q",
           "Don't show progress as we parse.") do |value|
      @verbosity = 0
    end

    opt.on("--verbose", "-v",
           "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

  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 DEPRECATED[e.args.first] then
      deprecated << e.args.first
    elsif %w[--format --ri -r --ri-site -R].include? e.args.first then
      raise
    else
      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
    invalid << '-p (with files)'
  end

  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

  @files = argv.dup

  finish
end

- (`Object`) quiet

Don't display progress as we process the files



717
718
719

# File 'lib/rdoc/options.rb', line 717

def quiet
  @verbosity.zero?
end

- (`Object`) quiet=(bool)

Set quietness to bool



724
725
726

# File 'lib/rdoc/options.rb', line 724

def quiet= bool
  @verbosity = bool ? 0 : 1
end

- (`Object`) setup_generator(generator_name = @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.

# File 'lib/rdoc/options.rb', line 735

def setup_generator generator_name = @generator_name
  @generator = @generators[generator_name]

  unless @generator then
    raise OptionParser::InvalidArgument,
          "Invalid output formatter #{generator_name}"
  end

  return if @generator_options.include? @generator

  @generator_name = generator_name
  @generator_options << @generator

  if @generator.respond_to? :setup_options then
    @option_parser ||= OptionParser.new
    @generator.setup_options self
  end
end

- (`Object`) template_dir_for(template)

Finds the template dir for template

# File 'lib/rdoc/options.rb', line 757

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

Class: RDoc::Options

Overview

Constant Summary

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Options) initialize

Instance Attribute Details

- (Object) charset

- (Object) coverage_report

- (Object) dry_run

- (Object) encoding

- (Object) exclude

- (Object) files

- (Object) force_output

- (Object) force_update

- (Object) formatter

- (Object) generator

- (Object) generator_options

- (Object) hyperlink_all

- (Object) line_numbers

- (Object) main_page

- (Object) op_dir

- (Object) option_parser

- (Object) pipe

- (Object) rdoc_include

- (Object) show_hash

- (Object) tab_width

- (Object) template

- (Object) template_dir

- (Object) title

- (Object) update_output_dir

- (Object) verbosity

- (Object) visibility

- (Object) webcvs