1 //! Utilities for validating string and char literals and turning them into
2 //! values they represent.
10 /// Errors 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.
57 /// Non-ascii character in byte string literal.
58 NonAsciiCharInByteString,
61 /// Takes a contents of a char literal (without quotes), and returns an
62 /// unescaped char or an error
63 pub fn unescape_char(literal_text: &str) -> Result<char, (usize, EscapeError)> {
64 let mut chars = literal_text.chars();
65 unescape_char_or_byte(&mut chars, Mode::Char)
66 .map_err(|err| (literal_text.len() - chars.as_str().len(), err))
69 /// Takes a contents of a byte literal (without quotes), and returns an
70 /// unescaped byte or an error.
71 pub fn unescape_byte(literal_text: &str) -> Result<u8, (usize, EscapeError)> {
72 let mut chars = literal_text.chars();
73 unescape_char_or_byte(&mut chars, Mode::Byte)
75 .map_err(|err| (literal_text.len() - chars.as_str().len(), err))
78 /// Takes a contents of a string literal (without quotes) and produces a
79 /// sequence of escaped characters or errors.
80 /// Values are returned through invoking of the provided callback.
81 pub fn unescape_str<F>(literal_text: &str, callback: &mut F)
83 F: FnMut(Range<usize>, Result<char, EscapeError>),
85 unescape_str_or_byte_str(literal_text, Mode::Str, callback)
88 /// Takes a contents of a byte string literal (without quotes) and produces a
89 /// sequence of bytes or errors.
90 /// Values are returned through invoking of the provided callback.
91 pub fn unescape_byte_str<F>(literal_text: &str, callback: &mut F)
93 F: FnMut(Range<usize>, Result<u8, EscapeError>),
95 unescape_str_or_byte_str(literal_text, Mode::ByteStr, &mut |range, char| {
96 callback(range, char.map(byte_from_char))
100 /// Takes a contents of a raw string literal (without quotes) and produces a
101 /// sequence of characters or errors.
102 /// Values are returned through invoking of the provided callback.
103 /// NOTE: Raw strings do not perform any explicit character escaping, here we
104 /// only translate CRLF to LF and produce errors on bare CR.
105 pub fn unescape_raw_str<F>(literal_text: &str, callback: &mut F)
107 F: FnMut(Range<usize>, Result<char, EscapeError>),
109 unescape_raw_str_or_byte_str(literal_text, Mode::Str, callback)
112 /// Takes a contents of a raw byte string literal (without quotes) and produces a
113 /// sequence of bytes or errors.
114 /// Values are returned through invoking of the provided callback.
115 /// NOTE: Raw strings do not perform any explicit character escaping, here we
116 /// only translate CRLF to LF and produce errors on bare CR.
117 pub fn unescape_raw_byte_str<F>(literal_text: &str, callback: &mut F)
119 F: FnMut(Range<usize>, Result<u8, EscapeError>),
121 unescape_raw_str_or_byte_str(literal_text, Mode::ByteStr, &mut |range, char| {
122 callback(range, char.map(byte_from_char))
126 /// What kind of literal do we parse.
127 #[derive(Debug, Clone, Copy)]
136 pub fn in_single_quotes(self) -> bool {
138 Mode::Char | Mode::Byte => true,
139 Mode::Str | Mode::ByteStr => false,
143 pub fn in_double_quotes(self) -> bool {
144 !self.in_single_quotes()
147 pub fn is_bytes(self) -> bool {
149 Mode::Byte | Mode::ByteStr => true,
150 Mode::Char | Mode::Str => false,
155 fn scan_escape(first_char: char, chars: &mut Chars<'_>, mode: Mode) -> Result<char, EscapeError> {
156 if first_char != '\\' {
157 // Previous character was not a slash, and we don't expect it to be
158 // an escape-only character.
159 return match first_char {
160 '\t' | '\n' => Err(EscapeError::EscapeOnlyChar),
161 '\r' => Err(EscapeError::BareCarriageReturn),
162 '\'' if mode.in_single_quotes() => Err(EscapeError::EscapeOnlyChar),
163 '"' if mode.in_double_quotes() => Err(EscapeError::EscapeOnlyChar),
165 if mode.is_bytes() && !first_char.is_ascii() {
166 // Byte literal can't be a non-ascii character.
167 return Err(EscapeError::NonAsciiCharInByte);
174 // Previous character is '\\', try to unescape it.
176 let second_char = chars.next().ok_or(EscapeError::LoneSlash)?;
178 let res = match second_char {
188 // Parse hexadecimal character code.
190 let hi = chars.next().ok_or(EscapeError::TooShortHexEscape)?;
191 let hi = hi.to_digit(16).ok_or(EscapeError::InvalidCharInHexEscape)?;
193 let lo = chars.next().ok_or(EscapeError::TooShortHexEscape)?;
194 let lo = lo.to_digit(16).ok_or(EscapeError::InvalidCharInHexEscape)?;
196 let value = hi * 16 + lo;
198 // For a byte literal verify that it is within ASCII range.
199 if !mode.is_bytes() && !is_ascii(value) {
200 return Err(EscapeError::OutOfRangeHexEscape);
202 let value = value as u8;
208 // We've parsed '\u', now we have to parse '{..}'.
210 if chars.next() != Some('{') {
211 return Err(EscapeError::NoBraceInUnicodeEscape);
214 // First characrer must be a hexadecimal digit.
215 let mut n_digits = 1;
216 let mut value: u32 = match chars.next().ok_or(EscapeError::UnclosedUnicodeEscape)? {
217 '_' => return Err(EscapeError::LeadingUnderscoreUnicodeEscape),
218 '}' => return Err(EscapeError::EmptyUnicodeEscape),
219 c => c.to_digit(16).ok_or(EscapeError::InvalidCharInUnicodeEscape)?,
222 // First character is valid, now parse the rest of the number
223 // and closing brace.
226 None => return Err(EscapeError::UnclosedUnicodeEscape),
227 Some('_') => continue,
230 return Err(EscapeError::OverlongUnicodeEscape);
233 // Incorrect syntax has higher priority for error reporting
234 // than unallowed value for a literal.
236 return Err(EscapeError::UnicodeEscapeInByte);
239 break std::char::from_u32(value).ok_or_else(|| {
240 if value > 0x10FFFF {
241 EscapeError::OutOfRangeUnicodeEscape
243 EscapeError::LoneSurrogateUnicodeEscape
249 c.to_digit(16).ok_or(EscapeError::InvalidCharInUnicodeEscape)?;
252 // Stop updating value since we're sure that it's is incorrect already.
255 let digit = digit as u32;
256 value = value * 16 + digit;
261 _ => return Err(EscapeError::InvalidEscape),
266 fn unescape_char_or_byte(chars: &mut Chars<'_>, mode: Mode) -> Result<char, EscapeError> {
267 let first_char = chars.next().ok_or(EscapeError::ZeroChars)?;
268 let res = scan_escape(first_char, chars, mode)?;
269 if chars.next().is_some() {
270 return Err(EscapeError::MoreThanOneChar);
275 /// Takes a contents of a string literal (without quotes) and produces a
276 /// sequence of escaped characters or errors.
277 fn unescape_str_or_byte_str<F>(src: &str, mode: Mode, callback: &mut F)
279 F: FnMut(Range<usize>, Result<char, EscapeError>),
281 assert!(mode.in_double_quotes());
282 let initial_len = src.len();
283 let mut chars = src.chars();
284 while let Some(first_char) = chars.next() {
285 let start = initial_len - chars.as_str().len() - first_char.len_utf8();
287 let unescaped_char = match first_char {
289 let second_char = chars.clone().next();
292 // Rust language specification requires us to skip whitespaces
293 // if unescaped '\' character is followed by '\n'.
294 // For details see [Rust language reference]
295 // (https://doc.rust-lang.org/reference/tokens.html#string-literals).
296 skip_ascii_whitespace(&mut chars);
299 _ => scan_escape(first_char, &mut chars, mode),
304 _ => scan_escape(first_char, &mut chars, mode),
306 let end = initial_len - chars.as_str().len();
307 callback(start..end, unescaped_char);
310 fn skip_ascii_whitespace(chars: &mut Chars<'_>) {
311 let str = chars.as_str();
312 let first_non_space = str
314 .position(|b| b != b' ' && b != b'\t' && b != b'\n' && b != b'\r')
315 .unwrap_or(str.len());
316 *chars = str[first_non_space..].chars()
320 /// Takes a contents of a string literal (without quotes) and produces a
321 /// sequence of characters or errors.
322 /// NOTE: Raw strings do not perform any explicit character escaping, here we
323 /// only translate CRLF to LF and produce errors on bare CR.
324 fn unescape_raw_str_or_byte_str<F>(literal_text: &str, mode: Mode, callback: &mut F)
326 F: FnMut(Range<usize>, Result<char, EscapeError>),
328 assert!(mode.in_double_quotes());
329 let initial_len = literal_text.len();
331 let mut chars = literal_text.chars();
332 while let Some(curr) = chars.next() {
333 let start = initial_len - chars.as_str().len() - curr.len_utf8();
335 let result = match curr {
336 '\r' => Err(EscapeError::BareCarriageReturnInRawString),
337 c if mode.is_bytes() && !c.is_ascii() => Err(EscapeError::NonAsciiCharInByteString),
340 let end = initial_len - chars.as_str().len();
342 callback(start..end, result);
346 fn byte_from_char(c: char) -> u8 {
348 assert!(res <= u8::max_value() as u32, "guaranteed because of Mode::Byte(Str)");
352 fn is_ascii(x: u32) -> bool {