1use std::borrow::Cow;
2use std::str::FromStr;
3
4use crate::repr::{Decor, Repr};
5use crate::InternalString;
6
7/// Key as part of a Key/Value Pair or a table header.
8///
9/// # Examples
10///
11/// ```notrust
12/// [dependencies."nom"]
13/// version = "5.0"
14/// 'literal key' = "nonsense"
15/// "basic string key" = 42
16/// ```
17///
18/// There are 3 types of keys:
19///
20/// 1. Bare keys (`version` and `dependencies`)
21///
22/// 2. Basic quoted keys (`"basic string key"` and `"nom"`)
23///
24/// 3. Literal quoted keys (`'literal key'`)
25///
26/// For details see [toml spec](https://github.com/toml-lang/toml/#keyvalue-pair).
27///
28/// To parse a key use `FromStr` trait implementation: `"string".parse::<Key>()`.
29#[derive(Debug)]
30pub struct Key {
31 key: InternalString,
32 pub(crate) repr: Option<Repr>,
33 pub(crate) leaf_decor: Decor,
34 pub(crate) dotted_decor: Decor,
35}
36
37impl Key {
38 /// Create a new table key
39 pub fn new(key: impl Into<InternalString>) -> Self {
40 Self {
41 key: key.into(),
42 repr: None,
43 leaf_decor: Default::default(),
44 dotted_decor: Default::default(),
45 }
46 }
47
48 /// Parse a TOML key expression
49 ///
50 /// Unlike `"".parse<Key>()`, this supports dotted keys.
51 #[cfg(feature = "parse")]
52 pub fn parse(repr: &str) -> Result<Vec<Self>, crate::TomlError> {
53 Self::try_parse_path(repr)
54 }
55
56 pub(crate) fn with_repr_unchecked(mut self, repr: Repr) -> Self {
57 self.repr = Some(repr);
58 self
59 }
60
61 /// While creating the `Key`, add `Decor` to it
62 #[deprecated(since = "0.21.1", note = "Replaced with `with_leaf_decor`")]
63 pub fn with_decor(self, decor: Decor) -> Self {
64 self.with_leaf_decor(decor)
65 }
66
67 /// While creating the `Key`, add `Decor` to it for the line entry
68 pub fn with_leaf_decor(mut self, decor: Decor) -> Self {
69 self.leaf_decor = decor;
70 self
71 }
72
73 /// While creating the `Key`, add `Decor` to it for between dots
74 pub fn with_dotted_decor(mut self, decor: Decor) -> Self {
75 self.dotted_decor = decor;
76 self
77 }
78
79 /// Access a mutable proxy for the `Key`.
80 pub fn as_mut(&mut self) -> KeyMut<'_> {
81 KeyMut { key: self }
82 }
83
84 /// Returns the parsed key value.
85 pub fn get(&self) -> &str {
86 &self.key
87 }
88
89 /// Returns key raw representation, if available.
90 pub fn as_repr(&self) -> Option<&Repr> {
91 self.repr.as_ref()
92 }
93
94 /// Returns the default raw representation.
95 #[cfg(feature = "display")]
96 pub fn default_repr(&self) -> Repr {
97 to_key_repr(&self.key)
98 }
99
100 /// Returns a raw representation.
101 #[cfg(feature = "display")]
102 pub fn display_repr(&self) -> Cow<'_, str> {
103 self.as_repr()
104 .and_then(|r| r.as_raw().as_str())
105 .map(Cow::Borrowed)
106 .unwrap_or_else(|| {
107 Cow::Owned(self.default_repr().as_raw().as_str().unwrap().to_owned())
108 })
109 }
110
111 /// Returns the surrounding whitespace
112 #[deprecated(
113 since = "0.21.1",
114 note = "Replaced with `dotted_decor_mut`, `leaf_decor_mut"
115 )]
116 pub fn decor_mut(&mut self) -> &mut Decor {
117 self.leaf_decor_mut()
118 }
119
120 /// Returns the surrounding whitespace for the line entry
121 pub fn leaf_decor_mut(&mut self) -> &mut Decor {
122 &mut self.leaf_decor
123 }
124
125 /// Returns the surrounding whitespace for between dots
126 pub fn dotted_decor_mut(&mut self) -> &mut Decor {
127 &mut self.dotted_decor
128 }
129
130 /// Returns the surrounding whitespace
131 #[deprecated(since = "0.21.1", note = "Replaced with `dotted_decor`, `leaf_decor")]
132 pub fn decor(&self) -> &Decor {
133 self.leaf_decor()
134 }
135
136 /// Returns the surrounding whitespace for the line entry
137 pub fn leaf_decor(&self) -> &Decor {
138 &self.leaf_decor
139 }
140
141 /// Returns the surrounding whitespace for between dots
142 pub fn dotted_decor(&self) -> &Decor {
143 &self.dotted_decor
144 }
145
146 /// The location within the original document
147 ///
148 /// This generally requires an [`ImDocument`][crate::ImDocument].
149 pub fn span(&self) -> Option<std::ops::Range<usize>> {
150 self.repr.as_ref().and_then(|r| r.span())
151 }
152
153 pub(crate) fn despan(&mut self, input: &str) {
154 self.leaf_decor.despan(input);
155 self.dotted_decor.despan(input);
156 if let Some(repr) = &mut self.repr {
157 repr.despan(input);
158 }
159 }
160
161 /// Auto formats the key.
162 pub fn fmt(&mut self) {
163 self.repr = None;
164 self.leaf_decor.clear();
165 self.dotted_decor.clear();
166 }
167
168 #[cfg(feature = "parse")]
169 fn try_parse_simple(s: &str) -> Result<Key, crate::TomlError> {
170 let mut key = crate::parser::parse_key(s)?;
171 key.despan(s);
172 Ok(key)
173 }
174
175 #[cfg(feature = "parse")]
176 fn try_parse_path(s: &str) -> Result<Vec<Key>, crate::TomlError> {
177 let mut keys = crate::parser::parse_key_path(s)?;
178 for key in &mut keys {
179 key.despan(s);
180 }
181 Ok(keys)
182 }
183}
184
185impl Clone for Key {
186 #[inline(never)]
187 fn clone(&self) -> Self {
188 Self {
189 key: self.key.clone(),
190 repr: self.repr.clone(),
191 leaf_decor: self.leaf_decor.clone(),
192 dotted_decor: self.dotted_decor.clone(),
193 }
194 }
195}
196
197impl std::ops::Deref for Key {
198 type Target = str;
199
200 fn deref(&self) -> &Self::Target {
201 self.get()
202 }
203}
204
205impl std::borrow::Borrow<str> for Key {
206 #[inline]
207 fn borrow(&self) -> &str {
208 self.get()
209 }
210}
211
212impl std::hash::Hash for Key {
213 fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
214 self.get().hash(state);
215 }
216}
217
218impl Ord for Key {
219 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
220 self.get().cmp(other.get())
221 }
222}
223
224impl PartialOrd for Key {
225 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
226 Some(self.cmp(other))
227 }
228}
229
230impl Eq for Key {}
231
232impl PartialEq for Key {
233 #[inline]
234 fn eq(&self, other: &Key) -> bool {
235 PartialEq::eq(self.get(), other.get())
236 }
237}
238
239impl PartialEq<str> for Key {
240 #[inline]
241 fn eq(&self, other: &str) -> bool {
242 PartialEq::eq(self.get(), other)
243 }
244}
245
246impl PartialEq<&str> for Key {
247 #[inline]
248 fn eq(&self, other: &&str) -> bool {
249 PartialEq::eq(self.get(), *other)
250 }
251}
252
253impl PartialEq<String> for Key {
254 #[inline]
255 fn eq(&self, other: &String) -> bool {
256 PartialEq::eq(self.get(), other.as_str())
257 }
258}
259
260#[cfg(feature = "display")]
261impl std::fmt::Display for Key {
262 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
263 crate::encode::encode_key(self, buf:f, input:None)
264 }
265}
266
267#[cfg(feature = "parse")]
268impl FromStr for Key {
269 type Err = crate::TomlError;
270
271 /// Tries to parse a key from a &str,
272 /// if fails, tries as basic quoted key (surrounds with "")
273 /// and then literal quoted key (surrounds with '')
274 fn from_str(s: &str) -> Result<Self, Self::Err> {
275 Key::try_parse_simple(s)
276 }
277}
278
279#[cfg(feature = "display")]
280fn to_key_repr(key: &str) -> Repr {
281 #[cfg(feature = "parse")]
282 {
283 if keyimpl Iterator
284 .as_bytes()
285 .iter()
286 .copied()
287 .all(crate::parser::key::is_unquoted_char)
288 && !key.is_empty()
289 {
290 Repr::new_unchecked(raw:key)
291 } else {
292 crate::encode::to_string_repr(
293 value:key,
294 style:Some(crate::encode::StringStyle::OnelineSingle),
295 literal:None,
296 )
297 }
298 }
299 #[cfg(not(feature = "parse"))]
300 {
301 crate::encode::to_string_repr(key, Some(crate::encode::StringStyle::OnelineSingle), None)
302 }
303}
304
305impl<'b> From<&'b str> for Key {
306 fn from(s: &'b str) -> Self {
307 Key::new(key:s)
308 }
309}
310
311impl<'b> From<&'b String> for Key {
312 fn from(s: &'b String) -> Self {
313 Key::new(key:s)
314 }
315}
316
317impl From<String> for Key {
318 fn from(s: String) -> Self {
319 Key::new(key:s)
320 }
321}
322
323impl From<InternalString> for Key {
324 fn from(s: InternalString) -> Self {
325 Key::new(key:s)
326 }
327}
328
329#[doc(hidden)]
330impl From<Key> for InternalString {
331 fn from(key: Key) -> InternalString {
332 key.key
333 }
334}
335
336/// A mutable reference to a `Key`'s formatting
337#[derive(Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
338pub struct KeyMut<'k> {
339 key: &'k mut Key,
340}
341
342impl KeyMut<'_> {
343 /// Returns the parsed key value.
344 pub fn get(&self) -> &str {
345 self.key.get()
346 }
347
348 /// Returns the raw representation, if available.
349 pub fn as_repr(&self) -> Option<&Repr> {
350 self.key.as_repr()
351 }
352
353 /// Returns the default raw representation.
354 #[cfg(feature = "display")]
355 pub fn default_repr(&self) -> Repr {
356 self.key.default_repr()
357 }
358
359 /// Returns a raw representation.
360 #[cfg(feature = "display")]
361 pub fn display_repr(&self) -> Cow<'_, str> {
362 self.key.display_repr()
363 }
364
365 /// Returns the surrounding whitespace
366 #[deprecated(
367 since = "0.21.1",
368 note = "Replaced with `dotted_decor_mut`, `leaf_decor_mut"
369 )]
370 pub fn decor_mut(&mut self) -> &mut Decor {
371 #![allow(deprecated)]
372 self.key.decor_mut()
373 }
374
375 /// Returns the surrounding whitespace for the line entry
376 pub fn leaf_decor_mut(&mut self) -> &mut Decor {
377 self.key.leaf_decor_mut()
378 }
379
380 /// Returns the surrounding whitespace for between dots
381 pub fn dotted_decor_mut(&mut self) -> &mut Decor {
382 self.key.dotted_decor_mut()
383 }
384
385 /// Returns the surrounding whitespace
386 #[deprecated(since = "0.21.1", note = "Replaced with `dotted_decor`, `leaf_decor")]
387 pub fn decor(&self) -> &Decor {
388 #![allow(deprecated)]
389 self.key.decor()
390 }
391
392 /// Returns the surrounding whitespace for the line entry
393 pub fn leaf_decor(&self) -> &Decor {
394 self.key.leaf_decor()
395 }
396
397 /// Returns the surrounding whitespace for between dots
398 pub fn dotted_decor(&self) -> &Decor {
399 self.key.dotted_decor()
400 }
401
402 /// Auto formats the key.
403 pub fn fmt(&mut self) {
404 self.key.fmt();
405 }
406}
407
408impl std::ops::Deref for KeyMut<'_> {
409 type Target = str;
410
411 fn deref(&self) -> &Self::Target {
412 self.get()
413 }
414}
415
416impl PartialEq<str> for KeyMut<'_> {
417 #[inline]
418 fn eq(&self, other: &str) -> bool {
419 PartialEq::eq(self.get(), other)
420 }
421}
422
423impl<'s> PartialEq<&'s str> for KeyMut<'s> {
424 #[inline]
425 fn eq(&self, other: &&str) -> bool {
426 PartialEq::eq(self.get(), *other)
427 }
428}
429
430impl PartialEq<String> for KeyMut<'_> {
431 #[inline]
432 fn eq(&self, other: &String) -> bool {
433 PartialEq::eq(self.get(), other.as_str())
434 }
435}
436
437#[cfg(feature = "display")]
438impl std::fmt::Display for KeyMut<'_> {
439 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
440 std::fmt::Display::fmt(&self.key, f)
441 }
442}
443
444#[test]
445#[cfg(feature = "parse")]
446#[cfg(feature = "display")]
447fn string_roundtrip() {
448 Key::new("hello").to_string().parse::<Key>().unwrap();
449}
450