Spec-Zone.ru › Tcllib

pt::peg::import

ИМЯ

pt::peg::import - Импорт PEG

Содержание

  • Содержание

  • Краткое описание

  • Описание

  • API

    • Команды пакета
    • Команда объекта
    • Методы объекта

  • Формат сериализации PEG

    • Пример

  • Формат сериализации PE

    • Пример

  • Ошибки, идеи, отзывы

  • Категория

  • Авторские права

КРАТКОЕ ОПИСАНИЕ

package require Tcl 8.5 9
package require Tcl 8.5 9
package require snit
package require fileutil::paths
package require pt::peg
package require pluginmgr
package require pt::peg::import ?1.0.2?

::pt::peg::import objectName
objectName method ?arg arg ...?
objectName destroy
objectName import text text ?format?
objectName import file path ?format?
objectName import object text object text ?format?
objectName import object file object path ?format?
objectName includes
objectName include add path
objectName include remove path
objectName include clear

ОПИСАНИЕ

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

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

Он находится в разделе импорта основного уровня Parser Tools и является одним из трёх столпов, на которых основано управление грамматиками разбора выражений.

Два других столпа, как показано выше, — это

  1. Экспорт PEG и

  2. Хранение PEG

Сведения о структуре данных, являющейся основным результатом работы объектов диспетчера, предоставляемых этим пакетом, см. в разделе Формат сериализации PEG.

Система плагинов нашего класса основана на пакете pluginmgr и настроена на поиск плагинов в следующих местах:

  1. переменная окружения GRAMMAR_PEG_IMPORT_PLUGINS,

  2. переменная окружения GRAMMAR_PEG_PLUGINS,

  3. переменная окружения GRAMMAR_PLUGINS,

  4. путь "~/.grammar/peg/import/plugin"

  5. путь "~/.grammar/peg/plugin"

  6. путь "~/.grammar/plugin"

  7. путь "~/.grammar/peg/import/plugins"

  8. путь "~/.grammar/peg/plugins"

  9. путь "~/.grammar/plugins"

  10. запись реестра "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\IMPORT\PLUGINS"

  11. запись реестра "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PEG\PLUGINS"

  12. запись реестра "HKEY_CURRENT_USER\SOFTWARE\GRAMMAR\PLUGINS"

Последние три места используются только при запуске пакета на компьютере под управлением операционной системы Windows(tm).

Вся система поставляется с тремя предопределёнными плагинами импорта:

  • container

    Подробности см. в документе Плагин импорта PEG. Из формата CONTAINER.

  • json

    Подробности см. в документе Плагин импорта PEG. Из формата JSON.

  • peg

    Подробности см. в документе Плагин импорта PEG. Из формата PEG.

Тем, кто хочет написать собственный плагин импорта для какого-либо формата, то есть разработчикам плагинов, необходимо прочитать и понять спецификацию API импорта Parser Tools, в которой подробно описано взаимодействие этого пакета с его плагинами.

API

Команды пакета

  • ::pt::peg::import objectName

    Эта команда создаёт новый объект диспетчера импорта и связанную с ним команду Tcl с именем objectName. Эта команда объекта подробно описана в разделах Команда объекта и Методы объекта. Если имя objectName не является полным, команда объекта будет создана в текущем пространстве имён; в противном случае она будет создана в указанном пространстве имён.

Команда объекта

Все объекты, созданные командой ::pt::peg::import, имеют следующий общий вид:

  • objectName method ?arg arg ...?

    Метод method и его аргументы arg определяют точное поведение команды. Подробные спецификации см. в разделе Методы объекта.

Методы объекта

  • objectName destroy

    Этот метод уничтожает объект, для которого он вызван.

  • objectName import text text ?format?

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

    Если формат не указан, по умолчанию используется text.

    Определение канонической сериализации приведено в разделе Формат сериализации PEG.

    Плагин должен соответствовать интерфейсу, описанному в спецификации API импорта Parser Tools.

  • objectName import file path ?format?

    Этот метод является удобной обёрткой для метода import text, описанного выше. Он считывает содержимое указанного файла в память, передаёт полученный текст методу import text и возвращает полученную сериализацию.

  • objectName import object text object text ?format?

    Этот метод является удобной обёрткой для метода import text, описанного выше. Предполагается, что object — это команда объекта, поддерживающая метод deserialize, который принимает каноническую сериализацию грамматики разбора выражений. Метод импортирует текст с помощью import text, а затем передаёт полученную сериализацию объекту object через deserialize. Этот метод возвращает пустую строку.

  • objectName import object file object path ?format?

    Этот метод работает так же, как import object text, за исключением того, что текст для преобразования считывается из указанного файла, а не передаётся в качестве аргумента.

  • objectName includes

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

  • objectName include add path

    Этот метод добавляет указанный путь path в список путей для поиска файлов включения при обработке входных данных. Путь добавляется в конец списка, поэтому поиск по нему выполняется после всех ранее добавленных путей. Команда возвращает пустую строку.

    Если путь уже известен, метод ничего не делает.

  • objectName include remove path

    Этот метод удаляет указанный путь path из списка путей для поиска файлов включения при обработке входных данных. Команда возвращает пустую строку.

    Если путь неизвестен, метод ничего не делает.

  • objectName include clear

    Этот метод очищает список путей для поиска файлов включения при обработке входных данных. Команда возвращает пустую строку.

