Руководство пользователя (русский)

Руководство пользователя KefirBB, версия 1.2, русский язык.

KefirBB — это Java-библиотека для преобразования текста между различными форматами. Изначально KefirBB разрабатывалась для преобразования BB-кодов в HTML. Однако гибкие возможности конфигурирования позволили использовать её и для других преобразований. Например, для преобразования XML в HTML или для фильтрации HTML-тэгов.

Новое в версии 1.2

• Полная поддержка Textile от TxStyle.
• Частичная поддержка Markdown от Markdown.
• Тэги для URL-адресов и Email: <url/> , <email/> — соответственно.
• Условный тэг для шаблонов.

Новое в версии 1.1

• Добавлены тэги паттерна начала строки, конца строки и пустой строки: <bol/> , <eol/> , <blankline/> — соответственно.
• В паттерне можно указывать тэги-призраки (ghost). Если парсер встречает такой тэг, позиция курсора не меняется.
• Добавлены действия для переменных.
• Можно указывать несколько паттернов в одном коде.

Новое в версии 1.0

• Изменены названия пакетов на org.kefirsf.bb .
• Добавлена возможность не учитывать регистр при создании кодов.
• Значительно увеличена производительность.
• Добалено ограничение на максимальную вложенность кодов для предотвращения java.lang.StackOverflowError
• Конфигурация для фильтрации HTML.

Для начала, Вам нужно подключить библиотеку kefirbb к вашему проекту. Для Maven-проектов достаточно прописать зависимость.

Для остальных проектов достаточно скачать kefirbb-1.2.jar и проследить, чтобы он был добавлен в classpath приложения.

Преобразованием текста занимаются объекты, реализующие интерфейс org.kefirsf.bb.TextProcessor .

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

Чтобы получить стандартный TextProcessor для преобразования BB-кодов в HTML, нужно воспользоваться фабрикой org.kefirsf.bb.BBProcessorFactory .

Теперь мы можем использовать его для преобразования нашего текста.

Объект processor является потокобезопасным. Это означает, что его можно использовать в нескольких потоках одновременно.

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

В составе библиотеки KefirBB содержится конфигурация для фильтрации HTML. Фильтрацию HTML необходимо применять над текстами, введенными пользователем, для предотвращения XSS-атак, а так же во избежание проблем с версткой.

KefirBB полностью поддерживает язык разметки Textile. Описание конфигурации можно найти по адресу TxStyle.

В версию 1.2 включена частичная поддержка языка разметки Markdown. Описание синтаксиса можно найти на странице Markdown Syntax. Текущая реализация не поддерживает в полной мере списки и цитирование.

Исключение специальных последовательностей

Часто встает задача исключения специальных последовательностей символов из текста и замены их другими последовательностями. Для этой цели, библиотека KefirBB содержит специальный класс org.kefirsf.bb.EscapeProcessor . Класс содержит конструктор, на вход которому подается массив последовательностей для исключения и замены.

Исключение специальных символов XML

Исключение специальных символов XML может понадобиться для вставки произвольного текста в XML или HTML документ. Эта задача появлется достаточно регулярно, поэтому библиотека KefirBB содержит специальную фабрику, которая строит объект org.kefirsf.bb.EscapeProcessor , сконфигурированный для исключения специальных символов XML.

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

Первый способ — это назвать файл конфигурации kefirbb.xml и поместить его в корень в classpath . После чего, воспользоваться стандартной фабрикой.

Фабрика сначала ищет конфигурацию по пути classpath*:kefirbb.xml и только если не находит, получает стандартную конфигурацию по пути classpath*:org/kefirsf/bb/default.xml . Отдельные параметры конфигурации могут быть вынесены в файлы kefirbb.properties и kefirbb.properties.xml , имеющие стандартный синтаксис java.util.Properties .

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

Можно получить конфигурацию из файла одним из двух способов.

Можно использовать конфигурацию, созданную программно.

Программную конфигурацию можно получить из XML-конфигурации при помощи фабрики org.kefirsf.bb.ConfigurationFactory .

