[첫화면으로]Perl/Pod-Usage

마지막으로 [b]

Pod::Usage 코어 모듈

1. perldoc Pod::Usage 정리
1.1. 이름
1.2. 개괄
1.3. 인자
1.4. 설명
1.5. 예문
1.5.1. 추천 용례
1.6. 경고
1.7. 참고
2. 기타 & Comments

1. perldoc Pod::Usage 정리

Perldoc:Pod::Usage 내용 정리

1.1. 이름

Pod::Usage, pod2usage() - 프로그램에 포함된 pod 문서로부터 사용법 메시지를 출력

1.2. 개괄

  use Pod::Usage

  my $message_text  = "This text precedes the usage message.";
  my $exit_status   = 2;          ## 종료 상태값
  my $verbose_level = 0;          ## 자세한 정도
  my $filehandle    = \*STDERR;   ## 출력할 파일핸들

  pod2usage($message_text);

  pod2usage($exit_status);

  pod2usage( { -message => $message_text ,
               -exitval => $exit_status  ,
               -verbose => $verbose_level,
               -output  => $filehandle } );

  pod2usage(   -msg     => $message_text ,
               -exitval => $exit_status  ,
               -verbose => $verbose_level,
               -output  => $filehandle   );

  pod2usage(   -verbose => 2,
               -noperldoc => 1  )

1.3. 인자

pod2usage는 하나의 인자, 또는 해쉬에 대응되는 인자 리스트를 인자로 받는다. 하나의 인자를 받을 경우는 그 인자는 다음 셋 중 하나여야 한다:

인자로 리스트 또는 해쉬 레퍼런스로 들어올 경우, 다음 요소 중 하나 이상이 포함되어 있어야 한다:

  pod2usage(-verbose => 99,
            -sections => [ qw(fred fred/subsection) ] );
  use Pod::Find qw(pod_where);
  pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );

1.4. 설명

(기본 개념과 상세 단계에 관한 설명은 앞에서 언급되었으므로 생략)

명시적으로 지정하지 않는 경우, 종료 상태값, 상세 단계, 출력에 사용할 스트림은 다음과 같이 결정된다:

다소 복잡해 보이는 이런 동작은, 다음과 같은 Unix 관례에 기반하여 대부분의 경우 올바른 결과를 낸다:

인자 하나를 받아서 적절하게 처리하는 예:

    use Pod::Usage;
    use Getopt::Long;

    ## Parse options
    GetOptions("help", "man", "flag1")  ||  pod2usage(2);
    pod2usage(1)  if ($opt_help);
    pod2usage(-verbose => 2)  if ($opt_man);

    ## Check for too many filenames
    pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);

위처럼 간략하게 표현한게 읽기 어렵거나 일관성이 없어서 싫다면 아래와 같은 식으로 쓸 수도 있다:

    use Pod::Usage;
    use Getopt::Long;

    ## Parse options
    GetOptions("help", "man", "flag1")  ||  pod2usage(-verbose => 0);
    pod2usage(-verbose => 1)  if ($opt_help);
    pod2usage(-verbose => 2)  if ($opt_man);

    ## Check for too many filenames
    pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
        if (@ARGV > 1);

동일한 결과를 내는 다양한 표현을 "예문"에서 확인하라.

1.5. 예문

다음의 각 구문은 모두 "SYNOPSIS" 섹션을 STDERR로 출력한 후, 종료 상태값 2를 반환하며 종료한다.

    pod2usage();
    pod2usage(2);
    pod2usage(-verbose => 0);
    pod2usage(-exitval => 2);
    pod2usage({-exitval => 2, -output => \*STDERR});
    pod2usage({-verbose => 0, -output  => \*STDERR});
    pod2usage(-exitval => 2, -verbose => 0);
    pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);

