НАЗВА¶

getopt - обробка параметрів команди (розширена)

КОРОТКИЙ ОПИС¶

getopt optstring parameters

getopt [options] [--] optstring parameters

getopt [options] -o|--options optstring [options] [--] parameters

ОПИС¶

getopt is used to break up (parse) options in command lines for easy parsing by shell procedures, and to check for valid options. It uses the GNU getopt(3) routines to do this.

Параметри, з якими викликають getopt, може бути поділено на дві частини: параметри, які змінюють спосіб обробки даних у getopt (параметри і рядок-параметрів у розділі КОРОТКИЙ ОПИС), і параметри, які має бути оброблено (параметри-команди у розділі КОРОТКИЙ ОПИС). Друга частина розпочинається на першому параметрі команди, який не є аргументом параметра, або після першого виявлення '--'. Якщо не буде знайдено жодного параметра '-o' або '--options' у першій частині, як рядок коротких параметрів буде оброблено перший параметр другої частини.

Якщо встановлено змінну середовища GETOPT_COMPATIBLE або якщо першим параметром не є параметр програми (він не починається з «-», перший формат у КОРОТКОМУ ОПИСІ), getopt виведе дані у форматі, який сумісний із форматами інших версій getopt(1). Програма виконуватиме переставляння параметрів та розпізнаватиме необов’язкові аргументи (див. розділ СУМІСНІСТЬ, щоб дізнатися більше).

Традиційні реалізації getopt(1) не можуть працювати із пробілами або іншими (специфічними для командної оболонки) спеціальними символами в аргументах та параметрах, відмінних від параметрів програми. Щоб усунути цю проблему, у цій реалізації передбачено можливість створення екранованих виведених даних, які може бути повторно оброблено командною оболонкою (зазвичай, за допомогою команди eval). Це дає змогу зберегти відповідні символи, але вам доведеться викликати getopt у спосіб, який вже не буде сумісним із іншими версіями (другий або третій формат у КОРОТКОМУ ОПИСІ). Щоб визначити, чи встановлено версію getopt(1) із розширеними можливостями, можна скористатися тестовим параметром (-T).

ПАРАМЕТРИ¶

-a, --alternative

-l, --longoptions довгі-параметри

-n, --name назва-програми

-o, --options короткі-параметри

-q, --quiet

-Q, --quiet-output

-s, --shell оболонка

-T, --test

-u, --unquoted

-h, --help

-V, --version

ОБРОБКА¶

У цьому розділі наведено визначення формату другої частини параметрів getopt (параметри-команди у КОРОТКОМУ ОПИСІ). У наступному розділі (ВИВЕДЕННЯ) описано дані, які виводить програма. Ці параметри типово є параметрами з якими викликано функцію командної оболонки. Слід зважати на те, що кожен параметр, з яким викликано функцію командної оболонки, має відповідати точно одному параметру у списку параметрів getopt (див. розділ ПРИКЛАДИ). Уся обробка виконується підпрограмами GNU getopt(3).

Параметри буде оброблено зліва праворуч. Кожен параметр буде класифіковано як короткий, довгий, аргумент параметра або непараметричний запис.

Простим коротким параметром є запис, що містить «-» за яким вказано символ короткого параметра. Якщо у параметра є обов’язковий аргумент, його можна дописати безпосередньо після символу параметра або як наступний параметр (тобто запис, який відокремлено пробілом у рядку команди). Якщо у параметра є необов’язковий аргумент, його має бути записано безпосередньо після символу параметра, якщо його використано.

Можна вказати декілька коротких параметрів після одного символу «-», якщо усі ці параметри (окрім, можливо, останнього) не мають обов’язкових або додаткових аргументів.

Запис довгого параметра, зазвичай, починається з «--», за якими має бути вказано назву довгого параметра. Якщо у параметра є обов’язковий аргумент, його може бути вписано безпосередньо після назви довгого параметра із відокремленням «=» або як наступний аргумент (тобто параметр, який відокремлено пробілом у рядку команди). Якщо у параметра є необов’язковий аргумент, його має бути записано безпосередньо після назви довгого параметра із відокремленням «=», якщо його використано (якщо ви додасте «=» без аргументу після нього, програма вважатиме, що аргументу немає; це вада програми, див. розділ ВАДИ). Довгі параметри можна скорочувати, аж до межі, коли їхні скорочення є однозначними.

