Signal the end of the data stream to this handler, forcing it to generate a result. Handlers may throw exceptions in response to this, such as a handler which wants the first event from an empty stream.

Further calls to step or finish after the first call to finish will result in undefined behavior. The general assumption is that a handler should be discarded after its finish method is called.

Advance the state of this handler by accepting a single input of type In. If doing so would cause this parser to complete, return a Left containing the output. Otherwise, return a Right containing the next parser state.

Handlers are assumed to be internally-mutable, so it is acceptable to simply update some internal state and then return Right(this), although in some cases it will be desirable to return a separate handler entirely.

Wraps this handler as a "top level" handler, which will inject a SpacTraceElement (representing the current input or the "EOF" signal) to any exception is thrown by this handler when calling its step or finish methods.

Used internally by Parser's parse methods.

Represent this parser as a Transformer which emits this parser's result

Like wrapSafe, but represents exceptions as Left and successful results as Right

Specialization of interruptedBy for stack-like input types, such that an interruption will occur upon entering a stack context that can be matched by the given matcher.

Example:

val preludeContext = * \ "prelude"
val dataContext = * \ "data"
for {
  prelude <- Splitter(preludeContext).firstOption[Prelude].beforeContext(dataContext).followedByStream
  data <- Splitter(dataContext).as[Data]
} yield data

Impose expectations on the sequence of inputs to be received by handlers created by this parser. As this parser's handler receives an input, the input will be tested against the head of the expectations list. If the test returns false, the expectation is failed and the handler will throw an exception. If the test returns true, the expectation is satisfied, and the handler will advance to the next expectation. If there are no more expectations left in the list (i.e. N inputs have satisfied the corresponding N expectations), then all expectations have been met and inputs will be treated as normal by the handler. If the handler receives an EOF before all expectations are met, it will throw an exception.

Create a copy of this parser that will treat a result from the interrupter as an early EOF. This is especially useful for creating followedBy chains involving optional elements.

Normally, a parser for an optional item in some context will not finish until that context ends, or until the item is encountered. So if the item is not present, followedBy logic won't work since the followUp parser/transformer will not see any events.

To make sure the leading parser can "fail fast", you can "interrupt" it, typically by creating a parser that immediately returns a result upon entering a particular context, i.e. the context in which the "following" parser will start. Parser#beforeContext provides a convenience for doing so.

Note that if the interrupter throws an exception, that exception will not be caught. If your interrupter might throw, pass interrupter.wrapSafe instead to swallow the exception.

Create a copy of this Parser whose result is transformed by the given function f.

Parser's main abstract method; constructs a new Handler representing this parser's logic. Parsers are expected to be immutable, but Handlers may be internally-mutable.

Combine this parser with the fallback such that failures from the underlying parsers will be ignored as long as at least one succeeds. The result will be the result of whichever underlying parser succeeds first. If all of the underlying parsers fail, a SpacException.FallbackChainFailure will be thrown by the returned parser's handler.

Consume the given source to produce an output or possibly throw a SpacException.

The Source[A] type is like Iterable[A] but uses the "lender" pattern to acquire the iterator and close any resources associated with the iterator after the iterator is consumed.

XML and JSON-specific Source constructors are provided by the "parser backend" libraries i.e. xml-spac-javax and json-spac-jackson.

Consume the given inputs iterator to produce an output or possibly throw a SpacException.

After calling this method, the inputs should be discarded, since consuming an Iterator is a destructive operation.

Like unwrapSafe, but rethrows exceptions from Left or returns results from Right. This operation is the opposite of attempt.

Low-level consumer method: creates a new handler and binds the caller position for its SpacTraceElement.

Used internally by the parse methods. Start with this method if you have some sequence-like datatype that doesn't provide an Iterator.

This is just a convenience for newHandler.asTopLevelhandler which helps construct a useful SpacTraceElement.

Convenience function to call step on a sequence of inputs all at once. If the step returns a result, this method will return a Left containing that result and the remainder of the inputs that were not consumed. If the inputs run out before the handler returns a result from a step, this method will return a Right containing the latest state of the handler. This method will not call the handler's finish().

In general, you won't call this method directly. Instead, use one of the Parser trait's parse methods.

