=encoding utf-8

=head1 NAME

Getopt::EX::Hashed - Getopt::Long 用ハッシュ格納オブジェクトの自動化

=head1 VERSION

Version 1.0601

=head1 SYNOPSIS

  # script/foo
  use App::foo;
  App::foo->new->run();

  # lib/App/foo.pm
  package App::foo;

  use Getopt::EX::Hashed; {
      Getopt::EX::Hashed->configure( DEFAULT => [ is => 'rw' ] );
      has start    => ' =i  s begin ' , default => 1;
      has end      => ' =i  e       ' ;
      has file     => ' =s@ f       ' , any => qr/^(?!\.)/;
      has score    => ' =i          ' , min => 0, max => 100;
      has answer   => ' =i          ' , must => sub { $_[1] == 42 };
      has mouse    => ' =s          ' , any => [ 'Frankie', 'Benjy' ];
      has question => ' =s          ' , any => qr/^(life|universe|everything)$/i;
  } no Getopt::EX::Hashed;

  sub run {
      my $app = shift;
      use Getopt::Long;
      $app->getopt or pod2usage();
      if ($app->answer == 42) {
          $app->question //= 'life';
          ...

=cut
=head1 DESCRIPTION

B<Getopt::EX::Hashed>は、B<Getopt::Long>およびB<Getopt::EX::Long>を含む互換モジュールのコマンドラインオプション値を格納するハッシュオブジェクトを自動化するモジュールです。モジュール名は B<Getopt::EX> と同じですが、今のところ B<Getopt::EX> の他のモジュールとは独立して動作します。

このモジュールの主な目的は、初期化と仕様を一箇所に統合することです。また、シンプルな検証インターフェイスも提供します。

C<is>パラメータが与えられると、アクセサメソッドが自動的に生成されます。同じ関数がすでに定義されている場合、プログラムは致命的なエラーを引き起こします。アクセサはオブジェクトが破棄されると削除されます。複数のオブジェクトが同時に存在する場合、問題が発生する可能性があります。

=head1 FUNCTION

=head2 B<has>

オプション・パラメータを以下の形式で宣言します。括弧はわかりやすくするためのもので、省略してもよい。

    has option_name => ( param => value, ... );

たとえば、整数値をパラメータとしてとり、C<-n>としても使えるオプションC<--number>を定義するには、次のようにします。

    has number => spec => "=i n";

アクセサは最初の名前で作成されます。この例では、アクセサは C<< $app->number >> と定義されます。

配列参照が与えられている場合、一度に複数の名前を宣言することができます。

    has [ 'left', 'right' ] => ( spec => "=i" );

名前がプラス(C<+>)で始まる場合、与えられたパラメータは既存の設定を更新します。

    has '+left' => ( default => 1 );

C<spec>パラメータは、最初のパラメータであればラベルを省略できます。

    has left => "=i", default => 1;

パラメータの数が偶数でない場合、デフォルトのラベルが先頭にあるとみなされます：最初のパラメータがコード参照であればC<action>、そうでなければC<spec>となります。

以下のパラメータが利用可能です。

=over 7

=item [ B<spec> => ] I<string>

オプション指定C<< spec => >> ラベルを省略できるのは、それが最初のパラメータである場合だけです。

I<string> では、オプションの仕様とエイリアスの名前は空白で区切られ、どのような順番でも表示できます。

C<--start>というオプションを持ち、その値として整数を取り、C<-s>とC<--begin>という名前でも使えるようにするには、次のように宣言します。

    has start => "=i s begin";

上記の宣言は、次の文字列にコンパイルされます。

    start|s|begin=i

にコンパイルされ、C<Getopt::Long>の定義に従います。もちろん、このように書くこともできます：

    has start => "s|begin=i";

名前とエイリアスにアンダースコア(C<_>)が含まれている場合、アンダースコアの代わりにダッシュ(C<->)を使った別のエイリアスが定義されます。

    has a_to_z => "=s";

上記の宣言は、次の文字列にコンパイルされます。

    a_to_z|a-to-z=s

特に何もする必要がない場合は、空文字列（または空白のみ）を値として与えます。そうでない場合は、オプションとはみなされません。

=item B<alias> => I<string>

B<alias>パラメータで、追加のエイリアス名を指定することもできます。C<spec>パラメータのものと違いはありません。

    has start => "=i", alias => "s begin";

=item B<is> => C<ro> | C<rw>

アクセサメソッドを生成するには、C<is>パラメータが必要です。読み込み専用ならC<ro>、読み書きならC<rw>を指定します。

読み書き可能なアクセサはlvalue属性を持っているので、それを代入することができます。このように使えます：

    $app->foo //= 1;

これは、次のように書くよりずっと簡単です。

    $app->foo(1) unless defined $app->foo;

以下のすべてのメンバにアクセッサを作りたい場合は、C<configure>でC<DEFAULT>パラメータを設定します。

    Getopt::EX::Hashed->configure( DEFAULT => [ is => 'rw' ] );

C<configure>でC<DEFAULT>パラメータを設定します。アクセサはC<new>時に生成されるので、この値はすべてのメンバに有効です。

=item B<default> => I<value> | I<coderef>

デフォルト値を設定します。デフォルト値が指定されない場合、メンバはC<undef>として初期化されます。

値が ARRAY または HASH の参照の場合、同じメンバを持つ新しい参照が割り当てられます。つまり、メンバ・データは複数のC<new>呼び出しで共有されます。C<new>を複数回呼び出してメンバ・データを変更する場合は注意してください。

コード・リファレンスが与えられると、B<new>の実行時に呼び出され、デフォルト値が得られます。これは、宣言ではなく実行時に値を評価したい場合に有効です。デフォルトのアクションを定義したい場合は、B<action>パラメータを使用します。

SCALARへの参照が与えられた場合、オプション値はハッシュオブジェクトメンバではなく、参照が示すデータに格納されます。この場合、ハッシュ・メンバにアクセスしても期待値は得られません。

=item [ B<action> => ] I<coderef>

パラメータ C<action> は、オプションを処理するために呼び出されるコード参照をとます。C<<action =>> ラベルは、それが最初のパラメータである場合に限り、省略することができます。

呼び出されたとき、ハッシュオブジェクトは C<$_> として渡されます。

    has [ qw(left right both) ] => '=i';
    has "+both" => sub {
        $_->{left} = $_->{right} = $_[1];
    };

これを C<< "<>" に使用することができます。">>ですべてを捕らえることができます。その場合、specパラメータは重要ではなく、必須でもないです。

    has ARGV => default => [];
    has "<>" => sub {
        push @{$_->{ARGV}}, $_[0];
    };

=back

以下のパラメータはすべてデータ・バリデーションのためのものです。最初の C<must> は汎用バリデータで、何でも実装できます。その他は一般的なルールのショートカットです。

=over 7

=item B<must> => I<coderef> | [ I<coderef> ... ]

パラメータ C<must> は、オプション値を検証するためのコードリファレンスを受け取ります。C<action> と同じ引数をとり、真偽値を返します。次の例では、オプションB<--answer>は有効な値として42だけを取ります。

    has answer => '=i',
        must => sub { $_[1] == 42 };

複数のコード参照が与えられた場合、すべてのコードが真を返さなければなりません。

    has answer => '=i',
        must => [ sub { $_[1] >= 42 }, sub { $_[1] <= 42 } ];

=item B<min> => I<number>

=item B<max> => I<number>

引数の最小値と最大値を設定します。

=item B<any> => I<arrayref> | qr/I<regex>/

有効な文字列パラメータリストを設定します。各項目は文字列または正規表現参照です。引数は、指定されたリストのいずれかの項目と同じか一致する場合に有効です。値がarrayrefでない場合は、単一の項目リスト（通常は正規表現）とみなされます。

以下の宣言はほぼ等価ですが、2番目の宣言は大文字小文字を区別しません。

    has question => '=s',
        any => [ 'life', 'universe', 'everything' ];

    has question => '=s',
        any => qr/^(life|universe|everything)$/i;

オプションの引数を使用する場合は、リストにデフォルト値を含めることを忘れないでください。そうしないとバリデーション・エラーになります。

    has question => ':s',
        any => [ 'life', 'universe', 'everything', '' ];

=back

=head1 METHOD

=head2 B<new>

初期化されたハッシュオブジェクトを取得するクラスメソッド。

=head2 B<optspec>

C<GetOptions>関数に渡すことができるオプション指定リストを返します。

    GetOptions($obj->optspec)

C<GetOptions>は、ハッシュ参照を第1引数に与えることで、ハッシュに値を格納する機能を持っていますが、これは必要ありません。

=head2 B<getopt> [ I<arrayref> ]

オプションを処理するために、呼び出し元のコンテキストで定義された適切な関数を呼び出します。

    $obj->getopt

    $obj->getopt(\@argv);

上記の例は、以下のコードのショートカットです。

    GetOptions($obj->optspec)

    GetOptionsFromArray(\@argv, $obj->optspec)

=head2 B<use_keys> I<keys>

ハッシュキーはC<Hash::Util::lock_keys>によって保護されているため、存在しないメンバにアクセスするとエラーになります。この関数を使用して、新しいメンバー・キーを宣言してから使用してください。

    $obj->use_keys( qw(foo bar) );

任意のキーにアクセスしたい場合は、オブジェクトのロックを解除してください。

    use Hash::Util 'unlock_keys';
    unlock_keys %{$obj};

この動作はC<configure>のC<LOCK_KEYS>パラメータで変更できます。

=head2 B<configure> B<label> => I<value>, ...

オブジェクトを作成する前に、クラスメソッドC<< Getopt::EX::Hashed->configure() >>を使用します。C<new()>を呼び出すと、パッケージ固有の設定がオブジェクトにコピーされ、以降の操作に使用されます。オブジェクト固有の設定を更新するには、C<< $obj->configure() >> を使用します。

以下の構成パラメータがあります。

=over 7

=item B<LOCK_KEYS> (default: 1)

ハッシュ・キーをロックします。これは、存在しないハッシュ・エントリへの偶発的なアクセスを避けるためです。

=item B<REPLACE_UNDERSCORE> (default: 1)

アンダースコアをダッシュに置き換えたエイリアスを生成します。

=item B<REMOVE_UNDERSCORE> (default: 0)

アンダースコアを削除したエイリアスを生成します。

=item B<GETOPT> (default: 'GetOptions')

=item B<GETOPT_FROM_ARRAY> (default: 'GetOptionsFromArray')

C<getopt> メソッドから呼び出される関数名を設定します。

=item B<ACCESSOR_PREFIX> (default: '')

指定されると、メンバ名の前に付加されてアクセサ・メソッドとなります。C<ACCESSOR_PREFIX> が C<opt_> と定義されている場合、メンバ C<file> のアクセサは C<opt_file> になります。

=item B<ACCESSOR_LVALUE> (default: 1)

trueを指定すると、読み書き可能なアクセサはlvalue属性を持ちます。この振る舞いを好まない場合はゼロを設定してください。

=item B<DEFAULT>

デフォルト・パラメータを設定します。C<has>の呼び出しでは、DEFAULTパラメータが引数パラメータの前に挿入されます。そのため、同じパラメータが両方に含まれている場合は、引数リストで後の方が優先されます。C<+>によるインクリメンタルコールは影響を受けないです。

DEFAULTの典型的な使い方はC<is>で、以下のすべてのハッシュ・エントリーのアクセサ・メソッドを用意することです。C<< DEFAULT => [] >>を宣言してリセットします。

    Getopt::EX::Hashed->configure(DEFAULT => [ is => 'ro' ]);

=back

=head2 B<reset>

クラスを元の状態にリセットします。

=head1 SEE ALSO

L<Getopt::Long>

L<Getopt::EX>, L<Getopt::EX::Long>

=head1 AUTHOR

Kazumasa Utashiro

=head1 COPYRIGHT

The following copyright notice applies to all the files provided in
this distribution, including binary files, unless explicitly noted
otherwise.

Copyright 2021-2024 Kazumasa Utashiro

=head1 LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut