Package io.urf.surf

Class SurfParser

  • public class SurfParser
extends java.lang.Object
    Simple parser for the Simple URF (SURF) document format.

    This parser is meant to be used once for parsing a single SURF document. It should not be used to parse multiple documents, as it maintains parsing state.

    The parser should be released after use so as not to leak memory of parsed resources when resources are present with tags/IDs/aliases.

    This implementation is not thread safe.

    Author:
    Garret Wilson

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static com.globalmentor.java.Characters WHITESPACE_EOL_CHARACTERS
      Whitespace and end-of-line characters.

    • Constructor Summary

      Constructors 
      Constructor Description
      SurfParser()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Optional<SurfObject> findObjectById​(java.lang.String typeHandle, java.lang.String id)
      Returns a parsed object by its type handle and ID.
      java.util.Optional<SurfObject> findObjectByTag​(java.net.URI tag)
      Returns a parsed object by its tag.
      java.util.Optional<java.lang.Object> findResourceByAlias​(java.lang.String alias)
      Returns a parsed resource by its alias.
      protected SurfObject getObjectById​(java.lang.String typeHandle, java.lang.String id)
      Returns a parsed object by its type handle and ID.
      java.util.Optional<java.lang.Object> parse​(java.io.InputStream inputStream)
      Parses a SURF resource from an input stream.
      java.util.Optional<java.lang.Object> parse​(java.io.Reader reader)
      Parses a SURF resource from a reader.
      java.util.Optional<java.lang.Object> parse​(java.lang.String string)
      Parses a SURF resource from a string.
      static byte[] parseBinary​(java.io.Reader reader)
      Parses a binary literal.
      static java.lang.Boolean parseBoolean​(java.io.Reader reader)
      Parses a Boolean value.
      static com.globalmentor.java.CodePointCharacter parseCharacter​(java.io.Reader reader)
      Parses a character literal.
      static int parseCharacterCodePoint​(java.io.Reader reader, char delimiter)
      Parses a character as content, without any delimiters.
      protected SurfObject parseDescription​(java.io.Reader reader, SurfObject resource)
      Parses the description properties of a resource.
      static com.globalmentor.net.EmailAddress parseEmailAddress​(java.io.Reader reader)
      Parses an email address.
      static java.lang.String parseHandle​(java.io.Reader reader)
      Parses a handle composed of a name token followed by zero or more name tokens, separated by handle segment delimiters.
      static java.net.URI parseIRI​(java.io.Reader reader)
      Parses an IRI.
      static java.lang.Object parseLabel​(java.io.Reader reader)
      Parses a label, surrounded by label delimiters, and which is returned as one of the following: tag The tag IRI as an absolute URI. ID Some object that is neither a URI nor a String and which will provide the ID using Object.toString(). alias An SurfParser.Alias containing the alias string.
      java.util.List<java.lang.Object> parseList​(io.urf.surf.SurfParser.Alias alias, java.io.Reader reader)
      Parses an a list.
      java.util.Map<java.lang.Object,​java.lang.Object> parseMap​(io.urf.surf.SurfParser.Alias alias, java.io.Reader reader)
      Parses a map.
      static com.globalmentor.net.MediaType parseMediaType​(java.io.Reader reader)
      Parses a media type.
      protected static java.lang.String parseMediaTypeRestrictedName​(java.io.Reader reader)
      Parses a restricted name of an Internet media type.
      protected static java.lang.String parseNameToken​(java.io.Reader reader)
      Parses a name token composed of a name token beginning character followed by zero or more name token characters.
      static java.lang.Number parseNumber​(java.io.Reader reader)
      Parses a number.
      protected SurfObject parseObject​(java.lang.Object label, java.io.Reader reader)
      Parses an object indicated by 42.
      SurfObject parseObject​(java.net.URI tag, java.io.Reader reader)
      Parses an object, a described resource instance indicated by 42.
      static java.util.regex.Pattern parseRegularExpression​(java.io.Reader reader)
      Parses a regular expression surrounded by regular expression delimiters and optionally ending with flags.
      java.lang.Object parseResource​(java.io.Reader reader)
      Parses a resource; either a tag or a resource representation with an optional description.
      java.lang.Object parseResource​(java.io.Reader reader, boolean allowDescription)
      Parses a resource; either a tag or a resource representation.
      protected static int parseSequence​(java.io.Reader reader, char sequenceEnd, com.globalmentor.io.function.IOConsumer<java.io.Reader> itemParser)
      Parses a general SURF sequence (such as a list).
      java.util.Set<java.lang.Object> parseSet​(io.urf.surf.SurfParser.Alias alias, java.io.Reader reader)
      Parses a set.
      static java.lang.String parseString​(java.io.Reader reader)
      Parses a string surrounded by string delimiters.
      static com.globalmentor.itu.TelephoneNumber parseTelephoneNumber​(java.io.Reader reader)
      Parses a telephone number.
      static java.time.temporal.TemporalAccessor parseTemporal​(java.io.Reader reader)
      Parses a temporal.
      static java.util.UUID parseUuid​(java.io.Reader reader)
      Parses a UUID.
      protected static int skipFiller​(java.io.Reader reader)
      Skips over SURF filler in a reader, which includes whitespace, line comments, and line breaks.
      protected static void skipLineComment​(java.io.Reader reader)
      Skips a single line comments.
      protected static java.util.Optional<java.lang.Boolean> skipSequenceDelimiters​(java.io.Reader reader)
      Skips over SURF sequence delimiters in a reader.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • WHITESPACE_EOL_CHARACTERS

        protected static final com.globalmentor.java.Characters WHITESPACE_EOL_CHARACTERS
        Whitespace and end-of-line characters.

    • Constructor Detail

      • SurfParser

        public SurfParser()

    • Method Detail

      • findResourceByAlias

        public java.util.Optional<java.lang.Object> findResourceByAlias​(@Nonnull
                                                                java.lang.String alias)
        Returns a parsed resource by its alias.
        Parameters:
        alias - The alias used by the resource in the document.
        Returns:
        The resource associated with the given alias, if any.

      • findObjectByTag

        public java.util.Optional<SurfObject> findObjectByTag​(@Nonnull
                                                      java.net.URI tag)
        Returns a parsed object by its tag.
        Parameters:
        tag - The global IRI identifier tag of the resource.
        Returns:
        The object associated with the given tag, if any.

      • findObjectById

        public java.util.Optional<SurfObject> findObjectById​(@Nonnull
                                                     java.lang.String typeHandle,
                                                     @Nonnull
                                                     java.lang.String id)
        Returns a parsed object by its type handle and ID.
        Parameters:
        typeHandle - The handle of the object's type.
        id - The object ID for the indicated type.
        Returns:
        The typed object with the given ID, if any.

      • getObjectById

        protected SurfObject getObjectById​(@Nonnull
                                   java.lang.String typeHandle,
                                   @Nonnull
                                   java.lang.String id)
        Returns a parsed object by its type handle and ID.
        Parameters:
        typeHandle - The handle of the object's type.
        id - The object ID for the indicated type.
        Returns:
        The typed object with the given ID, or null if no such object was found.

      • parse

        public java.util.Optional<java.lang.Object> parse​(@Nonnull
                                                  java.lang.String string)
                                           throws java.io.IOException,
                                                  com.globalmentor.io.ParseIOException
        Parses a SURF resource from a string.

        This is a convenience method that delegates to parse(Reader).

        Parameters:
        string - The string containing SURF data.
        Returns:
        The root SURF resource, which may be empty if the SURF document was empty.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        com.globalmentor.io.ParseIOException - if the SURF data was invalid.

      • parse

        public java.util.Optional<java.lang.Object> parse​(@Nonnull
                                                  java.io.InputStream inputStream)
                                           throws java.io.IOException,
                                                  com.globalmentor.io.ParseIOException
        Parses a SURF resource from an input stream.
        Parameters:
        inputStream - The input stream containing SURF data.
        Returns:
        The root SURF resource, which may be empty if the SURF document was empty.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        com.globalmentor.io.ParseIOException - if the SURF data was invalid.

      • parse

        public java.util.Optional<java.lang.Object> parse​(@Nonnull
                                                  java.io.Reader reader)
                                           throws java.io.IOException,
                                                  com.globalmentor.io.ParseIOException
        Parses a SURF resource from a reader.
        Parameters:
        reader - The reader containing SURF data.
        Returns:
        The root SURF resource, which may be empty if the SURF document was empty.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        com.globalmentor.io.ParseIOException - if the SURF data was invalid.

      • parseLabel

        public static java.lang.Object parseLabel​(@Nonnull
                                          java.io.Reader reader)
                                   throws java.io.IOException,
                                          com.globalmentor.io.ParseIOException
        Parses a label, surrounded by label delimiters, and which is returned as one of the following:
        tag
        The tag IRI as an absolute URI.
        ID
        Some object that is neither a URI nor a String and which will provide the ID using Object.toString().
        alias
        An SurfParser.Alias containing the alias string.

        The current position must be that of the beginning label delimiter character. The new position will be that immediately after the last label delimiter.

        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The tag parsed from the reader; either an SurfParser.Alias, an absolute URI for a tag, or String for an ID.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the label is not valid.
        See Also:
        SURF.LABEL_DELIMITER, parseHandle(Reader), parseIRI(Reader)

      • parseNameToken

        protected static java.lang.String parseNameToken​(@Nonnull
                                                 java.io.Reader reader)
                                          throws java.io.IOException,
                                                 com.globalmentor.io.ParseIOException
        Parses a name token composed of a name token beginning character followed by zero or more name token characters. The current position must be that of the first name token character. The new position will be that immediately after the last name token character.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The name token parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if there are are no name characters.
        See Also:
        SURF.Name.isTokenBeginCharacter(int), SURF.Name.isTokenCharacter(int)

      • parseHandle

        public static java.lang.String parseHandle​(@Nonnull
                                           java.io.Reader reader)
                                    throws java.io.IOException,
                                           com.globalmentor.io.ParseIOException
        Parses a handle composed of a name token followed by zero or more name tokens, separated by handle segment delimiters. The current position must be that of the first handle character. The new position will be that immediately after the last handle character.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The handle parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if there are are no handle characters.

      • parseResource

        public java.lang.Object parseResource​(@Nonnull
                                      java.io.Reader reader)
                               throws java.io.IOException
        Parses a resource; either a tag or a resource representation with an optional description. The next character read must be the start of the resource.
        Parameters:
        reader - The reader containing SURF data.
        Returns:
        An object representing the SURF resource read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        com.globalmentor.io.ParseIOException - if the SURF data was invalid.

      • parseResource

        public java.lang.Object parseResource​(@Nonnull
                                      java.io.Reader reader,
                                      boolean allowDescription)
                               throws java.io.IOException
        Parses a resource; either a tag or a resource representation. The next character read must be the start of the resource.
        Parameters:
        reader - The reader containing SURF data.
        allowDescription - Whether a description is allowed; if false, any following description delimiter will not be considered part of the resource.
        Returns:
        An object representing the SURF resource read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        com.globalmentor.io.ParseIOException - if the SURF data was invalid.

      • parseObject

        public SurfObject parseObject​(@Nullable
                              java.net.URI tag,
                              @Nonnull
                              java.io.Reader reader)
                       throws java.io.IOException
        Parses an object, a described resource instance indicated by 42. The next character read is expected to be 42.
        Parameters:
        tag - The object resource's globally identifying tag, or null if the object has no tag.
        reader - The reader containing SURF data.
        Returns:
        The SURF object read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        See Also:
        SURF.OBJECT_BEGIN

      • parseObject

        protected SurfObject parseObject​(@Nullable
                                 java.lang.Object label,
                                 @Nonnull
                                 java.io.Reader reader)
                          throws java.io.IOException
        Parses an object indicated by 42. The next character read is expected to be 42.

        If the given label indicates an ID, after parsing the object type if an object already exists with the given ID for that type, it will be immediately returned.

        Parameters:
        label - The object label; either an SurfParser.Alias, a URI representing a tag IRI, or a String representing an ID.
        reader - The reader containing SURF data.
        Returns:
        The SURF object read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        See Also:
        SURF.OBJECT_BEGIN

      • parseDescription

        protected SurfObject parseDescription​(@Nonnull
                                      java.io.Reader reader,
                                      @Nonnull
                                      SurfObject resource)
                               throws java.io.IOException
        Parses the description properties of a resource. The next character read is expected to be the start of the description 58.
        Parameters:
        reader - The reader containing SURF data.
        resource - The resource to which properties should be added; SURF only supports object descriptions.
        Returns:
        The described SURF resource read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.
        See Also:
        SURF.DESCRIPTION_BEGIN

      • parseBinary

        public static byte[] parseBinary​(@Nonnull
                                 java.io.Reader reader)
                          throws java.io.IOException,
                                 com.globalmentor.io.ParseIOException
        Parses a binary literal. The current position must be that of the beginning binary delimiter character. The new position will be that immediately after the last character in the base64 alphabet.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        An array of bytes Java URI containing the IRI parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the IRI is not in the correct format.
        See Also:
        SURF.BINARY_BEGIN

      • parseBoolean

        public static java.lang.Boolean parseBoolean​(@Nonnull
                                             java.io.Reader reader)
                                      throws java.io.IOException
        Parses a Boolean value. The next character read is expected to be the start of SURF.BOOLEAN_FALSE_LEXICAL_FORM or SURF.BOOLEAN_TRUE_LEXICAL_FORM.
        Parameters:
        reader - The reader containing SURF data.
        Returns:
        A Boolean representing the SURF boolean literal read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.

      • parseCharacter

        public static com.globalmentor.java.CodePointCharacter parseCharacter​(@Nonnull
                                                                      java.io.Reader reader)
                                                               throws java.io.IOException,
                                                                      com.globalmentor.io.ParseIOException
        Parses a character literal. The current position must be that of the beginning character delimiter character. The new position will be that immediately after the ending character delimiter character.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The code point character parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the character literal is empty, if a control character was present, if the character is not escaped correctly, or the reader has no more characters before the current character is completely parsed.
        See Also:
        parseCharacterCodePoint(Reader, char)

      • parseCharacterCodePoint

        public static int parseCharacterCodePoint​(@Nonnull
                                          java.io.Reader reader,
                                          char delimiter)
                                   throws java.io.IOException,
                                          com.globalmentor.io.ParseIOException
        Parses a character as content, without any delimiters. The current position must be that of the character, which may be an escape sequence. The new position will be that immediately after the character.

        This method always allows the delimiter to be escaped.

        Parameters:
        reader - The reader the contents of which to be parsed.
        delimiter - The delimiter that surrounds the character and which should be escaped.
        Returns:
        The code point parsed from the reader, or -1 if the unescaped delimiter was encountered.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if a control character was represented, if the character is not escaped correctly, or the reader has no more characters before the current character is completely parsed.

      • parseEmailAddress

        public static com.globalmentor.net.EmailAddress parseEmailAddress​(@Nonnull
                                                                  java.io.Reader reader)
                                                           throws java.io.IOException,
                                                                  com.globalmentor.io.ParseIOException
        Parses an email address. The current position must be that of the beginning email delimiter character. The new position will be that immediately after the last character in the email address.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        An instance of EmailAddress representing the SURF email addresses parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the email address is not in the correct format.
        See Also:
        SURF.EMAIL_ADDRESS_BEGIN

      • parseIRI

        public static java.net.URI parseIRI​(@Nonnull
                                    java.io.Reader reader)
                             throws java.io.IOException,
                                    com.globalmentor.io.ParseIOException
        Parses an IRI. The current position must be that of the beginning IRI delimiter character. The new position will be that immediately after the ending IRI delimiter character.

        SURF IRI short forms are accepted.

        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        A Java URI containing the IRI parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the IRI is not in the correct format.
        See Also:
        SURF.IRI_BEGIN, SURF.IRI_END

      • parseMediaType

        public static com.globalmentor.net.MediaType parseMediaType​(@Nonnull
                                                            java.io.Reader reader)
                                                     throws java.io.IOException,
                                                            com.globalmentor.io.ParseIOException
        Parses a media type. The current position must be that of the beginning media type delimiter character. The new position will be that immediately after the ending media type delimiter character.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        An instance of MediaType representing the SURF media type parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the media type is not in the correct format.
        See Also:
        SURF.MEDIA_TYPE_BEGIN, SURF.MEDIA_TYPE_END

      • parseMediaTypeRestrictedName

        protected static java.lang.String parseMediaTypeRestrictedName​(@Nonnull
                                                               java.io.Reader reader)
                                                        throws java.io.IOException,
                                                               com.globalmentor.io.ParseIOException
        Parses a restricted name of an Internet media type. The current position must be that of the first character of the restricted name. The new position will be that immediately after the restricted name, or at the end of the reader.
        API Note:
        The restricted-name production in RFC 6838 is used for the primary type, the subtype, and each parameter name.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        A media type restricted name parsed from the reader. The value is guaranteed to match the MediaType.RESTRICTED_NAME_PATTERN pattern.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the restricted name is not in the correct format.
        See Also:
        MediaType.RESTRICTED_NAME_PATTERN

      • parseNumber

        public static java.lang.Number parseNumber​(@Nonnull
                                           java.io.Reader reader)
                                    throws java.io.IOException,
                                           com.globalmentor.io.ParseIOException
        Parses a number. The current position must be that of the first character of the number. The new position will be that immediately after the number, or at the end of the reader.

        This implementation will return one of the following types:

        Long
        All non-decimal, non-fractional, non-exponent numbers that fall within the range of long.
        BigInteger
        All non-decimal, non-fractional, non-exponent numbers that fall outside the range of long.
        Double
        All non-decimal, fractional and/or exponent numbers.
        BigDecimal
        All decimal numbers.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        A Java Number containing the number parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the number is not in the correct format, or if the number is outside the range that can be represented by this parser.

      • parseRegularExpression

        public static java.util.regex.Pattern parseRegularExpression​(@Nonnull
                                                             java.io.Reader reader)
                                                      throws java.io.IOException,
                                                             com.globalmentor.io.ParseIOException
        Parses a regular expression surrounded by regular expression delimiters and optionally ending with flags. The current position must be that of the first regular expression delimiter character. The new position will be that immediately after the regular expression delimiter character or, if there are flags, after the last flag.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The pattern representing the regular expression parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the regular expressions is not escaped correctly or the reader has no more characters before the current regular expression is completely parsed.
        See Also:
        SURF.REGULAR_EXPRESSION_DELIMITER, SURF.REGULAR_EXPRESSION_ESCAPE

      • parseString

        public static java.lang.String parseString​(@Nonnull
                                           java.io.Reader reader)
                                    throws java.io.IOException,
                                           com.globalmentor.io.ParseIOException
        Parses a string surrounded by string delimiters. The current position must be that of the first string delimiter character. The new position will be that immediately after the string delimiter character.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The string parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if a control character was present, if the string is not escaped correctly, or the reader has no more characters before the current string is completely parsed.
        See Also:
        SURF.STRING_DELIMITER, parseCharacterCodePoint(Reader, char)

      • parseTelephoneNumber

        public static com.globalmentor.itu.TelephoneNumber parseTelephoneNumber​(@Nonnull
                                                                        java.io.Reader reader)
                                                                 throws java.io.IOException,
                                                                        com.globalmentor.io.ParseIOException
        Parses a telephone number. The current position must be that of the beginning telephone number delimiter character. The new position will be that immediately after the last character in the telephone number.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        An instance of TelephoneNumber representing the SURF telephone number parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the telephone number is not in the correct format.
        See Also:
        SURF.TELEPHONE_NUMBER_BEGIN

      • parseTemporal

        public static java.time.temporal.TemporalAccessor parseTemporal​(@Nonnull
                                                                java.io.Reader reader)
                                                         throws java.io.IOException,
                                                                com.globalmentor.io.ParseIOException
        Parses a temporal. The current position must be that of the beginning temporal delimiter. The new position will be that immediately after the temporal, or at the end of the reader.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        A Java representation of the temporal parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the temporal is not in the correct format, or if the temporal is outside the range that can be represented by this parser.
        See Also:
        SURF.TEMPORAL_BEGIN

      • parseUuid

        public static java.util.UUID parseUuid​(@Nonnull
                                       java.io.Reader reader)
                                throws java.io.IOException,
                                       com.globalmentor.io.ParseIOException
        Parses a UUID. The current position must be that of the beginning UUID delimiter character. The new position will be that immediately after the last character in the UUID.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        An instance of UUID representing the SURF UUID parsed from the reader.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.
        com.globalmentor.io.ParseIOException - if the UUID is not in the correct format.
        See Also:
        SURF.UUID_BEGIN

      • parseList

        public java.util.List<java.lang.Object> parseList​(@Nullable
                                                  io.urf.surf.SurfParser.Alias alias,
                                                  @Nonnull
                                                  java.io.Reader reader)
                                           throws java.io.IOException
        Parses an a list. The current position must be for 91. The new position will be that immediately following 93.

        Once the list is created, it will be associated with the given alias if any.

        Parameters:
        alias - The resource alias, or null if the resource has no alias.
        reader - The reader containing SURF data.
        Returns:
        The list read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.

      • parseMap

        public java.util.Map<java.lang.Object,​java.lang.Object> parseMap​(@Nullable
                                                                       io.urf.surf.SurfParser.Alias alias,
                                                                       @Nonnull
                                                                       java.io.Reader reader)
                                                                throws java.io.IOException
        Parses a map. The current position must be for 123. The new position will be that immediately following 125.

        Once the map is created, it will be associated with the given alias if any.

        Parameters:
        alias - The resource alias, or null if the resource has no alias.
        reader - The reader containing SURF data.
        Returns:
        The map read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.

      • parseSet

        public java.util.Set<java.lang.Object> parseSet​(@Nullable
                                                io.urf.surf.SurfParser.Alias alias,
                                                @Nonnull
                                                java.io.Reader reader)
                                         throws java.io.IOException
        Parses a set. The current position must be for 40. The new position will be that immediately following 41.

        Once the set is created, it will be associated with the given alias if any.

        Parameters:
        alias - The resource alias, or null if the resource has no alias.
        reader - The reader containing SURF data.
        Returns:
        The set read from the reader.
        Throws:
        java.io.IOException - If there was an error reading the SURF data.

      • parseSequence

        protected static int parseSequence​(@Nonnull
                                   java.io.Reader reader,
                                   char sequenceEnd,
                                   @Nonnull
                                   com.globalmentor.io.function.IOConsumer<java.io.Reader> itemParser)
                            throws java.io.IOException
        Parses a general SURF sequence (such as a list). This method skips whitespace, comments, and sequence delimiters. For each sequence item, IOConsumer.accept(Object) is called, passing the Reader, for the item to be parsed. The sequence ends when the sequence end delimiter or the end of the reader is reached.
        API Note:
        This method will return if it encounters the end of the reader, so if the sequence end is required the caller must check the return value., The sequence end is provided to detect the end of the sequence after a newline. This method does not guarantee that the sequence end will be reached. This means the method does not consume subsequent characters that are not part of the sequence, such as the bar in "foo bar", it is up to the caller to confirm that subsequent characters (which are considered "after the sequence") are as expected.
        Parameters:
        reader - The reader containing the sequence to parse.
        sequenceEnd - The character expected to end the sequence.
        itemParser - The parser strategy, which is passed the Reader to use for parsing.
        Returns:
        The next character that will be returned by the reader's Reader.read() operation, or -1 if the end of the reader has been reached without encountering the end of the sequence.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.

      • skipSequenceDelimiters

        protected static java.util.Optional<java.lang.Boolean> skipSequenceDelimiters​(@Nonnull
                                                                              java.io.Reader reader)
                                                                       throws java.io.IOException
        Skips over SURF sequence delimiters in a reader. Whitespace and comments. The new position will either be the that of the first non-whitespace and non-EOL character; or the end of the reader.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        Boolean.TRUE if a sequence delimiter was encountered that requires a following item, Boolean.FALSE if a sequence delimiter was encountered for which a following item is optional, or Optional.empty() if no sequence delimiter was encountered.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.

      • skipFiller

        protected static int skipFiller​(@Nonnull
                                java.io.Reader reader)
                         throws java.io.IOException
        Skips over SURF filler in a reader, which includes whitespace, line comments, and line breaks. The new position will either be the that of the first non-filler character or the end of the reader.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Returns:
        The next character that will be returned the reader's Reader.read() operation, or -1 if the end of the reader has been reached.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.

      • skipLineComment

        protected static void skipLineComment​(@Nonnull
                                      java.io.Reader reader)
                               throws java.io.IOException
        Skips a single line comments. The current position must be that of the line comment delimiter. The new position will either be the that of the following newline character or the end of the reader.
        Parameters:
        reader - The reader the contents of which to be parsed.
        Throws:
        java.lang.NullPointerException - if the given reader is null.
        java.io.IOException - if there is an error reading from the reader.