다음의 각 구문은 모두 STDERR에 "Syntax error."라는 메시지와 개행문자를 출력하고, "SYNOPSIS" 섹션을 출력한 후, 종료 상태값 2를 반환하며 종료한다.

    pod2usage("Syntax error.");
    pod2usage(-message => "Syntax error.", -verbose => 0);
    pod2usage(-msg  => "Syntax error.", -exitval => 2);
    pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});
    pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});
    pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);
    pod2usage(-message => "Syntax error.",
              -exitval => 2,
              -verbose => 0,
              -output  => \*STDERR);

다음의 각 구문은 "SYNOPSIS" 섹션, "OPTIONS" 섹션, "ARGUMENTS" 섹션을 STDOUT으로 출력하고 종료 상태값 1을 반환하며 종료한다.

    pod2usage(1);
    pod2usage(-verbose => 1);
    pod2usage(-exitval => 1);
    pod2usage({-exitval => 1, -output => \*STDOUT});
    pod2usage({-verbose => 1, -output => \*STDOUT});
    pod2usage(-exitval => 1, -verbose => 1);
    pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});

다음의 각 구문은 모두 전체 매뉴얼 페이지를 STDOUT으로 출력한 후, 종료 상태값 1을 반환하며 종료한다.

    pod2usage(-verbose  => 2);
    pod2usage({-verbose => 2, -output => \*STDOUT});
    pod2usage(-exitval  => 1, -verbose => 2);
    pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});

1.5.1. 추천 용례

아래 예제는 Getopt::Long과 조합하여 위의 기능을 전부 제공하는 코드:

    use Getopt::Long;
    use Pod::Usage;

    my $man = 0;
    my $help = 0;
    ## 옵션들을 추출하고, 문법에 에러가 있거나 명시적으로 요청이 있을 경우
    ## 사용법 메시지를 출력한다.
    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
    pod2usage(1) if $help;
    pod2usage(-verbose => 2) if $man;

    ## 인자가 하나도 없는 경우.
    ## STDIN이 터미널에 연결되어 있지 않다면 STDIN을 사용하도록 허용, 그렇지 않으면 사용법 출력
    pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));
    __END__

    =head1 NAME

    sample - Using GetOpt::Long and Pod::Usage

    =head1 SYNOPSIS

    sample [options] [file ...]

     Options:
       -help            brief help message
       -man             full documentation

    =head1 OPTIONS

    =over 8

    =item B<-help>

    Print a brief help message and exits.

    =item B<-man>

    Prints the manual page and exits.

    =back

    =head1 DESCRIPTION

    B<This program> will read the given input file(s) and do something
    useful with the contents thereof.

    =cut

1.6. 경고

기본적으로 pod2usage()는 $0의 값을 pod 입력 파일의 경로로 사용한다. 그러나 Perl이 실행되는 모든 시스템에서 $0이 올바르게 설정되지는 않는다. ($0이 발견되지 않는 경우 pod2usage()가 $ENV{PATH}-pathlist 옵션에 있는 디렉토리 목록을 검색하긴 하지만) 이런 시스템에서는, 명시적으로 pod 문서의 경로를 지정해 주어야 한다:

    pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");

실행하는 스크립트명이 상대 경로로 지정되었고, 스크립트 자체가 pod2usage를 호출하기 이전에 현재 작업 디렉토리를 변경하는 경우 (Perldoc:chdir 참조), 견고한 플랫폼에서는 Pod::Usage가 실패할 수 있다. 그러지 않도록 하라1

1.7. 참고

Perldoc:Pod::Parser, Perldoc:Getopt::Long (/Getopt-Long), Perldoc:Pod::Find

2. 기타 & Comments

이름:  
Homepage:
내용:
 


컴퓨터분류 Perl
각주:
1. 작업디렉토리를 pod2usage 호출 이전에 변경하지 말라는 의미인 듯

마지막 편집일: 2012-2-11 12:25 am (변경사항 [d])
1665 hits | Permalink | 변경내역 보기 [h] | 페이지 소스 보기