Stripc - из файла на языке Си
ИМЯ: stripc
stripc Извлекает документирующий заголовок из исходного файла на языке Си.
НАЗНАЧЕНИЕ
Печатает первый блок строк комментария в файле с исходным кодом на Си так, чтобы вы могли быстро идентифицировать назначение программы на Си.
ФОРМАТ
stripc файл [...]
ПРИМЕР ВЫЗОВА
stripc prog*.c > header
Извлекает начальные блоки комментариев из всех файлов и помещает в один файл с именем header.
ИСХОДНЫЙ КОД ДЛЯ stripc
1 : 2 # @(#) stripc v1.0 Strip comment header Author: Russ Sage 4 if [ "$#" -eq "0" ] 5 then echo "stripc: arg count error" >&2 6 echo "usage: stripc file [...]" >&2 7 exit 1 8 fi 10 for FILE in $@ 11 do 12 if [ ! -s $FILE ] 13 then echo "file \"$FILE\" does not exist" >&2 14 continue 15 fi 17 awk '/^\/\*/, /^ \*\// { if ($0 != " */") 18 print 19 else {print;exit} 20 }' $FILE 21 echo "^L" 22 done
(Перед тем как вводить этот исходный код, обратите внимание, что в строке 21 должен быть действительно символ control- L, введенный между двумя кавычками, по причинам, рассмотренным ниже.)
ПЕРЕМЕННАЯ СРЕДЫ
FILE Хранит имя файла, полученное из командной строки.
ОПИСАНИЕ
Зачем нам нужен stripc?
В больших проектах по разработке программного обеспечения требуется обычно много времени для работы с документацией. Имеются программные файлы для документирования, функциональные спецификации для написания программ и, наконец, руководства и справочные карты, глоссарии, указатели и т.д. Настоящий программный код должен иметь свою собственную встроенную документацию, иначе управление этим кодом становится очень трудным.
Чтобы избежать путаницы, нужно создать модель документации, а затем сделать ее стандартом, которому должны следовать все программисты. Даже если эта модель не будет абсолютно идеальной, ее наличие является первым шагом по созданию среды, которой вы можете управлять.
Следующие два инструментальные средства, которые мы предлагаем, следуют модели документации, описанной в дальнейшем тексте. Эта модель последовательна и понятна, ее можно дополнить или изменить по вашему усмотрению.
Что делает stripc?
Stripc печатает только первый заголовочный блок комментариев из начала исходного файла на языке Си. Желательно, чтобы этот блок содержал всю важную информацию о файле: его официальное имя, для чего он предназначен, кто его создал, когда он был создан и т.д. Внутри файла может размещаться одна или несколько функций или даже главная программа. Эта модель предполагает, что весь ваш код содержит очень мало главных программ и много независимых модулей.
Рассмотрим на модельном исходном файле, какого рода информацию мы должны извлечь из исходных файлов.
/* * Это документирующий заголовок для файла * с исходным кодом на языке Си. * Он поясняет, что содержится в файле (программы, функции, * библиотеки и т.д.) и идентифицирует проект. * */ Это отметка конца заголовочного комментария. ^L Инструменты извлечения применяют control-L как разделитель. /* Это документирующий заголовок для главной части программы. * Главная пометка должна объяснять, что это за программа * и что она делает. Здесь могут быть также указаны автор, * дата и история изменений. */ main() { /* Здесь находится главная Си-программа */ } ^L /* Это документирующий заголовок для определенной функции, * которая за ним следует. Документируется последователь- * ность вызова, вход и выход и общее назначение этой * функции. */ func(arg1,arg2) int arg1; char arg2; { /* Текст функции находится здесь */ } ^L /* Аналогично, этот блок комментариев документирует * следующую функцию. Наличие документации вместе с кодом * сокращает объем накладных расходов при чтении и * изменении кода. */ func(arg1,arg2) int arg1, arg2; { /* Текст функции находится здесь */ }
Как указывалось ранее, функция main не обязательна и, вероятно, встречается только в одном или двух файлах, в зависимости от вида программ, которые вы пишете. Один файл может иметь столько функций, сколько вы хотите, но рекомендуемое максимальное число - от одной до трех, в зависимости от того, как эти функции взаимосвязаны. В каждом файле имейте дело только с одной программируемой идеей и ее реализацией.
При изучении этой модели вы видите, что обеспечивается три уровня документации. Заголовок в начале файла извлекается с помощью stripc. Этот заголовок относится ко всему файлу в целом. Заголовок в начале главной программы относится ко всей программе и поддерживается с помощью stripf. Заголовок для каждой функции относится к этой функции. Эти заголовки обслуживаются командным файлом stripf, который обсуждается ниже.
Отметим, что между функциями имеется прогон формата (символ control-L кода ASCII). В предыдущем листинге мы указали эту комбинацию клавиш с помощью символа ^L, чтобы наши текстовые процессоры не производили лишних страниц при форматировании рукописи данной книги. Вам нужно в каждом случае действительно вводить control-L вместо ^L при размещении комментариев в ваших файлах и при вводе исходного кода данного и последующих командных файлов. Символ прогона формата используется в модели заголовка для отметки верхней границы первой функции в файле и для прогона страниц на печатающем устройстве при чистовой распечатке, чтобы каждая функция появлялась на новой странице.
В начале каждой функции (перед main или перед именем функции) должен существовать документирующий заголовок. Этот заголовок обычно отражает наиболее недавние изменения в этом модуле, и его можно считать более достоверным, чем заголовок документа, который был напечатан несколько недель или даже месяцев назад.
Входом для stripc является последовательность имен файлов с исходным кодом. Для каждого файла в командной строке проверяется, существует ли он и имеет ли размер больше, чем ноль байт. Если он не удовлетворяет этим критериям, то печатается сообщение об ошибке и проверяется следующий файл. Каждый файл читается с первого байта, и в нем ищется символьная строка начала комментария (/*). Когда она найдена, информация до символьной строки конца комментария (*/) построчно выводится в stdout. Если правые символы не найдены, ничего не печатается, но сообщение об ошибке не выводится, чтобы не испортить выводную информацию. После того как каждый файл обработан, в конце печатается прогон формата, который разбивает выводную информацию на страницы-разделы. Это применяется в основном, когда документирующие заголовки очень длинные и нуждаются в визуальной разбивке.
Отметим, что "извлечение" ("strip") здесь и в следующих двух утилитах означает не УДАЛЕНИЕ, а копирование соответствующей информации. Никаких изменений во входных файлах не делается.
Когда все файлы в командной строке обработаны, командный файл завершается.
ПРИМЕРЫ
1. $ stripc test?.c > test.filehdrs
Извлекает блок файловых комментариев из всех файлов, соответствующих строке "test", за которой следуют один произвольный символ, а затем .c. Сюда подходят test1, testA, testb и т.д. Все блоки комментариев помещаются в файл test.filehdrs в таком порядке, как они обрабатывались бы в цикле for.
2. $ for DIR in src1 src2 src3 > do > stripc $DIR/*.c > /tmp/$DIR.hdrs > done
Этот цикл проходит каждый из трех каталогов src1, src2 и src3. В каждом из них имеются исходные файлы, из которых нужно извлечь документирующие заголовки. Каждый раз берется один каталог, и stripc вызывается для всех исходных файлов на языке Си из данного каталога. Выход, т.е. все документирующие заголовки из файлов в этом каталоге, помещается в файл в каталоге /tmp. Файлы в /tmp имеют имена /tmp/src1.hdrs, /tmp/src2.hdrs и /tmp/src3.hdrs. Отметим, что число файлов, передаваемых stripc, имеет ограничение в 255 символов. После этого командная строка переполняется и выполнение командного файла аварийно завершается.
ПОЯСНЕНИЯ
Строки 4-8 делают проверку на ошибки. Если число параметров в командной строке нулевое, возникает ошибка. При вызове stripc должно быть хотя бы одно имя файла.
Цикл for в строках 10-22 пробегает по каждому имени файла из списка позиционных параметров в командной строке.
Первым делом, в строках 12-15 проверяется существование файла. Если файл не существует, выдается соответствующее сообщение об ошибке и цикл продолжается со следующим файлом.
Строки 17-20 - это цикл awk, который делает всю важную работу. Входным для awk является имя файла, которое сейчас обрабатывает цикл for.
Если вы не очень знакомы с программой awk, сообщим, что она вызывается так:
awk программа имя-файла
где программа состоит из последовательности предложений, имеющих вид:
шаблон { действие }
Указанное действие применяется к тексту, который соответствует шаблону. Для того чтобы утилита awk работала корректно, вы должны заключить всю программу в одинарные кавычки.
В stripc для указания начала комментария (/*) и конца комментария (*/) используются соответственно шаблоны
/^\/\*/ и /^ \*\//
Для интерпретации этих обозначений нужно вспомнить регулярные выражения ed, sed и grep. Регулярные выражения (РВ) должны быть ограничены (символом /). awk воспринимает два выражения, разделенные запятыми, как начальный и конечный шаблоны для квалификации вводных строк.
В данном примере начальное выражение означает "от начала строки (^), вслед за действительным символом косой черты (который должен быть экранирован, чтобы убрать его специальное значение, т.е. \/) и действительной звездочкой (\*), использовать все строки, обнаруженные вплоть до конечного выражения". Этим выбирается только первое вхождение сопоставляемого шаблона (т.е. первого блока комментариев), так как программа awk заканчивает работу при обнаружении завершающей строки. (Остальные блоки комментариев выбираются с помощью stripf вместе с именем функции и аргументами.)
Для каждой строки, которая соответствует набору выражений от начального до конечного, выполняются предложения, указанные в "действии".
Строки 17, 18 и 19 содержат предложение if-then= else, которое выполняет всю работу. Если $0 (что является всей строкой) НЕ равно пробелу и концу комментария (*/), печатается вся строка. Формируя таким образом предложение if, мы печатаем первую строку и все последующие строки, пока не доберемся до конца комментария.
Когда обнаружена последняя строка, результатом проверки является значение "ложь", поэтому выполняется else-часть. Поскольку мы знаем, что это последняя строка, мы печатаем ее для завершенности блока комментария, а затем выходим из awk. Отметим, что благодаря вложению этих двух команд вместе в фигурные скобки ({}), они рассматриваются как одно составное предложение.
После завершения awk производится эхо-отображение прогона формата на экран и берется следующий файл. Так продолжается до тех пор, пока все файлы в командной строке не будут обработаны.
