Библиотека com/teacode/wiki

Результат трансляции wiki текста представлен в виде структуры

struct Wiki {
  fix inp: sinput/Input!
  fix xtree: xml/Elem!
  fix xhtml: xml/Elem!
}

Здесь:

• inp – инпут-объект парсера с накопленной дополнительной информацией об оттранслированном документе (объект библиотеки com/teacode/sinput).
• xtree – представление документа в абстрактной xml модели (модель будет меняться)
• xhtml – финальное html-представление документа.

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

Методы wikimize

Методы wikimize являются единственным внешним интерфейсом библиотеки. Wiki документ подается в контексте методов. В наиболее общем виде wikimize содержит пять аргументов, но все они являются необязательными.

• Первый аргумент blacklist позволяет управлять набором разрешаемых компонент
• Остальные четыре аргумента getlocurl, getdoc, inp0 и params полезны, если пользователь библиотеки реализует собственные обработчики для локальных ссылок *[]() и локальных вставок +[](). Эти компоненты зависят от контекста, в котором используется библиотека Wiki, и самой библиотекой не определяются. Они позволяют глубоко интегрировать обработку wiki документов в самые разнообразные проекты.

Последние четыре аргумента нужны только в случае разработки сложных интегрированных проектов, поэтому при обычном использовании мы рекомендуем работать с методами wikimize/0 и wikimize/1. Результат формируется в виде структуры типа Wiki.

wikimize/5

Наиболее общий метод.

def String wikimize( 
  blacklist: String*, 
    getlocurl: Block?, 
      getdoc: Block?, 
        inp0: i/Input?, 
          params:q/Node*): Wiki!

Самый общий метод трансляции wiki текста. Параметры:

Параметр blacklist: String*

Реализованный в библиотеке вариант wiki является сложным, продвинутым, и содержит большое количество компонентов. Данный параметр позволяет отключить отдельные компоненты wiki, если в них нет необходимости:

• 'header – отключение заголовков ###
• 'emph – отключение выделений в тексте (_курсив_, __жирный__)
• 'ol – отключение упорядоченных списков
• 'ul – отключение неупорядоченных списков
• 'quote – отключение цитат >
• 'slink – отключение простых ссылок <http://..>
• 'link – отключение гиперссылок []()
• 'img – отключение изображений ![]()
• 'hr – отключение горизонтальных линий ***
• 'html – отключение встроенного HTML
• 'entity – отключение сущностей HTML &..;
• 'table – отключение таблиц |
• 'comment – отключение комментариев %%%
• 'math – отключение математических формул \\(..\\)
• 'fnote – отключение сносок ^[]
• 'meta – отключение метаинформации %%%> ...

Параметр getlocurl: Block?

Содержит нульместную анонимную функцию, обрабатывающую локальные ссылки вида *[](local-link). Библиотека wiki не обрабатывает такие ссылки, а оставляет это на усмотрение разработчика приложения, который должен предоставить обработчик в параметре getlocurl.

В контексте вызываемой анонимной функции подается объект структуры

struct LocLink(text: Any*, params: (map/M + base/Map)?)

В поле text подается локальная ссылка local-link, а в поле params – пятый аргумент wikimize, который может содержать дополнительную информацию, передаваемую разработчиком.

Результатом работы анонимной функции должно стать строковое значение URL, которое метод wikimize интерпретирует как адрес гиперссылки и вставляет в html-элемент a/href.

Параметр getdoc: Block?

Содержит нульместную анонимную функцию, обрабатывающую локальные вставки вида +[](local-link). Библиотека wiki не обрабатывает такие ссылки, а оставляет это на усмотрение разработчика приложения, который должен предоставить обработчик в параметре getdoc.

В контексте вызываемой анонимной функции getdoc подается объект структуры

struct LocLink(text: Any*, params: (map/M + base/Map)?)

В поле text подается локальная ссылка local-link, а в поле params – пятый аргумент wikimize, который может содержать дополнительную информацию, передаваемую разработчиком.

В качестве результата анонимная функция должна также вернуть структуру типа LocLink.

Если параметр params непустой, то параметр text интерпретируется как текст дочернего документа, который должен быть вставлен в родительский текст. В этом случае для обработки дочернего документа рекурсивно вызывается wikimize, результат которого вставляется в родительский текст.

Если параметр params пустой, то значение text интерпретируется как готовое значение, которое библиотекой не обрабатывается и вставляется в документ в не измененном виде.

Параметр inp0

Используется для импорта контекста родительского документа к документу дочернему. После обработки дочернего документа, необходимые данные, накопленные в процессе этой обработки, передаются обратно в родительский контекст. В основном этот параметр используется самой библиотекой при обработке локальных ссылок и локальных вставок.

Параметр params

В этом параметре пользователь может передать любые дополнительные данные, необходимые для исполнения getlocurl и getdoc.

wikimize/4

def String wikimize( 
  blacklist: String*, 
    getlocurl: Block?, 
      getdoc: Block?, 
        params: q/Node* ): Wiki!

wikimize/1

def String wikimize( blacklist: String* ): Wiki!

wikimize/0

def String wikimize: Wiki!