読者です 読者をやめる 読者になる 読者になる

OptConfig その2

前回の続き。

デフォルト値

:default でオプションを指定しない時のデフォルト値を指定できます。

o = OptConfig.new
o.option "port", :format=>1..65535, :default=>25
o.parse ["--port=123"]
o["port"]                # => 123
o.parse []
o["port"]                # => 25

アンダースコアをハイフンとみなす

:underscore_is_hyphen を指定すると、ハイフンの代わりにアンダースコアを使うことができます。

o = OptConfig.new
o.option "long-option", :underscore_is_hyphen=>true
o.parse ["--long_option"]
o["long-option"]          # => true

使用方法テキスト生成

:description でオプションに説明をつけておけば、usage メソッドで使用方法テキストを生成できます。

o = OptConfig.new
o.option "h", "hostname", :argument=>true, :default=>"localhost", :description=>"hostname"
o.option "p", "port", :description=>"port number"
o.option "P", "password", :description=>"password"
o.option "hidden-option"
o.option "help", :description=>"show this message"

ここで、o.usage を使用すると次の文字列が得られます。

  -h, --hostname          hostname
  -p, --port              port number
  -P, --password          password
  --help                  show this message

順番はオプションの定義順と同じです。:description が設定されていないオプションは表示されません。

説明中に "%s" を記述すると、その時点のオプションの値に置き換わります。

o = OptConfig.new
o.option "h", "hostname", :argument=>true, :default=>"localhost", :description=>"hostname (%s)"
o.option "p", "port", :format=>1..65535, :default=>110, :description=>"port number (%s)"
puts o.usage
o.parse ["--host=myhostname", "--port=999"]
puts
puts o.usage

この出力は次のようになります。

  -h, --hostname          hostname (localhost)
  -p, --port              port number (110)

  -h, --hostname          hostname (myhostname)
  -p, --port              port number (999)

parse の結果、値が変わっていることがわかります。

複数指定時の振る舞い

同じオプションが複数回指定された場合は、最後の値が有効になります。

o = OptConfig.new
o.option "hoge", :argument=>true
o.parse ["--hoge=123", "--hoge=abc"]
o["hoge"]        # => "abc"

:multiple=>true を指定すると、指定されたすべての値を配列で返すようになります。

o = OptConfig.new
o.option "hoge", :argument=>true, :multiple=>true
o.parse ["--hoge=123", "--hoge=abc"]
o["hoge"]        # => ["123", "abc"]

:multiple=>false を指定すると、複数回指定されたらエラーになります。

o = OptConfig.new
o.option "hoge", :argument=>true, :multiple=>false
o.parse ["--hoge=123", "--hoge=abc"]    # raise OptConfig::DuplicatedOption

:multiple 未指定時と同じ振る舞いにしたい場合は :last を指定します。

補完

長いオプション名は曖昧でない限り自動的に補完されます。

o = OptConfig.new
o.option "hoge"
o.option "fuga"
o.option "foo"
o.parse ["--h", "--fu"]
o["hoge"]           # => true
o["fuga"]           # => true
o.parse ["--f"]     # raise OptConfig::AmbiguousOption

補完したくない場合は :completion=>false を指定します。

o = OptConfig.new
o.option "hoge"
o.option "fuga"
o.option "foo", :completion=>false
o.parse ["--h", "--f"]
o["hoge"]           # => true
o["fuga"]           # => true

foo オプションは補完対象にならないため、--f の指定は曖昧にならず、--fuga に決定します。

オプション判定の中断

デフォルトでは、配列のすべての要素についてオプションを探しますが、OptConfig.new に :stop_at_non_option_argument=>true を設定すると、オプションでない要素(「-」で始まらない要素)が現れたときに、そこでパースを中断することができます。

o = OptConfig.new
o.option "hoge"
o.parse ["arg", "--hoge"]  # => ["arg"]
o["hoge"]                  # => true
o = OptConfig.new :stop_at_non_option_argument=>true
o.option "hoge"
o.parse ["arg", "--hoge"]  # => ["arg", "--hoge"]
o["hoge"]                  # => nil

属性のデフォルト値

オプションの属性(:argument, :default, :multiple 等)のデフォルト値は、OptConfig.new 時に指定しておくことができます。

o = OptConfig.new :argument=>true, :completion=>false, :description=>""
o.option "hoge"
o.option "hidden-option", :description=>nil     # usage に含まれない
o.option "help", :argument=>false               # 引数を取らない

ファイルからの読み込み

file= メソッドでファイル名を指定すると、parse 時にそのファイルからオプションを読み込みます。
ファイル内に記述されたのと同じオプションが parse の引数で指定された場合は、parse の引数の方が優先されます。

ファイル内に記述できるのは長いオプションだけです。「--」プレフィックスは記述しません。:completion が指定されていたとしても補完はされません。また、未知のオプションが指定されていてもエラーにはならず、無視されます。

ファイルの形式は1行に1オプションです。先頭が # の行や空行は無視されます。

opt1=value1
# = の前後に空白があっても良い
opt2 = value2
# = の代わりに空白で区切っても良い
opt3 value3
# 未知のオプションは無視される
unknown-option
o = OptConfig.new
o.option "opt1", :argument=>true
o.option "opt2", :argument=>true
o.option "opt3", :argument=>true
o.file = "/path/to/file"
o.parse ["--opt1=hoge"]
o["opt1"]           # => "hoge"
o["opt2"]           # => "value2"
o["opt3"]           # => "value3"

ignore_unknown_file_option を false にすると、ファイル内の未知のオプション名でエラーが発生します。

o = OptConfig.new
o.option "opt1", :argument=>true
o.option "opt2", :argument=>true
o.option "opt3", :argument=>true
o.ignore_unknown_file_option = false
o.file = "/path/to/file"
o.parse                   # raise OptConfig::UnknownOption

file, ignore_unknown_file_option は OptConfig.new 時に指定することもできます。

o = OptConfig.new :file=>"/path/to/file", :ignore_unknown_file_option=>false

セクション

ファイル内に "[セクション名]" を指定することで、1つのファイル内に複数のセクションを作成することができます。

[section1]
param = hogehoge
[section2]
param = fugafuga

どのセクションを使用するかは、OptConfig#section= で指定します。

o = OptConfig.new
o.option "param", :argument=>true
o.file = "/path/to/file"
o.section = "section1"
o.parse
o["param"]     # => "hogehoge"
o.section = "sectoin2"
o.parse
o["param"]     # => "fugafuga"

複数のセクションを読みたい場合は配列で指定します。

o.section = ["section1", "section2"]

file, ignore_unknown_file_option と同様に OptConfig.new でも指定できます。

o = OptConfig.new :section=>"section1"