GETOPT(1)

NAZWA
getopt - analizuje opcje wiersza poleceń (rozszerzone)

SKŁADNIA

getopt łańcuch-opcji parametry

getopt [opcje] [--] łańcuch-opcji parametry

getopt [opcje] -o|--options łańcuch-opcji [opcje] [--] parametry

OPIS

getopt służy do rozdzielenia (analizy) opcji w wierszu poleceń, w celu łatwego analizowania przez funkcje powłoki oraz sprawdzenia poprawności opcji. Program wykorzystuje do tego celu funkcje GNU getopt(3).

Parametry, z którymi wywoływany jest getopt, można podzielić na dwie części: opcje modyfikujące sposób analizy getopt (opcje i łańcuch-opcji w SKŁADNI) oraz parametry do przeanalizowania (parametry w SKŁADNI). Druga część rozpoczyna się od pierwszego parametru nieopcyjnego, który nie jest argumentem opcji lub po pierwszym wystąpieniu "--". Jeśli w pierwszej części nie wystąpi "-o" ani "--options", to pierwszy parametr drugiej części jest intepretowany jako łańcuch krótkich opcji.

Jeśli ustawiona jest zmienna środowiskowa GETOPT_COMPATIBLE lub gdy pierwszy parametr nie jest opcją (nie rozpoczyna się od "-", pierwszy format w SKŁADNI), getopt utworzy wyjście kompatybilne z innymi wersjami getopt(1). Mimo to, zmieniona zostanie kolejność parametrów oraz zostaną rozpoznane argumenty opcjonalne (więcej informacji w rozdziale KOMPATYBILNOŚĆ).

Tradycyjne implementacje getopt(1) nie radzą sobie z białymi znakami i innymi (zależnymi od powłoki) znakami specjalnymi w argumentach i parametrach niebędącymi opcjami. Aby rozwiązać ten problem, niniejsza implementacja potrafi utworzyć wyjście cytowane, które musi być ponownie zinterpretowane przez powłokę (zwykle poleceniem eval). Dzięki temu wspomniane znaki zostaną zachowane, ale konieczne jest wywołanie getopt w sposób, który nie będzie kompatybilny z innymi wersjami (drugi lub trzeci format w SKŁADNI). Aby określić, czy zainstalowano rozszerzoną wersję getopt(1), można skorzystać ze specjalnej opcji testowania (-T).

OPCJE

-a, --alternative
    Pozwala na rozpoczynanie długich opcji pojedynczym "-".

-l, --longoptions długie-opcje
    The long (multi-character) options to be recognized. More than one option name may be specified at once, by separating the names with commas, whitespace (spaces, tabs, or newlines). This option may be given more than once, the longopts are cumulative. Each long option name in longopts may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument.

-n, --name nazwa-programu
    Nazwa, która posłuży funkcjom getopt(3) do zgłaszania błędów. Proszę zauważyć, że błędy samego getopt(1) są wciąż zgłaszane jako pochodzące z getopt.

-o, --options krótkie-opcje
    Krótkie (jednoznakowe) opcje do rozpoznania. Jeśli nie poda się tej opcji, pierwszy parametr getopt niezaczynający się od "-" (i niebędącym argumentem opcji) służy jako łańcuch krótkich opcji. Po każdym znaku któtkich opcji w krótkich-opcjach można dopisać jeden dwukropek - aby wskazać że jest to argument wymagany albo dwa dwukropki - oznaczające argument opcjonalny. Pierwszy znak w krótkich-opcjach równy "+" lub "-" wpływa na sposób analizy i tworzenia wyjścia (więcej szczegółów w rozdziale TRYBY SKANOWANIA).

-q, --quiet
    Wyłącza zgłaszanie błędów przez getopt(3).

-Q, --quiet-output
    Nie tworzy normalnego wyjścia. Błędy są wciąż zgłaszane przez getopt(3), chyba że podano też opcję -q.

-s, --shell powłoka
    Ustawia konwencję cytowania na używaną przez powłokę. Jeśli nie podano opcji -s stosowane są konwencje powłoki BASH. Prawidłowymi argumentami są obecnie: "sh", "bash", "csh" i "tcsh".

