net.sf.mmm.util.scanner.api
Interface CharScannerSyntax

All Known Implementing Classes:

AbstractCharScannerSyntax, SimpleCharScannerSyntax

public interface CharScannerSyntax

This is the interface used to define the syntax to scan characters.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

CharStreamScanner.readUntil(char, boolean, CharScannerSyntax)

Method Summary

char	getAltQuoteEnd() This method gets the alternative character used to end a quotation.
char	getAltQuoteEscape() This method gets the character used to escape the alt-quote-end character within an quotation opened by alt-quote-start.
char	getAltQuoteStart() This method gets the alternative character used to start a quotation that should be terminated by a alt-quote-end character.
char	getEntityEnd() This method gets the character used to end an entity.
char	getEntityStart() This method gets the character used to start an entity.
char	getEscape() This method gets the character used as escape.
char	getQuoteEnd() This method gets the character used to end a quotation.
char	getQuoteEscape() This method gets the character used to escape the quote-end character within a quotation.
char	getQuoteStart() This method gets the character used to start a quotation that should be terminated by a quote-end character.
boolean	isAltQuoteEscapeLazy() If alt-quote-start, alt-quote-end and alt-quote-escape all point to the same character (which is NOT '\0'), then this method determines if alt-quotation escaping is lazy.
boolean	isQuoteEscapeLazy() If quote-start, quote-end and quote-escape all point to the same character (which is NOT '\0'), then this method determines if quotation escaping is lazy.
String	resolveEntity(String entity) This method resolves the given entity.

Method Detail

getEscape

char getEscape()

This method gets the character used as escape. The escape itself is omitted in the decoded output while the next character is taken as is without any special interpretation. This allows to encode special characters like a stop-character, quote-start, alt-quote-start, as well as the escape itself.
A very common example for an escape character is the backslash ( \).
Here are some examples:

escape	input	output
\	a\b\\c	ab\c
~	a~b~~~c	ab~c

ATTENTION:
The escape is disabled within quotations.

Returns:

the escape character or 0 ('\0') for no escaping.

See Also:

getEntityStart()

getQuoteStart

char getQuoteStart()

This method gets the character used to start a quotation that should be terminated by a quote-end character. The text inside the quote is taken as is (without the quote characters).
Common examples for quote characters are the single quotes (') and double quotes (").

Returns:

the character used to start a quotation or 0 ( '\0') to disable.

getQuoteEnd

char getQuoteEnd()

This method gets the character used to end a quotation.

Returns:

the character used to end a quotation.

See Also:

getQuoteStart()

getQuoteEscape

char getQuoteEscape()

This method gets the character used to escape the quote-end character within a quotation. This may be the quote-end itself so a duplicate quote-end represents a single occurrence of that character within a quotation. Otherwise the escape may be any other character.
Please note that this escaping is only active within a quotation opened by quote-start and only escapes the quote-end character and nothing else so in any other case the quote-escape is treated as a regular character.

quote-start	quote-end	quote-escape	input	output
'	'	'	a'bc'd	abcd
'	'	'	a'b''c'd	ab'cd
'	'	\	a'b\c\'d\\'e'f	ab\c'd\'ef

Returns:

the character used to escape the quote-end character or 0 ('\0') to disable.

isQuoteEscapeLazy

boolean isQuoteEscapeLazy()

If quote-start, quote-end and quote-escape all point to the same character (which is NOT '\0'), then this method determines if quotation escaping is lazy. This means that outside a quotation a double occurrence of the quote character is NOT treated as quotation but as escaped quote character. Otherwise if NOT lazy, the double quote character is treated as quotation representing the empty sequence.
Here are some examples:

quote-start	quote-end	quote-escape	quote-escape-lazy	input	output
'	'	'	true	''	'
'	'	'	false	''
'	'	'	true	''''	''
'	'	'	false	''''	'
'	'	'	true	'''a'	'a
'	'	'	false	'''a'	'a

Please note that for '''a' the complete sequence is treated as quote if quote-escape-lazy is false and otherwise just the trailing 'a'.

Returns:

true if quote-escaping is lazy, false otherwise.

getAltQuoteStart

char getAltQuoteStart()

This method gets the alternative character used to start a quotation that should be terminated by a alt-quote-end character. The text inside the quote is taken as is (without the quote characters).

Returns:

the alternative character used to start a quotation or 0 ('\0') to disable.

See Also:

getQuoteStart()

getAltQuoteEnd

char getAltQuoteEnd()

This method gets the alternative character used to end a quotation.

Returns:

the alternative character used to end a quotation.

See Also:

getAltQuoteStart()

getAltQuoteEscape

char getAltQuoteEscape()

This method gets the character used to escape the alt-quote-end character within an quotation opened by alt-quote-start.

Returns:

the character used to escape the quote-end character or 0 ('\0') to disable.

See Also:

getQuoteEscape()

isAltQuoteEscapeLazy

boolean isAltQuoteEscapeLazy()

If alt-quote-start, alt-quote-end and alt-quote-escape all point to the same character (which is NOT '\0'), then this method determines if alt-quotation escaping is lazy.

Returns:

true if alt-quote-escaping is lazy, false otherwise.

See Also:

isQuoteEscapeLazy()

getEntityStart

char getEntityStart()

This method gets the character used to start an entity. An entity is a specific encoded string surrounded with entity-start and entity-end. It will be decoded by resolveEntity(String).

Returns:

the character used to start an entity or 0 ( '\0') to disable.

getEntityEnd

char getEntityEnd()

This method gets the character used to end an entity.

Returns:

the character used to end an entity.

See Also:

getEntityStart()

resolveEntity

String resolveEntity(String entity)

This method resolves the given entity.
E.g. if entity-start is '&' and getEntityEnd() is ';' then if the string "<" is scanned, this method is called with "lt" as entity argument and may return "<".

Parameters:

entity - is the entity string that was found surrounded by entity-start and entity-end excluding these characters.

Returns:

the decoded entity.