KefirBB user guide

KefirBB user guide, version 0.5, english.

Introduction

KefirBB is a Java-library for text processing. Initially it develop for BB2HTML translation. But flexible cponfiguration allowed use it for others translations. For example XML2HTML or for HTML filtration.

Getting started

At first you must download kefir-bb-0.5.jar and add it to your application classpath. Files can be downloaded from official project site http://kefir-bb.sourceforge.net

You can get processor object implements interface ru.perm.kefir.bbcode.TextProcessor with ru.perm.kefir.bbcode.BBProcessorFactory:

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

Now you can use it for text processing:

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

The processor is thread-safe. You can use it in some threads.

Configuration

Declarative configuration

KefirBB has very flexible configuration. User can use own configuration with configuration file kefirbb.xml in classpath. Other default configuration at ~classpath:/ru/perm/kefir/bbcode/default.xml will be used.

Configuration file is the XML-file, that define text translation. The XML schema can be got at http://kefir-bb.sourceforge.net/schemas/kefir-bb-0.5.xsd. The configuration is a root tag of document. This is simple example of configuration of processor which filter XML special symbols:

<?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>

Codes

Code is a atomic unit of text tranlation. Code define which how text fragment must be translated.

Code can be defined with code tag. Tag must contain two tags: pattern — the pattern for search a text fragment for translation; template — the template for text generation. Tag code has 2 attributes: name define name of code and priority define priority of code (bigger value is greater priority, "0" by default).

Tag pattern can contains plain text and tags var. The text processor find text fragments for translation by text in pattern tag. Tag var define variable and has attributes:

• name — name of variable, "variable" by default;
• parse — mark that variable value must be processed, "true" by default;
• regex — regular expression for variable validation, used if parse=false;
• scope — scope for process variable, used if parse=true, "ROOT" by default;
• inherit — mark that scope must be inherit from outer code, "false" by default;
• transparent — mark that variable can be accessible from outer code, "false" by default.

Tag template can contains text and var tags, for generation. But var accept only one attribute name, "variable" by default.

Example of code tag:

<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>

Tag code can be defined inside tags configuration or scope.

Scopes

Scope define which codes can be used for text processing. By default used scope with name "ROOT". If user not defined "ROOT" scope. Then all codes defined outside scope tags will be added to ROOT-scope.

Scope can be defined with scope tag which must be inside configuration tag. Tag scope has attributes:

• name — name of scope;
• parent — parent scope, all codes from parent will be added to child scope;
• ignoreText — ignore texts outside codes.

Tag scope can contains code for code definition and coderef tag as reference for code defined outside of scope. Tag coderef has one attribute name which indicate code by name.

Parameters

Parameters is a predefined variables which cna be used for text generation. It can be defined inside params tag with param tags, which has two attributes: name — variable name and value — variable value. For example:

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

Also parameters can be defined in standard properties file kefirbb.properties or kefirbb.properties.xml at classpath. See java.util.Properties.

Prefix and suffix

Prefix and suffix will be added at begin and end of processed text. They defined with prefix and suffix tags analogous template tag

Programmatic configuration

Programmatic configuration define with ru.perm.kefir.bbcode.Configuration class. For example:

// 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");

Also tou can get configuration with ru.perm.kefir.bbcode.ConfigurationFactory:

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

Vitaliy Samolovskih aka Kefir
kefir@perm.ru