НАЗВА

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

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

getopt рядок-параметрів параметри-команди

getopt [параметри] [--] рядок-параметрів параметри-команди

getopt [параметри] -o|--options рядок-параметрів [параметри] [--] параметри-команди

ОПИС

getopt використовують для поділу (обробки) параметрів у рядках команд для спрощення обробки процедурами оболонки і перевірки коректності параметрів. Для цього буде використано процедури GNU getopt(3).

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

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

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

ПАРАМЕТРИ

-a, --alternative

Дозволити розпочинати довгі параметри одинарним «-».

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

Довгі (із багатьма символами) параметри, які має бути розпізнано. Можна одночасно вказати декілька параметрів, відокремивши їхні назви комами. Цей параметр можна вказувати декілька разів, остаточне значення довгих-параметрів є накопичувальним. Після кожної довгої назви параметра у довгих-параметрах можна дописати двокрапку, щоб вказати, що аргумент є обов'язковим, і дві двокрапки, щоб вказати, що є необов'язковий аргумент.

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

Назва, яку буде використано процедурами getopt(3) при звітуванні про помилки. Зауважте, що про помилки getopt(1) програма звітуватиме як про помилки getopt.

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

Короткі (односимвольні) параметри, які слід розпізнати. Якщо цей параметр не вказано, як рядок коротких параметрів буде використано перший параметр getopt, який не починається з «-» (і не є аргументом параметра команди). Після кожного символу параметра у коротких-параметрах може бути дописано одну двокрапку для позначення того, що у параметра є обов'язковий аргумент, і дві двокрапки для позначення того, що у параметра є необов'язковий аргумент. Першим символом коротких-параметрів може бути «+» або «-» для впливу на спосіб, у який буде оброблено параметри і виведено дані (див. розділ РЕЖИМИ СКАНУВАННЯ, щоб дізнатися більше).

-q, --quiet

Вимкнути звітування про помилки від getopt(3).

-Q, --quiet-output

Не створювати звичайне виведення. getopt(3) звітуватиме про помилки, якщо ви не використовували -q.

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

Встановити параметри екранування за параметрами оболонки. Якщо не вказано параметр -s, буде використано параметри обробки BASH. У поточній версії коректними аргументами є «sh», «bash», «csh» і «tcsh».

-T, --test

Перевірити, чи є getopt(1) у вашій системі розширеною версією чи застарілою. У відповідь ця версія програми не виведе жодних даних і встановить стан помилки 4. Інші реалізації getopt(1) та ця версія, якщо встановлено змінну середовища GETOPT_COMPATIBLE, виведуть «--» і стан помилки 0.

-u, --unquoted

Не екранувати виведені дані. Зауважте, що пробіли і спеціальні (залежно від командної оболонки) символи можуть у цьому режимі призвести до проблем (як це трапляється із іншими реалізаціями getopt(1)).

-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 повертає код помилки 0 для успішної обробки, 1, якщо getopt(3) повертає помилки, 2, якщо функції не вдалося обробити власні параметри, 3, якщо сталася внутрішня помилка, наприклад вичерпання пам'яті, і 4, якщо програму викликано із параметром -T.

ПРИКЛАДИ

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

СЕРЕДОВИЩЕ

POSIXLY_CORRECT

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

GETOPT_COMPATIBLE

Примушує getopt до використання першого формату виклику, як його описано у розділі КОРОТКИЙ ОПИС.

ВАДИ

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

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

АВТОР

Frodo Looijaard <frodo@frodo.looijaard.name>

ДИВ. ТАКОЖ

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

ЗВІТИ ПРО ВАДИ

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

ДОСТУПНІСТЬ

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

ПЕРЕКЛАД

Український переклад цієї сторінки посібника виконано Andriy Rysin <arysin@gmail.com> і Yuri Chornoivan <yurchor@ukr.net>

Цей переклад є безкоштовною документацією; будь ласка, ознайомтеся з умовами GNU General Public License Version 3. НЕ НАДАЄТЬСЯ ЖОДНИХ ГАРАНТІЙ.

Якщо ви знайшли помилки у перекладі цієї сторінки підручника, будь ласка, надішліть електронний лист до списку листування перекладачів: trans-uk@lists.fedoraproject.org.