Perl/Pod-Usage 페이지의 소스 보기
마지막으로 [b]
-- Loading page list... --
내용출력
로그인[l]
Diary
[f]
최근변경내역
[r]
페이지목록[i]
횡설수설[2]
게시판[3]
링크
수정할 수 없습니다: Perl/Pod-Usage 는 읽기 전용 페이지입니다.
= Pod::Usage 코어 모듈 = <toc> == # perldoc Pod::Usage 정리 == Perldoc:Pod::Usage 내용 정리 === # 이름 === Pod::Usage, pod2usage() - 프로그램에 포함된 pod 문서로부터 사용법 메시지를 출력 === # 개괄 === {{{#!vim perl 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 ) }}} === # 인자 === '''pod2usage'''는 하나의 인자, 또는 해쉬에 대응되는 인자 리스트를 인자로 받는다. 하나의 인자를 받을 경우는 그 인자는 다음 셋 중 하나여야 한다: * 사용법 메시지 바로 앞에 출력될 텍스트 메시지를 담고 있는 문자열 * 종료 상태값에 해당하는 숫자값 * 해쉬 레퍼런스 인자로 리스트 또는 해쉬 레퍼런스로 들어올 경우, 다음 요소 중 하나 이상이 포함되어 있어야 한다: * <code>-message</code> 또는 <code>-msg</code> ** 사용법 메시지 바로 앞에 출력될 텍스트 메시지를 담고 있는 문자열 * <code>-exitval</code> ** exit()에 전달될 종료 상태값. 정수값 또는 "NOEXIT"문자열. "NOEXIT"의 경우 프로세스를 종료하지 않고 리턴하게 한다. * <code>-verbose</code> ** 사용법 메시지를 출력할 때 얼마나 자세히 출력할 것인지 지정. ** 0일 경우, POD문서의 "SYNOPSIS" 섹션만 출력됨 ** 1일 경우, "SYNOPSIS" 섹션과 더불어, "OPTIONS", "ARGUMENTS", "OPTIONS AND ARGUMENTS" 섹션이 출력됨 ** 2일 경우, 전체 맨페이지가 출력됨 ** 99일 경우, -sections 파라메터에서 지정한 섹션들이 출력됨 (Perldoc:Pod::Select 참조) * <code>-sections</code> ** -verbose 값이 99일 때 출력할 섹션들의 목록 ** <code>"NAME|SYNOPSIS|DESCRIPTION|VERSION"</code>과 같이 문자열로 설정할 수도 있고 ** <code>[ qw(fred fred/subsection) ]</code>과 같이 배열 레퍼런스로 설정할 수도 있다 {{{#!vim perl pod2usage(-verbose => 99, -sections => [ qw(fred fred/subsection) ] ); }}} * <code>-output</code> ** 사용법 메시지가 출력될 파일핸들 레퍼런스 또는 파일 경로명. ** 종료상태값이 2 이상일 때 디폴트값은 <code>\*STDERR</code>, 종료상태값이 2보다 작을 때는 <code>\*STDOUT</code> * <code>-input</code> ** 스크립트의 POD 문서를 읽어들일 파일핸들 레퍼런스 또는 파일 경로명 ** 디폴트값은 <code>$0</code>(English.pm을 사용할 경우 <code>$PROGRAM_NAME</code>) 변수의 값 ** 만일 모듈에서 pod2usage()를 호출하게 하면서 모듈의 POD를 출력하고자 한다면, 다음과 같이 하라: {{{#!vim perl use Pod::Find qw(pod_where); pod2usage( -input => pod_where({-inc => 1}, __PACKAGE__) ); }}} * <code>-pathlist</code> ** 입력 파일이 존재하지 않을 경우, 그 파일을 검색할 디렉토리 경로 목록 ** 디폴트값은 <code>$ENV{PATH}</code>의 값 ** 배열 레퍼런스, 또는 <code>$ENV{PATH}</code>에서 사용되는 경로 구분자(Unix에서는 <code>:</code>, MSWin32와 DOS에서는 <code>;</code>)를 사용하는 문자열로 지정 * <code>-noperldoc</code> ** 기본적으로, -verbose 값이 2 이상일 때 Pod::Usage는 Perldoc:perldoc""을 호출한다. 이는 스크립트를 Cpan:PAR""로 압축할 경우 제대로 동작하지 않음. ** -noperldoc 옵션을 사용하면 perldoc을 따로 호출하지 않고 간단한 텍스트 포매터(Perldoc:Pod::Text"")를 사용하여 출력함 === # 설명 === (기본 개념과 상세 단계에 관한 설명은 앞에서 언급되었으므로 생략) 명시적으로 지정하지 않는 경우, 종료 상태값, 상세 단계, 출력에 사용할 스트림은 다음과 같이 결정된다: * 종료 상태값과 상세 단계가 둘 다 명시되지 않을 경우, 기본값은 종료 상태값 2, 상세 단계 0 * 종료 상태값만 명시된 경우, 종료값이 2보다 작으면 상세 단계는 1, 2 이상이면 상세 단계 0이 됨 * 상세 단계만 명시된 경우, 상세 단계가 0이면 종료 상태값 2, 그 외에는 종료 상태값 1이 됨 * 종료 상태값이 2보다 작은 경우 출력은 <code>STDOUT</code>에 출력됨. 그 외 경우는 <code>STDERR</code>에 출력됨 다소 복잡해 보이는 이런 동작은, 다음과 같은 Unix 관례에 기반하여 대부분의 경우 올바른 결과를 낸다: * 종료 상태값 0은 "성공"을 의미 * 종료 상태값 1은 정상적이지는 않지만 결함에 의한 것도 아닌 종료를 의미 * 2이상의 종료 상태값은 치명적인 에러를 의미 * 명령행 문법이 잘못되어서 사용법 메시지를 출력하는 경우는 <code>STDERR</code>로 출력. 반면 사용자가 명시적으로 요구하여(-help 옵션 등) 사용법 메시지를 출력하는 경우는 <code>STDOUT</code>으로 출력 * 사용자의 명시적 요구에 의해 사용법을 출력하는 경우는 종료 상태값 1을 반환하며 종료. 또한 이런 경우는 보다 상세한 사용법을 출력 인자 하나를 받아서 적절하게 처리하는 예: {{{#!vim perl 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); }}} 위처럼 간략하게 표현한게 읽기 어렵거나 일관성이 없어서 싫다면 아래와 같은 식으로 쓸 수도 있다: {{{#!vim perl 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); }}} 동일한 결과를 내는 다양한 표현을 "예문"에서 확인하라. === # 예문 === 다음의 각 구문은 모두 "SYNOPSIS" 섹션을 <code>STDERR</code>로 출력한 후, 종료 상태값 2를 반환하며 종료한다. {{{#!vim perl 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); }}} 다음의 각 구문은 모두 <code>STDERR</code>에 "Syntax error."라는 메시지와 개행문자를 출력하고, "SYNOPSIS" 섹션을 출력한 후, 종료 상태값 2를 반환하며 종료한다. {{{#!vim perl 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" 섹션을 <code>STDOUT</code>으로 출력하고 종료 상태값 1을 반환하며 종료한다. {{{#!vim perl 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}); }}} 다음의 각 구문은 모두 전체 매뉴얼 페이지를 <code>STDOUT</code>으로 출력한 후, 종료 상태값 1을 반환하며 종료한다. {{{#!vim perl pod2usage(-verbose => 2); pod2usage({-verbose => 2, -output => \*STDOUT}); pod2usage(-exitval => 1, -verbose => 2); pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT}); }}} ==== # 추천 용례 ==== * 실행할 때 사용된 명령행 문법에 에러가 발견될 경우 일종의 사용법 메시지를 <code>STDERR</code>에 출력해야 한다. * 사용법 메시지를 <code>STDOUT</code>으로 출력하도록 하는 옵션(보통은 <code>-H</code> 또는 <code>-help</code>)을 제공해야 한다. * 어떤 경우는 전체 문서를 <code>STDOUT</code>으로 출력하도록 하는 옵션(예를 들어 <code>-man</code>)을 제공할 수도 있다. 아래 예제는 Getopt::Long과 조합하여 위의 기능을 전부 제공하는 코드: {{{#!vim perl 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 }}} === # 경고 === 기본적으로 pod2usage()는 <code>$0</code>의 값을 pod 입력 파일의 경로로 사용한다. 그러나 Perl이 실행되는 모든 시스템에서 <code>$0</code>이 올바르게 설정되지는 않는다. (<code>$0</code>이 발견되지 않는 경우 pod2usage()가 <code>$ENV{PATH}</code>나 <code>-pathlist</code> 옵션에 있는 디렉토리 목록을 검색하긴 하지만) 이런 시스템에서는, 명시적으로 pod 문서의 경로를 지정해 주어야 한다: {{{#!vim perl pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs"); }}} 실행하는 스크립트명이 상대 경로로 지정되었고, 스크립트 자체가 pod2usage를 호출하기 이전에 현재 작업 디렉토리를 변경하는 경우 (Perldoc:chdir 참조), 견고한 플랫폼에서는 Pod::Usage가 실패할 수 있다. 그러지 않도록 하라<footnote(작업디렉토리를 pod2usage 호출 이전에 변경하지 말라는 의미인 듯)> === # 참고 === Perldoc:Pod::Parser, Perldoc:Getopt::Long ([[/Getopt-Long]]), Perldoc:Pod::Find == # 기타 & Comments == <div class="comments"> <longcomments(100)> ---- </div> ---- [[컴퓨터분류]] [[Perl]]
Perl/Pod-Usage
페이지로 돌아가기 |
다른 수정본 보기
![[첫화면으로]](/raymundo_logo.jpg){kind=logo}
Perl/Pod-Usage 페이지의 소스 보기Perl/Pod-Usage 페이지의 소스 보기