Усі параметри, запис яких не починається з «-», і які не є аргументами попереднього параметра, вважаються непараметричними записами. Усі параметри після параметра «--» завжди вважаються непараметричними записами. Якщо встановлено змінну середовища POSIXLY_CORRECT або якщо рядок коротких параметрів починається з «+», решту параметрів буде оброблено як непараметричний запис, щойно буде виявлено перший непараметричний запис.

ВИВЕДЕННЯ¶

Виведені дані буде створено для усіх елементів, які описано у попередньому розділі. Виведення буде виконано у тому самому порядку, у якому елементи вказано у вхідних даних, окрім непараметричних записів. Дані буде виведено у сумісному (неекранованому) режимі, або у такий спосіб, який зберігає пробіли та інші спеціальні символи в аргументах і непараметричних записах (див. НЕЙТРАЛІЗАЦІЯ). Коли скрипт командної оболонки оброблятиме виведені дані, буде зроблено припущення, що ці дані складаються з певних елементів, які може бути оброблено один за одним (за допомогою команди зсуву (shift) у більшості мов програмування). Обробка буде неідеальною у режимі без екранування, оскільки елементи може бути поділено у неочікуваних, якщо у них містяться пробіли або спеціальні символи.

Якщо з обробкою параметрів виникають проблеми, наприклад, через те, що не знайдено обов’язковий аргумент або не розпізнано параметр, до stderr буде повідомлено про помилку, програма не виводитиме даних для проблемного елемента і поверне ненульовий стан помилки.

Для короткого параметра одинарний символ «-» і символ параметра буде створено як один параметр. Якщо у параметра є аргумент, наступний параметр буде аргументом. Якщо параметр приймає необов’язковий аргумент, але такого аргументу не знайдено, буде створено наступний параметр, але порожній у режимі нейтралізації, і не буде створено другого параметра у режимі без нейтралізації (режимі сумісності). Зауважте, що у багатьох інших реалізаціях getopt(1) не передбачено підтримки необов’язкових аргументів.

Якщо вказано декілька коротких параметрів після одинарного символу «-», кожен з них буде у виведених даних окремим параметром.

Для довгого параметра буде виведено «--» і повну назву параметра, як один параметр. Так програма робитиме незалежно від того, чи було скорочено параметр або використано із одинарним «-» у вхідних даних. Аргументи буде оброблено так, як і для коротких записів параметрів.

Зазвичай, програма не створює жодних непараметричних записів у виведених даних до виведення усіх параметрів та їхніх аргументів. За параметрами буде додано «--» як окремий параметр, а вже за ним буде виведено непараметричні записи у порядку, у якому їх було виявлено, кожен як окремий параметр. Лише якщо першим символом рядка коротких параметрів є «-», буде виведено непараметричний запис у місці, де його було виявлено у вхідних даних (підтримки такого варіанта обробки не передбачено, якщо використано перший з форматів розділу КОРОТКИЙ ОПИС; у випадку використання цього формату усі попередні символи «-» і «+» буде проігноровано).

ЛАПКИ¶

У режимі сумісності програма не зможе обробляти пробіли або «спеціальні» символи в аргументах або непараметричних записах. Коли виведені дані буде передано скрипту оболонки, скрипт не зможе визначити, як має бути поділено на окремі параметри виведені дані. Щоб обійти цю проблему, у цій реалізації програми запропоновано скористатися нейтралізацією. Ідея полягає у тому, що дані буде виведено із лапками навколо кожного з параметрів. Коли виведені дані буде ще раз передано командній оболонці (зазвичай, за допомогою команди eval), вона належним чином поділить дані на окремі параметри.

Нейтралізацію не буде увімкнено, якщо встановлено змінну середовища GETOPT_COMPATIBLE, якщо використано першу форму з розділу КОРОТКИЙ ОПИС або якщо буде виявлено параметр «-u».

