Moduł Pod::Usage

Uniwersytet Gdański - Instytut Matematyki - Zakład Informatyki - Strona domowa

Spis treści

  1. Co to jest?
  2. Argumenty
  3. Przykłady
  4. Dodatkowe informacje

Co to jest?

Wyświetla wiadomość o użyciu z wbudowanego dokumentu pod

Składnia
use Pod::Usage my $message_text = "This text precedes the usage message."; my $exit_status = 2; ## The exit status to use my $verbose_level = 0; ## The verbose level to use my $filehandle = \*STDERR; ## The filehandle to write to 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 wyświetli wiadomość użycia dla wywołującego skryptu (używając jego wewnętrznej dokumentacji POD) a później zakończy skrypt z pożądanym statusem zakończenia. Wiadomość wyświetlona może mieć jeden z trzech poziomów gadatliwości: Jeśli poziom gadatliwości to 0, wtedy tylko streszczenie jest wypisywane. Jeśli poziom gadatliwości to 1, wtedy streszczenie wraz z opisem (jeśli obecny) argumentów linii komend. Jeśli poziom gadatliwości to 2, wtedy cała strona podręcznika zostanie wyświetlona.

POD (Plain Old Documentation) jest to system dokumentacji 'inline' zaprojektowany przez samego Larrego Walla, służy do dokumentowania programów perlowych w wygodny i prosty sposób. Do pewnego stopnia dokumentację tę można integrować z programem perla. POD jest przez kompilator perla ignorowany. Sekwencja POD zaczyna się od dowolnego polecenia rozpoczynającego się w pierwszej kolumnie od znaku =.

