xbn.template
Class Template

java.lang.Object
  |
  +--xbn.XBNObject
        |
        +--xbn.template.Template

All Implemented Interfaces:

Named

Direct Known Subclasses:

TemplateOrderedGaps

public class Template

extends XBNObject

implements Named

A template is text that contains one or more ~G~gaps~EG~, each representing a piece of information whose value is populated at runtime.

Source code: Template.java. Example code See the example code for TemplateFiller

Rules for a template

• A template must contain one or more unique gaps.
• Each unique gap may exist one or more times. Duplicates may be added or removed at any time, as long as at least one of each unique gap exists.
• Gaps may be re-ordered within a template without consequence.

Rules for a gap

For the sake of this documentation, it is assumed that the gap tag delimiter is '~', the text for the gap start and end tags is "G" and "EG", respectively, and the escape character is '\\'. Use GapConfig to configure different values.

• A gap has the following format: ~G~GAPNAME~EG~
• The name of a gap may be between one and TConfigDefaults.getMaxGapNameLength characters in length (inclusive). It is recommended that all gap names be enforced to be only letters, digits and underscores, but you need to enforce this on your own.
• To literally display the gap tag delimiter, escape it with '\'. This is useful for recursive templates: \~G\~sub_gap\~EG\~
• '\' must also be escaped (by itself) in order to be displayed literally.

To learn more...

Read the documentation for the various functions in TemplateData.

What's the difference between unique and absolute gaps?

Pretend this is your template:

Hello there ~G~name_first~EG~ ~G~name_last~EG~

I hope things are going well for you, ~G~name_first~EG~.

Love, Me.

In order, the absolute gaps are: name_first, name_last, name_first

And the unique gaps are: name_first, name_last

Note that for every space before and after absolute gaps, there is a surrounding text element. In other words, the number of surrounding text elements is always exactly one more that the number of absolute gaps.

Fields inherited from class xbn.XBNObject

bFALSE_IN_PRODUCTION, bTRUE_IN_PRODUCTION, sCNSTR, sES, sLINE_SEP

Constructor Summary

Template(ForLineRetrieval flr_srcTxt)
Create a Template.

Template(ForLineRetrieval flr_srcTxt, TParseConfig tp_config)
Create a Template.

Template(ForLineRetrieval flr_srcTxt, TParseConfig tp_config, TFilter template_filter)
Create a Template.

Template(String s_name, ForLineRetrieval flr_srcTxt)
Create a Template.

Template(String s_name, ForLineRetrieval flr_srcTxt, TParseConfig tp_config)
Create a Template.

Template(String s_name, ForLineRetrieval flr_srcTxt, TParseConfig tp_config, TFilter template_filter)
Create a Template.

Template(Template t_emplate)
Create a copy of the provided Template.

Template(TemplateData template_data)
Create a Template.

Method Summary

AOSLHashtable	getAOSLHashtable() Get the AOSLHashtable for direct manipulation.
String	getListAbs() Get a listing of the absolute gap names.
String	getListAbs(String s_divider) Get a listing of the absolute gap names.
String	getListAbs(String s_prefix, String s_postfix) Get a listing of the absolute gap names.
String	getListAbs(String s_prefix, String s_divider, String s_postfix) Get a listing of the absolute gap names.
String	getListUnq() Get a listing of the unique gap names.
String	getListUnq(String s_divider) Get a listing of the unique gap names.
String	getListUnq(String s_prefix, String s_postfix) Get a listing of the unique gap names.
String	getListUnq(String s_prefix, String s_divider, String s_postfix) Get a listing of the unique gap names.
String	getName() What is the name of this object?.
String	getSurroundingText(int i_dx) From the absolute-to-unique-gap-map array, get the unique gap array index for the requested absolute gap.
int	getSurroundingTextCount() How many surrounding text elements exist in this template?.
TemplateData	getTemplateData() Get the TemplateData for direct manipulation.
TFilter	getTFilter() Get the TFilter for direct manipulation.
int	getUnqArrIdxFromAbs(int i_absArrIdx) Given the provided absolute gap's array index, what is the array index for the corresponding unique gap?
UniqueStringAP	getUSAPAbsolute() Get the UniqueStringAP, which contains all absolute gaps.
UniqueStringAP	getUSAPUnique() Get the UniqueStringAP, which contains all unique gaps.
protected void	throwAX(String s_callingFunc, String s_message) Throw an AssertException.
protected void	throwTFX(String s_callingFunc, String s_message) Throw a TemplateFormatException with a standardized message.
protected void	throwTFX(String s_callingFunc, String s_name, String s_message) Throw a TemplateFormatException with a standardized message.
String	toString() Get some information about this Template.