-T, --test
    Sprawdza, czy używany program getopt(1) jest opisywaną tu wersją rozszerzoną, czy starą wersją. Niniejsza wersja nie tworzy wyjścia i ustawia status błędu na 4. Inne implementacje getopt(1) oraz ta wersja, jeśli ustawiono zmienną środowiskową GETOPT_COMPATIBLE, zwróci "--" i status błędu 0.

-u, --unquoted
    Nie używa cytowania w wyjściu. Proszę zauważyć, że białe znaki i znaki specjalne (zależne od powłoki) mogą spowodować w tym trybie rozgardiasz (podobnie jak dzieje się w innych implementacjach getopt(1)).

-U, --unknown
    Leave unknown options as they are and suppress error messages from getopt(3). Since there is no way to know whether an unknown option requires an argument, a non-option argument that follows the unknown option after a whitespace, is considered an option argument, therefore the argument will be left untouched and printed next to the respective unknown option. To prevent unexpected behavior, short options should be specified individually.

-h, --help
    Wyświetla ten tekst i wychodzi.

-V, --version
    Wyświetla wersję i wychodzi.

ANALIZOWANIE

Niniejszy rozdział określa format drugiej części parametrów getopt (parametry w SKŁADNI). Kolejny rozdział (WYJŚCIE) opisuje tworzone wyjście. Parametry te były zwykle parametrami, z którymi wywołano funkcję powłoki. Należy uważać, aby każdy parametr, z którym wywołano funkcję powłoki, odpowiadał dokładnie jednemu parametrowi w liście parametrów getopt (zob. PRZYKŁADY). Cała analiza jest dokonywana przez funkcje getopt(3) GNU.

Parametry są analizowane od lewej do prawej strony. Każdy parametr jest klasyfikowany jako: krótka opcja, długa opcja, argument do opcji albo parametr niebędący opcją.

Prostą krótką opcją jest "-" po którym następuje znak krótkiej opcji, z wyłączeniem znaków ":", ";" oraz "?", które są zarezerwowane przez getopt(3). Jeśli opcja ma wymagany argument, może być on zapisany bezpośrednio po znaku opcji lub jako następny parametr (tj. rozdzielony białym znakiem w wierszu polecenia). Jeśli opcja ma argument opcjonalny, jeśli jest obecny, musi być podany bezpośrednio po znaku opcji (bez odstępu).

Po jednym "-" można podać wiele krótkich opcji, o ile tylko nie mają one argumentów wymaganych lub opcjonalnych (to ograniczenie nie dotyczy ostatniej opcji).

Długie opcje zaczynają się zwykle od "--", po którym następuje nazwa długiej opcji. Jeśli opcja ma argument wymagany, może być: zapisany bezpośrednio po nazwie długiej opcji, rozdzielony znakiem '=' albo być następnym argumentem (tj. rozdzielony białym znakiem w wierszu polecenia). Jeśli opcja ma argument opcjonalny, jeśli jest obecny, musi być podany tuż po nazwie długiej opcji, rozdzielony od niej znakiem "=" (jeśli poda się sam znak "=" jest to interpretowane jak gdyby argument nie był obecny; jest to niewielki błąd, zob. USTERKI). Nazwy długich opcji można skracać, o ile tylko tak skrócona nazwa nie będzie niejednoznaczna.

Każdy parametr niezaczynający się od "-" oraz niebędący wymaganym argumentem poprzedniej opcji jest parametrem nieopcyjnym. Każdy parametr po "--" jest zawsze interpretowany jako parametr nieopcyjny. Jeśli ustawiona jest zmienna środowiskowa POSIXLY_CORRECT lub gdy łańcuch krótkiej opcji zaczyna się znakiem "+", wszystkie pozostałe parametry są interpretowane jako parametry nieopcyjne po tym, jak zostanie odnaleziony pierwszy parametr nieopcyjny.

WYJŚCIE

