rustc_ast/
format.rs

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

rustc_ast/
format.rs
