Книга Джедая

May the Force be with you.

Содержание

Парсер
- Общие сведения
- Программный интерфейс парсера
Плагины
Бакенды
- Программный интерфейс бакенда
  - Посетить

Парсер

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

Парсер полностью реализован в виде одной обработки ПарсерВстроенногоЯзыка.epf, которая предоставляет три механизма:

Разбор исходного кода на встроенном языке платформы 1С:Предприятие 8.3 с результатом в виде AST.
Встроенный механизм обхода AST для плагинов.
Встроенный механизм замен участков текста в исходнике.

На платформе 1С:Предприятие 8.3 создать экземпляр парсера можно следующим образом:

Путь = "C:\git\bsparser\build\ПарсерВстроенногоЯзыка.epf";
Парсер = ВнешниеОбработки.Создать(Путь, Ложь);

В скрипте на OneScript создать экземпляр парсера можно следующим образом:

ПодключитьСценарий("C:\git\bsparser\src\ПарсерВстроенногоЯзыка\Ext\ObjectModule.bsl", "ПарсерВстроенногоЯзыка");
Парсер = Новый ПарсерВстроенногоЯзыка;

Экземпляры плагинов и бакендов создаются аналогично.

Типичный сценарий работы с плагинами, которые регистрируют ошибки:

Плагины = Новый Массив;
Плагины.Добавить(Новый ДетекторНеиспользуемыхПеременных);
Плагины.Добавить(Новый ДетекторПропущенныхТочекСЗапятой);
Парсер.Пуск(Исходник, Плагины);
Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
  Сообщить(СтрШаблон("%1 [стр: %2; кол: %3]", Ошибка.Текст, Ошибка.НомерСтрокиНачала, Ошибка.НомерКолонкиНачала))
КонецЦикла;

Типичный сценарий работы с плагинами, которые генерируют текст:

Результаты = ПарсерВстроенногоЯзыка.Пуск(Исходник, Плагин);
Сообщить(СтрСоединить(Результаты));

Типичный сценарий работы с плагинами, которые регистрируют замены:

Плагины = Новый Массив;
Плагины.Добавить(Новый РасстановкаПропущенныхТочекСЗапятой);
Плагины.Добавить(Новый ЗаменаНеканоничныхКлючевыхСлов);
Парсер.Пуск(Исходник, Плагины);
ИсправленныйИсходник = Парсер.ВыполнитьЗамены();
Сообщить(ИсправленныйИсходник);

Типичный сценарий работы с бакендом:

АСД = Парсер.Разобрать(Исходник);
Текст = Бакенд.Посетить(Парсер, АСД);
Сообщить(Текст);

Программный интерфейс парсера

Основные методы

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

Чаще всего используется метод Пуск(), который заключает в себе типовую последовательность вызовов Разобрать(), Подключить(), Посетить() и Очистить(). Рабочие примеры использования данных методов смотрите в скриптах в папке /oscript

`Пуск(Исходник, Плагины, Параметры, Окружение): Массив`

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

Параметры:

Исходник: Строка -- исходный код для анализа.
Плагины: Массив или Обработка -- плагины, с которыми будет выполняться обход AST.
Параметры: Соответствие (необязательный) -- параметры плагинов.
Окружение: Структура (необязательный) -- окружение (контекст), в котором будет выполняться разбор исходника.

Пример с одним плагином:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);

Плагин = ВнешниеОбработки.Создать(ПлагинПуть, Ложь);

Парсер.Пуск(Исходник, Плагин); // тут выполняется синтаксический анализ и обход АСД с плагинами

Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
    Сообщить(Ошибка.Текст); // вывод найденных парсером и плагином ошибок
КонецЦикла;

Пример с набором плагинов:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);

Плагины = Новый Массив;
Плагины.Добавить(ВнешниеОбработки.Создать(Плагин1Путь, Ложь));
Плагины.Добавить(ВнешниеОбработки.Создать(Плагин2Путь, Ложь));

Парсер.Пуск(Исходник, Плагины); // тут выполняется синтаксический анализ и обход АСД с плагинами

Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
    Сообщить(Ошибка.Текст); // вывод найденных парсером и плагинами ошибок
КонецЦикла;

Пример с параметрами плагинов:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);
Плагин1 = ВнешниеОбработки.Создать(Плагин1Путь, Ложь);
Плагин2 = ВнешниеОбработки.Создать(Плагин2Путь, Ложь);

Плагины = Новый Массив;
Плагины.Добавить(Плагин1);
Плагины.Добавить(Плагин2);

Параметры = Новый Соответствие; // у каждого плагина своя структура параметров
Параметры[Плагин1.ЭтотОбъект] = Новый Структура("Параметр1, Параметр2", 1, 2);
Параметры[Плагин2.ЭтотОбъект] = Новый Структура("Параметр1, Параметр2", 3, 4)

Парсер.Пуск(Исходник, Плагины, Параметры); // тут выполняется синтаксический анализ и обход АСД с плагинами

Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
  Сообщить(Ошибка.Текст); // вывод найденных парсером и плагинами ошибок
КонецЦикла;

Пример с окружением:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);
Узлы = Парсер.Узлы();