Wyjście tworzone jest dla każdego elementu opisanego w poprzednim rozdziale. Wyjście jest tworzone w tej samej kolejności jak elementy podane w wejściu, z wyjątkiem parametrów nieopcyjnych. Wyjście może być tworzone w trybie kompatybilności (niecytowanym) lub w taki sposób, że zachowywane są białe znaki i inne specjalne znaki wewnętrz argumentów i parametrów nieopcyjnych (zob. CYTOWANIE). Gdy wyjście jest analizowane w skrypcie powłoki, będzie wyglądało na utworzone z wyraźnie oddzielnych elementów, które mogą być przetwarzane pojedynczo (w większości języków powłoki za pomocą polecenia shift). Jest to niedoskonałe w trybie niecytowanym, ponieważ elementy mogą być przełamane w nieoczekiwanych miejscach, jeśli zawierają białe znaki lub znaki specjalne.

Jeśli przy analizie parametrów wystąpią problemy np. z powodu braku wymaganego argumentu lub nierozpoznania opcji, na standardowe wyjście błędó zostanie zgłoszony błąd, dla problematycznego elementu nie zostanie utworzone wyjście, a program zwróci niezerowy status błędu.

W przypadku krótkiej opcji, jako jeden parametr zostanie utworzony pojedynczy "-" wraz ze znakiem opcji. Jeśli opcja przyjmuje argument opcjonalny, lecz nie zostanie on odnaleziony, w trybie cytowania zostanie utworzony następny, pusty parametr, natomiast w trybie niecytowanym (kompatybilności) drugi parametr nie będzie tworzony. Proszę zauważyć, że wiele innych implementacji getopt(1) nie obśługuje argumentów opcjonalnych.

Jeśli po pojedynczym "-" podano wiele krótkich opcji, każda będzie obecna w wyjściu jako oddzielny parametr.

W przypadku długiej opcji, jako jeden parametr zostanie utworzone "--" wraz z pełną nazwą opcji. Tak dzieje się niezależnie od tego, czy użyto skróconej nazwy opcji, albo opcję podano w wejściu z pojedynczym "-". Argumenty są obsługiwane w taki sam sposób jak w przypadku krótkich opcji.

Zwykle wyjście parametrów nieopcyjnych nie jest tworzone aż do momentu wygenerowania wszystkich opcji i ich argumentów. Następnie tworzone jest "--"' jako pojedynczy parametr, a po nim następują parametry nieopcyjne, w kolejności ich odnalezienia, każdy jako oddzielny parametr. Tylko gdy pierwszym znakiem łańcucha krótkich opcji był "-", wyjście parametrów nieopcyjnych jest tworzone w miejscu jego odnalezienia na werjściu (nie jest to obsługiwane w pierwszym formacie SKŁADNI; w takim przypadku wszystkie poprzedzające wystąpienia "-" i "+" są ignorowane).

CYTOWANIE

W trybie kompatybilności, białe znaki oraz znaki "specjalne" w argumentach lub parametrach nieopcyjnych nie są poprawnie obsługiwane. W miarę wysyłania wyjścia do skryptu powłoki, skrypt nie wie w jaki sposób ma rozdzielić wyjście na poszczególne parametry. Aby naprawić ten problem, niniejsza implementacja oferuje cytowanie. Dzięki temu tworzone wyjście posiada znaki cytowania wokół każdego parametru. Gdy to wyjście jest następnie ponownie przesyłane do powłoki (zwykle poleceniem eval powłoki), jest poprawnie dzielone na poszczególne parametry.

Cytowanie nie jest włączane, gdy ustawiona jest zmienna środowiskowa GETOPT_COMPATIBLE, korzysta się z pierwszej postaci SKŁADNI lub gdy poda się opcję "-u".

Różne powłoki korzystają z różnych konwencji cytowania. Opcja "-s" służy do wyboru używanej powłoki. Obecnie obsługiwane są następujące powłoki: "sh", "bash", "csh" i "tcsh". W praktyce rozróżniane są jedynie dwie odmiany: konwencje cytowania w stylu sh i w stylu csh. Nawet jeśli korzysta się z innego języka skryptowego powłoki, prawdopodobnie jedna z tych dwóch konwencji będzie prawidłowa.

TRYBY SKANOWANIA