Methods inherited from class xbn.XBNObject

getXMsgPrefix, sop, sopl, sopl, throwAX, throwAXIfBadStr, throwAXIfNull, throwAXSpoof

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Template

public Template(ForLineRetrieval flr_srcTxt)
         throws TemplateFormatException

Create a Template.

Equal to Template(null, flr_srcTxt)

Template

public Template(String s_name,
                ForLineRetrieval flr_srcTxt)
         throws TemplateFormatException

Create a Template.

Equal to Template(s_name, flr_srcTxt, (new TParseConfig()))

Template

public Template(ForLineRetrieval flr_srcTxt,
                TParseConfig tp_config)
         throws TemplateFormatException

Create a Template.

Equal to Template(null, flr_srcTxt, tp_config, null)

Template

public Template(String s_name,
                ForLineRetrieval flr_srcTxt,
                TParseConfig tp_config)
         throws TemplateFormatException

Create a Template.

Equal to Template(s_name, flr_srcTxt, tp_config, null)

Template

public Template(ForLineRetrieval flr_srcTxt,
                TParseConfig tp_config,
                TFilter template_filter)
         throws TemplateFormatException

Create a Template.

Equal to Template(null, flr_srcTxt, tp_config, template_filter)

Template

public Template(String s_name,
                ForLineRetrieval flr_srcTxt,
                TParseConfig tp_config,
                TFilter template_filter)
         throws TemplateFormatException

Create a Template.

Parameters:

s_templateName - The name of the template. See getName

flr_srcTxt - The source text for this Template. May not be null.

tp_config - The configuration defining a gap. May not be null.

template_filter - The TFilter used to enforce the integrity of the about-to-be-retrieved template text. If null, no restrictions are imposed. See getTFilter.

Template

public Template(Template t_emplate)

Create a copy of the provided Template.

Parameters:

t_emplate - The Tempate to copy. May not be null.

Template

public Template(TemplateData template_data)

Create a Template.

Parameters:

template_data - The TempateData. May not be null.

Method Detail

getTFilter

public final TFilter getTFilter()

Get the TFilter for direct manipulation.

This is only used in the constructor, but is referenced here for giggles.

getTemplateData

public final TemplateData getTemplateData()

Get the TemplateData for direct manipulation.

getAOSLHashtable

public final AOSLHashtable getAOSLHashtable()

Get the AOSLHashtable for direct manipulation.

Returns:

getTemplateData().getAOSLookup().getAOSLHashtable()

getUSAPUnique

public final UniqueStringAP getUSAPUnique()

Get the UniqueStringAP, which contains all unique gaps.

Returns:

getTemplateData().getAOSLookup().getUSAPUnique()

getUSAPAbsolute

public final UniqueStringAP getUSAPAbsolute()

Get the UniqueStringAP, which contains all absolute gaps.

Returns:

getTemplateData().getAOSLookup().getUSAPAbsolute()

getListUnq

public String getListUnq()

Get a listing of the unique gap names.

Returns:

(new ListPA()).get(getUSAPUnique().getUniqueStringPAS())

getListUnq

public String getListUnq(String s_divider)

Get a listing of the unique gap names.

Returns:

