rustc_ast/
format.rs

1use rustc_data_structures::fx::FxHashMap;
2use rustc_macros::{Decodable, Encodable};
3use rustc_span::{Ident, Span, Symbol};
4
5use crate::Expr;
6use crate::ptr::P;
7use crate::token::LitKind;
8
9// Definitions:
10//
11// format_args!("hello {abc:.xyz$}!!", abc="world");
12// └──────────────────────────────────────────────┘
13//                     FormatArgs
14//
15// format_args!("hello {abc:.xyz$}!!", abc="world");
16//                                     └─────────┘
17//                                      argument
18//
19// format_args!("hello {abc:.xyz$}!!", abc="world");
20//              └───────────────────┘
21//                     template
22//
23// format_args!("hello {abc:.xyz$}!!", abc="world");
24//               └────┘└─────────┘└┘
25//                      pieces
26//
27// format_args!("hello {abc:.xyz$}!!", abc="world");
28//               └────┘           └┘
29//                   literal pieces
30//
31// format_args!("hello {abc:.xyz$}!!", abc="world");
32//                     └─────────┘
33//                     placeholder
34//
35// format_args!("hello {abc:.xyz$}!!", abc="world");
36//                      └─┘  └─┘
37//                      positions (could be names, numbers, empty, or `*`)
38
39/// (Parsed) format args.
40///
41/// Basically the "AST" for a complete `format_args!()`.
42///
43/// E.g., `format_args!("hello {name}");`.
44#[derive(Clone, Encodable, Decodable, Debug)]
45pub struct FormatArgs {
46    pub span: Span,
47    pub template: Vec<FormatArgsPiece>,
48    pub arguments: FormatArguments,
49    /// The raw, un-split format string literal, with no escaping or processing.
50    ///
51    /// Generally only useful for lints that care about the raw bytes the user wrote.
52    pub uncooked_fmt_str: (LitKind, Symbol),
53    /// Was the format literal written in the source?
54    /// - `format!("boo")` => true,
55    /// - `format!(concat!("b", "o", "o"))` => false,
56    /// - `format!(include_str!("boo.txt"))` => false,
57    ///
58    /// If it wasn't written in the source then we have to be careful with spans pointing into it
59    /// and suggestions about rewriting it.
60    pub is_source_literal: bool,
61}
62
63/// A piece of a format template string.
64///
65/// E.g. "hello" or "{name}".
66#[derive(Clone, Encodable, Decodable, Debug)]
67pub enum FormatArgsPiece {
68    Literal(Symbol),
69    Placeholder(FormatPlaceholder),
70}
71
72/// The arguments to format_args!().
73///
74/// E.g. `1, 2, name="ferris", n=3`,
75/// but also implicit captured arguments like `x` in `format_args!("{x}")`.
76#[derive(Clone, Encodable, Decodable, Debug)]
77pub struct FormatArguments {
78    arguments: Vec<FormatArgument>,
79    num_unnamed_args: usize,
80    num_explicit_args: usize,
81    names: FxHashMap<Symbol, usize>,
82}
83
84impl FormatArguments {
85    pub fn new() -> Self {
86        Self {
87            arguments: Vec::new(),
88            names: FxHashMap::default(),
89            num_unnamed_args: 0,
90            num_explicit_args: 0,
91        }
92    }
93
94    pub fn add(&mut self, arg: FormatArgument) -> usize {
95        let index = self.arguments.len();
96        if let Some(name) = arg.kind.ident() {
97            self.names.insert(name.name, index);
98        } else if self.names.is_empty() {
99            // Only count the unnamed args before the first named arg.
100            // (Any later ones are errors.)
101            self.num_unnamed_args += 1;
102        }
103        if !matches!(arg.kind, FormatArgumentKind::Captured(..)) {
104            // This is an explicit argument.
105            // Make sure that all arguments so far are explicit.
106            assert_eq!(
107                self.num_explicit_args,
108                self.arguments.len(),
109                "captured arguments must be added last"
110            );
111            self.num_explicit_args += 1;
112        }
113        self.arguments.push(arg);
114        index
115    }
116
117    pub fn by_name(&self, name: Symbol) -> Option<(usize, &FormatArgument)> {
118        let i = *self.names.get(&name)?;
119        Some((i, &self.arguments[i]))
120    }
121
122    pub fn by_index(&self, i: usize) -> Option<&FormatArgument> {
123        (i < self.num_explicit_args).then(|| &self.arguments[i])
124    }
125
126    pub fn unnamed_args(&self) -> &[FormatArgument] {
127        &self.arguments[..self.num_unnamed_args]
128    }
129
130    pub fn named_args(&self) -> &[FormatArgument] {
131        &self.arguments[self.num_unnamed_args..self.num_explicit_args]
132    }
133
134    pub fn explicit_args(&self) -> &[FormatArgument] {
135        &self.arguments[..self.num_explicit_args]
136    }
137
138    pub fn all_args(&self) -> &[FormatArgument] {
139        &self.arguments[..]
140    }
141
142    pub fn all_args_mut(&mut self) -> &mut Vec<FormatArgument> {
143        &mut self.arguments
144    }
145}
146
147#[derive(Clone, Encodable, Decodable, Debug)]
148pub struct FormatArgument {
149    pub kind: FormatArgumentKind,
150    pub expr: P<Expr>,
151}
152
153#[derive(Clone, Encodable, Decodable, Debug)]
154pub enum FormatArgumentKind {
155    /// `format_args(…, arg)`
156    Normal,
157    /// `format_args(…, arg = 1)`
158    Named(Ident),
159    /// `format_args("… {arg} …")`
160    Captured(Ident),
161}
162
163impl FormatArgumentKind {
164    pub fn ident(&self) -> Option<Ident> {
165        match self {
166            &Self::Normal => None,
167            &Self::Named(id) => Some(id),
168            &Self::Captured(id) => Some(id),
169        }
170    }
171}
172
173#[derive(Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
174pub struct FormatPlaceholder {
175    /// Index into [`FormatArgs::arguments`].
176    pub argument: FormatArgPosition,
177    /// The span inside the format string for the full `{…}` placeholder.
178    pub span: Option<Span>,
179    /// `{}`, `{:?}`, or `{:x}`, etc.
180    pub format_trait: FormatTrait,
181    /// `{}` or `{:.5}` or `{:-^20}`, etc.
182    pub format_options: FormatOptions,
183}
184
185#[derive(Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
186pub struct FormatArgPosition {
187    /// Which argument this position refers to (Ok),
188    /// or would've referred to if it existed (Err).
189    pub index: Result<usize, usize>,
190    /// What kind of position this is. See [`FormatArgPositionKind`].
191    pub kind: FormatArgPositionKind,
192    /// The span of the name or number.
193    pub span: Option<Span>,
194}
195
196#[derive(Copy, Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
197pub enum FormatArgPositionKind {
198    /// `{}` or `{:.*}`
199    Implicit,
200    /// `{1}` or `{:1$}` or `{:.1$}`
201    Number,
202    /// `{a}` or `{:a$}` or `{:.a$}`
203    Named,
204}
205
206#[derive(Copy, Clone, Encodable, Decodable, Debug, PartialEq, Eq, Hash)]
207pub enum FormatTrait {
208    /// `{}`
209    Display,
210    /// `{:?}`
211    Debug,
212    /// `{:e}`
213    LowerExp,
214    /// `{:E}`
215    UpperExp,
216    /// `{:o}`
217    Octal,
218    /// `{:p}`
219    Pointer,
220    /// `{:b}`
221    Binary,
222    /// `{:x}`
223    LowerHex,
224    /// `{:X}`
225    UpperHex,
226}
227
228#[derive(Clone, Encodable, Decodable, Default, Debug, PartialEq, Eq)]
229pub struct FormatOptions {
230    /// The width. E.g. `{:5}` or `{:width$}`.
231    pub width: Option<FormatCount>,
232    /// The precision. E.g. `{:.5}` or `{:.precision$}`.
233    pub precision: Option<FormatCount>,
234    /// The alignment. E.g. `{:>}` or `{:<}` or `{:^}`.
235    pub alignment: Option<FormatAlignment>,
236    /// The fill character. E.g. the `.` in `{:.>10}`.
237    pub fill: Option<char>,
238    /// The `+` or `-` flag.
239    pub sign: Option<FormatSign>,
240    /// The `#` flag.
241    pub alternate: bool,
242    /// The `0` flag. E.g. the `0` in `{:02x}`.
243    pub zero_pad: bool,
244    /// The `x` or `X` flag (for `Debug` only). E.g. the `x` in `{:x?}`.
245    pub debug_hex: Option<FormatDebugHex>,
246}
247
248#[derive(Copy, Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
249pub enum FormatSign {
250    /// The `+` flag.
251    Plus,
252    /// The `-` flag.
253    Minus,
254}
255
256#[derive(Copy, Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
257pub enum FormatDebugHex {
258    /// The `x` flag in `{:x?}`.
259    Lower,
260    /// The `X` flag in `{:X?}`.
261    Upper,
262}
263
264#[derive(Copy, Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
265pub enum FormatAlignment {
266    /// `{:<}`
267    Left,
268    /// `{:>}`
269    Right,
270    /// `{:^}`
271    Center,
272}
273
274#[derive(Clone, Encodable, Decodable, Debug, PartialEq, Eq)]
275pub enum FormatCount {
276    /// `{:5}` or `{:.5}`
277    Literal(u16),
278    /// `{:.*}`, `{:.5$}`, or `{:a$}`, etc.
279    Argument(FormatArgPosition),
280}
rustc_ast/format.rs

rustc_ast/
format.rs
