Class Parser.OrEmpty

java.lang.Object
com.google.common.labs.parse.Parser.OrEmpty
All Implemented Interfaces:
Production<T>
Enclosing class:
Parser<T>
public final class Parser.OrEmpty extends Object implements Production<T>
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

invalid reference 
sequence()
and Parser.followedBy(Parser.OrEmpty) methods can be used to specify that a Parser.OrEmpty production 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 Details

    • between

      public final Parser<T>.OrEmpty between(Parser<?>.OrEmpty prefix, Parser<?>.OrEmpty suffix)
      The current parser enclosed between prefix and suffix, both allowed to be empty.
      Specified by:
      between in interface Production<T>
      Since:
      9.5

    • 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> then(Parser<S> suffix)
      Description copied from interface: Production
      After matching the current production, proceed to match suffix.
      Specified by:
      then in interface Production<T>

    • 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.
      Specified by:
      then in interface Production<T>

    • followedBy

      public Parser<T> followedBy(Parser<?> suffix)
      Description copied from interface: Production
      The current production must be followed by non-empty suffix.
      Specified by:
      followedBy in interface Production<T>

    • 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.
      Specified by:
      followedBy in interface Production<T>

    • optionallyFollowedBy

      public Parser<T>.OrEmpty optionallyFollowedBy(String suffix)
      The current optional (or zero-or-more) parser may optionally be followed by suffix.
      Specified by:
      optionallyFollowedBy in interface Production<T>
      Since:
      9.5

    • optionallyFollowedBy

      public final Parser<T>.OrEmpty optionallyFollowedBy(String suffix, Function<? super T, ? extends T> op)
      If this parser matches, optionally applies the op function if the pattern is followed by suffix.
      Specified by:
      optionallyFollowedBy in interface Production<T>
      Since:
      10.0

    • optionallyFollowedBy

      public final <S> Parser<T>.OrEmpty optionallyFollowedBy(Parser<S> suffix, BiFunction<? super T, ? super S, ? extends T> op)
      If this parser matches, optionally matches suffix with the op BiFunction to transform the current parser's result.
      Specified by:
      optionallyFollowedBy in interface Production<T>
      Since:
      10.0

    • 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.
      Specified by:
      parse in interface Production<T>

    • 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.
      Specified by:
      parseSkipping in interface Production<T>

    • 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.
      Specified by:
      parseSkipping in interface Production<T>

    • matches

      public boolean matches(String input)
      Returns true if this parser matches the entirety of the input, or if the input is empty. It's similar to the regex Matcher.matches(String) method.
      Specified by:
      matches in interface Production<T>
      Since:
      9.9.1