Skip navigation links

oracle.javatools.parser.properties
Class PropertiesLexer

java.lang.Object
oracle.javatools.parser.AbstractLexer
oracle.javatools.parser.properties.PropertiesLexer

All Implemented Interfaces:

Lexer, PropertiesTokens

public class PropertiesLexer

extends AbstractLexer

implements PropertiesTokens

The PropertiesLexer is an implementation of the Lexer interface for a *.properties or *.rts file. Although *.rts are somewhat compatible with *.properties files, the lexing rules provided by this module is tailored to *.properties files. The format of an *.rts file is described by the following excerpt from the RTS JavaDoc documentation:

Specification of the RTS source file format: An RTS source file is a text file description of a set of string resources. Each such resource consists of an identifying key and its associated string.

The format of an RTS source file has been designed for compatibility with java ".properties" files" so that a java ".properties" file may serve as a valid RTS source file. RTS source files differ from ".properties" files by allowing keys to be any Unicode string and by providing rules for associating comments with resources.

Each line in a source file may represent a resource, a comment or be blank. Any line consisting only of whitespace is considered blank. Any line in which the first non-whitespace character is a # or a ! is a comment. All other lines represent string resources.

A line representing a string resource consists of a key/value pair. The key is represented by the text beginning with the first non-whitespace character continuing up to (but not including) the the next non-escaped whitespace, =, or : character. To represent a key that contains whitespace, =, or :'s, one may escape any such character by preceding it with a \. The precise escape mechanism is as follows: \ followed by any character is treated as the character itself (with no syntactic meaning attached) except in cases where that character is a:

• t - treated as a tab
• n - treated as a newline
• r - treated as a return
• u - treated (along with the next four digits) as a unicode character

The string value consists of the text from the first non-whitespace character following the key up until end of the line. As with java ".properties" files, if the first non-whitespace character is a : or an =, then the string resource begins with the first non-whitespace character following the : or =. The escape character, \, may be used to represent a string beginning with whitespace. If the line representing a string resource ends with an non-escaped \, the resource definition is continued onto the next line, starting with the first non-escaped whitespace character.

Comments in an RTS source file may be associated with resources so that a comment can contain information about a particular entry. A resource is associated with the comment that immediately preceeds it. There may be blank lines between the comment and the resource -- however, blank line lines between comment lines cause the separated lines to be treated as different comments -- so that only the last comment is associated with a subsequent resource. A line containg only a # or ! is not treated as a blank.

In the following example, key1 is associated with comment lines 1-3 while key 2 is associated with comment lines 5 and 6 (but not 4).

    # Example RTS source file

    # comment_line_1
    # comment_line_2
    # comment_line_3

    key1 = string_1

    # comment_line_4

    # comment_line_5
    # comment_line_6

    key2 = string_2
 

There are a couple quirks of the *.properties files (at least based on the implementation of PropertyResourceBundle) which are followed here:

• A line is recognized by a comment only when the first character (not just first non-whitespace) is '#' or '!'.
• The escape character (as a continuation character) is used for continuing the resource definition and may occur in either the key or value.

Because of these quirks, the lexing for a *.rts file may not completely follow the formats of an *.rts file (which may be more relaxed.)

This lexer does not assist in the deciphering of the contents of the actual property definition. Use the DefinitionLexer for this purpose.

This lexer requires a normalized buffer with only '\n' EOL characters.

See Also:

Lexer, PropertiesTokens

Nested Class Summary

Nested classes/interfaces inherited from class oracle.javatools.parser.AbstractLexer

AbstractLexer.DefaultLexerToken

Field Summary

Fields inherited from class oracle.javatools.parser.AbstractLexer

currentPos, textBuffer

Fields inherited from interface oracle.javatools.parser.properties.PropertiesTokens

TK_COMMENT, TK_DEFINITION

Fields inherited from interface oracle.javatools.parser.Lexer

TK_EOF, TK_NOT_FOUND

Constructor Summary

PropertiesLexer()
Constructs a default PropertiesLexer with a starting position of 0.

Method Summary

void	backup() Unlexes the last found token.
int	lex(LexerToken lexedToken) Scans the text buffer at the current position and returns the token that was found.
void	setPosition(int offset) Sets the current lex (read) position to the given offset in the buffer.
void	setSkipComments(boolean skipComments) Sets whether the PropertiesLexer should generate tokens for comments in the *.properties and *.rts files.
static java.lang.String	tokenToString(int token) Utility routine to map the token to a string representation of the token (for debug printing.)
static java.lang.String	tokenToText(int token) Utility routine to map the token to the original text (if retrievable) of the token (for debug printing.)

Methods inherited from class oracle.javatools.parser.AbstractLexer

createLexerToken, getTextBuffer, setTextBuffer

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertiesLexer

public PropertiesLexer()

Constructs a default PropertiesLexer with a starting position of 0. Clients must call setTextBuffer() to initialize the text buffer used for the Lexer. To start lexing from an offset other than 0, call setPosition().

Method Detail

setSkipComments

public void setSkipComments(boolean skipComments)

Sets whether the PropertiesLexer should generate tokens for comments in the *.properties and *.rts files.

Parameters:

skipComments - true to ignore comments in token generation

lex

public int lex(LexerToken lexedToken)

Scans the text buffer at the current position and returns the token that was found. The token and offset information is also stored in the lexedToken instance passed in to the call.

Specified by:

lex in interface Lexer

Specified by:

lex in class AbstractLexer

Parameters:

lexedToken - the instance passed in where token info is stored

Returns:

the token that was found, same as calling lexedToken.getToken() (for convenience)

backup

public void backup()

Unlexes the last found token. The next call to lex() will return the last token and offset information found.

Specified by:

backup in interface Lexer

Specified by:

backup in class AbstractLexer

setPosition

public void setPosition(int offset)

Sets the current lex (read) position to the given offset in the buffer. It is the clients responsibility to ensure that this offset corresponds to the start of the line, otherwise, unexpected (and incorrect) results may occur.

Specified by:

setPosition in interface Lexer

Overrides:

setPosition in class AbstractLexer

Parameters:

offset - the offset for the next lex() operation.

tokenToString

public static java.lang.String tokenToString(int token)

Utility routine to map the token to a string representation of the token (for debug printing.)

Parameters:

token - the token to map

Returns:

a printable representation of the token

tokenToText

public static java.lang.String tokenToText(int token)

Utility routine to map the token to the original text (if retrievable) of the token (for debug printing.)

Parameters:

token - the token to map

Returns:

a printable representation of the token

Skip navigation links