Руководство пользователя KefirBB

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

Введение

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

Начало работы

Для того чтобы начать работать с KefirBB вам нужно получить файл kefir-bb-0.5.jar и добавить его в classpath своего приложения. Скачать библиотеку можно с официальной страницы проекта http://kefir-bb.sourceforge.net.

Чтобы преобразовать текст, для начала вы должны получить объект типа ru.perm.kefir.bbcode.TextProcessor:

TextProcessor processor = BBProcessorFactory.getInstance().create();

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

assert "&".equals(processor.process("&"));

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

Конфигурация

Декларативная конфигурация

KefirBB имеет очень гибкую конфигурацию. Пользователь может использовать свои настройки добавив файл конфигурации kefirbb.xml в classpath. Если пользователь этого не сделает, то для настройки будет использован файл конфигурации по умолчанию, находящийся ~classpath:/ru/perm/kefir/bbcode/default.xml.

Файл конфигурации — это XML-файл описывающий преобразование текста. Схема находится по адресу: http://kefir-bb.sourceforge.net/schemas/kefir-bb-0.5.xsd. В качестве корневого должен быть использован тэг configuration. Пример простой конфигурации для процессора, фильтрующего спецсимволы XML:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="http://kefir-bb.sourceforge.net/schemas"
        xsi:schemaLocation="http://kefir-bb.sourceforge.net/schemas http://kefir-bb.sourceforge.net/schemas/kefir-bb-0.5.xsd">
    <!-- XML escape symbols -->
    <scope name="ROOT">
        <code>
            <pattern>&amp;</pattern>
            <template>&amp;amp;</template>
        </code>
        <code>
            <pattern>&apos;</pattern>
            <template>&amp;apos;</template>
        </code>
        <code>
            <pattern>&lt;</pattern>
            <template>&amp;lt;</template>
        </code>
        <code>
            <pattern>&gt;</pattern>
            <template>&amp;gt;</template>
        </code>
        <code>
            <pattern>&quot;</pattern>
            <template>&amp;quot;</template>
        </code>
    </scope>
</configuration>

Коды

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

Код определяется при помощи тэга code. Внутри которого обязательны 2 тэга: pattern — образец по которому находится фрагмент текста, который должен быть обработан; template — шаблон для генерации нового текста. Так же у тэга code определены 2 аттрибута: name — название тэга и priority — приоритет кода (чем больше тем выше приоритет, по умолчанию "0").

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

Тэг template так же может содержит текст и тэг var, однако тэг var может иметь только 1 атрибут name, по умолчанию "variable", чтобы определить, значение какой переменной подставить в текст.

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

<code name="bold">
    <pattern>[b]<var inherit="true"/>[/b]</pattern>
    <template>&lt;span style=&quot;font-weight:bold;&quot;&gt;<var/>&lt;/span&gt;</template>
</code>

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

Область видимости

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

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

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

Параметры

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

<params>
    <param name="music" value="Punk"/>
</params>

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

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

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

Программная конфигурация

Программная кофигурация задается классом ru.perm.kefir.bbcode.Configuration. Пример:

// Create configuration
Configuration cfg = new Configuration();

// Set the prefix and suffix
cfg.setPrefix(new Template(Arrays.asList(new Constant("["))));
cfg.setSuffix(new Template(Arrays.asList(new Constant("]"))));

// Configure default scope
Scope scope = new Scope(Scope.ROOT);

// Create code and add it to scope
Code code = new Code(
    new Pattern(Arrays.asList(new Constant("val"))),
    new Template(Arrays.asList(new NamedValue("value")))
);
Set<Code> codes = new HashSet<Code>();
codes.add(code);
scope.setScopeCodes(codes);

// Set scope to configuration
cfg.setScope(scope);

// Set the parameter
cfg.addParam("value", "KefirBB");

Так же вы можете получить программную конфигурацию при помощи ru.perm.kefir.bbcode.ConfigurationFactory:

Configuration configuration = ConfigurationFactory.getInstance().create();

Самоловских Виталий aka Kefir
kefir@perm.ru