O ile nie jest wyraźnie określone, domyślnie wartość zakończenia programu, poziom gadatliwości, oraz strumień wyjściowy są określane w następujący sposób:

  • Jeśli zarówno status zakończenia ani poziom gadatliwości nie są określone, wtedy domyślnie używany jest status 2 z poziomem gadatliwości 0.
  • Jeśli status zakończenia jest określony ale poziom gadatliwości nie, wtedy poziom gadatliwości będzie ustawiony na 1, jeśli status jest mniejszy niż 2 w przeciwnym wypadku 0.
  • Jeśli status zakończenia nie jest określony ale poziom gadatliwości jest dany, wtedy status domyślnie będzie ustawiony na 2, jeśli poziom gadatliwości jest 0, w przeciwnym przypadku 1.
  • Jeśli użyty status zakończenia jest mniejszy niż 2, wtedy wyniki są wyświetlane na standardowe wyjście. W przeciwnym przypadku na standardowe wyjście błędu.
    •

    Pomimo tego, że powyższe wydaje sie odrobinę zagmatwane, generalnie zachowuje się poprawnie w większości sytuacji. Określenie domyślniej wartości jaka ma zostać użyta jest opierana na następującej uniksowej konwencji:

  • Status zakończenia równy 0 oznacza sukces.
  • Status zakończenia równy 1 oznacza możliwą nienormalność, ale nie definitywne, przerwanie programu.
  • Status zakończenia równy 2 oznacza fatalny błąd.
  • Wiadomości użycia wyświetlone jako rezultat błędnej składni w linii poleceń powinny iść na standardowe wyjście błędu. Jednakże wiadomość o użyciu które są wyświetlane poprzez wyraźne żądanie powinny wychodzić na standardowe wyjście.
  • Jeśli wiadomość o użyciu była wyświetlona na żądanie użytkownika, zazwyczaj oczekiwane jest aby status zakończenia programu był równy 1.

    • pod2usage nie wymusza powyższej konwencji, ale ustawia ją jako domyślna jeśli nie sprecyzujesz inaczej. Umiejętność pod2usage() do akceptowania pojedyńczego numeru bądź też napisu do użycia jako niewinnie wyglądająca funkcja radząca sobie z wiadomościami o błędzie:

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

    Niektórzy użytkownicy mogą czuć że powyższa skrótowość nie jest czytelna ani spójna i mogą w zamian zrobić coś bardziej w tym rodzaju:

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

    Argumenty

    Dla pod2usage powinniśmy dać albo jeden argument, albo listę argumentów odpowiadającą haszowi. Kiedy dany jest pojedyńczy argument, powinien on odpowiadać dokładnie jednemu z poniższych:

  • Napis zawierający wiadomość tekstową która ma zostać wyświetlona przed wypisaniem wiadomości o użyciu
  • Wartość numeryczna odpowiadająca pożądanemu statusowi zakończenia programu
  • Wskaźnik do hasza

    • Jeśli dany jest więcej niż jeden argument wtedy zakładane jest, że cała lista argumentów to hasz. Jeśli hasz jest dostarczony (obojętnie czy jako lista czy wskaźnik) powinien zawierać jeden bądź więcej elementów z następującymi kluczami:

    -message
    -msg

    Tekst wiadomości która ma zostać wyświetlona przed wyświetleniem wiadomości o użyciu programu.

    -exitval

    Pożądany status zakończenia programu który ma zostać przekazany do funkcji exit(). Powinna to być liczba całkowita, bądź też napis "NOEXIT", aby zasygnalizować, że kontora powinna zostać zwrócona beż zakończenia wywoływanego procesu.

    -verbose

    Pożądany poziom gadatliwości który ma zostać użyty aby wypisywać wiadomości o użyciu. Jeśli ta wartość jest równa 0, wtedy jedynie paragraf SYNOPSIS (czyli jak sama nazwa wskazuje paragraf zawierający streszczenie opisu programu) z tego dokumentu pod zostanie wyświetlona. Jeśli odpowiadająca wartość wynosi 1, wtedy paragrafy SYNOPSIS, OPTIONS, ARGUMENTS (paragraf zawierający opis argumentów dostępnych w programie), bądź OPTIONS AND ARGUMENTS (paragraf zawierający opcje oraz argumenty które są dostępne w damym porogramie)zostaną wyświetlone. Jeśli odpowiadająca wartość wynosi 2 bądź więcej wtedy cała strona podręcznika zostanie wyświetlona.

    Specjalny poziom gadatliwości 99 potrzebuje również określenia parametru -sections; wtedy te paragrafy zostaną wypisane.

    -sections

    Napis reprezentujący listę wyboru paragrafów które mają zostać wypisane kiedy opcja -verbose jest ustawiona na 99. Przykładowo "NAME|SYNOPSIS|DESCRIPTION|VERSION" , czyli odpowiedni nazwa,streszczenie,opis,wersja.

    -output

    Wskaźnik do uchwytu do pliku, bądź ścieżka do pliku w którym wiadomość o użyciu ma zostać zapisana. Domyślnie jest to \*STDERR, chyba że wartość zakończenia programu jest mniejsza niż 2 (w takim przypadku domyślnie jest to \*STDOUTM).

    -input

    Wskaźnik do uchwytu do pliku, bądź też ścieżka do pliku z którego wywołany skrypt powinien czytać dokumentacje pod. Domyślnie jest to plik wskazywany przez $0 ($PROGRAM_NAME dla użytkowników English.pm).

    -pathlist

    Lista ścieżek do folderów. Jeśli plik wejściowy nie istnieje, wtedy szukany w zadanych folderach (w kolejności w jakiej foldery występują na liście). Domyślnie z listy folderów wskazywanych przez $ENV{PATH}. Lista może zostać określona zarówno jako wskaźnik do tablicy, jak i napis ścieżek do folderów który używa takiego samego separatora jakiego używa $ENV{PATH}.

    -noperldoc

    Domyślnie Pod::Usage wywoła perldoc kiedy -verbose >= 2 jest określone. To nie działa dobrze dla przykładu jeśli skrypt został spakowany przez PAR. Opcja -noperldoc zataja zewnętrzne wywołanie perldoc i używa prostego "formatera" tekstu Pod::Text aby przetworzyć POD.

    Przykłady

    Rekomendowane użycie tego modułu:
    use Getopt::Long; use Pod::Usage; my $man = 0; my $help = 0; ## Parse options and print usage if there is a syntax error, ## or if usage was explicitly requested. GetOptions('help|?' => \$help, man => \$man) or pod2usage(2); pod2usage(1) if $help; pod2usage(-verbose => 2) if $man; ## If no arguments were given, then allow STDIN to be used only ## if it's not connected to a terminal (otherwise print usage) 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

    Daje to dość schludny wynik. Bardzo przypominający standardowe zachowanie programów na platformach uniksowych.


    Jak można zauważyć zapewne jest to standardowe zachowanie użytownika który pierwszy raz uruchamia program :). Niestety mało kto stara się przeczytać najpierw dokumentacje. Dopiera kiedy coś nie działa po naszej myśli zaczynamy o tym myśleć. Moduł ten zapewnia poprawne zachowanie naszego programu w takich właśnie przypadkach.

    Dodatkowe informacje.

    Przydatne linki

    Dokumentacja tego modułu w cpan'ie

    Kontakt i informacje o autorze opracowania

    Autor modułu:

    Brad Appleton

    Autor przekładu: MD

    Numer GG: Słoneczko 2194164

    Uniwersytet Gdański - Instytut Informatyki - Strona domowa - Perl - Wyklady
    [c] Piotr Arłukowicz, materiały z tej strony udostępnione są na licencji GNU.