Формат сериализации PEG

Здесь описан формат, используемый Parser Tools для сериализации грамматик разбора выражений в виде неизменяемых значений для передачи, сравнения и т. д.

Мы различаем обычную и каноническую сериализации. У PEG может быть несколько обычных сериализаций, но канонической будет только одна из них.

  • обычная сериализация

    1. Сериализация любого PEG представляет собой вложенный словарь Tcl.
    2. Этот словарь содержит один ключ — pt::grammar::peg — и соответствующее ему значение. Это значение содержит данные грамматики.

    3. Данные грамматики представляют собой словарь Tcl, содержащий набор нетерминальных символов и начальное выражение. Соответствующие ключи и их значения:

      • rules

        Значение — это словарь Tcl, ключами которого являются имена нетерминальных символов, известных грамматике.

        1. Каждый нетерминальный символ может встречаться только один раз.
        2. Пустая строка не является допустимым нетерминальным символом.

        3. Значение для каждого символа само является словарём Tcl. Соответствующие ключи и их значения в этом словаре:

          + __is__

  The value is the serialization of the parsing expression
  describing the symbols sentennial structure, as specified
  in the section [PE serialization format](#section4)\.

+ __mode__

  The value can be one of three values specifying how a
  parser should handle the semantic value produced by the
  symbol\.

    - __value__

      The semantic value of the nonterminal symbol is an
      abstract syntax tree consisting of a single node node
      for the nonterminal itself, which has the ASTs of the
      symbol's right hand side as its children\.

    - __leaf__

      The semantic value of the nonterminal symbol is an
      abstract syntax tree consisting of a single node node
      for the nonterminal, without any children\. Any ASTs
      generated by the symbol's right hand side are
      discarded\.

    - __void__

      The nonterminal has no semantic value\. Any ASTs
      generated by the symbol's right hand side are
      discarded \(as well\)\.

      • start

        Значение представляет собой сериализацию начального выражения разбора грамматики, описанную в разделе Формат сериализации PE.

    4. Терминальные символы грамматики задаются неявно как множество всех терминальных символов, используемых в начальном выражении и в правых частях правил грамматики.

  • каноническая сериализация

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

    1. Ключи во всех вложенных словарях Tcl отсортированы по возрастанию в порядке словаря, как при выполнении встроенной команды Tcl lsort -increasing -dict.
    2. Строковое представление значения является каноническим представлением словаря Tcl, то есть не содержит лишних пробелов.

Пример

Предположим, что задан следующий PEG для простых математических выражений:

PEG calculator (Expression)
    Digit      <- '0'/'1'/'2'/'3'/'4'/'5'/'6'/'7'/'8'/'9'       ;
    Sign       <- '-' / '+'                                     ;
    Number     <- Sign? Digit+                                  ;
    Expression <- Term (AddOp Term)*                            ;
    MulOp      <- '*' / '/'                                     ;
    Term       <- Factor (MulOp Factor)*                        ;
    AddOp      <- '+'/'-'                                       ;
    Factor     <- '(' Expression ')' / Number                   ;
END;

тогда его каноническая сериализация (без учёта пробелов) имеет вид:

pt::grammar::peg {
    rules {
        AddOp      {is {/ {t -} {t +}}                                                                mode value}
        Digit      {is {/ {t 0} {t 1} {t 2} {t 3} {t 4} {t 5} {t 6} {t 7} {t 8} {t 9}}                mode value}
        Expression {is {x {n Term} {* {x {n AddOp} {n Term}}}}                                        mode value}
        Factor     {is {/ {x {t (} {n Expression} {t )}} {n Number}}                                  mode value}
        MulOp      {is {/ {t *} {t /}}                                                                mode value}
        Number     {is {x {? {n Sign}} {+ {n Digit}}}                                                 mode value}
        Sign       {is {/ {t -} {t +}}                                                                mode value}
        Term       {is {x {n Factor} {* {x {n MulOp} {n Factor}}}}                                    mode value}
    }
    start {n Expression}
}

Формат сериализации PE

Здесь описан формат, используемый Parser Tools для сериализации выражений разбора в виде неизменяемых значений для передачи, сравнения и т. д.

Мы различаем обычную и каноническую сериализации. У выражения разбора может быть несколько обычных сериализаций, но канонической будет только одна из них.

  • Обычная сериализация

    • Атомарные выражения разбора

      1. Строка epsilon является атомарным выражением разбора. Она соответствует пустой строке.
      2. Строка dot является атомарным выражением разбора. Она соответствует любому символу.
      3. Строка alnum является атомарным выражением разбора. Она соответствует любой букве или цифре Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      4. Строка alpha является атомарным выражением разбора. Она соответствует любой букве Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      5. Строка ascii является атомарным выражением разбора. Она соответствует любому символу Unicode с кодом меньше U0080. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      6. Строка control является атомарным выражением разбора. Она соответствует любому управляющему символу Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      7. Строка digit является атомарным выражением разбора. Она соответствует любой цифре Unicode. Обратите внимание, что сюда входят символы за пределами диапазона [0..9]. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      8. Строка graph является атомарным выражением разбора. Она соответствует любому печатному символу Unicode, кроме пробела. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      9. Строка lower является атомарным выражением разбора. Она соответствует любой строчной букве Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      10. Строка print является атомарным выражением разбора. Она соответствует любому печатному символу Unicode, включая пробел. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      11. Строка punct является атомарным выражением разбора. Она соответствует любому знаку пунктуации Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      12. Строка space является атомарным выражением разбора. Она соответствует любому пробельному символу Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      13. Строка upper является атомарным выражением разбора. Она соответствует любой прописной букве Unicode. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      14. Строка wordchar является атомарным выражением разбора. Она соответствует любому символу слова Unicode. Это любой буквенно-цифровой символ (см. alnum) и любой символ соединительной пунктуации (например, подчёркивание). Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      15. Строка xdigit является атомарным выражением разбора. Она соответствует любой шестнадцатеричной цифре. Это пользовательское расширение PE, основанное на встроенной команде Tcl string is.
      16. Выражение [list t x] является атомарным выражением разбора. Оно соответствует терминальной строке x.
      17. Выражение [list n A] является атомарным выражением разбора. Оно соответствует нетерминалу A.

    • Составные выражения разбора

      1. Для выражений разбора e1, e2, ... результат [list / e1 e2 ... ] также является выражением разбора. Это упорядоченный выбор, также называемый приоритетным выбором.
      2. Для выражений разбора e1, e2, ... результат [list x e1 e2 ... ] также является выражением разбора. Это последовательность.
      3. Для выражения разбора e результат [list * e] также является выражением разбора. Это замыкание Клини, описывающее ноль или более повторений.
      4. Для выражения разбора e результат [list + e] также является выражением разбора. Это положительное замыкание Клини, описывающее одно или более повторений.
      5. Для выражения разбора e результат [list & e] также является выражением разбора. Это предикат просмотра вперёд «и».
      6. Для выражения разбора e результат [list ! e] также является выражением разбора. Это предикат просмотра вперёд «не».
      7. Для выражения разбора e результат [list ? e] также является выражением разбора. Это необязательный ввод.

  • Каноническая сериализация

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

    1. Строковое представление значения является каноническим представлением чистого списка Tcl, то есть не содержит лишних пробелов.
    2. Терминалы не кодируются как диапазоны, в которых начало и конец совпадают.

Пример

Предположим, что выражение разбора, показанное в правой части правила, имеет вид:

Expression <- Term (AddOp Term)*

тогда его каноническая сериализация (без учёта пробелов) имеет вид:

{x {n Term} {* {x {n AddOp} {n Term}}}}

Ошибки, идеи, отзывы

В этом документе и описываемом в нём пакете, несомненно, есть ошибки и другие проблемы. Сообщайте о них в категории pt в системе отслеживания ошибок Tcllib. Также сообщайте о любых идеях по улучшению пакета и/или документации.

Предлагая изменения кода, предоставляйте унифицированные различия, то есть вывод команды diff -u.

Также обратите внимание: предпочтительнее прикладывать вложения, а не вставлять исправления непосредственно в текст. Чтобы добавить вложение, откройте форму Edit для задачи сразу после её создания, а затем воспользуйтесь самой левой кнопкой во вторичной панели навигации.

КАТЕГОРИЯ

Разбор и грамматики

АВТОРСКИЕ ПРАВА

Авторские права © 2009 Andreas Kupries

Licensed under the BSD license
https://core.tcl-lang.org/tcllib/doc/trunk/embedded/md/tcllib/files/modules/pt/pt_peg_import.md

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API