1 //! Utilities for validating string and char literals and turning them into
2 //! values they represent.
10 /// Errors and warnings that can occur during string unescaping.
11 #[derive(Debug, PartialEq, Eq)]
12 pub enum EscapeError {
13 /// Expected 1 char, but 0 were found.
15 /// Expected 1 char, but more than 1 were found.
18 /// Escaped '\' character without continuation.
20 /// Invalid escape character (e.g. '\z').
22 /// Raw '\r' encountered.
24 /// Raw '\r' encountered in raw string.
25 BareCarriageReturnInRawString,
26 /// Unescaped character that was expected to be escaped (e.g. raw '\t').
29 /// Numeric character escape is too short (e.g. '\x1').
31 /// Invalid character in numeric escape (e.g. '\xz')
32 InvalidCharInHexEscape,
33 /// Character code in numeric escape is non-ascii (e.g. '\xFF').
36 /// '\u' not followed by '{'.
37 NoBraceInUnicodeEscape,
38 /// Non-hexadecimal value in '\u{..}'.
39 InvalidCharInUnicodeEscape,
42 /// No closing brace in '\u{..}', e.g. '\u{12'.
43 UnclosedUnicodeEscape,
45 LeadingUnderscoreUnicodeEscape,
46 /// More than 6 characters in '\u{..}', e.g. '\u{10FFFF_FF}'
47 OverlongUnicodeEscape,
48 /// Invalid in-bound unicode character code, e.g. '\u{DFFF}'.
49 LoneSurrogateUnicodeEscape,
50 /// Out of bounds unicode character code, e.g. '\u{FFFFFF}'.
51 OutOfRangeUnicodeEscape,
53 /// Unicode escape code in byte literal.
55 /// Non-ascii character in byte literal, byte string literal, or raw byte string literal.
58 /// After a line ending with '\', the next line contains whitespace
59 /// characters that are not skipped.
60 UnskippedWhitespaceWarning,
62 /// After a line ending with '\', multiple lines are skipped.
63 MultipleSkippedLinesWarning,
67 /// Returns true for actual errors, as opposed to warnings.
68 pub fn is_fatal(&self) -> bool {
71 EscapeError::UnskippedWhitespaceWarning | EscapeError::MultipleSkippedLinesWarning
76 /// Takes a contents of a literal (without quotes) and produces a
77 /// sequence of escaped characters or errors.
78 /// Values are returned through invoking of the provided callback.
79 pub fn unescape_literal<F>(src: &str, mode: Mode, callback: &mut F)
81 F: FnMut(Range<usize>, Result<char, EscapeError>),
84 Mode::Char | Mode::Byte => {
85 let mut chars = src.chars();
86 let result = unescape_char_or_byte(&mut chars, mode == Mode::Byte);
87 callback(0..(src.len() - chars.as_str().len()), result);
89 Mode::Str | Mode::ByteStr => unescape_str_or_byte_str(src, mode == Mode::ByteStr, callback),
90 Mode::RawStr | Mode::RawByteStr => {
91 unescape_raw_str_or_raw_byte_str(src, mode == Mode::RawByteStr, callback)
96 /// Takes a contents of a char literal (without quotes), and returns an
97 /// unescaped char or an error
98 pub fn unescape_char(src: &str) -> Result<char, (usize, EscapeError)> {
99 let mut chars = src.chars();
100 unescape_char_or_byte(&mut chars, false).map_err(|err| (src.len() - chars.as_str().len(), err))
103 /// Takes a contents of a byte literal (without quotes), and returns an
104 /// unescaped byte or an error.
105 pub fn unescape_byte(src: &str) -> Result<u8, (usize, EscapeError)> {
106 let mut chars = src.chars();
107 unescape_char_or_byte(&mut chars, true)
109 .map_err(|err| (src.len() - chars.as_str().len(), err))
112 /// What kind of literal do we parse.
113 #[derive(Debug, Clone, Copy, PartialEq)]
124 pub fn in_double_quotes(self) -> bool {
126 Mode::Str | Mode::ByteStr | Mode::RawStr | Mode::RawByteStr => true,
127 Mode::Char | Mode::Byte => false,
131 pub fn is_byte(self) -> bool {
133 Mode::Byte | Mode::ByteStr | Mode::RawByteStr => true,
134 Mode::Char | Mode::Str | Mode::RawStr => false,
139 fn scan_escape(chars: &mut Chars<'_>, is_byte: bool) -> Result<char, EscapeError> {
140 // Previous character was '\\', unescape what follows.
141 let res = match chars.next().ok_or(EscapeError::LoneSlash)? {
151 // Parse hexadecimal character code.
153 let hi = chars.next().ok_or(EscapeError::TooShortHexEscape)?;
154 let hi = hi.to_digit(16).ok_or(EscapeError::InvalidCharInHexEscape)?;
156 let lo = chars.next().ok_or(EscapeError::TooShortHexEscape)?;
157 let lo = lo.to_digit(16).ok_or(EscapeError::InvalidCharInHexEscape)?;
159 let value = hi * 16 + lo;
161 // For a non-byte literal verify that it is within ASCII range.
162 if !is_byte && !is_ascii(value) {
163 return Err(EscapeError::OutOfRangeHexEscape);
165 let value = value as u8;
171 // We've parsed '\u', now we have to parse '{..}'.
173 if chars.next() != Some('{') {
174 return Err(EscapeError::NoBraceInUnicodeEscape);
177 // First character must be a hexadecimal digit.
178 let mut n_digits = 1;
179 let mut value: u32 = match chars.next().ok_or(EscapeError::UnclosedUnicodeEscape)? {
180 '_' => return Err(EscapeError::LeadingUnderscoreUnicodeEscape),
181 '}' => return Err(EscapeError::EmptyUnicodeEscape),
182 c => c.to_digit(16).ok_or(EscapeError::InvalidCharInUnicodeEscape)?,
185 // First character is valid, now parse the rest of the number
186 // and closing brace.
189 None => return Err(EscapeError::UnclosedUnicodeEscape),
190 Some('_') => continue,
193 return Err(EscapeError::OverlongUnicodeEscape);
196 // Incorrect syntax has higher priority for error reporting
197 // than unallowed value for a literal.
199 return Err(EscapeError::UnicodeEscapeInByte);
202 break std::char::from_u32(value).ok_or_else(|| {
203 if value > 0x10FFFF {
204 EscapeError::OutOfRangeUnicodeEscape
206 EscapeError::LoneSurrogateUnicodeEscape
212 c.to_digit(16).ok_or(EscapeError::InvalidCharInUnicodeEscape)?;
215 // Stop updating value since we're sure that it's incorrect already.
218 let digit = digit as u32;
219 value = value * 16 + digit;
224 _ => return Err(EscapeError::InvalidEscape),
230 fn ascii_check(c: char, is_byte: bool) -> Result<char, EscapeError> {
231 if is_byte && !c.is_ascii() {
232 // Byte literal can't be a non-ascii character.
233 Err(EscapeError::NonAsciiCharInByte)
239 fn unescape_char_or_byte(chars: &mut Chars<'_>, is_byte: bool) -> Result<char, EscapeError> {
240 let c = chars.next().ok_or(EscapeError::ZeroChars)?;
242 '\\' => scan_escape(chars, is_byte),
243 '\n' | '\t' | '\'' => Err(EscapeError::EscapeOnlyChar),
244 '\r' => Err(EscapeError::BareCarriageReturn),
245 _ => ascii_check(c, is_byte),
247 if chars.next().is_some() {
248 return Err(EscapeError::MoreThanOneChar);
253 /// Takes a contents of a string literal (without quotes) and produces a
254 /// sequence of escaped characters or errors.
255 fn unescape_str_or_byte_str<F>(src: &str, is_byte: bool, callback: &mut F)
257 F: FnMut(Range<usize>, Result<char, EscapeError>),
259 let mut chars = src.chars();
261 // The `start` and `end` computation here is complicated because
262 // `skip_ascii_whitespace` makes us to skip over chars without counting
263 // them in the range computation.
264 while let Some(c) = chars.next() {
265 let start = src.len() - chars.as_str().len() - c.len_utf8();
266 let result = match c {
268 match chars.clone().next() {
270 // Rust language specification requires us to skip whitespaces
271 // if unescaped '\' character is followed by '\n'.
272 // For details see [Rust language reference]
273 // (https://doc.rust-lang.org/reference/tokens.html#string-literals).
274 skip_ascii_whitespace(&mut chars, start, callback);
277 _ => scan_escape(&mut chars, is_byte),
282 '"' => Err(EscapeError::EscapeOnlyChar),
283 '\r' => Err(EscapeError::BareCarriageReturn),
284 _ => ascii_check(c, is_byte),
286 let end = src.len() - chars.as_str().len();
287 callback(start..end, result);
290 fn skip_ascii_whitespace<F>(chars: &mut Chars<'_>, start: usize, callback: &mut F)
292 F: FnMut(Range<usize>, Result<char, EscapeError>),
294 let tail = chars.as_str();
295 let first_non_space = tail
297 .position(|b| b != b' ' && b != b'\t' && b != b'\n' && b != b'\r')
298 .unwrap_or(tail.len());
299 if tail[1..first_non_space].contains('\n') {
300 // The +1 accounts for the escaping slash.
301 let end = start + first_non_space + 1;
302 callback(start..end, Err(EscapeError::MultipleSkippedLinesWarning));
304 let tail = &tail[first_non_space..];
305 if let Some(c) = tail.chars().nth(0) {
306 // For error reporting, we would like the span to contain the character that was not
307 // skipped. The +1 is necessary to account for the leading \ that started the escape.
308 let end = start + first_non_space + c.len_utf8() + 1;
309 if c.is_whitespace() {
310 callback(start..end, Err(EscapeError::UnskippedWhitespaceWarning));
313 *chars = tail.chars();
317 /// Takes a contents of a string literal (without quotes) and produces a
318 /// sequence of characters or errors.
319 /// NOTE: Raw strings do not perform any explicit character escaping, here we
320 /// only produce errors on bare CR.
321 fn unescape_raw_str_or_raw_byte_str<F>(src: &str, is_byte: bool, callback: &mut F)
323 F: FnMut(Range<usize>, Result<char, EscapeError>),
325 let mut chars = src.chars();
327 // The `start` and `end` computation here matches the one in
328 // `unescape_str_or_byte_str` for consistency, even though this function
329 // doesn't have to worry about skipping any chars.
330 while let Some(c) = chars.next() {
331 let start = src.len() - chars.as_str().len() - c.len_utf8();
332 let result = match c {
333 '\r' => Err(EscapeError::BareCarriageReturnInRawString),
334 _ => ascii_check(c, is_byte),
336 let end = src.len() - chars.as_str().len();
337 callback(start..end, result);
342 pub fn byte_from_char(c: char) -> u8 {
344 debug_assert!(res <= u8::MAX as u32, "guaranteed because of Mode::ByteStr");
348 fn is_ascii(x: u32) -> bool {