Module error

Error management

Errors are designed with multiple needs in mind:

• Accumulate more context as the error goes up the parser chain
• Distinguish between recoverable errors, unrecoverable errors, and more data is needed
• Have a very low overhead, as errors are often discarded by the calling parser (examples: repeat, alt)
• Can be modified according to the user’s needs, because some languages need a lot more information
• Help thread-through the stream

To abstract these needs away from the user, generally winnow parsers use the ModalResult alias, rather than Result. Parser::parse is a top-level operation that can help convert to a Result for integrating with your application’s error reporting.

Error types include:

• EmptyError when the reason for failure doesn’t matter
• ContextError
• InputError (mostly for testing)
• TreeError (mostly for testing)
• [Custom errors][crate::_topic::error]

Structs

• ContextError
  Accumulate context while backtracking errors
• EmptyError
  Track an error occurred without any other StrContext
• InputError
  Capture input on error
• ParseError
  See Parser::parse
• TreeErrorBase
  See TreeErrorFrame::Kind, ParserError::append
• TreeErrorContext
  See TreeErrorFrame::Context, AddContext::add_context

Enums

• ErrMode
  Add parse error state to ParserErrors
• Needed
  Contains information on needed data if a parser returned Incomplete
• StrContext
  Additional parse context for ContextError added via Parser::context
• StrContextValue
  See StrContext
• TreeError
  Trace all error paths, particularly for tests
• TreeErrorFrame
  See TreeError::Stack

Traits

• AddContext
  Used by Parser::context to add custom data to error while backtracking
• ErrorConvert
  Equivalent of From implementation to avoid orphan rules in bits parsers
• FromExternalError
  Create a new error with an external error, from std::str::FromStr
• ModalError
  Manipulate the how parsers respond to this error
• ParserError
  The basic Parser trait for errors

Type Aliases

• ModalResult
  Modal error reporting for Parser::parse_next
• Result
  By default, the error type (E) is ContextError.