1//! Parsing library for [`defmt`] format strings.
2//!
3//! This is an implementation detail of [`defmt`] and not meant to be consumed by other tools at the
4//! moment so all the API is unstable.
5//!
6//! [`defmt`]: https://github.com/knurling-rs/defmt
7
8#![cfg_attr(docsrs, feature(doc_cfg))]
9#![doc(html_logo_url = "https://knurling.ferrous-systems.com/knurling_logo_light_text.svg")]
10
11mod display_hint;
12#[cfg(test)]
13mod tests;
14mod types;
15
16use std::{borrow::Cow, ops::Range};
17
18pub use crate::{
19 display_hint::{DisplayHint, TimePrecision},
20 types::Type,
21};
22
23/// The kinds of error this library can return
24#[derive(thiserror::Error, Debug, PartialEq, Eq, Clone)]
25pub enum Error {
26 #[error("invalid type specifier `{0:?}`")]
27 InvalidTypeSpecifier(String),
28 #[error("unable to parse given integer")]
29 InvalidInteger(#[from] std::num::ParseIntError),
30 #[error("invalid array specifier (missing length)")]
31 InvalidArraySpecifierMissingLength,
32 #[error("invalid array specifier (missing `]`")]
33 InvalidArraySpecifierMissingBracket,
34 #[error("trailing data after bitfield range")]
35 TrailingDataAfterBitfieldRange,
36 #[error("malformed format string (missing display hint after ':')")]
37 MalformedFormatString,
38 #[error("unknown display hint: {0:?}")]
39 UnknownDisplayHint(String),
40 #[error("unexpected content `{0:?}` in format string")]
41 UnexpectedContentInFormatString(String),
42 #[error("unmatched `{{` in format string")]
43 UnmatchedOpenBracket,
44 #[error("unmatched `}}` in format string")]
45 UnmatchedCloseBracket,
46 #[error("conflicting types for argument {0}: used as {1:?} and {2:?}")]
47 ConflictingTypes(usize, Type, Type),
48 #[error("argument {0} is not used in this format string")]
49 UnusedArgument(usize),
50}
51
52/// A parameter of the form `{{0=Type:hint}}` in a format string.
53#[derive(Clone, Debug, Eq, PartialEq)]
54pub struct Parameter {
55 /// The argument index to display at this position.
56 pub index: usize,
57 /// The type of the argument to display, e.g. '=u8', '=bool'.
58 pub ty: Type,
59 /// The display hint, e.g. ':x', ':b', ':a'.
60 pub hint: Option<DisplayHint>,
61}
62
63/// A part of a format string.
64#[derive(Clone, Debug, Eq, PartialEq)]
65pub enum Fragment<'f> {
66 /// A literal string (eg. `"literal "` in `"literal {:?}"`).
67 Literal(Cow<'f, str>),
68
69 /// A format parameter.
70 Parameter(Parameter),
71}
72
73/// A parsed formatting parameter (contents of `{` `}` block).
74///
75/// # Syntax
76///
77/// ```notrust
78/// param := '{' [ argument ] [ '=' argtype ] [ ':' format_spec ] '}'
79/// argument := integer
80///
81/// argtype := bitfield | '?' | format-array | '[?]' | byte-array | '[u8]' | 'istr' | 'str' |
82/// 'bool' | 'char' | 'u8' | 'u16' | 'u32' | 'u64' | 'u128' | 'usize' | 'i8' | 'i16' | 'i32' |
83/// 'i64' | 'i128 | 'isize' | 'f32' | 'f64'
84/// bitfield := integer '..' integer
85/// format-array := '[?;' spaces integer ']'
86/// byte-array := '[u8;' spaces integer ']'
87/// spaces := ' '*
88///
89/// format_spec := [ zero_pad ] type
90/// zero_pad := '0' integer
91/// type := 'a' | 'b' | 'o' | 'x' | 'X' | '?' | 'us'
92/// ```
93#[derive(Debug, PartialEq)]
94struct Param {
95 index: Option<usize>,
96 ty: Type,
97 hint: Option<DisplayHint>,
98}
99
100/// The log level
101#[derive(Clone, Copy, Debug, Eq, PartialEq, PartialOrd)]
102pub enum Level {
103 Trace,
104 Debug,
105 Info,
106 Warn,
107 Error,
108}
109
110impl Level {
111 pub fn as_str(self) -> &'static str {
112 match self {
113 Level::Trace => "trace",
114 Level::Debug => "debug",
115 Level::Info => "info",
116 Level::Warn => "warn",
117 Level::Error => "error",
118 }
119 }
120}
121
122fn parse_range(mut s: &str) -> Option<(Range<u8>, usize /* consumed */)> {
123 // consume first number
124 let start_digits = s
125 .as_bytes()
126 .iter()
127 .take_while(|b| (**b as char).is_ascii_digit())
128 .count();
129 let start = s[..start_digits].parse().ok()?;
130
131 // next two `char`s should be `..`
132 if &s[start_digits..start_digits + 2] != ".." {
133 return None;
134 }
135 s = &s[start_digits + 2..];
136
137 // consume second number
138 let end_digits = s
139 .as_bytes()
140 .iter()
141 .take_while(|b| (**b as char).is_ascii_digit())
142 .count();
143 let end = s[..end_digits].parse().ok()?;
144
145 // check for faulty state
146 if end <= start || start >= 128 || end > 128 {
147 return None;
148 }
149
150 Some((start..end, start_digits + end_digits + 2))
151}
152
153/// Parse and consume an array at the beginning of `s`.
154///
155/// Return the length of the array.
156fn parse_array(mut s: &str) -> Result<usize, Error> {
157 // skip spaces
158 let len_pos: usize = s
159 .find(|c: char| c != ' ')
160 .ok_or(err:Error::InvalidArraySpecifierMissingLength)?;
161 s = &s[len_pos..];
162
163 // consume length
164 let after_len: usize = s
165 .find(|c: char| !c.is_ascii_digit())
166 .ok_or(err:Error::InvalidArraySpecifierMissingBracket)?;
167 let len: usize = s[..after_len].parse::<usize>()?;
168 s = &s[after_len..];
169
170 // consume final `]`
171 if s != "]" {
172 return Err(Error::InvalidArraySpecifierMissingBracket);
173 }
174
175 Ok(len)
176}
177
178/// Parser mode
179#[derive(Clone, Copy, Debug, Eq, PartialEq)]
180pub enum ParserMode {
181 /// Rejects unknown display hints
182 Strict,
183 /// Accepts unknown display hints
184 ForwardsCompatible,
185}
186
187/// Parse `Param` from `&str`
188///
189/// * example `input`: `0=Type:hint` (note: no curly braces)
190fn parse_param(mut input: &str, mode: ParserMode) -> Result<Param, Error> {
191 const TYPE_PREFIX: &str = "=";
192 const HINT_PREFIX: &str = ":";
193
194 // First, optional argument index.
195 let mut index = None;
196 let index_end = input
197 .find(|c: char| !c.is_ascii_digit())
198 .unwrap_or(input.len());
199
200 if index_end != 0 {
201 index = Some(input[..index_end].parse::<usize>()?);
202 }
203
204 // Then, optional type
205 let mut ty = Type::default(); // when no explicit type; use the default one
206 input = &input[index_end..];
207
208 if input.starts_with(TYPE_PREFIX) {
209 // skip the prefix
210 input = &input[TYPE_PREFIX.len()..];
211
212 // type is delimited by `HINT_PREFIX` or end-of-string
213 let type_end = input.find(HINT_PREFIX).unwrap_or(input.len());
214 let type_fragment = &input[..type_end];
215
216 const FORMAT_ARRAY_START: &str = "[?;";
217 const U8_ARRAY_START: &str = "[u8;";
218
219 // what comes next is the type
220 ty = if let Ok(ty) = type_fragment.parse() {
221 Ok(ty)
222 } else if let Some(s) = type_fragment.strip_prefix(U8_ARRAY_START) {
223 Ok(Type::U8Array(parse_array(s)?))
224 } else if let Some(s) = type_fragment.strip_prefix(FORMAT_ARRAY_START) {
225 Ok(Type::FormatArray(parse_array(s)?))
226 } else if let Some((range, used)) = parse_range(type_fragment) {
227 // Check for bitfield syntax.
228 match used != type_fragment.len() {
229 true => Err(Error::TrailingDataAfterBitfieldRange),
230 false => Ok(Type::BitField(range)),
231 }
232 } else {
233 Err(Error::InvalidTypeSpecifier(input.to_owned()))
234 }?;
235
236 input = &input[type_end..];
237 }
238
239 // Then, optional hint
240 let mut hint = None;
241
242 if input.starts_with(HINT_PREFIX) {
243 // skip the prefix
244 input = &input[HINT_PREFIX.len()..];
245 if input.is_empty() {
246 return Err(Error::MalformedFormatString);
247 }
248
249 hint = match (DisplayHint::parse(input), mode) {
250 (Some(a), _) => Some(a),
251 (None, ParserMode::Strict) => return Err(Error::UnknownDisplayHint(input.to_owned())),
252 (None, ParserMode::ForwardsCompatible) => Some(DisplayHint::Unknown(input.to_owned())),
253 };
254 } else if !input.is_empty() {
255 return Err(Error::UnexpectedContentInFormatString(input.to_owned()));
256 }
257
258 Ok(Param { index, ty, hint })
259}
260
261fn push_literal<'f>(frag: &mut Vec<Fragment<'f>>, unescaped_literal: &'f str) -> Result<(), Error> {
262 // Replace `{{` with `{` and `}}` with `}`. Single braces are errors.
263
264 // Scan for single braces first. The rest is trivial.
265 let mut last_open = false;
266 let mut last_close = false;
267 for c in unescaped_literal.chars() {
268 match c {
269 '{' => last_open = !last_open,
270 '}' => last_close = !last_close,
271 _ if last_open => return Err(Error::UnmatchedOpenBracket),
272 _ if last_close => return Err(Error::UnmatchedCloseBracket),
273 _ => {}
274 }
275 }
276
277 // Handle trailing unescaped `{` or `}`.
278 if last_open {
279 return Err(Error::UnmatchedOpenBracket);
280 } else if last_close {
281 return Err(Error::UnmatchedCloseBracket);
282 }
283
284 // FIXME: This always allocates a `String`, so the `Cow` is useless.
285 let literal = unescaped_literal.replace("{{", "{").replace("}}", "}");
286 frag.push(Fragment::Literal(literal.into()));
287 Ok(())
288}
289
290/// Returns `Some(smallest_bit_index, largest_bit_index)` contained in `params` if
291/// `params` contains any bitfields. Otherwise `None`.
292pub fn get_max_bitfield_range<'a, I>(params: I) -> Option<(u8, u8)>
293where
294 I: Iterator<Item = &'a Parameter> + Clone,
295{
296 let largest_bit_index: Option = paramsimpl Iterator
297 .clone()
298 .map(|param: &'a Parameter| match &param.ty {
299 Type::BitField(range: &Range) => range.end,
300 _ => unreachable!(),
301 })
302 .max();
303
304 let smallest_bit_index: Option = paramsimpl Iterator
305 .map(|param: &'a Parameter| match &param.ty {
306 Type::BitField(range: &Range) => range.start,
307 _ => unreachable!(),
308 })
309 .min();
310
311 match (smallest_bit_index, largest_bit_index) {
312 (Some(smallest: u8), Some(largest: u8)) => Some((smallest, largest)),
313 (None, None) => None,
314 _ => unreachable!(),
315 }
316}
317
318pub fn parse(format_string: &str, mode: ParserMode) -> Result<Vec<Fragment<'_>>, Error> {
319 let mut fragments = Vec::new();
320
321 // Index after the `}` of the last format specifier.
322 let mut end_pos = 0;
323
324 // Next argument index assigned to a parameter without an explicit one.
325 let mut next_arg_index = 0;
326
327 let mut chars = format_string.char_indices();
328 while let Some((brace_pos, ch)) = chars.next() {
329 if ch != '{' {
330 // Part of a literal fragment.
331 continue;
332 }
333
334 // Peek at the next char.
335 if chars.as_str().starts_with('{') {
336 // Escaped `{{`, also part of a literal fragment.
337 chars.next(); // Move after both `{`s.
338 continue;
339 }
340
341 if brace_pos > end_pos {
342 // There's a literal fragment with at least 1 character before this parameter fragment.
343 let unescaped_literal = &format_string[end_pos..brace_pos];
344 push_literal(&mut fragments, unescaped_literal)?;
345 }
346
347 // Else, this is a format specifier. It ends at the next `}`.
348 let len = chars
349 .as_str()
350 .find('}')
351 .ok_or(Error::UnmatchedOpenBracket)?;
352 end_pos = brace_pos + 1 + len + 1;
353
354 // Parse the contents inside the braces.
355 let param_str = &format_string[brace_pos + 1..][..len];
356 let param = parse_param(param_str, mode)?;
357 fragments.push(Fragment::Parameter(Parameter {
358 index: param.index.unwrap_or_else(|| {
359 // If there is no explicit index, assign the next one.
360 let idx = next_arg_index;
361 next_arg_index += 1;
362 idx
363 }),
364 ty: param.ty,
365 hint: param.hint,
366 }));
367 }
368
369 // Trailing literal.
370 if end_pos != format_string.len() {
371 push_literal(&mut fragments, &format_string[end_pos..])?;
372 }
373
374 // Check for argument type conflicts.
375 let mut args = Vec::new();
376 for frag in &fragments {
377 if let Fragment::Parameter(Parameter { index, ty, .. }) = frag {
378 if args.len() <= *index {
379 args.resize(*index + 1, None);
380 }
381
382 match &args[*index] {
383 None => args[*index] = Some(ty.clone()),
384 Some(other_ty) => match (other_ty, ty) {
385 (Type::BitField(_), Type::BitField(_)) => {} // FIXME: Bitfield range shouldn't be part of the type.
386 (a, b) if a != b => {
387 return Err(Error::ConflictingTypes(*index, a.clone(), b.clone()))
388 }
389 _ => {}
390 },
391 }
392 }
393 }
394
395 // Check that argument indices are dense (all arguments must be used).
396 for (index, arg) in args.iter().enumerate() {
397 if arg.is_none() {
398 return Err(Error::UnusedArgument(index));
399 }
400 }
401
402 Ok(fragments)
403}
404