Pierwszym znakiem łańcucha krótkich opcji może być "-" lub "+" wskazując specjalny tryb skanowania. Jeśli użyta zostanie pierwsza postać SKŁADNI, znaki te są ignorowane, ale wciąż sprawdzana jest zmienna środowiskowa POSIXLY_CORRECT.

Jeśli pierwszym znakiem jest "+" lub ustawiona jest zmienna środowiskowa POSIXLY_CORRECT, analiza zatrzymuje się po napotkaniu pierwszego parametru nieopcyjnego (tj. parametru niezaczynającego się od "-"), który nie jest argumentem opcji. Pozostałe parametry są interpretowane jako parametry nieopcyjne.

Jeśli pierwszym znakiem jest "-", parametry nieopcyjne są wypisywane w miejscu ich odnalezienia; w zwykłym trybie działania są zbierane na końcu wyjścia, po wygenerowaniu parametru "--". Proszę zauważyć, że parametr "--" też jest generowany, ale w opisywanym trybie specjalnym będzie zawsze ostatnim parametrem.

ZGODNOŚĆ

Niniejszą wersję getopt(1) napisano w sposób zachowujący maksymalną kompatybilność z innymi wersjami programu. Zwykle można je zastąpić tą wersję bez konieczności dokonywania jakichkolwiek modyfikacji, a otrzymując pewne korzyści.

Jeśli pierwszym znakiem pierwszego parametru getopt nie jest "-", getopt wejdzie w tryb kompatybilności. Zinterpretuje swój pierwszy parametr jako łańcuch krótkich opcji, a wszystkie pozostałe argumenty zostaną przeanalizowane. Wciąż dokona zmiany kolejności parametrów (tj. wszystkie parametry nieopcyjne są wypisywane na końcu), chyba że ustawiona jest zmienna środowiskowa POSIXLY_CORRECT - wówczas getopt automatycznie poprzedzi krótkie opcje znakiem "+".

Zmienna środowiskowa GETOPT_COMPATIBLE zmusza getopt do wejścia w tryb kompatybilności. Jej łącze ustawienie ze zmienną środowiskową POSIXLY_CORRECT gwarantuje 100% kompatybilność dla "trudnych" programów. Zwykle żadna z nich nie jest jednak konieczna.

W trybie kompatybilności, początkowe znaki "-" i "+" w łańcuchu krótkich opcji są ignorowane.

KODY ZAKOŃCZENIA

getopt zwraca kod błędu 0 w przypadku pomyślnej analizy; 1 jeśli getopt(3) zwróci błędy; 2 jeśli nie rozpoznaje swoich własnych parametrów; 3 jeśli wystąpi błąd wewnętrzny, taki jak brak pamięci oraz 4 gdy zostanie wywołany z opcją -T.

PRZYKŁADY

Przykładowe skrypty dla powłok (ba)sh i (t)csh są dostarczane razem z programem getopt(1) i instalowane w katalogu /usr/share/doc/util-linux.

ŚRODOWISKO

POSIXLY_CORRECT
    Zmienna sprawdzane przez funkcje getopt(3). Jeśli jest ustawiona, analiza zatrzymuje się po napotkaniu parametru niebędącego opcją ani argumentem opcji. Wszystkie pozostałe parametry są również interpretowane jako parametry nieopcyjne, niezależnie od tego, czy zaczynają się od znaku "-".

GETOPT_COMPATIBLE
    Zmusza getopt do użycie pierwszego formatu wywołania opisanego w SKŁADNI.

USTERKI

getopt(3) potrafi analizować długie opcje z argumentami opcjonalnymi, które są podane jako pusty argumenty opcjonalne (lecz nie może tego czynić wobec krótkich opcji). Ten program getopt(1) traktuje puste argumenty tak, jakby były nieobecne.

Składnia nie jest zbyt intuicyjna, gdy nie są potrzebne zmienne z krótkimi opcjami (trzeba je ustawić jawnie na pusty łańcuch).

AUTOR

ZOBACZ TAKŻE

bash(1), tcsh(1), getopt(3)

ZGŁASZANIE BŁĘDÓW

Problemy należy zgłaszać w

DOSTĘPNOŚĆ

Polecenie getopt jest częścią pakietu util-linux, który można pobrać ze strony