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

-l, --longoptions długie-opcje

-n, --name nazwa-programu

-o, --options krótkie-opcje

-q, --quiet

-Q, --quiet-output

-s, --shell powłoka

-T, --test

-u, --unquoted

-h, --help

-V, --version

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

GETOPT_COMPATIBLE

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¶

Frodo Looijaard <frodo@frodo.looijaard.name>

ZOBACZ TAKŻE¶

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

ZGŁASZANIE BŁĘDÓW¶

Problemy należy zgłaszać w systemie śledzenia błędów <https://github.com/util-linux/util-linux/issues>.

DOSTĘPNOŚĆ¶

Polecenie getopt jest częścią pakietu util-linux, który można pobrać ze strony Archiwum jądra Linux <https://www.kernel.org/pub/linux/utils/util-linux/>.