Описание языка

Описание языка

Общие сведения

Документация: программная/эксплуатационная
Предмет: формальный язык
Аудитория: пользователи языка (программисты, операторы, кодеры, верстальщики)
Задачи: обеспечить пользователю языка возможность решать задачи, которые могут быть перед ним поставлены, на описываемом формальном языке
Стандарты: ГОСТ 19.504-79

Цели и задачи

К формальным языкам относятся всевозможные языки программирования, языки управления заданиями, языки описания экранных и печатных форм, языки описания структур данных, языки разметки и т. п. Они могут быть очень разными. Попробуйте найти что-нибудь общее между Фортраном и, скажем, тем языком, который используется в пакете TeX для форматирования текста. Кроме очевидного свойства, состоящего в том, что все это искусственные языки с определенным набором элементов (слов) и строгими грамматическими правилами.

Но в том-то и дело, что пользователю языка — программисту, оператору, кодеру, верстальщику — кроме как из описания узнать о них неоткуда. Программу или даже устройство можно в той или иной мере изучать «методом тыка», но по отношению к языку он не работает совсем. Правда, язык можно изучать, читая написанный на нем код. Однако, даже изучив сотню страниц, вы не будете уверены ни в том, что вы ознакомились со всеми словами и конструкциями, ни в правильности понимания вами прочитанного.

Таким образом, задача описания языка состоит в том, чтобы дать читателю исчерпывающее представление о формальном языке и обеспечить ему возможность применять язык в полном объеме.

Содержание документа

В описании языка должны быть изложены следующие сведения:

  1. Назначение и сфера применения языка.
  2. Чем является текст, написанный на этом языке. Иначе говоря, что на этом языке пишут: программы, макросы, документы определенного назначения и т.п.
  3. Основные синтаксические правила языка, т. е. типы элементов текста и допустимые способы их соединения друг с другом. Например, программа на алгоритмическом языке вроде Фортрана или Бейсика представляет собой последовательность операторов, а XML-документ — дерево вложенных друг в друга элементов.
  4. Логика исполнения программы или обработки документа. В разных языках она, вообще говоря, разная. Например, операторы в программе на алгоритмическом языке обрабатываются последовательно сверху вниз (если эта последовательность не изменяется явно посредством всевозможных операторов перехода и ветвления или неявно механизмами вроде исключений). И совсем по-другому происходит применение XSLT-стиля к XML-документу или CSS-стиля к HTML-документу.
  5. Конкретные элементы языка и связанные с ними синтаксические конструкции. В случае языка программирования это, как правило, операторы, в случае языка разметки всевозможные элементы или ключи.
  6. Встроенные функциональные блоки, например, стандартные функции (хотя это касается, скорее, определенного транслятора, фреймворка или парсера, нежели языка как такового).

Кроме того, в описании языка могут быть приведены:

  • рекомендации по стилю программирования (кодирования);
  • типология ошибок, методы их выявления и поиска;
  • методы оптимизации по быстродействию, памяти и прочим параметрам;
  • перечень рекомендованных трансляторов, фреймворков или парсеров.

И любые другие детали, знание которых помогает пользователю делать свою работу по возможности хорошо и быстро.

Пограничная тема — сообщения об ошибках, выводимые транслятором или парсером. С одной стороны, их описание необходимо программисту или кодеру. С другой стороны, для одного языка (скажем, для JavaScript и XSLT) может существовать много разных обрабатывающих программ, и у каждой из них могут быть свои сообщения об одних и тех же ошибках. Поэтому сообщениям об ошибках (если они сами по себе недостаточно ясны) самое место в руководстве программиста по каждому продукту, в котором реализована поддержка этого языка.

Методика и стиль изложения

Сложно формализовать это требование, но самое главное, что необходимо сделать в описании языка, — выразить и донести до читателя его основную идею. Можно скрупулезно описать все элементы языка XSLT, синтаксис языка LISP или языка FORT, но если читатель не поймет, как в принципе ведет себя «исполнитель», которому «адресован» текст, написанный на этом язык, создавать работоспособные программы он не сможет. С языками разметки все, конечно, попроще, но все равно, описывая их, приходится объяснять как устроен документ, и как будет вести себя парсер при его разборе.

Описание языка должно быть самодостаточным. Составляя этот документ, мы не можем полагаться на знание читателем других языков, даже широко распространенных. Недопустимо писать, что «оператор цикла в языке Ща минус минус имеет такой же синтаксис, как в языке Си плюс плюс» и тем ограничиться или описать только имеющиеся отличия. Необходимо дать полноценное описание оператора со всеми вариантами и нюансами, как будто прежде человечество не создавало ничего даже отдаленно похожего. Это означает, что хотя бы одной-двумя фразами придется дать и само понятие цикла.

Описание каждого оператора или другого элемента должно сопровождаться примерами (которые автор описания не поленился собственноручно отладить).

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

Типовая структура

