Package gamedata

Class 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()
      Returns true if the parser was created in gentle mode.
      abstract R next()
      Returns the next resource listed in the file, or null 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.

      • Methods inherited from class java.lang.Object

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

    • 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 resource
        gentle - if true, 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 resource
        charset - the name of the character set to use, such as "UTF-8"
        gentle - if true, 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 from
        gentle - if true, 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 from
        charset - the name of the character set to use, such as "UTF-8"
        gentle - if true, 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, or null if there are no more resources available.
        Returns:
        the next resource
        Throws:
        java.io.IOException - if an I/O error occurs
        ResourceParserException - 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 be null

      • getLanguage

        public final Language getLanguage()
        Returns the language that the parser will use to look up localizable values in the resource file. The default is Language.getInterface().
        Returns:
        the interface language used to look up tile names

      • isParsingGently

        public final boolean isParsingGently()
        Returns true 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 to null, but can be changed with setIdentifier(java.lang.String). If the identifier is null, then this will return &lt;???&gt;.
        Returns:
        the identifier, or the "unknown identifier" if the identifier is null

      • getIdentifier

        public java.lang.String getIdentifier()
        Returns the identifier. If null, then null is returned. Otherwise, this is exactly the same as getIdentifierString().
        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 a ResourceParserException.
        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 to error(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 for readProperty( 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 - if true, 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 interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException - if an I/O error occurs while trying to close the resource