Ruby OptionParser クラスのリファレンス

ruby 2.0.0-p247 環境で、ri OptionParser | col -bx したものの日本語訳です。

以前 (2008年3月16日)、Ruby: OptionParser (optparse.rb) の使い方 にて、OptionParser の記事を書きましたが、もっと完全なドキュメントが身近にありました。OptionParser のすべての機能について網羅した、こちらの説明のほうがよいでしょう。

OptionParser < Object

(from ruby core)

---

OptionParser

イントロダクション Introduction

OptionParser はコマンドラインオプション分析のためのクラスです。GetoptLong より、ずっと先進的で、にも関わらず使うのがより簡単、またいっそう Ruby 指向のソリューションです。

仕様 Features

1. 引数指定とそれを処理するコードは、同じ場所に書かれます。
2. オプションの要約を出力することができます; この要約文を別々にメンテする必要は、ありません。
3. 選択的や必須の引数を、非常に優雅に指定されます。
4. 引数たちを、自動で、指定のクラスに変換することができます。
5. 引数たちを、適切なセットに制限することができます。

これらの仕様すべて、下記の例にデモしてあります。完全なドキュメントは、#make_switch を見よ。

必要最小限の例 Minimal example

  require 'optparse'
options = {}
OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options[:verbose] = v
end
end.parse!
p options
p ARGV

完全な記述例 Complete example

下記の例は、完全な Ruby のプログラムです。あなたは実行できますし、さまざまなオプションを指定してみることで、影響をみれます。おそらくこれは optparse の仕様を学ぶのにベストな方法でしょう。

  require 'optparse'
require 'optparse/time'
require 'ostruct'
require 'pp'
class OptparseExample
CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }
#
# オプションたちの構造記述を返す。
# Return a structure describing the options.
#
def self.parse(args)
# コマンドラインで指定されたオプションたちは、*options* の中に集められる
# われわれはここではデフォルトの値をセットする。
# The options specified on the command line will be collected in *options*.
# We set default values here.
options = OpenStruct.new
options.library = []
options.inplace = false
options.encoding = "utf8"
options.transfer_type = :auto
options.verbose = false
opt_parser = OptionParser.new do |opts|
opts.banner = "Usage: example.rb [options]"
opts.separator ""
opts.separator "Specific options:"
# 必須の引数。
# Mandatory argument.
opts.on("-r", "--require LIBRARY",
"Require the LIBRARY before executing your script") do |lib|
options.library << lib
end
# 選択的な引数; 複数行による記述。
# Optional argument; multi-line description.
opts.on("-i", "--inplace [EXTENSION]",
"Edit ARGV files in place",
"  (make backup if EXTENSION supplied)") do |ext|
options.inplace = true
options.extension = ext || ''
options.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
end
# 引数 'delay' を Float 型に制約する。
# Cast 'delay' argument to a Float.
opts.on("--delay N", Float, "Delay N seconds before executing") do |n|
options.delay = n
end
# 引数 'time' を Time オブジェクトに制限する。
# Cast 'time' argument to a Time object.
opts.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
options.time = time
end
# 8 進数の整数に制限する。
# Cast to octal integer.
opts.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
"Specify record separator (default \\0)") do |rs|
options.record_separator = rs
end
# 列挙 (リスト) の引数。
# List of arguments.
opts.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
options.list = list
end
# キーワード補完。われわれは、特定の引数セットを指定している (CODES
# と CODE_ALIASES - 文字はハッシュであることに注目), そしてユーザは
# もっとも短いあいまいなテキストを使うかもしれない。
# Keyword completion.  We are specifying a specific set of arguments (CODES
# and CODE_ALIASES - notice the latter is a Hash), and the user may provide
# the shortest unambiguous text.
code_list = (CODE_ALIASES.keys + CODES).join(',')
opts.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
"  (#{code_list})") do |encoding|
options.encoding = encoding
end
# キーワード補完を使った選択的な引数。
# Optional argument with keyword completion.
opts.on("--type [TYPE]", [:text, :binary, :auto],
"Select transfer type (text, binary, auto)") do |t|
options.transfer_type = t
end
# ブーリアン・スイッチ。
# Boolean switch.
opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
options.verbose = v
end
opts.separator ""
opts.separator "Common options:"
# 引数なしで、tail での表示。これはオプションたちのサマリーをプリントする。
# やってみて！
# No argument, shows at tail.  This will print an options summary.
# Try it and see!
opts.on_tail("-h", "--help", "Show this message") do
puts opts
exit
end
# もうひとつの典型的なスイッチ (バージョンを表示)。
# Another typical switch to print the version.
opts.on_tail("--version", "Show version") do
puts OptionParser::Version.join('.')
exit
end
end
opt_parser.parse!(args)
options
end  # parse()
end  # class OptparseExample
options = OptparseExample.parse(ARGV)
pp options
pp ARGV

シェル補完 Shell Completion

For modern shells (e.g. bash, zsh, etc.), you can use shell completion for command line options.

モダンなシェル (e.g. bash, zsh, など) では、コマンドライン・オプションの ためにシェルの補完が使えます。

さらなるドキュメント Further documentation

上述した例はこのクラスをどのように使うかについて学ぶに十分でしょう。もしなんらかの疑問があれば、http://bugs.ruby-lang.org にチケットを切ってください。

---

定数 Constants:

• DecimalInteger 10進数整数形式、Integer 型にコンバートするためのもの。
• DecimalNumeric
  10進数の整数/浮動小数形式、整数を Integer に, 浮動小数を Float に 変換するためのもの。
• OctalInteger Ruby/C ライクな 8進数/16進数/2進数 整数形式、Integer 型に変換する ためのもの。
• SPLAT_PROC [not documented]

クラスメソッド Class methods:

  accept
each_const
getopts
inc
new
reject
search_const
show_version
terminate
top
with

インスタンスメソッド Instance methods:

  abort
accept
banner
base
candidate
complete
def_head_option
def_option
def_tail_option
default_argv
define
define_head
define_tail
environment
getopts
help
inc
load
make_switch
new
notwice
on
on_head
on_tail
order
order!
parse
parse!
permute
permute!
program_name
reject
release
remove
search
separator
set_banner
set_program_name
set_summary_indent
set_summary_width
summarize
summary_indent
summary_width
terminate
to_a
to_s
top
ver
version
visit
warn

属性 Attributes:

  attr_accessor default_argv
attr_accessor set_summary_indent
attr_accessor set_summary_width
attr_accessor summary_indent
attr_accessor summary_width
attr_writer banner
attr_writer program_name
attr_writer release
attr_writer set_banner
attr_writer set_program_name
attr_writer version

---