ГОСТ 19.506-79 дает следующую типовую структуру описания языка (очевидно, она ориентирована только на языки программирования, и не учитывает существование языков разметки):

  1. Общие сведения.
  2. Элементы языка.
  3. Способы структурирования программы.
  4. Средства обмена данными.
  5. Встроенные элементы.
  6. Средства отладки.

Пример структуры описания языка программирования:

Особенности

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

Примеры

Парсер 2. Руководство пользователя

Парсер 2 — скриптовой язык, т. е. специализированный язык программирования, предназначенный для написания программного кода серверных частей веб-сайтов. Сам язык и интерпретатор для него созданы программистами Студии Артемия Лебедева. Описание языка Парсер 2 разработано «Философтом». (В настоящее время вторая версия Парсера уступила место третьей, объектно-ориентированной.) Заглавие «Руководство пользователя» дано документу из маркетинговых соображений. Документ не является в чистом виде описанием языка, скорее, это руководство программиста, в которое такое описание включено. Однако наибольший объем информации в документе приходится именно на него.

ВВЕДЕНИЕ
 Кому и зачем нужен Парсер?
 Как это работает?
 Как научиться делать сайты с помощью Парсера?
 Кодер, помни!
 Условные обозначения
1. ОСНОВНЫЕ КОНСТРУКЦИИ ЯЗЫКА
 1.1. Веб-страницы, HTML-файлы и шаблоны страниц
 1.2. Операторы
 1.3. Макросы
  1.3.1. Общее представление о макросах
  1.3.2. Наглядный пример использования макроса
  1.3.3. Правила записи макросов
  1.3.4. Вызов макросов с помощью оператора macro
  1.3.5. Шаблоны с описаниями макросов. Макрос main
  1.3.6. Инициализация страниц. Макрос autoexec
 1.4. Таблицы
  1.4.1. Зачем нужны таблицы?
  1.4.2. Механизм таблиц в Парсере
  1.4.3. Текущая таблица
  1.4.4. Заполнение таблицы данными
  1.4.5. Текущая строка, навигация и поиск в таблице
  1.4.6. Обращение к данным в таблице
  1.4.7. Перебор строк текущей таблицы
 1.5. Переменные
 1.6. Уровни обработки
 1.7. Математические и логические выражения
 1.8. Форматные строки
2. ПРИМЕР САЙТА
 2.1. О чем эта глава?
 2.2. Техническое задание
 2.3. Конструкция сайта
 2.4. Реализация
  2.4.1. Файлы данных
  2.4.2. Структура разделов. Макрос section_html
  2.4.3. Шаблон раздела «Новости»
  2.4.4. Единый шаблон новости
 2.5. Работа над ошибками
 2.6. Упражнения
