Руководство пользователя 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>&</pattern>
<template>&amp;</template>
</code>
<code>
<pattern>'</pattern>
<template>&apos;</template>
</code>
<code>
<pattern><</pattern>
<template>&lt;</template>
</code>
<code>
<pattern>></pattern>
<template>&gt;</template>
</code>
<code>
<pattern>"</pattern>
<template>&quot;</template>
</code>
</scope>
</configuration>
Код — это основная единица преобразования текста. Именно код определяет какой фрагмент текста должен быть преобразован и как он должен быть преобразован.
Код определяется при помощи тэга code
. Внутри которого обязательны 2 тэга:
pattern
— образец по которому находится фрагмент текста, который должен быть обработан;
template
— шаблон для генерации нового текста.
Так же у тэга code
определены 2 аттрибута:
name
— название тэга и
priority
— приоритет кода (чем больше тем выше приоритет, по умолчанию "0").
Тэг pattern
может содержать текст и тэг var
. Во время обработки процессор ищет
фрагменты текста соответствующие тексту в тэге pattern
кода. Тэг var
введен для
определения переменных значений и имеет следующие атрибуты:
name
— название переменной, по умолчанию "variable";parse
— флаг указывающий на то, требуется ли обработка текста переменной,
по умолчанию "true";regex
— регулярное выражение, которому должна удовлетворять переменная,
используется только если parse=false
;
scope
— определяет область видимости, которая будет использована для обработки
текста переменной, используется только если parse=true
, по умолчанию "ROOT";
inherit
— определяет что нужно унаследовать область видимости от внешнего кода,
по умолчанию "false";
transparent
— определяет что переменная должна быть видна внешнему коду,
по умолчанию "false", введен для обработки атрибутов.
Тэг template
так же может содержит текст и тэг var
, однако тэг
var
может иметь только 1 атрибут name
, по умолчанию "variable",
чтобы определить, значение какой переменной подставить в текст.
Пример тэга code
:
<code name="bold">
<pattern>[b]<var inherit="true"/>[/b]</pattern>
<template><span style="font-weight:bold;"><var/></span></template>
</code>
Тэг code
может быть определен непосредственно внутри тэга configuration
или внутри тэга scope
.
Область видимости определяет какие коды могут быть использованы для обработки фрагмента текста.
По умолчанию используется область видимости с именем "ROOT". Даже если она не определена
в конфигурации то она все равно будет создана и в нее будут включены все коды определенные
в тэге configuration
но не в тэгах scope
. Это удобно — для
простых конфигурация с небольшим количеством кодов разработчик может вовсе не заботиться об областях видимости.
Область видимости определяется при помощи тэга scope
, который может находиться внутри тэга
configuration
. Для тэга scope
определны следующие атрибуты:
name
— название области видимости;parent
— область видимости из которой будут унаследованы все коды;ignoreText
— означает что при обработке текста в этой области видимости нужно
игнорировать весь текст, который не относится ни к одному из допустимых внутри этой области видимости кодов.
Внутри тэга 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