Creates a copy of this parser which unwraps the resulting Try, throwing an exception if the result was a Failure. This operation is the opposite of wrapSafe.

Returns this parser, with the output type widened to Out2, which is some supertype of Out. Uses asInstanceOf rather than creating a new parser.

Creates a copy of this parser, but with a different toString

Create a copy of this Parser whose handler will catch NonFatal exceptions thrown by the underlying logic. Caught exceptions will be yielded as a Failure output. Normal results will be wrapped in Success.

Intermediate object for creating a sequenced parser in which the result of this parser will be used to initialize a second parser as soon as it is available.

In other words, the source (series of In values) will be fed into this Parser until this parser's handler returns a result of type Out. At that point, the second parser (as specified by using the apply or flatMap methods on the FollowedBy returned by this method) will be instantiated. Any relevant "stack events" (see Stackable) will be replayed so the second parser has the right context, and from that point on, all In values will be sent to the second parser. When that second parser returns a result, that result becomes the output of the combined parser created by this.followedBy(out => makeSecondParser(out))

Examples:

val p1: Parser[A] = /* ... */
def getP2(p1Result: A): Parser[B] = /* ... */
val combined: Parser[B] = p1.followedBy(getP2)

// alternative `flatMap` syntax
val combined: Parser[B] = for {
  p1Result <- p1.followedBy
  p2Result <- getP2(p1Result)
} yield p2Result

See Parser's interruptedBy, which is useful when a transformer.parseFirstOption must be followedBy some other parser.

Intermediate object for creating a sequenced parser in which the result of this parser will be used to initialize a second parser as soon as it is available.

In other words, the source (series of In values) will be fed into this Parser until this parser's handler returns a result of type Out. At that point, the second parser (as specified by using the apply or flatMap methods on the FollowedBy returned by this method) will be instantiated. Any relevant "stack events" (see Stackable) will be replayed so the second parser has the right context, and from that point on, all In values will be sent to the second parser. When that second parser returns a result, that result becomes the output of the combined parser created by this.followedBy(out => makeSecondParser(out))

Examples:

val p1: Parser[A] = /* ... */
def getP2(p1Result: A): Parser[B] = /* ... */
val combined: Parser[B] = p1.followedBy(getP2)

// alternative `flatMap` syntax
val combined: Parser[B] = for {
  p1Result <- p1.followedBy
  p2Result <- getP2(p1Result)
} yield p2Result

See Parser's interruptedBy, which is useful when a transformer.parseFirstOption must be followedBy some other parser.

Alias for followedBy, for use when Cat's ApplyOps gets in the way with its own useless followedBy method.

Alias for followedBy, for use when Cat's ApplyOps gets in the way with its own useless followedBy method.

Intermediate object creating a transformer that depends on this parser. Particularly useful in cases where one or more specific "info" elements precede a stream of other elements which require that "info" to be parsed.

Examples:

val p1: Parser[In, A] = /* ... */
def getP2Stream(p1Result: A): Transformer[In, B] = /* ... */
val combined: Transformer[In, B] = p1.andThenStream(getP2Stream)

// alternative `flatMap` syntax
val combined: Transformer[In, B] = for {
  p1Result <- p1.andThenStream
  p2Result <- getP2Stream(p1Result)
} yield p2Result

See followedBy for a general explanation of how the combination works.

See also, interruptedBy, which is useful when a transformer.parseFirstOption must be followedBy some other transformer.

Intermediate object creating a transformer that depends on this parser. Particularly useful in cases where one or more specific "info" elements precede a stream of other elements which require that "info" to be parsed.

Examples:

val p1: Parser[In, A] = /* ... */
def getP2Stream(p1Result: A): Transformer[In, B] = /* ... */
val combined: Transformer[In, B] = p1.andThenStream(getP2Stream)

// alternative `flatMap` syntax
val combined: Transformer[In, B] = for {
  p1Result <- p1.andThenStream
  p2Result <- getP2Stream(p1Result)
} yield p2Result

See followedBy for a general explanation of how the combination works.

See also, interruptedBy, which is useful when a transformer.parseFirstOption must be followedBy some other transformer.