(new ListPA(s_divider)).get(getUSAPUnique().getUniqueStringPAS())

getListUnq

public String getListUnq(String s_prefix,
                         String s_postfix)

Get a listing of the unique gap names.

Returns:

(new ListPA(s_prefix, s_postfix)).get(getUSAPUnique().getUniqueStringPAS())

getListUnq

public String getListUnq(String s_prefix,
                         String s_divider,
                         String s_postfix)

Get a listing of the unique gap names.

Returns:

(new ListPA(s_prefix, s_divider, s_postfix)).get(getUSAPUnique().getUniqueStringPAS())

getListAbs

public String getListAbs()

Get a listing of the absolute gap names.

Returns:

(new ListPA()).get(getUSAPAbsolute().getUniqueStringPAS())

getListAbs

public String getListAbs(String s_divider)

Get a listing of the absolute gap names.

Returns:

(new ListPA(s_divider)).get(getUSAPAbsolute().getUniqueStringPAS())

getListAbs

public String getListAbs(String s_prefix,
                         String s_postfix)

Get a listing of the absolute gap names.

Returns:

(new ListPA(s_prefix, s_postfix)).get(getUSAPAbsolute().getUniqueStringPAS())

getListAbs

public String getListAbs(String s_prefix,
                         String s_divider,
                         String s_postfix)

Get a listing of the absolute gap names.

Returns:

(new ListPA(s_prefix, s_divider, s_postfix)).get(getUSAPAbsolute().getUniqueStringPAS())

getUnqArrIdxFromAbs

public final int getUnqArrIdxFromAbs(int i_absArrIdx)

Given the provided absolute gap's array index, what is the array index for the corresponding unique gap?

Returns:

getUSAPAbsolute().getUniqueString(i_absArrIdx).getUnqArrIdx()

getSurroundingText

public String getSurroundingText(int i_dx)

From the absolute-to-unique-gap-map array, get the unique gap array index for the requested absolute gap.

Pretend this is your template:

Hello there ~G~name_first~EG~ ~G~name_last~EG~

I hope things are going well for you, ~G~name_first~EG~.

Love, Me.

Here is a complete listing of all the surrounding text elements:

• "Hello there "
• " "
• "[NEWLINE]I hope things are going well for you, "
• ".[NEWLINE]Love, Me."

Note that for every space between surrounding text elements, there is an absolute gap. In other words, the number of absolute gaps is always exactly one less that the number of surrounding text elements.

For an in-depth description of all the internal Template objects, see TemplateData.

Returns:

[internal TemplateData].getAOSSurroundingText().getString(i_dx)

getSurroundingTextCount

public int getSurroundingTextCount()

How many surrounding text elements exist in this template?. This will always return a number exactly one greater than the number of absolute gaps.

For an in-depth description of all the internal Template objects, see TemplateData.

Returns:

[internal TemplateData].getAOSSurroundingText().getLength()

getName

public String getName()

Description copied from interface: Named

What is the name of this object?. This identifier is used throughout the xbn.named package, particularly in NamedArray.

Specified by:

getName in interface Named

toString

public String toString()

Get some information about this Template.

Overrides:

toString in class Object

throwTFX

protected final void throwTFX(String s_callingFunc,
                              String s_message)
                       throws TemplateFormatException

Throw a TemplateFormatException with a standardized message.

Equal to throw new TemplateFormatException(s_callingFunc, getName(), s_message)

throwTFX

protected final void throwTFX(String s_callingFunc,
                              String s_name,
                              String s_message)
                       throws TemplateFormatException

Throw a TemplateFormatException with a standardized message.

Equal to throw new TemplateFormatException(s_callingFunc + (getName()==null?"":" [getName()=" + getName() + "]") + s_message)

throwAX

protected final void throwAX(String s_callingFunc,
                             String s_message)

Throw an AssertException.

Equal to throwAX(s_callingFunc + (getName()==null?"":" [getName()=" + getName() + "]") + s_message)