Perl/Pod-Usage

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 정리

1.1. 이름

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. 인자

• 사용법 메시지 바로 앞에 출력될 텍스트 메시지를 담고 있는 문자열
• 종료 상태값에 해당하는 숫자값
• 해쉬 레퍼런스

• -message 또는 -msg
  • 사용법 메시지 바로 앞에 출력될 텍스트 메시지를 담고 있는 문자열
• -exitval
  • exit()에 전달될 종료 상태값. 정수값 또는 "NOEXIT"문자열. "NOEXIT"의 경우 프로세스를 종료하지 않고 리턴하게 한다.
• -verbose
  • 사용법 메시지를 출력할 때 얼마나 자세히 출력할 것인지 지정.
  • 0일 경우, POD문서의 "SYNOPSIS" 섹션만 출력됨
  • 1일 경우, "SYNOPSIS" 섹션과 더불어, "OPTIONS", "ARGUMENTS", "OPTIONS AND ARGUMENTS" 섹션이 출력됨
  • 2일 경우, 전체 맨페이지가 출력됨
  • 99일 경우, -sections 파라메터에서 지정한 섹션들이 출력됨 (Pod::Select 참조)
• -sections
  • -verbose 값이 99일 때 출력할 섹션들의 목록
  • "NAME|SYNOPSIS|DESCRIPTION|VERSION"과 같이 문자열로 설정할 수도 있고
  • [ qw(fred fred/subsection) ]과 같이 배열 레퍼런스로 설정할 수도 있다

  pod2usage(-verbose => 99,
            -sections => [ qw(fred fred/subsection) ] );

• -output
  • 사용법 메시지가 출력될 파일핸들 레퍼런스 또는 파일 경로명.
  • 종료상태값이 2 이상일 때 디폴트값은 \*STDERR, 종료상태값이 2보다 작을 때는 \*STDOUT
• -input
  • 스크립트의 POD 문서를 읽어들일 파일핸들 레퍼런스 또는 파일 경로명
  • 디폴트값은 $0(English.pm을 사용할 경우 $PROGRAM_NAME) 변수의 값
  • 만일 모듈에서 pod2usage()를 호출하게 하면서 모듈의 POD를 출력하고자 한다면, 다음과 같이 하라:

  use Pod::Find qw(pod_where);
  pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) );

• -pathlist
  • 입력 파일이 존재하지 않을 경우, 그 파일을 검색할 디렉토리 경로 목록
  • 디폴트값은 $ENV{PATH}의 값
  • 배열 레퍼런스, 또는 $ENV{PATH}에서 사용되는 경로 구분자(Unix에서는 :, MSWin32와 DOS에서는 ;)를 사용하는 문자열로 지정
• -noperldoc
  • 기본적으로, -verbose 값이 2 이상일 때 Pod::Usage는 perldoc을 호출한다. 이는 스크립트를 PAR로 압축할 경우 제대로 동작하지 않음.
  • -noperldoc 옵션을 사용하면 perldoc을 따로 호출하지 않고 간단한 텍스트 포매터(Pod::Text)를 사용하여 출력함

1.4. 설명

• 종료 상태값과 상세 단계가 둘 다 명시되지 않을 경우, 기본값은 종료 상태값 2, 상세 단계 0
• 종료 상태값만 명시된 경우, 종료값이 2보다 작으면 상세 단계는 1, 2 이상이면 상세 단계 0이 됨
• 상세 단계만 명시된 경우, 상세 단계가 0이면 종료 상태값 2, 그 외에는 종료 상태값 1이 됨
• 종료 상태값이 2보다 작은 경우 출력은 STDOUT에 출력됨. 그 외 경우는 STDERR에 출력됨

• 종료 상태값 0은 "성공"을 의미
• 종료 상태값 1은 정상적이지는 않지만 결함에 의한 것도 아닌 종료를 의미
• 2이상의 종료 상태값은 치명적인 에러를 의미
• 명령행 문법이 잘못되어서 사용법 메시지를 출력하는 경우는 STDERR로 출력. 반면 사용자가 명시적으로 요구하여(-help 옵션 등) 사용법 메시지를 출력하는 경우는 STDOUT으로 출력
• 사용자의 명시적 요구에 의해 사용법을 출력하는 경우는 종료 상태값 1을 반환하며 종료. 또한 이런 경우는 보다 상세한 사용법을 출력

    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. 예문

    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);

    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);

    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});

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

1.5.1. 추천 용례

• 실행할 때 사용된 명령행 문법에 에러가 발견될 경우 일종의 사용법 메시지를 STDERR에 출력해야 한다.
• 사용법 메시지를 STDOUT으로 출력하도록 하는 옵션(보통은 -H 또는 -help)을 제공해야 한다.
• 어떤 경우는 전체 문서를 STDOUT으로 출력하도록 하는 옵션(예를 들어 -man)을 제공할 수도 있다.

    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(-exitval => 2, -input => "/path/to/your/pod/docs");

1.7. 참고

2. 기타 & Comments