mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
a80ba17d67
2. Add new :section: directive which starts a new section in the output. The title following :section: is used as the section heading, and the remainder of the comment containing the section is used as introductory text. Subsequent methods, aliases, attributes, and classes will be documented in this section. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@7344 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
575 lines
17 KiB
Ruby
575 lines
17 KiB
Ruby
# 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 = @inline_source = 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
|