diff --git a/src/diagnostic.rs b/src/diagnostic.rs index 03e4526..6efb8a3 100644 --- a/src/diagnostic.rs +++ b/src/diagnostic.rs @@ -128,7 +128,7 @@ impl Diagnostic { /// associated with. /// /// Identical to calling `self.span()` when the [`Diagnostic`] has no children. - pub fn merged_span(&self) -> Result { + pub fn merged_span(&self) -> core::result::Result { let mut merged_span = self.span.clone(); for child in &self.children { merged_span = merged_span.join(&child.merged_span()?)?; diff --git a/src/parsable.rs b/src/parsable.rs index 1e269bf..cc1aaf8 100644 --- a/src/parsable.rs +++ b/src/parsable.rs @@ -1,3 +1,5 @@ +//! Contains a menagerie of useful types that implement the [`Parsable`] trait. + use super::*; mod everything; diff --git a/src/parsable/everything.rs b/src/parsable/everything.rs index 9ce296f..39aa905 100644 --- a/src/parsable/everything.rs +++ b/src/parsable/everything.rs @@ -12,7 +12,7 @@ impl Spanned for Everything { } impl Parsable for Everything { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let span = Span::new( stream.source().clone(), stream.position..(stream.source().len()), @@ -21,7 +21,7 @@ impl Parsable for Everything { Ok(Everything(span)) } - fn parse_value(value: Self, stream: &mut ParseStream) -> ParseResult { + fn parse_value(value: Self, stream: &mut ParseStream) -> Result { let s = value.span(); let text = s.source_text(); if stream.remaining() == text { diff --git a/src/parsable/exact.rs b/src/parsable/exact.rs index 9883797..7d08a59 100644 --- a/src/parsable/exact.rs +++ b/src/parsable/exact.rs @@ -26,14 +26,14 @@ impl Spanned for Exact { make_parsable!(Exact); impl Parsable for Exact { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { Ok(Exact(Span::new( stream.source().clone(), stream.position..stream.position, ))) } - fn parse_value(value: Self, stream: &mut ParseStream) -> ParseResult { + fn parse_value(value: Self, stream: &mut ParseStream) -> Result { let s = value.0; let text = s.source_text(); if stream.remaining().starts_with(text) { diff --git a/src/parsable/nothing.rs b/src/parsable/nothing.rs index ab0ab63..36cfd68 100644 --- a/src/parsable/nothing.rs +++ b/src/parsable/nothing.rs @@ -12,7 +12,7 @@ impl Spanned for Nothing { } impl Parsable for Nothing { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { if stream.position < stream.source().len() { return Err(Error::new( stream.current_span(), @@ -26,7 +26,7 @@ impl Parsable for Nothing { Ok(Nothing(stream.current_span())) } - fn parse_value(_value: Self, stream: &mut ParseStream) -> ParseResult { + fn parse_value(_value: Self, stream: &mut ParseStream) -> Result { stream.parse() } diff --git a/src/parsable/numbers.rs b/src/parsable/numbers.rs index 6a17da8..8892aed 100644 --- a/src/parsable/numbers.rs +++ b/src/parsable/numbers.rs @@ -21,7 +21,7 @@ impl Spanned for U64 { } impl Parsable for U64 { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let mut digits = Vec::new(); let start_position = stream.position; while let Ok(_) = stream.next_digit() { @@ -84,7 +84,7 @@ impl Spanned for U128 { } impl Parsable for U128 { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let mut digits = Vec::new(); let start_position = stream.position; while let Ok(_) = stream.next_digit() { @@ -134,7 +134,7 @@ impl Spanned for I64 { } impl Parsable for I64 { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let mut digits = Vec::new(); let start_position = stream.position; let mut sign = 1; @@ -196,7 +196,7 @@ impl Spanned for I128 { } impl Parsable for I128 { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let mut digits = Vec::new(); let start_position = stream.position; let mut sign = 1; @@ -279,7 +279,7 @@ impl Spanned for Decimal { make_parsable!(Decimal); impl Parsable for Decimal { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let start_position = stream.position; if stream.next_char()? == '-' { stream.consume(1)?; @@ -319,7 +319,7 @@ impl Spanned for BoundedI64 { } impl Parsable for BoundedI64 { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let i = stream.parse::()?; if i.0 < MIN { return Err(Error::new( diff --git a/src/parsable/optional.rs b/src/parsable/optional.rs index 253cad8..b2b5784 100644 --- a/src/parsable/optional.rs +++ b/src/parsable/optional.rs @@ -58,7 +58,7 @@ impl Display for Optional { impl FromStr for Optional { type Err = T::Err; - fn from_str(s: &str) -> Result { + fn from_str(s: &str) -> core::result::Result { let Ok(val) = s.parse() else { return Ok(Optional::None); }; @@ -67,14 +67,14 @@ impl FromStr for Optional { } impl Parsable for Optional { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { if stream.peek::() { return Ok(Optional::Some(stream.parse::()?)); } Ok(Optional::None) } - fn parse_value(value: Self, stream: &mut ParseStream) -> ParseResult { + fn parse_value(value: Self, stream: &mut ParseStream) -> Result { match value { Optional::Some(val) => stream.parse_value(val).map(Optional::Some), Optional::None => Ok(Optional::None), diff --git a/src/parsable/whitespace.rs b/src/parsable/whitespace.rs index 7dbfd14..c469fb5 100644 --- a/src/parsable/whitespace.rs +++ b/src/parsable/whitespace.rs @@ -12,7 +12,7 @@ impl Spanned for Whitespace { make_parsable!(Whitespace); impl Parsable for Whitespace { - fn parse(stream: &mut ParseStream) -> ParseResult { + fn parse(stream: &mut ParseStream) -> Result { let start_position = stream.position; while let Ok(c) = stream.next_char() { if !c.is_whitespace() { diff --git a/src/parsing.rs b/src/parsing.rs index b054146..a181508 100644 --- a/src/parsing.rs +++ b/src/parsing.rs @@ -11,6 +11,7 @@ use self::parsable::Exact; use super::*; +/// Represents an error that occurred during parsing. #[derive(Clone, PartialEq, Eq, Hash)] pub struct Error(Diagnostic); @@ -35,6 +36,7 @@ impl Debug for Error { } impl Error { + /// Creates a new [`Error`] with the given [`Span`] and message. pub fn new(span: Span, message: impl ToString) -> Error { Error(Diagnostic::new( DiagnosticLevel::Error, @@ -45,6 +47,7 @@ impl Error { )) } + /// Creates a new [`Error`] expecting a certain value at the given [`Span`]. pub fn expected(span: Span, expected: impl Display) -> Error { Error(Diagnostic::new( DiagnosticLevel::Error, @@ -56,7 +59,8 @@ impl Error { } } -pub type ParseResult = core::result::Result; +/// Represents the result of a parsing operation. +pub type Result = core::result::Result; #[derive(Clone, Debug, PartialEq, Eq, Hash)] pub struct ParseStream { @@ -80,16 +84,16 @@ impl ParseStream { Span::new(self.source.clone(), self.position..self.source.len()) } - pub fn parse(&mut self) -> ParseResult { + pub fn parse(&mut self) -> Result { T::parse(self) } - pub fn parse_value(&mut self, value: T) -> ParseResult { + pub fn parse_value(&mut self, value: T) -> Result { T::parse_value(value, self) } /// note: panics upon invalid regex syntax - pub fn parse_regex(&mut self, reg: impl Pattern) -> ParseResult { + pub fn parse_regex(&mut self, reg: impl Pattern) -> Result { let reg = reg.to_regex(); match reg.find(self.remaining()) { Some(m) => { @@ -117,11 +121,11 @@ impl ParseStream { self.fork().parse_regex(reg).is_ok() } - pub fn parse_str(&mut self, value: impl ToString) -> ParseResult { + pub fn parse_str(&mut self, value: impl ToString) -> Result { self.parse_value(Exact::from(value)) } - pub fn parse_istr(&mut self, value: impl ToString) -> ParseResult { + pub fn parse_istr(&mut self, value: impl ToString) -> Result { let text = value.to_string().to_lowercase(); let remaining_lower = self.remaining().to_lowercase(); if remaining_lower.starts_with(&text) { @@ -146,10 +150,7 @@ impl ParseStream { .starts_with(&s.to_string().to_lowercase()) } - pub fn parse_any_value_of( - &mut self, - values: [T; N], - ) -> ParseResult { + pub fn parse_any_value_of(&mut self, values: [T; N]) -> Result { for i in 0..N { if self.peek_value(values[i].clone()) { return self.parse_value(values[i].clone()); @@ -171,7 +172,7 @@ impl ParseStream { pub fn parse_any_str_of( &mut self, values: [impl ToString; N], - ) -> ParseResult<(Exact, usize)> { + ) -> Result<(Exact, usize)> { for (i, s) in values.iter().enumerate() { let s = s.to_string(); if self.peek_str(&s) { @@ -194,7 +195,7 @@ impl ParseStream { pub fn parse_any_istr_of( &mut self, values: [impl ToString; N], - ) -> ParseResult<(Exact, usize)> { + ) -> Result<(Exact, usize)> { for (i, s) in values.iter().enumerate() { let s = s.to_string(); if self.peek_istr(&s) { @@ -234,7 +235,7 @@ impl ParseStream { self.clone() } - pub fn consume(&mut self, num_chars: usize) -> ParseResult { + pub fn consume(&mut self, num_chars: usize) -> Result { if self.remaining().len() < num_chars { return Err(Error::new( self.remaining_span(), @@ -255,7 +256,7 @@ impl ParseStream { span } - pub fn next_char(&self) -> ParseResult { + pub fn next_char(&self) -> Result { if self.remaining().is_empty() { return Err(Error::new(self.current_span(), "unexpected end of input")); } @@ -270,13 +271,13 @@ impl ParseStream { Ok(c) } - pub fn parse_char(&mut self) -> ParseResult { + pub fn parse_char(&mut self) -> Result { let c = self.next_char()?; self.position += 1; Ok(c) } - pub fn next_digit(&self) -> ParseResult { + pub fn next_digit(&self) -> Result { Ok(match self.next_char()? { '0' => 0, '1' => 1, @@ -292,13 +293,13 @@ impl ParseStream { }) } - pub fn parse_digit(&mut self) -> ParseResult { + pub fn parse_digit(&mut self) -> Result { let digit = self.next_digit()?; self.position += 1; Ok(digit) } - pub fn next_alpha(&self) -> ParseResult { + pub fn next_alpha(&self) -> Result { let c = self.next_char()?; if !c.is_ascii_alphabetic() { return Err(Error::new( @@ -309,7 +310,7 @@ impl ParseStream { Ok(c) } - pub fn parse_alpha(&mut self) -> ParseResult { + pub fn parse_alpha(&mut self) -> Result { let c = self.next_alpha()?; self.position += 1; Ok(c) @@ -333,7 +334,7 @@ impl> From for ParseStream { } } -pub fn parse(stream: impl Into) -> ParseResult { +pub fn parse(stream: impl Into) -> Result { T::parse(&mut stream.into()) } @@ -352,9 +353,9 @@ pub fn common_prefix(s1: &str, s2: &str) -> String { pub trait Parsable: Clone + Debug + PartialEq + Eq + Hash + Display + Spanned + FromStr + Peekable { - fn parse(stream: &mut ParseStream) -> ParseResult; + fn parse(stream: &mut ParseStream) -> Result; - fn parse_value(value: Self, stream: &mut ParseStream) -> ParseResult { + fn parse_value(value: Self, stream: &mut ParseStream) -> Result { let s = value.span(); let text = s.source_text(); if stream.remaining().starts_with(text) { @@ -449,23 +450,23 @@ pub trait Pattern: Sized { /// Tries to derive a [`Regex`] from the underlying value, returning a [`regex::Error`] if /// the value is not a valid [`Regex`]. - fn try_to_regex(self) -> Result; + fn try_to_regex(self) -> core::result::Result; } impl Pattern for Regex { - fn try_to_regex(self) -> Result { + fn try_to_regex(self) -> core::result::Result { Ok(self) } } impl Pattern for &str { - fn try_to_regex(self) -> Result { + fn try_to_regex(self) -> core::result::Result { Regex::new(self) } } impl Pattern for String { - fn try_to_regex(self) -> Result { + fn try_to_regex(self) -> core::result::Result { Regex::new(&self) } } diff --git a/src/span.rs b/src/span.rs index 633b89b..c766b69 100644 --- a/src/span.rs +++ b/src/span.rs @@ -154,7 +154,7 @@ impl Span { /// /// If the two spans do not come from the same [`Source`], this method will return an error /// unless one or more of the spans is [`Span::blank()`]. - pub fn join(&self, other: &Span) -> Result { + pub fn join(&self, other: &Span) -> core::result::Result { if self.source.is_empty() { return Ok(other.clone()); }