Файл конфигурации — это XML-файл описывающий преобразование текста. Постоянный адрес схемы в Интернет (http://kefirsf.org/kefirbb/schema/kefirbb-1.2.xsd). В качестве корневого должен быть использован тэг configuration без атрибутов.

Пример простой конфигурации для процессора, фильтрующего спецсимволы XML:

Код — это основная единица преобразования текста. Именно код определяет какой фрагмент текста должен быть преобразован и как он должен быть преобразован.

Код определяется при помощи тэга code . Внутри которого обязательны 2 тэга:

• pattern — образец по которому находится фрагмент текста, который должен быть обработан, начиная с версии 1.1, паттернов может быть несколько в одном коде;
• template — шаблон для генерации нового текста.

Так же у тэга code определены 2 аттрибута:

• name — название кода;
• priority — приоритет кода (чем больше тем выше приоритет, по умолчанию "0").

Пример тэга code :

Тэг code может быть определен непосредственно внутри тэга configuration или внутри тэга scope .

Тэг pattern может содержать текст и тэги: var , constant , junk , bol , eol , blankline , url , email . Во время обработки, процессор ищет фрагменты текста соответствующие тексту и константам в тэге pattern кода. Для тэга pattern можно так же указать атрибут ignoreCase , типа boolean . Если значение атрибута ignoreCase равно true , сравнение текста с образцом не будет зависеть от регистра.

Тэг var введен для определения переменных значений и имеет следующие атрибуты:

• name — название переменной, по умолчанию variable ;
• parse — флаг указывающий на то, требуется ли обработка текста переменной, по умолчанию true ;
• regex — регулярное выражение, которому должна удовлетворять переменная, используется только если parse=false ;
• scope — определяет область видимости, которая будет использована для обработки текста переменной, используется только если parse=true , по умолчанию ROOT ;
• inherit — определяет что нужно унаследовать область видимости от внешнего кода, по умолчанию false ;
• transparent — определяет что переменная должна быть видна внешнему коду, по умолчанию false , введен для обработки атрибутов;
• action — действие, которую нужно проделать с переменной:
  • rewrite — переписывает значение переменной, поведение по умолчанию;
  • append — добавляет к уже имеющемуся значению переменной новое значение;
  • check — проверяет что текущее значение переменной совпадает с тем что в тексте.

  Тэг constant используется для обозначения константных значений в тэге pattern . Имеет следующие атрибуты:

  • value — значение константы;
  • ignoreCase — указывает на необходимость игнорировать регистр символов;
  • ghost — указывает на то что позицию курсора менять не нужно.

  Тэг junk игнорирует все символы в исходном тексте до терминатора.

  Тэг bol служит индикатором начала строки. Многие языки разметки, опираются на начало строки, поэтому он и был введен. Следует учесть, что при обработке тэга bol текущая позиция не изменяется и курсор по прежнему будет находиться на начале строки, поэтому нельзя после тэга bol ставить тэг var с областью видимости, включающей этот же код. Это приведет к появлению бесконечного цикла.

  Тэг eol — конец строки. Обрабатывает символы конца строки, независимо от системы, в которой они были поставлены. Имеет следующие аттрибуты:

  • ghost — указывает на то что позицию курсора менять не нужно.

  Тэг blankline — пустая строка. Имеет следующие аттрибуты:

  • ghost — указывает на то что позицию курсора менять не нужно.

  Тэг url испольуется для обозначения URL-адресов. Имеет следующие аттрибуты:

  • name — название переменной, в которую будет помещен URL-адрес, по умолчанию url ;
  • local — позволяет использовать локальные адреса;
  • schemaless — позволяет использовать адреса без указания схемы, в этом случае все адреса будут HTTP;
  • ghost — указывает на то что позицию курсора менять не нужно.

  Тэг email — парсит email-адреса. Имеет следующие аттрибуты:

  • name — название переменной, в которую будет помещен email-адрес, по умолчанию email ;
  • ghost — указывает на то что позицию курсора менять не нужно.

  Тэг template может содержать текст и тэги var и if .

  Тэг var используется для подстановки в результирующий текст значений переменных. Имеет следующие аттрибуты:

  • name — название переменной, значение которой нужно подставить в текст;
  • function — позволяет модифицировать значение переменной перед подстановкой. В настоящее время доступны следующие функции:
    • value — значение переменной, поведение по умолчанию;
    • length — длина текста переменной.

    Условный тэг if содержит аттрибут name и проверяет, была ли ранее проинициализирована переменная с данным именем. Если переменная с данным именем действительно была проинициализирована в данном коде, то в результирующий текст попадет содержимое тэга if . В противном случае — нет. Тэг if , так же как и тэг template может содержать текст, тэги var и if .

    Область видимости определяет какие коды могут быть использованы для обработки фрагмента текста. По умолчанию, используется область видимости с именем ROOT . Даже если она не определена в конфигурации то она все равно будет создана и в нее будут включены все коды определенные в тэге configuration но не в тэгах scope . Это удобно — для простых конфигурация с небольшим количеством кодов, разработчик может вовсе не заботиться об областях видимости.

    Область видимости определяется при помощи тэга scope , который может находиться внутри тэга configuration . Для тэга scope определны следующие атрибуты:

    • name — название области видимости;
    • parent — область видимости из которой будут унаследованы все коды;
    • ignoreText — означает что при обработке текста в этой области видимости нужно игнорировать весь текст, который не относится ни к одному из допустимых внутри этой области видимости кодов;
    • strong — указывает на то что в тексте могут содержаться только тэги из данной области видимости;
    • min — указывает минимальное количество тэгов из данной области видимости, которые должны содержаться в тексте, по умолчанию -1 — не определено;
    • max — указывает максимальное количество тэгов из данной области видимости, которые могут содержаться в тексте, по умолчанию -1 — не определено.

    Внутри тэга scope допустимы тэги:

    • code — для определения кода (см. выше);
    • coderef — для ссылки на код, определенный вне тэга scope . У тэга coderef определен один атрибут name , который должен совпадать с именем кода.

    Параметры — это заранее определенные переменные, которые могут быть использованы при генерации текста в кодах, префиксе и суффиксе. Параметры определяются внутри тэга params при помощи тэгов param , у которых есть 2 атрибута:

    • name — название переменной;
    • value — значение.

    Так же параметры могут быть заданы в отдельном файле kefirbb.properties или kefirbb.properties.xml в classpath . Форматы файлов определены в классе java.util.Properties .

    Префикс и суффикс

    Префикс и суффикс добавляются в начале и конце обрабатываемого текста соответственно. Определяются при помощи тэгов prefix и suffix , аналогично тэгу template .

    📎📎📎📎📎📎📎📎📎📎