Skip to content

Commit

Permalink
Document remaining undocumented lalrpop-util items (#996)
Browse files Browse the repository at this point in the history
* Document remaining undocumented lalrpop-util items

Enable `warn(missing_docs)` for lalrpop-util

* fixup! Document remaining undocumented lalrpop-util items

* Fix descriptions of ParseError variants
  • Loading branch information
dburgener authored Nov 25, 2024
1 parent 0aab635 commit 35f1346
Showing 1 changed file with 38 additions and 7 deletions.
45 changes: 38 additions & 7 deletions lalrpop-util/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
//! number for each crate.
#![cfg_attr(not(feature = "std"), no_std)]
#![warn(rust_2018_idioms)]
#![warn(missing_docs)]

extern crate alloc;

Expand All @@ -25,7 +26,7 @@ use std::error::Error;
pub mod lexer;
pub mod state_machine;

/// Error type for errors returned by lalrpop parsers
/// Error type for errors returned by lalrpop parsers.
///
/// For the built-in lexer, the generic parameters default to:
/// ParseError<usize, lexer::Token<'_>, &'static str>.
Expand All @@ -46,13 +47,16 @@ pub mod state_machine;
/// ```
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub enum ParseError<L, T, E> {
/// Generated by the parser when it encounters a token (or EOF) it did not
/// expect.
InvalidToken { location: L },
/// Generated by the internal lexer when it encounters a token (or EOF) it
/// did not expect.
InvalidToken {
/// The end of the invalid token.
location: L,
},

/// Generated by the parser when it encounters an EOF it did not expect.
UnrecognizedEof {
/// The end of the final token
/// The end of the final token.
location: L,

/// The set of expected tokens: these names are taken from the
Expand All @@ -62,6 +66,9 @@ pub enum ParseError<L, T, E> {
},

/// Generated by the parser when it encounters a token it did not expect.
///
/// This means that the next token in the stream was not valid at this
/// point in the grammar.
UnrecognizedToken {
/// The unexpected token of type `T` with a span given by the two `L` values.
token: (L, T, L),
Expand All @@ -73,10 +80,16 @@ pub enum ParseError<L, T, E> {
},

/// Generated by the parser when it encounters additional, unexpected tokens.
ExtraToken { token: (L, T, L) },
ExtraToken {
/// The extra token, with a type of `T` with a span given by the two `L` values.
token: (L, T, L),
},

/// Custom error type.
User { error: E },
User {
/// Custom user error.
error: E,
},
}

impl<L, T, E> ParseError<L, T, E> {
Expand All @@ -86,6 +99,8 @@ impl<L, T, E> ParseError<L, T, E> {
tok_op: impl FnOnce(T) -> TT,
err_op: impl FnOnce(E) -> EE,
) -> ParseError<LL, TT, EE> {
// The signature of token is (L, T, L), so we need to call loc_op on both the "start" and
// "end" values for a token.
let maptok = |(s, t, e): (L, T, L)| (loc_op(s), tok_op(t), loc_op(e));
match self {
ParseError::InvalidToken { location } => ParseError::InvalidToken {
Expand All @@ -108,14 +123,30 @@ impl<L, T, E> ParseError<L, T, E> {
}
}

/// Transform a `ParseError` by applying a function to the location field.
///
/// This could be useful to ensure that all fields implement some trait, or
/// to apply an offset to a location.
///
/// (Note that unlike `map_token()` and `map_error()`, the closure argument
/// for this function is `FnMut`. This is so that it can be called
/// multiple times to apply to the starting and ending location of tokens.)
pub fn map_location<LL>(self, op: impl FnMut(L) -> LL) -> ParseError<LL, T, E> {
self.map_intern(op, |x| x, |x| x)
}

/// Transform a `ParseError` by applying a function to the token field.
///
/// This could be useful to ensure that all fields implement some trait, or
/// to transform a token in some way (eg escaping).
pub fn map_token<TT>(self, op: impl FnOnce(T) -> TT) -> ParseError<L, TT, E> {
self.map_intern(|x| x, op, |x| x)
}

/// Transform a `ParseError` by applying a function to the error field.
///
/// This could be useful to ensure that all fields implement some trait, or
/// to transform to a different error type in place.
pub fn map_error<EE>(self, op: impl FnOnce(E) -> EE) -> ParseError<L, T, EE> {
self.map_intern(|x| x, |x| x, op)
}
Expand Down

0 comments on commit 35f1346

Please sign in to comment.