Module snippetory.core

Package org.jproggy.snippetory.spi

Interface Encoding

All Known Implementing Classes:

Encodings

public interface Encoding

The purpose of an encoding is to ensure the syntactical correctness of an output by escaping terms or characters with special meaning in the syntax of the output file. For example the ampersand is illegal within XML as it's used to mark an entity. It has to be replaced by &.

By handling those technical issues of the output file within the template definition the handling logic gets more reusable. And simpler to implement. This is a simple but very efficient abstraction layer.

As the encoding is inherited throughout the tree of snippets within a Template a single encoding definition is sufficient for many cases. However, combination of encodings is common as well. This is why it can be overwritten as often as needed, for entire subtrees or just for single leaf nodes.

In addition to encodings there is another concept in Snippetory that looks similar at first sight: The Format serves two purposes, conversion and decoration. While the distinction to conversion is pretty obvious decoration is a string to string operation, too. But decoration formats are less technical and rather work in the problem domain of the template.

See Also:

Official documentation on encodings, Extending the platform

Method Summary

Modifier and Type	Method	Description
String	getName()	The identifier for registering and retrieval of this Encoding
static void	register(Encoding value)
static void	registerOverwite(Encoding target, Transcoding overwrite)
void	transcode(Appendable target, CharSequence value, String sourceEncoding)	Sometimes it's possible to combine data encoded in different ways after applying a special action to one of the strings.

Method Detail

register

static void register(Encoding value)

registerOverwite

static void registerOverwite(Encoding target,
                             Transcoding overwrite)

transcode

void transcode(Appendable target,
               CharSequence value,
               String sourceEncoding)
        throws IOException,
               IncompatibleEncodingException

Sometimes it's possible to combine data encoded in different ways after applying a special action to one of the strings. This action might be a translation like wiki syntax to HTML or simply apply default escaping to the data and mix encodings that way. I.e. when adding HTML to a string-encoded location would be possible. (Since invention of html_string it`s forbidden anyway.) However, line breaks or quotation marks would have to be escaped.

In other cases no action will be needed. String encoded data can be added to HTML as this is a container format and is able to carry string definition within script-section for instance.

However, some combinations of encodings are illegal. Especially the plain encoding can't be combined with others. In those cases an IncompatibleEncodingException is thrown.

Parameters:

target - result of the action has to be appended to target.

value - has be transcoded

sourceEncoding - Value is already encoded with this encoding

Throws:

IncompatibleEncodingException - if the encoding can't be taken as is and can't be decoded.

IOException

getName

String getName()

The identifier for registering and retrieval of this Encoding