Книга: Разработка приложений в среде Linux. Второе издание

26.2.4. Автоматические справочные сообщения

26.2.4. Автоматические справочные сообщения

Одним из преимуществ использования библиотеки popt является ее способность автоматически генерировать справочные сообщения и сообщения об использовании. В справочных сообщениях указывается каждый параметр командной строки и приводится его подробное описание, а в сообщениях об использовании приводится краткий перечень доступных параметров без какого-либо сопроводительного текста. Для создания каждого типа сообщения в библиотеке popt предусмотрена отдельная функция.

#include <popt.h>
void poptPrintHelp(poptContext con, FILE * f, int flags);
void poptPrintUsage(poptContext con, FILE * f, int flags);

Обе эти функции ведут себя практически одинаково, записывая соответствующий тип сообщения в файл f. Аргумент flags на данный момент не используется ни одной из этих функций, и должен быть равен нулю для совместимости с будущими версиями библиотеки popt.

Поскольку за справочное сообщение отвечает параметр --help, а за сообщение об использовании — параметр --usage, библиотека popt предлагает простой способ добавления этих двух параметров в программу. Чтобы добавить эти параметры в таблицу параметров, можно использовать макрос POPT_AUTOHELP[185], который выводит соответствующие сообщения в STDOUT и закрывается после возвращения кода 0[186]. В следующем примере показана таблица параметров в файле grep.с; мы должны добавить одну строку в таблицу параметров для grep, чтобы активизировать автоматическое генерирование справочных сообщений.

 95: struct poptOption optionsTable[] = {
 96:  { "extended-regexp", 'E', POPT_ARG_VAL,
 97:    &mode, MODE_EXTENDED,
 98:    "шаблоном для соответствия является расширенное регулярное "
 99:    "выражение" },
100:  { "fixed-strings", 'F', POPT_ARG_VAL,
101:    &mode, MODE_FIXED,
102:    "шаблоном для соответствия является базовая строка, (не "
103:    "регулярное выражение)", NULL },
104:  { "basic-regexp", 'G', POPT_ARG_VAL,
105:    &mode, MODE_REGEXP,
106:    "шаблоном для соответствия является базовое регулярное выражение" },
107:  { "ignore-case", 'i', POPT_ARG_NONE, &ignoreCase, 0,
108:    "выполнять поиск, чувствительный к регистру", NULL },
109:  { "max-count", 'm', POPT_ARG_INT, &maxCount, 0,
110:    "завершить после получения N совпадений", "N" },
111:  { "regexp", 'е', POPT_ARG_STRING, &pattern, 0,
112:    "регулярное выражение для поиска", "pattern" },
113:  POPT_AUTOHELP
114:  { NULL, ' ', POPT_ARG_NONE, NULL, 0, NULL, NULL }
115: };

Ниже показан пример того, как выглядит справочное сообщение, сгенерированное данной таблицей параметров.

Usage: grep [OPTION...]
Использование: grep [ПАРАМЕТРЫ...]
 -Е, --extended-regexp  шаблоном для соответствия является
                        расширенное регулярное выражение
 -F, --fixed-strings    шаблоном для соответствия является
                        базовая строка (не регулярное выражение)
 -G, --basic-regexp     шаблоном для соответствия является базовое
                        регулярное выражение
 -i, --ignore-case      выполнять поиск, чувствительный к регистру
 -m, --max-count=N      завершить после получения N совпадений
 -е, --regexp=pattern   регулярное выражение для поиска
Help options:
 -?, --help  Show this help message
 --usage     Display brief usage message
Параметры справки:
 -?, --help  Показать это сообщение
 --usage     Отобразить краткое сообщение об использовании

Хотя эта информация и имеет привлекательный вид, она требует некоторых уточнений. В первой строке не сказано, что команда ожидает имена файлов в командной строке. Показанный здесь текст [OPTION...] принят в popt по умолчанию, и с помощью функции poptSetOtherOptionHelp() может быть изменен для получения более детального описания.

#include <popt.h>
poptSetOtherOptionHelp(poptContext con, const char * text);

Первым параметром является содержимое, а второй параметр определяет текст, который должен появиться после имени программы. Если добавить следующий вызов

poptSetOtherOptionHelp(optCon, "<шаблон> <список файлов>");

то первая строка в справочном сообщении будет изменена на

Usage: grep <шаблон> <список файлов>
Использование: grep <шаблон> <список файлов>

что является более точным.

Последнее, что требуется уточнить в отношении справочных сообщений, это способ обработки вложенных таблиц. Давайте снова обратимся к справочному сообщению для нашей программы grep; для параметров справки выделяется отдельный раздел справочного сообщения. Если элемент POPT_ARG_INCLUDE_TABLE таблицы параметров содержит член descrip, то строка будет использоваться в качестве описания для всех параметров во вложенной таблице, и эти параметры будут отображаться в своем собственном разделе справочного сообщения (подобно параметрам справки для tail). Если descrip будет иметь значение NULL, то параметры для вложенной таблицы будут отображаться вместе с параметрами из главной таблицы, а не в своем собственном разделе.

Иногда программы предлагают параметры, которые, возможно, не должны использоваться; они могут быть включены для поддержки унаследованных приложений или приложений, разработанных только для тестирования. Автоматическая генерация справочных сообщений для такого параметра можно подавить с помощью битового "ИЛИ" POPT_ARGFLAG_DOC_HIDDEN и члена arg структуры struct poptOption, описывающей данный параметр.

Оглавление книги