У різних оболонках використовують різні угоди щодо нейтралізації. Ви можете скористатися параметром «-s» для вибору тієї оболонки, якою ви користуєтеся. У поточній версії передбачено підтримку таких оболонок: «sh», «bash», «csh» і «tcsh». Насправді, програма розрізняє лише два «різновиди»: sh-подібні угоди щодо нейтралізації та csh-подібні угоди щодо нейтралізації. Ймовірно, якщо ви користуєтеся іншою мовою скриптів оболонок, у ній використано один із вказаних вище різновидів нейтралізації.

РЕЖИМИ СКАНУВАННЯ¶

Першим символом рядка коротких параметрів може бути «-» або «+» на позначення спеціального режиму сканування. Якщо використано перший формат виклику з розділу КОРОТКИЙ ОПИС, їх буде проігноровано; втім, перевірку значення змінної середовища POSIXLY_CORRECT все одно буде виконано.

Якщо першим символом є «+ або якщо встановлено змінну середовища POSIXLY_CORRECT, обробку буде зупинено, щойно буде виявлено перший непараметричний запис (тобто параметр, який не починається з «-»), який не є аргументом параметра. Решту параметрів буде оброблено як непараметричні записи.

Якщо першим символом є «-», непараметричні записи буде виведено на місці, де їх було знайдено; за звичайних умов, їх буде зібрано наприкінці виведених даних після створеного параметра «--». Зауважте, що цей параметр «--» буде створеним, але у цьому режимі він завжди буде останнім параметром.

СУМІСНІСТЬ¶

Цю версію getopt(1) було створено якомога суміснішою із іншими версіями. Зазвичай, ви можете просто замінити їх цією версією без будь-яких змін у командах і з деякими перевагами у можливостях.

Якщо першим символом першого параметра getopt не є «-», getopt перейде у режим сумісності. Програма оброблятиме свій перший параметр як рядок коротких параметрів. Буде також оброблено усю решту аргументів. Програма виконуватиме переставляння параметрів (тобто усі непараметричні записи буде виведено наприкінці), якщо не встановлено змінної середовища POSIXLY_CORRECT. Якщо змінну встановлено, getopt допише «+» перед короткими параметрами автоматично.

Змінна середовища GETOPT_COMPATIBLE примушує getopt до роботи у режимі сумісності. Одночасне встановлення значення цієї змінної середовища та змінної середовища POSIXLY_CORRECT вмикає режим повної сумісності для «складних» програм. Зазвичай же, потреби у використанні цих змінних немає.

У режимі сумісності початкові символи «-» і «+» у коротких рядках параметрів буде проігноровано.

ПОВЕРНУТІ КОДИ¶

getopt returns error code 0 for successful parsing, 1 if getopt(3) returns errors, 2 if it does not understand its own parameters, 3 if an internal error occurs like out-of-memory, and 4 if it is called with -T.

ПРИКЛАДИ¶

Приклади скриптів для (ba)sh і (t)csh є частиною дистрибутива getopt(1), їх буде встановлено до каталогу /usr/share/doc/util-linux.

СЕРЕДОВИЩЕ¶

POSIXLY_CORRECT

GETOPT_COMPATIBLE

ВАДИ¶

getopt(3) can parse long options with optional arguments that are given an empty optional argument (but cannot do this for short options). This getopt(1) treats optional arguments that are empty as if they were not present.

Синтаксис, якщо ви не хочете використовувати жодної змінної коротких параметрів, не є аж надто інтуїтивно зрозумілим (вам варто встановлювати для них явним чином значення порожнього рядка).

АВТОР¶

Frodo Looijaard <frodo@frodo.looijaard.name>

ТАКОЖ ПЕРЕГЛЯНЬТЕ¶

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

ЯК НАДІСЛАТИ ЗВІТ ПРО ВАДИ¶

Для звітування щодо вад скористайтеся системою стеження за вадами - <https://github.com/util-linux/util-linux/issues>.

ДОСТУП ДО ПРОГРАМИ¶

Програма getopt є частиною пакунка util-linux, який можна отримати з архіву ядра Linux <https://www.kernel.org/pub/linux/utils/util-linux/>.