3. ОПЕРАТОРЫ ПАРСЕРА
 3.1. Переменные, выражения, вычисления
  3.1.1. Файлы-счетчики. Оператор counter
  3.1.2. Математические выражения. Оператор eval
  3.1.3. Присвоение переменной значения. Оператор var с двумя аргументами
  3.1.4. Получение значения переменной. Оператор var с одним аргументом
  3.1.5. Присвоение переменной значения. Оператор var с аргументом-операцией
  3.1.6. Присвоение переменной значения. Оператор var с форматированием
  3.1.7. Получение псевдослучайного числа. Оператор random
 3.2. Макросы
  3.2.1. Вызов макроса. Оператор macro
  3.2.2. Динамическое описание макроса. Оператор macro_new
  3.2.3. Загрузка макросов из файла. Оператор macro_use
  3.2.4. Проверка существования макроса. Оператор macro_exists
 3.3. Ветвление кода
  3.3.1. Выбор одного варианта из двух. Оператор if
  3.3.2. Выбор одного варианта из нескольких. Оператор switch
  3.3.3. Проверка строки на пустоту. Оператор default
  3.3.4. Проверка строки на пустоту. Оператор ifdef
  3.3.5. Проверка значений на равенство. Оператор eq
  3.3.6. Сравнение целочисленных значений. Оператор cmp
  3.3.7. Сравнение строки c началом URI страницы. Оператор start
  3.3.8. Вывод «полосатых» HTML-таблиц. Оператор color
 3.4. Циклы
  3.4.1. Цикл с условием. Оператор while
  3.4.2. Цикл с параметром. Оператор for
 3.5. Базы данных
  3.5.1. Подключение к SQL-серверу. Оператор server
  3.5.2. Выполнение SQL-запроса. Оператор sql
 3.6. Таблицы
  3.6.1. Назначение текущей таблицы. Оператор context
  3.6.2. Заполнение таблицы данными из кода. Оператор config
  3.6.3. Загрузка данных в таблицу. Оператор load
  3.6.4. Проверка таблицы на пустоту. Оператор empty
  3.6.5. Обращение к элементам таблицы. Оператор item
  3.6.6. Перебор строк таблицы. Оператор menu
  3.6.7. Вывод данных в табличной форме. Оператор table
  3.6.8. Поиск в таблице. Оператор locate
  3.6.9. Перемещение по таблице. Оператор shift
  3.6.10. Поворот текущей строки таблицы. Оператор flip
  3.6.11. Сортировка таблицы. Оператор sort
  3.6.12. Запись данных из таблицы в файл. Оператор save
 3.7. Строки
  3.7.1. Получение длины строки. Оператор length
  3.7.2. Выделение подстроки слева. Оператор left
  3.7.3. Выделение подстроки справа. Оператор right
  3.7.4. Выделение подстроки в середине. Оператор mid
  3.7.5. Поиск подстроки в строке. Оператор findstr
  3.7.6. Получение символа по ASCII-коду. Оператор char
  3.7.7. Получение ASCII-кода символа. Оператор ascii
  3.7.8. Разбиение строки на подстроки слева направо. Оператор lsplit
  3.7.9. Разбиение строки на подстроки справа налево. Оператор rsplit
  3.7.10  Преобразование к верхнему регистру. Оператор toupper
  3.7.11. Преобразование к нижнему регистру. Оператор tolower
  3.7.12. Обрезка строки. Оператор truncate
  3.7.13. Преобразование служебных символов в теги. Оператор unescape_br
 3.8. Формы, запросы, переменные окружения
  3.8.1. Значения в полях формы. Оператор form
  3.8.2. Численные значения в полях формы. Оператор number
  3.8.3. Значение переменной QUERY_STRING. Оператор query
  3.8.4. Переменные окружения веб-сервера. Оператор env
  3.8.5. URI страницы. Оператор uri
  3.8.6. Формирование множества значений поля. Оператор combine
  3.8.7. Определение типа и версии браузера. Оператор browser
  3.8.8. Кодирование строки для URL. Оператор mangle
  3.8.9. Формирование HTTP-заголовка ответа. Оператор header
 3.9. Сервисы и протоколы Интернета
  3.9.1. Запись и чтение cookie. Оператор cookie
  3.9.2. Запуск CGI-скриптов. Оператор exeс
  3.9.3. Отправка сообщений по электронной почте. Оператор sendmail
  3.9.4. Вложение данных в электронное сообщение. Оператор uuencode
 3.10. Файлы
  3.10.1. Выделение имени файла из пути. Оператор name
  3.10.2. Проверка существования файла на диске. Оператор -f
  3.10.3. Получение информации о файле. Оператор stat
  3.10.4. Поиск файла. Оператор find
  3.10.5. Загрузка в таблицу оглавления каталога. Оператор index
  3.10.6. Выгрузка файла с сервера. Оператор download
  3.10.7. Загрузка файла на сервер. Оператор upload
  3.10.8. Вложение файла в формате uuencode. Оператор upload
  3.10.9. Удаление файла. Оператор unlink
 3.11. Поиск и замена с использованием регулярных выражений
  3.11.1. Поиск подстроки по шаблону. Оператор match
  3.11.2. Замена подстроки, отвечающей шаблону. Оператор match
 3.12. Множества
  3.12.1. Проверка вхождения элемента во множество. Оператор optionset
  3.12.2. Удаление элемента из множества. Оператор optionclear
  3.12.3. Пересечение множеств. Оператор optionand
  3.12.4. Объединение множеств. Оператор optionor
  3.12.5. Подсчет элементов множества. Оператор optioncount
 3.13. Календарь
  3.13.1. Получение текущей даты. Оператор date   
  3.13.2. Загрузка в таблицу даты и времени. Оператор loadtimestamp
  3.13.3. Загрузка в таблицу календаря на месяц. Оператор calendar
  3.13.4. Загрузка в таблицу календаря на неделю. Оператор calendar
  3.13.5. Сдвиг даты на один день, месяц или год. Оператор dateoffset
 3.14. Графические файлы 
  3.14.1. Получение размеров изображения. Оператор imgsize
  3.14.2. Формирование изображения. Оператор gif_template
 3.15. Код и режимы его обработки
  3.15.1. Вставка комментария. Оператор rem
  3.15.2. Обработка кода. Оператор process 
  3.15.3. Установка уровня обработки. Оператор level
  3.15.4. Оптимизация HTML-кода. Оператор optimize
4. РЕКОМЕНДАЦИИ ПО ИСПОЛЬЗОВАНИЮ ЯЗЫКА
 4.1. Как сделать код «комильфо»?
 4.2. Комментируйте код
 4.3. Внимательно относитесь к именам
 4.4. Макросы должны быть обозримыми
 4.5. Правильно структурируйте код
 4.6. Не используйте оператор form вместо number
ПРИЛОЖЕНИЕ A. УСТАНОВКА ПАРСЕРА НА ВЕБ-СЕРВЕР ПОД APACHE
ПРИЛОЖЕНИЕ B. УСТАНОВКА ПАРСЕРА НА ВЕБ-СЕРВЕР ПОД IIS 4+
ПРИЛОЖЕНИЕ C. РЕГУЛЯРНЫЕ ВЫРАЖЕНИЯ В СТАНДАРТЕ POSIX 1003.2

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG