0
# JSONPath Parsing
1

2
Comprehensive parsing functionality that converts JSONPath string expressions into executable Abstract Syntax Tree (AST) objects. The parser supports the full JSONPath syntax with extensions including union operations, filtering, and named operators.
3

4
## Capabilities
5

6
### Main Parse Function
7

8
The primary entry point for parsing JSONPath expressions from strings into executable objects.
9

10
```python { .api }
11
def parse(string):
12
    """
13
    Parse a JSONPath string expression into a JSONPath object.
14
    
15
    Parameters:
16
    - string: str, JSONPath expression to parse
17
    
18
    Returns:
19
    JSONPath: Executable JSONPath AST object
20
    
21
    Raises:
22
    Exception: Parse error with location information
23
    """
24
```
25

26
**Usage Example:**
27

28
```python
29
from jsonpath_rw import parse
30

31
# Basic field access
32
expr = parse('$.name')
33

34
# Array indexing and field access
35
expr = parse('users[0].email')
36

37
# Wildcard and descendant queries
38
expr = parse('$..*')
39

40
# Complex expressions with filtering
41
expr = parse('$.users[*] where @.age')
42
```
43

44
### JsonPathParser Class
45

46
Advanced parser class providing fine-grained control over the parsing process with debugging capabilities and token stream processing.
47

48
```python { .api }
49
class JsonPathParser:
50
    """
51
    LALR parser for JSONPath expressions using PLY (Python Lex-Yacc).
52
    """
53
    
54
    def __init__(self, debug=False, lexer_class=None):
55
        """
56
        Initialize the parser.
57
        
58
        Parameters:
59
        - debug: bool, enable debugging output
60
        - lexer_class: class, custom lexer class (default: JsonPathLexer)
61
        """
62
    
63
    def parse(self, string, lexer=None):
64
        """
65
        Parse a JSONPath string expression.
66
        
67
        Parameters:
68
        - string: str, JSONPath expression to parse
69
        - lexer: JsonPathLexer, custom lexer instance
70
        
71
        Returns:
72
        JSONPath: Parsed JSONPath AST object
73
        """
74
    
75
    def parse_token_stream(self, token_iterator, start_symbol='jsonpath'):
76
        """
77
        Parse from a token iterator.
78
        
79
        Parameters:
80
        - token_iterator: iterator, token stream
81
        - start_symbol: str, grammar start symbol
82
        
83
        Returns:
84
        JSONPath: Parsed JSONPath AST object
85
        """
86
```
87

88
### JsonPathLexer Class
89

90
Lexical analyzer that tokenizes JSONPath expressions, handling various string quoting styles and named operators.
91

92
```python { .api }
93
class JsonPathLexer:
94
    """
95
    Lexical analyzer for JSONPath expressions.
96
    """
97
    
98
    tokens = ['DOUBLEDOT', 'NUMBER', 'ID', 'NAMED_OPERATOR', 'WHERE']
99
    literals = ['*', '.', '[', ']', '(', ')', '$', ',', ':', '|', '&']
100
    states = [('singlequote', 'exclusive'), ('doublequote', 'exclusive'), ('backquote', 'exclusive')]
101
    reserved_words = {'where': 'WHERE'}
102
    
103
    def __init__(self, debug=False):
104
        """
105
        Initialize the lexer.
106
        
107
        Parameters:
108
        - debug: bool, enable debugging output
109
        """
110
    
111
    def tokenize(self, string):
112
        """
113
        Convert string to token iterator.
114
        
115
        Parameters:
116
        - string: str, input string to tokenize
117
        
118
        Yields:
119
        Token objects with type, value, and position information
120
        
121
        Raises:
122
        JsonPathLexerError: Lexical analysis errors
123
        """
124
```
125

126
### JsonPathLexerError Exception
127

128
Exception raised during lexical analysis when invalid characters or syntax are encountered.
129

130
```python { .api }
131
class JsonPathLexerError(Exception):
132
    """
133
    Exception raised for lexical analysis errors.
134
    
135
    Contains detailed error message with line and column information
136
    to help identify the location of syntax problems in JSONPath expressions.
137
    
138
    Raised in the following situations:
139
    - Unexpected characters in input
140
    - Unterminated string literals
141
    - Invalid escape sequences
142
    - Missing docstrings when using PYTHONOPTIMIZE=2
143
    """
144
```
145

146
## Supported Syntax
147

148
### Atomic Expressions
149

150
- `$` - Root object
151
- `@` or `` `this` `` - Current object  
152
- `` `parent` `` - Parent object (named operator)
153
- `field` - Field access
154
- `[field]` - Bracketed field access
155
- `[n]` - Array index access
156

157
### Operators
158

159
- `.` - Child access (path1.path2)
160
- `..` - Descendant access (path1..path2)
161
- `|` - Union (path1|path2)
162
- `&` - Intersection (path1&path2) - **Note: Not implemented**
163
- `where` - Filtering (path1 where path2)
164

165
### Array Operations
166

167
- `[*]` - All array elements
168
- `[start:end]` - Array slice
169
- `[start:]` - Slice from start
170
- `[:end]` - Slice to end
171

172
### Field Operations
173

174
- `*` - All fields
175
- `field1,field2` - Multiple specific fields
176
- `[field1,field2]` - Bracketed multiple fields
177

178
### String Quoting
179

180
Fields can be quoted using single quotes, double quotes, or remain unquoted:
181

182
- `field` - Unquoted field
183
- `'field name'` - Single-quoted field
184
- `"field name"` - Double-quoted field
185

186
## Error Handling
187

188
Parse errors include location information (line and column) to help identify syntax issues:
189

190
```python
191
try:
192
    expr = parse('$.invalid[syntax')
193
except Exception as e:
194
    print(f"Parse error: {e}")
195
    # Output: Parse error at 1:15 near token syntax (ID)
196
```