Class Parser.OrEmpty

java.lang.Object
com.google.common.labs.parse.Parser.OrEmpty
Enclosing class:
Parser<T>
public final class Parser.OrEmpty extends Object
Facilitates a fluent chain for matching the current parser optionally. This is needed because we require all parsers to match at least one character. So optionality is only legal when combined together with a non-empty prefix, suffix or both, which will be specified by methods of this class.

Besides between() and followedBy(), the sequence() and Parser.followedBy(Parser.OrEmpty) methods can be used to specify that a Parser.OrEmpty grammar rule follows a regular consuming Parser.

The following is a simplified example of parsing a CSV line: a comma-separated list of fields with an optional trailing newline. The field values can be empty; empty line results in empty list [], not [""]: 


 Parser<String> field = consecutive(noneOf(",\n"));
 Parser<?> newline = string("\n");
 Parser<List<String>> csvRow =
     anyOf(
         newline.thenReturn(List.of()),          // empty line -> []
         field
             .orElse("")                         // empty field is ok
             .delimitedBy(",")                   // comma-separated
             .notEmpty()                         // non-empty line
             .followedByOrEof(newline));         // trailing newline optional on last line

In addition, the parse(java.lang.String) convenience method is provided to parse potentially-empty input in this one stop shop without having to remember to check for emptiness, because this class already knows the default value to use when the input is empty.

  • Method Summary

    Modifier and Type
    Method
    Description
    Parser<T>
    between(Parser<?> prefix, Parser<?> suffix)
    The current optional (or zero-or-more) parser must be enclosed between non-empty prefix and suffix.
    Parser<T>
    between(String prefix, String suffix)
    The current optional (or zero-or-more) parser must be enclosed between non-empty prefix and suffix.
    Parser<List<T>>.OrEmpty
    delimitedBy(String delimiter)
    The current optional parser repeated and delimited by delimiter.
    <R> Parser<R>.OrEmpty
    delimitedBy(String delimiter, Collector<? super T, ?, R> collector)
    The current optional parser repeated and delimited by delimiter.
    <S> Parser<T>.OrEmpty
    followedBy(Parser<S>.OrEmpty suffix)
    The current optional (or zero-or-more) parser may optionally be followed by suffix.
    Parser<T>
    followedBy(String suffix)
    The current optional (or zero-or-more) parser must be followed by non-empty suffix.
    final Parser<T>
    immediatelyBetween(String prefix, String suffix)
    The current optional (or zero-or-more) parser must be immediately enclosed between non-empty prefix and suffix (no skippable characters as specified by parseSkipping() in between).
    Parser<T>
    notEmpty()
    Returns the otherwise equivalent Parser that will fail instead of returning the default value if empty.
    T
    parse(String input)
    Parses the entire input string and returns the result; if input is empty, returns the default empty value.
    T
    parseSkipping(Parser<?> skip, String input)
    Parses the entire input string, ignoring patterns matched by skip, and returns the result; if there's nothing to parse except skippable content, returns the default empty value.
    T
    parseSkipping(CharPredicate charsToSkip, String input)
    Parses the entire input string, ignoring charsToSkip, and returns the result; if there's nothing to parse except skippable content, returns the default empty value.
    <S> Parser<S>.OrEmpty
    then(Parser<S>.OrEmpty suffix)
    After matching the current optional (or zero-or-more) parser, proceed to match suffix.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • between

      public Parser<T> between(String prefix, String suffix)
      The current optional (or zero-or-more) parser must be enclosed between non-empty prefix and suffix.

    • between

      public Parser<T> between(Parser<?> prefix, Parser<?> suffix)
      The current optional (or zero-or-more) parser must be enclosed between non-empty prefix and suffix.

    • immediatelyBetween

      public final Parser<T> immediatelyBetween(String prefix, String suffix)
      The current optional (or zero-or-more) parser must be immediately enclosed between non-empty prefix and suffix (no skippable characters as specified by parseSkipping() in between). Useful for matching a literal string, such as zeroOrMore(isNot('"')).immediatelyBetween("\"", "\"").

    • delimitedBy

      public <R> Parser<R>.OrEmpty delimitedBy(String delimiter, Collector<? super T, ?, R> collector)
      The current optional parser repeated and delimited by delimiter. Since this is an optional parser, at least one value is guaranteed to be collected by the provided collector, even if match failed. That is, on match failure, the default value (e.g. from orElse()) will be used.

      Note that it's different from Parser.zeroOrMoreDelimitedBy(java.lang.String), which may produce empty list, but each element is guaranteed to be non-empty.

    • delimitedBy

      public Parser<List<T>>.OrEmpty delimitedBy(String delimiter)
      The current optional parser repeated and delimited by delimiter. Since this is an optional parser, at least one element is guaranteed to be returned, even if match failed. For example, consecutive(WORD).orElse("").delimitedBy(",") will parse input ",a," as List.of("", "a", ""); and parse empty input "" as List.of("").

      Note that it's different from Parser.zeroOrMoreDelimitedBy(java.lang.String), which may produce empty list, but each element is guaranteed to be non-empty.

    • then

      public <S> Parser<S>.OrEmpty then(Parser<S>.OrEmpty suffix)
      After matching the current optional (or zero-or-more) parser, proceed to match suffix.

    • followedBy

      public Parser<T> followedBy(String suffix)
      The current optional (or zero-or-more) parser must be followed by non-empty suffix.

      Note that there is no after(), but you can use sequence() and Parser.followedBy(Parser.OrEmpty) to specify that a Parser.OrEmpty grammar rule follows a regular consuming Parser.

    • followedBy

      public <S> Parser<T>.OrEmpty followedBy(Parser<S>.OrEmpty suffix)
      The current optional (or zero-or-more) parser may optionally be followed by suffix.

    • notEmpty

      public Parser<T> notEmpty()
      Returns the otherwise equivalent Parser that will fail instead of returning the default value if empty.

      parser.optional().notEmpty() is equivalent to parser.

      Useful when multiple optional parsers are chained together with any of them successfully consuming some input.

    • parse

      public T parse(String input)
      Parses the entire input string and returns the result; if input is empty, returns the default empty value.

    • parseSkipping

      public T parseSkipping(Parser<?> skip, String input)
      Parses the entire input string, ignoring patterns matched by skip, and returns the result; if there's nothing to parse except skippable content, returns the default empty value.

    • parseSkipping

      public T parseSkipping(CharPredicate charsToSkip, String input)
      Parses the entire input string, ignoring charsToSkip, and returns the result; if there's nothing to parse except skippable content, returns the default empty value.