=head1 NAME

Getopt::EX::Hashed - Getopt::Long용 해시 저장소 객체 자동화

=head1 VERSION

Version 1.0503

=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<-- 숫자> 옵션을 정의하려면 다음과 같이 하세요.

    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<-s> 및 C<--begin>이라는 이름으로도 사용할 수 있는 C<--start>라는 옵션을 가지려면 다음과 같이 선언합니다.

    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<ACCESSOR_LVALUE> 파라미터를 0으로 설정합니다. 접근자는 C<new> 시점에 생성되므로 이 값은 모든 멤버에 유효합니다.

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

기본값을 설정합니다. 기본값을 지정하지 않으면 멤버는 C<undef>로 초기화됩니다.

값이 배열 또는 해시 참조인 경우 동일한 멤버를 가진 새 참조가 할당됩니다. 즉, 멤버 데이터가 여러 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<< "<>" >>에 사용하여 모든 것을 잡을 수 있습니다. 이 경우 사양 매개변수는 중요하지 않으며 필요하지 않습니다.

    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<--답변>은 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가 아닌 경우 단일 항목 목록으로 간주됩니다(일반적으로 regexpref).

다음 선언은 두 번째 선언이 대소문자를 구분하지 않는다는 점을 제외하면 거의 동일합니다.

    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>에는 해시 참조를 첫 번째 인자로 제공하여 값을 해시에 저장하는 기능이 있지만, 반드시 필요한 것은 아닙니다.

=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<파일>에 대한 접근자는 C<opt_file>이 됩니다.

=item B<ACCESSOR_LVALUE> (default: 1)

참이면 읽기-쓰기 액세스자는 lvalue 속성을 갖습니다. 이 동작이 마음에 들지 않으면 0으로 설정하세요.

=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
