org.jproggy.snippetory
Enum Encodings

java.lang.Object
  extended by java.lang.Enum<Encodings>
      extended by org.jproggy.snippetory.Encodings
All Implemented Interfaces:
Serializable, Comparable<Encodings>, Encoding

public enum Encodings
extends Enum<Encodings>
implements Encoding

Provides direct access to the predefined encodings. Even though the functionality of identifying an format and the default implementation for this format are done nearby, the Snippetory template engine always uses implementation, that's registered. This allows to overwrite to default implementation and still use this enum to identify a format.
All default implementations defined here respect NULL as a wild card that never has to be transcoded.


Enum Constant Summary
html
          html is derived from xml.
html_string
          In JavaScript I've sometimes data that is transported in a string before it's displayed as html.
NULL
          The wild card encoding.
plain
          Plain text.
string
          Most C-based languages have almost the same rules.
url
          Applies url encoding to the data.
xml
          It's assumed that Snippetory is used in a modern Unicode based environment.
 
Field Summary
 
Fields inherited from interface org.jproggy.snippetory.spi.Encoding
REGISTRY
 
Method Summary
 TemplateContext context()
           
 String getName()
          the name is used to identify a format.
 Template parse(CharSequence data)
           
 void transcode(Appendable target, CharSequence value, String encodingName)
          Sometimes it's possible to combine data encoded in different ways after applying a special action to one of the strings.
static Encodings valueOf(String name)
          Returns the enum constant of this type with the specified name.
static Encodings[] values()
          Returns an array containing the constants of this enum type, in the order they are declared.
 EncodedData wrap(CharSequence data)
          Marks the data to be encoded according to specified encodinng.
 
Methods inherited from class java.lang.Enum
compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.jproggy.snippetory.spi.Encoding
escape
 

Enum Constant Detail

xml

public static final Encodings xml
It's assumed that Snippetory is used in a modern Unicode based environment. Though, only a minimal escaping is done:
< --> &lt;
& --> &amp;

As xml is a compound format, i.e. it can contain other formats, almost each other will be placed within without any transcoding. Only on plain text the normal escaping is applied.


html

public static final Encodings html
html is derived from xml. It just converts line breaks to <br />-tags to enable transporting of simple formatting within the data bound. Be aware: this applies to data bound, not to some kind of source code like in html pages, so we do not break with the good practice of separating the layout of source code and it's resulting appearance.


url

public static final Encodings url
Applies url encoding to the data. The character encoding is utf-8.


string

public static final Encodings string
Most C-based languages have almost the same rules. This implementation fits at least Java and JavaScript.


html_string

public static final Encodings html_string
In JavaScript I've sometimes data that is transported in a string before it's displayed as html.


plain

public static final Encodings plain
Plain text. You will get an IllegalEncodingExcption if you try to bind encoded data to it.


NULL

public static final Encodings NULL
The wild card encoding. Fits to any other, any other fits to this. Sometimes it's necessary to work around the checks. But in general you should not use it.

Method Detail

values

public static Encodings[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
for (Encodings c : Encodings.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static Encodings valueOf(String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:
name - the name of the enum constant to be returned.
Returns:
the enum constant with the specified name
Throws:
IllegalArgumentException - if this enum type has no constant with the specified name
NullPointerException - if the argument is null

transcode

public void transcode(Appendable target,
                      CharSequence value,
                      String encodingName)
               throws IOException
Description copied from interface: Encoding
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 string-encoded data this is possible. However, line breaks or quotation marks will have to be escaped. (We are talking about a file that contains a definition of a string of course)
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.

Specified by:
transcode in interface Encoding
Parameters:
target - result of the action has to be appended to target.
value - has be transcoded
encodingName - Value is already encoded with this encoding
Throws:
IOException

getName

public String getName()
the name is used to identify a format. There may exist different implementations for the same format.

Specified by:
getName in interface Encoding

context

public TemplateContext context()

parse

public Template parse(CharSequence data)

wrap

public EncodedData wrap(CharSequence data)
Marks the data to be encoded according to specified encodinng.