前回の続き。
デフォルト値
: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
セクション
ファイル内に "[セクション名]" を指定することで、１つのファイル内に複数のセクションを作成することができます。
[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"
