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
             .followedBy(newline.optional())     // optional trailing newline
             .notEmpty());                       // fail if the line is completely empty

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

    • 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.

    • 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.

    • notEmpty

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

      parser.optional().failIfEmpty() 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.