Skip to main content

parquet_variant/
path.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5use crate::utils::parse_path;
6use arrow_schema::ArrowError;
7use std::{borrow::Cow, ops::Deref};
8
9/// Represents a qualified path to a potential subfield or index of a variant
10/// value.
11///
12/// Can be used with [`Variant::get_path`] to retrieve a specific subfield of
13/// a variant value.
14///
15/// [`Variant::get_path`]: crate::Variant::get_path
16///
17/// Create a [`VariantPath`] from a vector of [`VariantPathElement`], or
18/// from a single field name or index.
19///
20/// # Example: Simple paths
21/// ```rust
22/// # use parquet_variant::{VariantPath, VariantPathElement};
23/// // access the field "foo" in a variant object value
24/// let path = VariantPath::try_from("foo").unwrap();
25/// // access the first element in a variant list vale
26/// let path = VariantPath::from(0);
27/// ```
28///
29/// # Example: Compound paths
30/// ```
31/// # use parquet_variant::{VariantPath, VariantPathElement};
32/// /// You can also create a path by joining elements together:
33/// // access the field "foo" and then the first element in a variant list value
34/// let path = VariantPath::try_from("foo").unwrap().join(0);
35/// // this is the same as the previous one
36/// let path2 = VariantPath::from_iter(["foo".into(), 0.into()]);
37/// assert_eq!(path, path2);
38/// // you can also create a path from a vector of `VariantPathElement` directly
39/// let path3 = [
40///   VariantPathElement::field("foo"),
41///   VariantPathElement::index(0)
42/// ].into_iter().collect::<VariantPath>();
43/// assert_eq!(path, path3);
44/// ```
45///
46/// # Example: From Dot notation strings
47/// ```
48/// # use parquet_variant::{VariantPath, VariantPathElement};
49/// /// You can also convert strings directly into paths using dot notation
50/// let path = VariantPath::try_from("foo.bar.baz").unwrap();
51/// let expected = VariantPath::try_from("foo").unwrap().join("bar").join("baz");
52/// assert_eq!(path, expected);
53/// ```
54///
55/// # Example: Accessing Compound paths
56/// ```
57/// # use parquet_variant::{VariantPath, VariantPathElement};
58/// /// You can access the paths using slices
59/// // access the field "foo" and then the first element in a variant list value
60/// let path = VariantPath::try_from("foo").unwrap()
61///   .join("bar")
62///   .join("baz");
63/// assert_eq!(path[1], VariantPathElement::field("bar"));
64/// ```
65///
66/// # Example: Accessing field with bracket
67/// ```
68/// # use parquet_variant::{VariantPath, VariantPathElement};
69/// let path = VariantPath::try_from("a['b.c'].d[2]['3']").unwrap();
70/// let expected = VariantPath::from_iter([VariantPathElement::field("a"),
71///     VariantPathElement::field("b.c"),
72///     VariantPathElement::field("d"),
73///     VariantPathElement::index(2),
74///     VariantPathElement::field("3")]);
75/// assert_eq!(path, expected)
76/// ```
77#[derive(Debug, Clone, PartialEq, Default)]
78pub struct VariantPath<'a>(Vec<VariantPathElement<'a>>);
79
80impl<'a> VariantPath<'a> {
81    /// Create a new `VariantPath` from a vector of `VariantPathElement`.
82    pub fn new(path: Vec<VariantPathElement<'a>>) -> Self {
83        Self(path)
84    }
85
86    /// Return the inner path elements.
87    pub fn path(&self) -> &Vec<VariantPathElement<'_>> {
88        &self.0
89    }
90
91    /// Return a new `VariantPath` with element appended
92    pub fn join(mut self, element: impl Into<VariantPathElement<'a>>) -> Self {
93        self.push(element);
94        self
95    }
96
97    /// Append a new element to the path
98    pub fn push(&mut self, element: impl Into<VariantPathElement<'a>>) {
99        self.0.push(element.into());
100    }
101
102    /// Returns whether [`VariantPath`] has no path elements
103    pub fn is_empty(&self) -> bool {
104        self.0.is_empty()
105    }
106}
107
108impl<'a> From<Vec<VariantPathElement<'a>>> for VariantPath<'a> {
109    fn from(value: Vec<VariantPathElement<'a>>) -> Self {
110        Self::new(value)
111    }
112}
113
114/// Create from &str with support for dot notation
115impl<'a> TryFrom<&'a str> for VariantPath<'a> {
116    type Error = ArrowError;
117
118    fn try_from(path: &'a str) -> Result<Self, Self::Error> {
119        parse_path(path).map(VariantPath::new)
120    }
121}
122
123/// Create from usize
124impl From<usize> for VariantPath<'_> {
125    fn from(index: usize) -> Self {
126        VariantPath::new(vec![VariantPathElement::index(index)])
127    }
128}
129
130impl<'a> From<&[VariantPathElement<'a>]> for VariantPath<'a> {
131    fn from(elements: &[VariantPathElement<'a>]) -> Self {
132        VariantPath::new(elements.to_vec())
133    }
134}
135
136/// Create from iter
137impl<'a> FromIterator<VariantPathElement<'a>> for VariantPath<'a> {
138    fn from_iter<T: IntoIterator<Item = VariantPathElement<'a>>>(iter: T) -> Self {
139        VariantPath::new(Vec::from_iter(iter))
140    }
141}
142
143impl<'a> Deref for VariantPath<'a> {
144    type Target = [VariantPathElement<'a>];
145
146    fn deref(&self) -> &Self::Target {
147        &self.0
148    }
149}
150
151/// Element of a [`VariantPath`] that can be a field name, an index, or a list element wildcard.
152///
153/// See [`VariantPath`] for more details and examples.
154#[derive(Debug, Clone, PartialEq)]
155pub enum VariantPathElement<'a> {
156    /// Access field with name `name`
157    Field { name: Cow<'a, str> },
158    /// Access the list element at `index`
159    Index { index: usize },
160    /// Match the shared element schema of a list (`[*]`)
161    ListElement,
162}
163
164impl<'a> VariantPathElement<'a> {
165    pub fn field(name: impl Into<Cow<'a, str>>) -> VariantPathElement<'a> {
166        let name = name.into();
167        VariantPathElement::Field { name }
168    }
169
170    pub fn index(index: usize) -> VariantPathElement<'a> {
171        VariantPathElement::Index { index }
172    }
173
174    pub fn list_element() -> VariantPathElement<'a> {
175        VariantPathElement::ListElement
176    }
177}
178
179// Conversion utilities for `VariantPathElement` from string types
180impl<'a> From<Cow<'a, str>> for VariantPathElement<'a> {
181    fn from(name: Cow<'a, str>) -> Self {
182        VariantPathElement::field(name)
183    }
184}
185
186impl<'a> From<&'a str> for VariantPathElement<'a> {
187    fn from(name: &'a str) -> Self {
188        VariantPathElement::field(Cow::Borrowed(name))
189    }
190}
191
192impl From<String> for VariantPathElement<'_> {
193    fn from(name: String) -> Self {
194        VariantPathElement::field(Cow::Owned(name))
195    }
196}
197
198impl<'a> From<&'a String> for VariantPathElement<'a> {
199    fn from(name: &'a String) -> Self {
200        VariantPathElement::field(Cow::Borrowed(name.as_str()))
201    }
202}
203
204impl From<usize> for VariantPathElement<'_> {
205    fn from(index: usize) -> Self {
206        VariantPathElement::index(index)
207    }
208}
209
210#[cfg(test)]
211mod tests {
212    use super::*;
213
214    #[test]
215    fn test_variant_path_empty() {
216        let path = VariantPath::from_iter([]);
217        assert!(path.is_empty());
218    }
219
220    #[test]
221    fn test_variant_path_empty_str() {
222        let path = VariantPath::try_from("").unwrap();
223        assert!(path.is_empty());
224    }
225
226    #[test]
227    fn test_variant_path_non_empty() {
228        let p = VariantPathElement::from("a");
229        let path = VariantPath::from_iter([p]);
230        assert!(!path.is_empty());
231    }
232
233    #[test]
234    fn test_variant_path_dot_notation_with_array_index() {
235        let path = VariantPath::try_from("city.store.books[3].title").unwrap();
236
237        let expected = VariantPath::try_from("city")
238            .unwrap()
239            .join("store")
240            .join("books")
241            .join(3)
242            .join("title");
243
244        assert_eq!(path, expected);
245    }
246
247    #[test]
248    fn test_variant_path_dot_notation_with_only_array_index() {
249        let path = VariantPath::try_from("[3]").unwrap();
250
251        let expected = VariantPath::from(3);
252
253        assert_eq!(path, expected);
254    }
255
256    #[test]
257    fn test_variant_path_dot_notation_with_starting_array_index() {
258        let path = VariantPath::try_from("[3].title").unwrap();
259
260        let expected = VariantPath::from(3).join("title");
261
262        assert_eq!(path, expected);
263    }
264
265    #[test]
266    fn test_variant_path_field_in_bracket() {
267        // field with index
268        let path = VariantPath::try_from("foo[0].bar").unwrap();
269        let expected = VariantPath::from_iter([
270            VariantPathElement::field("foo"),
271            VariantPathElement::index(0),
272            VariantPathElement::field("bar"),
273        ]);
274        assert_eq!(path, expected);
275
276        // index in the end
277        let path = VariantPath::try_from("foo.bar[42]").unwrap();
278        let expected = VariantPath::from_iter([
279            VariantPathElement::field("foo"),
280            VariantPathElement::field("bar"),
281            VariantPathElement::index(42),
282        ]);
283        assert_eq!(path, expected);
284
285        // list wildcard is distinct from a quoted field named "*"
286        let path = VariantPath::try_from("foo[*]['*']").unwrap();
287        let expected = VariantPath::from_iter([
288            VariantPathElement::field("foo"),
289            VariantPathElement::list_element(),
290            VariantPathElement::field("*"),
291        ]);
292        assert_eq!(path, expected);
293
294        // invalid index will be treated as field
295        let path = VariantPath::try_from("foo.bar['abc'][\"def\"]").unwrap();
296        let expected = VariantPath::from_iter([
297            VariantPathElement::field("foo"),
298            VariantPathElement::field("bar"),
299            VariantPathElement::field("abc"),
300            VariantPathElement::field("def"),
301        ]);
302        assert_eq!(path, expected);
303
304        // a number quoted with `'` is treated as field, not index
305        let path = VariantPath::try_from("foo['0'].bar[\"1\"]").unwrap();
306        let expected = VariantPath::from_iter([
307            VariantPathElement::field("foo"),
308            VariantPathElement::field("0"),
309            VariantPathElement::field("bar"),
310            VariantPathElement::field("1"),
311        ]);
312        assert_eq!(path, expected);
313
314        // an unescaped closing bracket is literal inside a quoted field
315        for input in [r#"["a]b"]"#, "['a]b']"] {
316            let path = VariantPath::try_from(input).unwrap();
317            let expected = VariantPath::from_iter([VariantPathElement::field("a]b")]);
318            assert_eq!(path, expected);
319        }
320
321        // quoted brackets do not consume the following path element
322        let path = VariantPath::try_from(r#"["[0]"][1]"#).unwrap();
323        let expected = VariantPath::from_iter([
324            VariantPathElement::field("[0]"),
325            VariantPathElement::index(1),
326        ]);
327        assert_eq!(path, expected);
328
329        // escaped quotes and an unescaped bracket remain one quoted field
330        let path = VariantPath::try_from(r#"["\"][\""]"#).unwrap();
331        let expected = VariantPath::from_iter([VariantPathElement::field(r#""][""#)]);
332        assert_eq!(path, expected);
333
334        // the existing escaped spelling remains supported
335        let path = VariantPath::try_from(r#"["a\]b"]"#).unwrap();
336        let expected = VariantPath::from_iter([VariantPathElement::field("a]b")]);
337        assert_eq!(path, expected);
338    }
339
340    #[test]
341    fn test_variant_path_bracket_field_ownership() {
342        use VariantPathElement::Field;
343
344        let path = VariantPath::try_from(r#"[""]["plain"]["escaped\]field"]['a]b']"#).unwrap();
345
346        assert!(matches!(
347            &path[..],
348            [
349                Field { name: Cow::Borrowed("") },
350                Field { name: Cow::Borrowed("plain") },
351                Field { name: Cow::Owned(escaped) },
352                Field { name: Cow::Borrowed("a]b") },
353            ] if escaped == "escaped]field"
354        ));
355    }
356
357    #[test]
358    fn test_invalid_path_parse() {
359        // Leading dot
360        let err = VariantPath::try_from(".foo.bar").unwrap_err();
361        assert_eq!(err.to_string(), "Parser error: Unexpected leading '.'");
362
363        // Trailing dot
364        let err = VariantPath::try_from("foo.bar.").unwrap_err();
365        assert_eq!(err.to_string(), "Parser error: Unexpected trailing '.'");
366
367        // No ']' will be treated as error
368        let err = VariantPath::try_from("foo.bar[2.baz").unwrap_err();
369        assert_eq!(err.to_string(), "Parser error: Unclosed '[' at byte 7");
370
371        // No ']' because of escaped.
372        let err = VariantPath::try_from("foo.bar[2\\].fds").unwrap_err();
373        assert_eq!(err.to_string(), "Parser error: Unclosed '[' at byte 7");
374
375        // Trailing backslash in bracket
376        let err = VariantPath::try_from("foo.bar[fdafa\\").unwrap_err();
377        assert_eq!(err.to_string(), "Parser error: Unclosed '[' at byte 7");
378
379        // No '[' before ']'
380        let err = VariantPath::try_from("foo.bar]baz").unwrap_err();
381        assert_eq!(err.to_string(), "Parser error: Unexpected ']' at byte 7");
382
383        // Invalid number(without quote) parse
384        let err = VariantPath::try_from("foo.bar[123abc]").unwrap_err();
385        assert_eq!(
386            err.to_string(),
387            "Parser error: Invalid token in bracket request: `123abc`. Expected `*`, a quoted string, or a number(e.g., `[*]`, `['field']`, or `[123]`)"
388        );
389
390        let err = VariantPath::try_from("foo.bar[abc]").unwrap_err();
391        assert_eq!(
392            err.to_string(),
393            "Parser error: Invalid token in bracket request: `abc`. Expected `*`, a quoted string, or a number(e.g., `[*]`, `['field']`, or `[123]`)"
394        );
395
396        // Out-of-range integer indexes are invalid path tokens.
397        let too_large_index = (usize::MAX as u128) + 1;
398        let err = VariantPath::try_from(format!("[{too_large_index}]").as_str()).unwrap_err();
399        assert!(
400            err.to_string()
401                .contains("Parser error: Invalid token in bracket request"),
402            "{err}"
403        );
404    }
405}