Struct ParseStack 

pub struct ParseStack<'i> {
    pub(crate) at: usize,
    pub external: Option<Arc<dyn Error + Send + Sync>>,
    pub(crate) pending: Vec<StringContext>,
    pub(crate) layers: Vec<Layer>,
    pub(crate) source: &'i str,
}

A custom nested and span-aware parser error.

This error type is used across the ALPM project and provides well-formated and detailed parsing errors. It allows addition of context per layer/type. For more information on the formatting see the Display impl of ParseStack.

Fields

at: usize

Byte offset of the deepest failure within the input.

external: Option<Arc<dyn Error + Send + Sync>>

An external error, for the case that the final parser failure happened outside of winnow.

pending: Vec<StringContext>

The StringContext instances that are not yet captured by a layer boundary.

layers: Vec<Layer>

All closed nesting layers, innermost first.

source: &'i str

The full original source text. Required for rendering.

Implementations

impl<'i> ParseStack<'i>

pub(crate) fn close_layer(self, name: String, start: usize) -> Self

Moves all pending context calls into a new layer named name.

This is called by the LayerParser in case an error unwinds.

pub(crate) fn innermost(&self) -> LayerRef<'_>

Returns the innermost layer.

Pending context belongs to the outermost “anonymous” layer that’s not yet named. If no named layer can be found, but there’s some pending context, we return the pending context as an anonymous layer as a fallback.

pub(crate) fn layer_stack(&self) -> Vec<LayerRef<'_>>

Returns the stack from outermost to innermost.

Pending context is positioned first as an anonymous outermost layer.

pub(crate) fn innermost_expected(&self) -> Vec<String>

Returns all “expected” style contexts of the innermost layer that has any.

The layers are searched from the innermost outwards, with pending context being the outermost anonymous layer. If there’s no hit on the innermost layer, we just take the next best layer with such context to at least provide some information to the user.

Returns an empty list if no layer has any “expected” style context.

pub(crate) fn headline(&self) -> String

Returns the “headline” for the error.

Tries to get the best match available in the following order:

• StringContext::Label name of the innermost layer
• Name of first non-anonymous string
• A simple fallback to the static string "invalid".

fn anonymous_layer(&self) -> LayerRef<'_>

Takes the current pending context and return it as an anonymous layer.

Trait Implementations

impl<'i> AddContext<LocatingSlice<&'i str>, StrContext> for ParseStack<'i>

fn add_context( self, _input: &Input<'i>, _token_start: &<Input<'i> as Stream>::Checkpoint, context: StrContext, ) -> Self

Add a new context entry to the current layer.

This provides backwards compatibility with winnow’s Parser::context API. The StrContext is internally converted to our owned StringContext representation.

Entries are staged inside Self until the current layer is closed.

impl<'i> Clone for ParseStack<'i>

fn clone(&self) -> ParseStack<'i>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'i> Debug for ParseStack<'i>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for ParseStack<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Displays this parse error.

The rendered output is structured into three visual sections:

1. A headline with the innermost available label context.
2. A source snippet with an underline spanning from beginning of the innermost named layer up to the exact failing character. Any expected literals are shown next to the caret.
3. A footer that provides error context from outermost to innermost layers.

Named layers are rendered with their parser name and a mini source preview:

error: invalid package release
  |
1 | foo-1:1.0.0-bar-any
  |             ^ expected positive decimal integer
  |
  = while parsing:
    installed package name: (foo-1:1.0.0-bar-any)
    └ alpm-package-version: (1:1.0.0-bar-any)
      │ → an alpm-package-version (full or full with epoch) followed by a `-` and an alpm-architecture
      └ alpm-pkgrel: (bar-any)
        → invalid package release
        → A freeform description over here
        → expected positive decimal integer

Pending context that has not yet unwound past a named layer is rendered as an anonymous outermost layer:

  = while parsing:
    → alpm-package file name
    → a package name, followed by an alpm-package-version...
    └ installed package name: (foo-1:1.0.0_any)

Color output is controlled globally via [colored::control] (for example via [colored::control::set_override]).

impl Error for ParseStack<'_>

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl<'i, E: Error + Send + Sync + 'static> FromExternalError<LocatingSlice<&'i str>, E> for ParseStack<'i>

fn from_external_error(input: &Input<'i>, e: E) -> Self

Like [ParserError::from_input] but also include an external error.

impl<'i> ParserError<LocatingSlice<&'i str>> for ParseStack<'i>

fn or(self, other: Self) -> Self

When handling multiple parsing branches (alt), keep the failure that reached further into the input.

type Inner = ParseStack<'i>

Generally, Self

fn from_input(input: &Input<'i>) -> Self

Creates an error from the input position

fn into_inner(self) -> Result<Self::Inner, Self>

Unwrap the mode, returning the underlying error, if present

fn assert(input: &I, _message: &'static str) -> Self

where I: Debug,

Process a parser assertion

fn incomplete(input: &I, _needed: Needed) -> Self

There was not enough data to determine the appropriate action

fn append(self, _input: &I, _token_start: &<I as Stream>::Checkpoint) -> Self

Like [ParserError::from_input] but merges it with the existing error.

fn is_backtrack(&self) -> bool

Is backtracking and trying new parse branches allowed?

fn is_incomplete(&self) -> bool

Is more data [Needed]

fn needed(&self) -> Option<Needed>

Extract the [Needed] data, if present