Плагин = ВнешниеОбработки.Создать(ПлагинПуть, Ложь));

Окружение = Парсер.Окружение();

// например, контекст формы:
Элемент = Узлы.ЭлементОкружения.Добавить();
Элемент.Имя = "ЭтаФорма";
ПроизвольноеОкружение.Переменные.Вставить("ЭтаФорма", Элемент);
// ...
Элемент = Узлы.ЭлементОкружения.Добавить();
Элемент.Имя = "РеквизитФормыВЗначение";
ПроизвольноеОкружение.Методы.Вставить("РеквизитФормыВЗначение", Элемент);
// ...

Парсер.Пуск(Исходник, Плагины,, Окружение);

Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
  Сообщить(Ошибка.Текст); // вывод найденных парсером и плагином ошибок
КонецЦикла;

`Разобрать(Исходник, Окружение): Структура`

Выполняет разбор исходника в указанном окружении и возвращает AST.

Параметры:

Исходник: Строка -- исходный код для анализа.
Окружение: Структура (необязательный) -- окружение (контекст), в котором будет выполняться разбор исходника.

Пример:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);
Узлы = Парсер.Узлы();

Окружение = Парсер.Окружение();

// например, контекст формы:
Элемент = Узлы.ЭлементОкружения.Добавить();
Элемент.Имя = "ЭтаФорма";
ПроизвольноеОкружение.Переменные.Вставить("ЭтаФорма", Элемент);
// ...
Элемент = Узлы.ЭлементОкружения.Добавить();
Элемент.Имя = "РеквизитФормыВЗначение";
ПроизвольноеОкружение.Методы.Вставить("РеквизитФормыВЗначение", Элемент);
// ...

АСД = Парсер.Разобрать(Исходник, Окружение);

Сообщить(АСД.Объявления.Количество());

`Подключить(Плагины)`

Подключает плагины к парсеру.

Параметры:

Плагины: Массив или Обработка -- плагины для подключения к парсеру.

Пример:

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);
Плагин = ВнешниеОбработки.Создать(ПлагинПуть, Ложь);

АСД = Парсер.Разобрать(Исходник); // тут выполняется синтаксический анализ
Парсер.Подключить(Плагин); // тут плагин подключается к парсеру
Парсер.Посетить(АСД); // тут выполняется обход АСД с вызовом подписок плагина

Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
    Сообщить(Ошибка.Текст); // вывод найденных парсером и плагином ошибок
КонецЦикла;

`Посетить(Модуль, Параметры)`

Выполняет обход AST с подключенными плагинами и указанными параметрами плагинов.

Параметры:

Модуль: Структура -- АСД для обхода.
Параметры: Соответствие (необязательный) -- параметры плагинов, с которыми нужно выполнить обход.

Пример:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);
Плагин = ВнешниеОбработки.Создать(ПлагинПуть, Ложь);

АСД = Парсер.Разобрать(Исходник); // тут выполняется синтаксический анализ
Парсер.Подключить(Плагин); // тут плагин подключается к парсеру
Парсер.Посетить(АСД); // тут выполняется обход АСД с вызовом подписок плагина

Для Каждого Ошибка Из Парсер.ТаблицаОшибок() Цикл
    Сообщить(Ошибка.Текст); // вывод найденных парсером и плагином ошибок
КонецЦикла;

`Токенизировать(Исходник): ТаблицаЗначений`

Выполняет лексический анализ и возвращает таблицу токенов.

Параметры:

Исходник: Строка -- исходный код для анализа.

Пример:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);

ТаблицаТокенов = Парсер.Токенизировать(Исходник); // тут выполняется лексический анализ

Для Каждого ДанныеТокена Из ТаблицаТокенов Цикл
    Сообщить(ДанныеТокена.Токен); // вывод всех токенов
КонецЦикла;

`ВыполнитьЗамены(): Строка`

Возвращает исходник после выполнения на нем замен участков текста.

Пример:

Исходник = ЧтениеТекста.Прочитать();

Парсер = ВнешниеОбработки.Создать(ПарсерПуть, Ложь);
Плагин = ВнешниеОбработки.Создать(ПлагинПуть, Ложь);

Парсер.Пуск(Исходник, Плагин); // тут плагин наполняет таблицу замен

ИсправленныйИсходник = Парсер.ВыполнитьЗамены(); // тут по таблице замен последовательно заменяются участки текста в исходнике.

Сообщить(ИсправленныйИсходник)

`Очистить()`

Очищает в парсере таблицы токенов и узлов. Так освобождается память и парсер подготавливается к следующему разбору. Перед разбором таблицы улов не очищаются, т.к. могут быть наполнены извне при формировании внешнего окружения. Метод Пуск() уже включает этот вызов.

Пример:

ПарсерВстроенногоЯзыка = Новый ПарсерВстроенногоЯзыка;
АСД = ПарсерВстроенногоЯзыка.Разобрать(Исходник);
Сайт = ГенераторДокументации.Посетить(ПарсерВстроенногоЯзыка, АСД);
ПарсерВстроенногоЯзыка.Очистить();

Дополнительные методы

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

Примеры использования данных методов смотрите в плагинах в папке /plugins

`Узлы(): Структура`

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