OptConfig

Author:	TOMITA Masahiro <tommy@tmtm.org>
License:	Ruby‘s. see www.ruby-lang.org/en/LICENSE.txt

OptConfig はコマンドラインオプションのパーサです。
ファイルからオプションを読み込むこともできます。
-s 形式と —long-option 形式の両方を扱うことができます。
長い形式のオプションは曖昧でなければ補完されます。
usage に使用する文字列を自動的に生成します。
オプションの引数の形式を指定できます。

Download

Required

StringValidator stringvalidator.rubyforge.org/

Install

 $ make
 # make install

Usage

 require "optconfig"
 opt = OptConfig.new
 opt.option "p", "port=num", :format=>1..65535, :default=>110, :description=>"port number (%s)"
 opt.option "h", "hostname=name", :format=>true, :default=>"localhost", :description=>"hostname (%s)"
 opt.option "hogehoge", :description=>"enable hogehoge flag"

 argv = %w[-p 12345 -h 192.168.1.1 arg1 arg2]
 opt.parse argv    # => ["arg1", "arg2"]
 opt["p"]          # => 12345
 opt["port"]       # => 12345 (same as opt["p"])
 opt["h"]          # => "192.168.1.1"
 opt["hogehoge"]   # => nil (means not set)
 opt["x"]          # raise OptConfig::UnknownOption
 argv              # => ["-p", "12345", "-h", "192.168.1.1", "arg1", "arg2"]
 opt.parse! argv   # => ["arg1", "arg2"]
 argv              # => ["arg1", "arg2"]

opt.usage は次の文字列を生成します。

   -p, --port=num         port number (12345)
   -h, --hostname=name    hostname (192.168.1.1)
   --hogehoge             enable hogehoge flag

オプション定義

OptConfig#option でオプションを定義します。引数は、オプション名のリストと、オプションの属性を表す Hash です。

オプション名: 1文字の英数字、または2文字以上の英数字と「-」「_」。同じオプションに複数の名前をつける場合は複数指定します。 "long-name=val" の形式で指定すると :argument 属性が true になります。 "long-name[=val]" の形式で指定すると :argument 属性が :optional になります。

オプション属性(Hash)のキーは以下の通りです。

:argument

オプションが引数を取るかどうか。

nil :	format が真の場合は引数必須、偽の場合は引数不要 (デフォルト)。
true :	引数必須。
false :	引数不要。
:optional :	引数を省略可能。省略時は OptConfig#[] は true になる。

:format

オプション引数の形式。

true :	任意。
false/nil :	オプションが引数を必要としない (デフォルト)。
:boolean :	オプション引数が "1", "true", "enable", "yes", "y", "on" で true、"0", "false", "disable", "no", "n", "off" で false を返す。
その他 :	StringValidator の rule オブジェクトとみなして引数の形式をチェックする。

:default

オプションが指定されなかった場合のデフォルト値。

:description

オプションの説明文字列。説明は usage() で出力されます。 nil の場合は usage() でオプションについて出力されません。文字列中の %s はオプションの値に置換されます。

:multiple

複数指定された場合の振る舞い。

true :	複数指定可能。OptConfig#[] は配列を返す。
false/nil :	複数指定された場合はエラー。
:last :	最後に指定されたものが有効(デフォルト)。

:completion

長いオプションを補完するかどうか (デフォルト: true)。

:underscore_is_hyphen

アンダースコアをハイフンとみなすかどうか (デフォルト: nil)

:in_config

オプションファイル内に記述可能かどうか (デフォルト: true)。

:proc

parse() 時にオプションを見つける度に実行される Proc オブジェクト。オプション引数の正当性を確認した後に実行されます。ブロック引数は、オプション名, Option オブジェクト, オプション引数です。ブロックの評価結果は OptConfig#[] の戻り値として使用されます。

:pre_proc

:proc と同じですが、オプション引数の正当性の確認前に実行されます。ブロック引数は、オプション名, Option オブジェクト, オプション引数です。ブロックの評価結果はオプション引数として使用されます。

オプションファイル

parse よりも前に file= でファイル名を指定するか、OptConfig.new 時に :file 属性を指定すると、そのファイルからオプションを読み込みます。ファイルで指定されたオプションよりも、parse の引数で指定されたオプションの方が優先度が高いです。

オプションファイルの形式は次の通りです:

 option-name = value

option-name には1文字のオプション名は指定できません。

「=」の前後の空白はあってもなくても構いません。「=」は省略可能です。その場合は、オプション名と値との間に一つ以上の空白が必要です。

「#」で始まる行はコメントとみなされます。空行も無視されます。指定できるオプションは長い形式のオプションだけです。

ファイル中に「[section_name]」という行を置くと、その行以降がセクションとして扱われます。OptConfig#section= でセクション名を指定すると、指定したセクションのオプションのみが読み込まれます。OptConfig#section= に配列を設定すると、複数のセクションから読み込みます。 OptConfig#section を設定しない場合は、すべてのセクションからオプションを読み込みます。

Required files

stringvalidator

optconfig.rb