Class ResourceParser<R>
- java.lang.Object
-
- gamedata.ResourceParser<R>
-
- All Implemented Interfaces:
java.io.Closeable
,java.lang.AutoCloseable
- Direct Known Subclasses:
ClassMap.Parser
,ConversionMap.Parser
,TileSet.Parser
public abstract class ResourceParser<R> extends java.lang.Object implements java.io.Closeable
An abstract base class for building parsers that convert descriptive text files (such as tile sets, class maps, or silhouette files) into resources.Resource parsers can be created in gentle mode, in which case they will avoid throwing parsing exceptions. When an error occurs in gentle mode, the parser will log a warning message. Concrete subclasses should either skip that resource or else substitute default values. When not running in gentle mode, the parser should throw a
ResourceParserException
.Parsers built with this class create resources by reading lines from a text file. Support is included for lines that use a [key, value] syntax like settings files, but any file format can be used. The supplied line-reading methods automatically skip comment lines, and concatenate lines that end in a backslash. For more details, see the description of
EscapedLineReader
; this class conforms exactly to the behaviour of that class when reading lines.- Since:
- 3.0
- Author:
- Chris Jennings
- See Also:
StrangeEons.log
-
-
Constructor Summary
Constructors Constructor Description ResourceParser(java.io.InputStream in, boolean gentle)
Creates a parser for the specified input stream.ResourceParser(java.io.InputStream in, java.lang.String charset, boolean gentle)
Creates a parser for the specified input stream and encoding.ResourceParser(java.lang.String resource, boolean gentle)
Creates a parser for the specified resource file.ResourceParser(java.lang.String resource, java.lang.String charset, boolean gentle)
Creates a parser for the specified resource file and encoding.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
close()
If this parser was created directly for a resource identifier, then calling this method closes the input stream that was created for the resource.protected void
error(java.lang.String message)
A convenience method that may be called by subclasses when an error occurs.protected java.lang.String
errorMessage(java.lang.String message)
Returns an error message that includes the current identifier string and line number.java.lang.String
getIdentifier()
Returns the identifier.java.lang.String
getIdentifierString()
Returns an identifier that can be used in error messages.Language
getLanguage()
Returns the language that the parser will use to look up localizable values in the resource file.protected int
getLineNumber()
Returns the current line number in the file.boolean
isParsingGently()
Returnstrue
if the parser was created in gentle mode.abstract R
next()
Returns the next resource listed in the file, ornull
if there are no more resources available.protected java.lang.String
readLine()
Returns the next non-comment line.protected java.lang.String
readNonemptyLine()
Returns the next line that is neither a comment nor empty.protected java.lang.String[]
readProperty()
Parses and returns the next line as a [key, value] pair.protected java.lang.String[]
readProperty(boolean skipEmptyLines)
Parses and returns the next line as a [key, value] pair.void
setIdentifier(java.lang.String id)
Sets the identifier to use to identify this resource in error messages.void
setLanguage(Language language)
Sets the language that the parser will use to look up any localizable values in the resource file.protected void
warning(java.lang.String message)
A convenience method that may be called by subclasses to log a warning message.
-
-
-
Constructor Detail
-
ResourceParser
public ResourceParser(java.lang.String resource, boolean gentle) throws java.io.IOException
Creates a parser for the specified resource file.- Parameters:
resource
- the location of the desired tile set resourcegentle
- iftrue
, parses in gentle mode- Throws:
java.io.IOException
-
ResourceParser
public ResourceParser(java.lang.String resource, java.lang.String charset, boolean gentle) throws java.io.IOException
Creates a parser for the specified resource file and encoding.- Parameters:
resource
- the location of the desired tile set resourcecharset
- the name of the character set to use, such as "UTF-8"gentle
- iftrue
, parses in gentle mode- Throws:
java.io.IOException
-
ResourceParser
public ResourceParser(java.io.InputStream in, boolean gentle) throws java.io.IOException
Creates a parser for the specified input stream.- Parameters:
in
- the input stream to read fromgentle
- iftrue
, parses in gentle mode- Throws:
java.io.IOException
- if an I/O error occurs
-
ResourceParser
public ResourceParser(java.io.InputStream in, java.lang.String charset, boolean gentle) throws java.io.IOException
Creates a parser for the specified input stream and encoding.- Parameters:
in
- the input stream to read fromcharset
- the name of the character set to use, such as "UTF-8"gentle
- iftrue
, parses in gentle mode- Throws:
java.io.IOException
- if an I/O error occurs
-
-
Method Detail
-
next
public abstract R next() throws java.io.IOException
Returns the next resource listed in the file, ornull
if there are no more resources available.- Returns:
- the next resource
- Throws:
java.io.IOException
- if an I/O error occursResourceParserException
- if a parsing exception occurs and the parser is not in gentle mode, or if the parser cannot recover from the error even in gentle mode
-
setLanguage
public final void setLanguage(Language language)
Sets the language that the parser will use to look up any localizable values in the resource file.- Parameters:
language
- the language to use; must not benull
-
getLanguage
public final Language getLanguage()
Returns the language that the parser will use to look up localizable values in the resource file. The default isLanguage.getInterface()
.- Returns:
- the interface language used to look up tile names
-
isParsingGently
public final boolean isParsingGently()
Returnstrue
if the parser was created in gentle mode.- Returns:
true
if bad entries will be skipped where possible
-
getIdentifierString
public java.lang.String getIdentifierString()
Returns an identifier that can be used in error messages. If the parser was created with the resource-based constructor, this will default to the resource name. Otherwise it will default tonull
, but can be changed withsetIdentifier(java.lang.String)
. If the identifier isnull
, then this will return<???>
.- Returns:
- the identifier, or the "unknown identifier" if the identifier is
null
-
getIdentifier
public java.lang.String getIdentifier()
Returns the identifier. Ifnull
, thennull
is returned. Otherwise, this is exactly the same asgetIdentifierString()
.- Returns:
- the identifier, or
null
-
setIdentifier
public void setIdentifier(java.lang.String id)
Sets the identifier to use to identify this resource in error messages.- Parameters:
id
- the identifier value to use to identify the source- See Also:
getIdentifierString()
-
errorMessage
protected java.lang.String errorMessage(java.lang.String message)
Returns an error message that includes the current identifier string and line number.- Parameters:
message
- a message to include as part of the returned string- Returns:
- a string that includes the identifier, line number, and message in a standard format
-
error
protected void error(java.lang.String message)
A convenience method that may be called by subclasses when an error occurs. If gentle parsing is enabled, it will log the message, resource identifier, and line number. Otherwise, it will throw aResourceParserException
.- Parameters:
message
- the error message to include
-
warning
protected void warning(java.lang.String message)
A convenience method that may be called by subclasses to log a warning message. It is similar toerror(java.lang.String)
, but never throws an exception. If gentle parsing is enabled, it will log the specified message. If strict parsing is enabled, it does nothing.- Parameters:
message
- the warning message to include
-
readLine
protected final java.lang.String readLine() throws java.io.IOException
Returns the next non-comment line. This is called by subclasses to implement parsing.- Returns:
- the next non-comment line, or
null
if the end of file was reached - Throws:
java.io.IOException
- if an I/O error occurs while reading from the source
-
readNonemptyLine
protected final java.lang.String readNonemptyLine() throws java.io.IOException
Returns the next line that is neither a comment nor empty. An empty line is a line that contains only whitespace. This is called by subclasses to implement parsing.- Returns:
- the next non-empty line, or
null
if the end of file was reached - Throws:
java.io.IOException
- if an I/O error occurs while reading from the source
-
readProperty
protected final java.lang.String[] readProperty() throws java.io.IOException
Parses and returns the next line as a [key, value] pair. This is a cover forreadProperty( true )
.- Returns:
- the next non-empty line split into a [key, value] pair, or
null
if the end of file was reached - Throws:
java.io.IOException
- if an I/O error occurs while reading from the source
-
readProperty
protected final java.lang.String[] readProperty(boolean skipEmptyLines) throws java.io.IOException
Parses and returns the next line as a [key, value] pair. If there is no value, it will be an empty string. If empty lines are not skipped, and an empty line is read, then both the key and value will be empty strings.- Parameters:
skipEmptyLines
- iftrue
, empty lines are skipped and the next non-empty line is parsed- Returns:
- the next line split into a [key, value] pair, or
null
if the end of file was reached - Throws:
java.io.IOException
- if an I/O error occurs while reading from the source
-
getLineNumber
protected final int getLineNumber()
Returns the current line number in the file. This is used by parsers to help compose meaningful error messages.- Returns:
- the current line number (starting from 1)
-
close
public final void close() throws java.io.IOException
If this parser was created directly for a resource identifier, then calling this method closes the input stream that was created for the resource. If this parser was created using an input stream supplied by the caller, then this method does nothing.- Specified by:
close
in interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Throws:
java.io.IOException
- if an I/O error occurs while trying to close the resource
-
-