io.urf.surf

Class SurfParser

java.lang.Object

io.urf.surf.SurfParser

public class SurfParser
extends 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 and Description
protected static com.globalmentor.java.Characters	WHITESPACE_EOL_CHARACTERS Whitespace and end-of-line characters.

Constructor Summary

Constructors

Constructor and Description
SurfParser()

Method Summary

Modifier and Type	Method and Description
Optional<SurfObject>	findObjectById(String typeHandle, String id) Returns a parsed object by its type handle and ID.
Optional<SurfObject>	findObjectByTag(URI tag) Returns a parsed object by its tag.
Optional<Object>	findResourceByAlias(String alias) Returns a parsed resource by its alias.
protected SurfObject	getObjectById(String typeHandle, String id) Returns a parsed object by its type handle and ID.
Optional<Object>	parse(InputStream inputStream) Parses a SURF resource from an input stream.
Optional<Object>	parse(Reader reader) Parses a SURF resource from a reader.
Optional<Object>	parse(String string) Parses a SURF resource from a string.
static byte[]	parseBinary(Reader reader) Parses a binary literal.
static Boolean	parseBoolean(Reader reader) Parses a Boolean value.
static com.globalmentor.java.CodePointCharacter	parseCharacter(Reader reader) Parses a character literal.
static int	parseCharacterCodePoint(Reader reader, char delimiter) Parses a character as content, without any delimiters.
protected SurfObject	parseDescription(Reader reader, SurfObject resource) Parses the description properties of a resource.
static com.globalmentor.net.EmailAddress	parseEmailAddress(Reader reader) Parses an email address.
static String	parseHandle(Reader reader) Parses a handle composed of a name token followed by zero or more name tokens, separated by handle segment delimiters.
static URI	parseIRI(Reader reader) Parses an IRI.
static Object	parseLabel(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 Alias containing the alias string.
List<Object>	parseList(io.urf.surf.SurfParser.Alias alias, Reader reader) Parses an a list.
Map<Object,Object>	parseMap(io.urf.surf.SurfParser.Alias alias, Reader reader) Parses a map.
protected static String	parseNameToken(Reader reader) Parses a name token composed of a name token beginning character followed by zero or more name token characters.
static Number	parseNumber(Reader reader) Parses a number.
protected SurfObject	parseObject(Object label, Reader reader) Parses an object indicated by .
SurfObject	parseObject(URI tag, Reader reader) Parses an object, a described resource instance indicated by .
static Pattern	parseRegularExpression(Reader reader) Parses a regular expression surrounded by regular expression delimiters and optionally ending with flags.
Object	parseResource(Reader reader) Parses a resource; either a tag or a resource representation with an optional description.
Object	parseResource(Reader reader, boolean allowDescription) Parses a resource; either a tag or a resource representation.
protected static int	parseSequence(Reader reader, char sequenceEnd, com.globalmentor.io.function.IOConsumer<Reader> itemParser) Parses a general SURF sequence (such as a list).
Set<Object>	parseSet(io.urf.surf.SurfParser.Alias alias, Reader reader) Parses a set.
static String	parseString(Reader reader) Parses a string surrounded by string delimiters.
static com.globalmentor.itu.TelephoneNumber	parseTelephoneNumber(Reader reader) Parses a telephone number.
static TemporalAccessor	parseTemporal(Reader reader) Parses a temporal.
static UUID	parseUuid(Reader reader) Parses a UUID.
protected static int	skipFiller(Reader reader) Skips over SURF filler in a reader, including whitespace and line comments.The new position will either be the that of the first non-whitespace character or the end of the input stream.
protected static int	skipLineBreaks(Reader reader) Skips over SURF line breaks in a reader, including whitespace and line comments.
protected static Optional<Boolean>	skipSequenceDelimiters(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 Optional<Object> findResourceByAlias(@Nonnull
                                            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 Optional<SurfObject> findObjectByTag(@Nonnull
                                            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 Optional<SurfObject> findObjectById(@Nonnull
                                           String typeHandle,
                                           @Nonnull
                                           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
                                   String typeHandle,
                                   @Nonnull
                                   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 Optional<Object> parse(@Nonnull
                              String string)
                       throws 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:

IOException - If there was an error reading the SURF data.

com.globalmentor.io.ParseIOException - if the SURF data was invalid.

parse

public Optional<Object> parse(@Nonnull
                              InputStream inputStream)
                       throws 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:

IOException - If there was an error reading the SURF data.

com.globalmentor.io.ParseIOException - if the SURF data was invalid.

parse

public Optional<Object> parse(@Nonnull
                              Reader reader)
                       throws 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:

IOException - If there was an error reading the SURF data.

com.globalmentor.io.ParseIOException - if the SURF data was invalid.

parseLabel

public static Object parseLabel(@Nonnull
                                Reader reader)
                         throws 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 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 Alias, an absolute URI for a tag, or String for an ID.

Throws:

NullPointerException - if the given reader is null.

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 String parseNameToken(@Nonnull
                                       Reader reader)
                                throws 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:

NullPointerException - if the given reader is null.

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 String parseHandle(@Nonnull
                                 Reader reader)
                          throws 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:

NullPointerException - if the given reader is null.

IOException - if there is an error reading from the reader.

com.globalmentor.io.ParseIOException - if there are are no handle characters.

parseResource

public Object parseResource(@Nonnull
                            Reader reader)
                     throws 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:

IOException - If there was an error reading the SURF data.

com.globalmentor.io.ParseIOException - if the SURF data was invalid.

parseResource

public Object parseResource(@Nonnull
                            Reader reader,
                            boolean allowDescription)
                     throws 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, an following description delimiter will not be considered part of the resource.

Returns:

An object representing the SURF resource read from the reader.

Throws:

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
                              URI tag,
                              @Nonnull
                              Reader reader)
                       throws IOException

Parses an object, a described resource instance indicated by . The next character read is expected to be .

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:

IOException - If there was an error reading the SURF data.

See Also:

SURF.OBJECT_BEGIN

parseObject

protected SurfObject parseObject(@Nullable
                                 Object label,
                                 @Nonnull
                                 Reader reader)
                          throws IOException

Parses an object indicated by . The next character read is expected to be .

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 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:

IOException - If there was an error reading the SURF data.

See Also:

SURF.OBJECT_BEGIN

parseDescription

protected SurfObject parseDescription(@Nonnull
                                      Reader reader,
                                      @Nonnull
                                      SurfObject resource)
                               throws IOException

Parses the description properties of a resource. The next character read is expected to be the start of the description .

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:

IOException - If there was an error reading the SURF data.

See Also:

SURF.DESCRIPTION_BEGIN

parseBinary

public static byte[] parseBinary(@Nonnull
                                 Reader reader)
                          throws 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:

NullPointerException - if the given reader is null.

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 Boolean parseBoolean(@Nonnull
                                   Reader reader)
                            throws 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:

IOException - If there was an error reading the SURF data.

parseCharacter

public static com.globalmentor.java.CodePointCharacter parseCharacter(@Nonnull
                                                                      Reader reader)
                                                               throws 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:

NullPointerException - if the given reader is null.

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
                                          Reader reader,
                                          char delimiter)
                                   throws 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:

NullPointerException - if the given reader is null.

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
                                                                  Reader reader)
                                                           throws 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:

NullPointerException - if the given reader is null.

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 URI parseIRI(@Nonnull
                           Reader reader)
                    throws 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:

NullPointerException - if the given reader is null.

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

parseNumber

public static Number parseNumber(@Nonnull
                                 Reader reader)
                          throws 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:

Integer

All non-decimal, non-fractional, non-exponent non-decimal numbers that fall within the range of int.

Long

All non-decimal, non-fractional, non-exponent numbers that fall outside the range of int but within the range of long.

Double

All non-decimal fractional numbers that fall within the range of double.

BigInteger

All non-fractional decimal numbers.

BigDecimal

All fractional 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:

NullPointerException - if the given reader is null.

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 Pattern parseRegularExpression(@Nonnull
                                             Reader reader)
                                      throws 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:

NullPointerException - if the given reader is null.

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 String parseString(@Nonnull
                                 Reader reader)
                          throws 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:

NullPointerException - if the given reader is null.

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
                                                                        Reader reader)
                                                                 throws 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:

NullPointerException - if the given reader is null.

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 TemporalAccessor parseTemporal(@Nonnull
                                             Reader reader)
                                      throws 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:

NullPointerException - if the given reader is null.

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 UUID parseUuid(@Nonnull
                             Reader reader)
                      throws 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:

NullPointerException - if the given reader is null.

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 List<Object> parseList(@Nullable
                              io.urf.surf.SurfParser.Alias alias,
                              @Nonnull
                              Reader reader)
                       throws IOException

Parses an a list. The current position must be for . The new position will be that immediately following .

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:

IOException - If there was an error reading the SURF data.

parseMap

public Map<Object,Object> parseMap(@Nullable
                                   io.urf.surf.SurfParser.Alias alias,
                                   @Nonnull
                                   Reader reader)
                            throws IOException

Parses a map. The current position must be for . The new position will be that immediately following .

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:

IOException - If there was an error reading the SURF data.

parseSet

public Set<Object> parseSet(@Nullable
                            io.urf.surf.SurfParser.Alias alias,
                            @Nonnull
                            Reader reader)
                     throws IOException

Parses a set. The current position must be for . The new position will be that immediately following .

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:

IOException - If there was an error reading the SURF data.

parseSequence

protected static int parseSequence(@Nonnull
                                   Reader reader,
                                   char sequenceEnd,
                                   @Nonnull
                                   com.globalmentor.io.function.IOConsumer<Reader> itemParser)
                            throws 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.

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:

NullPointerException - if the given reader is null.

IOException - if there is an error reading from the reader.

skipSequenceDelimiters

protected static Optional<Boolean> skipSequenceDelimiters(@Nonnull
                                                          Reader reader)
                                                   throws 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 input stream.

Parameters:

reader - The reader the contents of which to be parsed.

Returns:

Boolean.TRUE if a line delimiter was encountered that requires a following item, Boolean.FALSE if a line delimiter was encountered for which a following item is optional, or Optional.empty() if no line ending was encountered.

Throws:

NullPointerException - if the given reader is null.

IOException - if there is an error reading from the reader.

skipFiller

protected static int skipFiller(@Nonnull
                                Reader reader)
                         throws IOException

Skips over SURF filler in a reader, including whitespace and line comments.The new position will either be the that of the first non-whitespace character or the end of the input stream.

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:

NullPointerException - if the given reader is null.

IOException - if there is an error reading from the reader.

skipLineBreaks

protected static int skipLineBreaks(@Nonnull
                                    Reader reader)
                             throws IOException

Skips over SURF line breaks in a reader, including whitespace and line comments. The new position will either be the that of the first non-whitespace and non-EOL character; or the end of the input stream.

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:

NullPointerException - if the given reader is null.

IOException - if there is an error reading from the reader.