Сообщение об использовании

В компьютерном программировании сообщение об использовании или справочное сообщение — это краткое сообщение, отображаемое программой, которая для выполнения использует интерфейс командной строки . Это сообщение обычно состоит из правильного использования командной строки для программы и включает список правильных командной строки, аргументов или параметров приемлемых для указанной программы.

Сообщения об использовании используются программой как быстрый способ проинформировать пользователя о правильном синтаксисе команд и не должны заменять правильные сообщения об ошибках или подробную документацию, такую ​​как справочная страница .

Шаблон

На Unix-подобных платформах сообщения об использовании обычно следуют одному и тому же шаблону:

• Они часто начинаются с команды «Использование:», за которой следует список аргументов .
• Для обозначения необязательных аргументов обычно используются квадратные скобки , а также их можно использовать для группировки параметров, которые необходимо указывать вместе.
• Для обозначения обязательных аргументов угловые скобки , соответствующие тем же правилам группировки, что и квадратные скобки. обычно используются
• Эксклюзивные параметры можно указать, разделив их вертикальными полосами внутри групп.

Примеры

Вот пример, основанный на NetBSD руководстве по стилю исходного кода :

Usage: program [-aDde] [-f | -g] [-n number] [-b b_arg | -c c_arg] req1 req2 [opt1 [opt2]]

Это будет означать, что «программу» следует вызывать с помощью:

• варианты без операндов: a, D, d, e (любой из которых можно опустить). Обратите внимание, что в этом случае некоторые параметры чувствительны к регистру.
• эксклюзивные варианты: f, g (обозначены вертикальной чертой)
• варианты с операндами: n
• эксклюзивные опции с операндами: b, c
• обязательные аргументы: req1, req2
• необязательный аргумент opt1, который можно использовать с opt2 или без него (в группе он помечен как необязательный с помощью другого набора квадратных скобок)
• необязательный аргумент opt2, для которого требуется opt1

Выполнение

Чтобы напечатать оператор использования в сценарии оболочки , можно написать:

case "$arg" in
...
h) printf 'Usage: %s parameter1 parameter2 ...\n' "$(basename "$0")"
   exit 0
   ;;
...
esac

Антипаттерны

Оператор использования не является сообщением об ошибке, но часто используется как ленивый способ избежать вывода полезного сообщения об ошибке. Заявление об использовании следует распечатывать только по специальному запросу пользователя (через --help, или -h, или -?или какой-либо аналогичный флаг или аргумент) и должен быть записан в стандартный вывод; Если пользователь ввел неверную командную строку, правильно написанная программа командной строки напечатает краткое сообщение об ошибке, описывающее точную ошибку, совершенную пользователем, вместо того, чтобы печатать оператор использования и требовать от пользователя выяснить, в чем заключалась ошибка. Например, если пользователю не удается передать правильное количество аргументов, одна строка, сообщающая об отсутствии аргумента, гораздо полезнее, чем несколько страниц вывода, обеспечивающих общее использование.

См. также

• Интерфейс командной строки