0
# Core API Functions
1

2
High-level parsing functions and parser discovery utilities that provide the main interface for using jc programmatically. These functions handle parser loading, data parsing, and metadata retrieval.
3

4
## Capabilities
5

6
### Primary Parsing Function
7

8
The main high-level API function for parsing data using any available parser.
9

10
```python { .api }
11
def parse(
12
    parser_mod_name: Union[str, ModuleType],
13
    data: Union[str, bytes, Iterable[str]],
14
    quiet: bool = False,
15
    raw: bool = False,
16
    ignore_exceptions: Optional[bool] = None,
17
    **kwargs
18
) -> Union[JSONDictType, List[JSONDictType], Iterator[JSONDictType]]:
19
    """
20
    Parse data using the specified parser module.
21

22
    Parameters:
23
    - parser_mod_name: Name of parser module (accepts module_name, cli-name, --argument-name variants) or Module object
24
    - data: Data to parse (string/bytes for standard parsers, iterable of strings for streaming parsers)
25
    - quiet: Suppress warning messages if True
26
    - raw: Output preprocessed JSON if True
27
    - ignore_exceptions: Ignore parsing exceptions if True (streaming parsers only)
28
    - **kwargs: Additional parser-specific arguments
29

30
    Returns:
31
    - Standard Parsers: Dictionary or List of Dictionaries
32
    - Streaming Parsers: Generator Object containing Dictionaries
33

34
    Raises:
35
    - ModuleNotFoundError: If parser module is not found or invalid
36
    """
37
```
38

39
### Parser Module Access
40

41
Direct access to parser module objects for advanced usage patterns.
42

43
```python { .api }
44
def get_parser(parser_mod_name: Union[str, ModuleType]) -> ModuleType:
45
    """
46
    Return parser module object and validate it's a valid parser module.
47

48
    Parameters:
49
    - parser_mod_name: Name of parser module or Module object (accepts module_name, cli-name, --argument-name variants)
50

51
    Returns:
52
    - Module: The parser Module object
53

54
    Raises:
55
    - ModuleNotFoundError: If Module is not found or is not a valid parser Module
56
    """
57
```
58

59
### Parser Discovery
60

61
Functions to discover available parsers and their capabilities.
62

63
```python { .api }
64
def parser_mod_list(
65
    show_hidden: bool = False,
66
    show_deprecated: bool = False
67
) -> List[str]:
68
    """
69
    Returns a list of all available parser module names.
70

71
    Parameters:
72
    - show_hidden: Include parsers marked as hidden
73
    - show_deprecated: Include parsers marked as deprecated
74

75
    Returns:
76
    - List of parser module names
77
    """
78

79
def plugin_parser_mod_list(
80
    show_hidden: bool = False,
81
    show_deprecated: bool = False
82
) -> List[str]:
83
    """
84
    Returns a list of plugin parser module names (subset of parser_mod_list).
85

86
    Parameters:
87
    - show_hidden: Include parsers marked as hidden
88
    - show_deprecated: Include parsers marked as deprecated
89

90
    Returns:
91
    - List of plugin parser module names
92
    """
93

94
def standard_parser_mod_list(
95
    show_hidden: bool = False,
96
    show_deprecated: bool = False
97
) -> List[str]:
98
    """
99
    Returns a list of standard (non-streaming) parser module names.
100

101
    Parameters:
102
    - show_hidden: Include parsers marked as hidden
103
    - show_deprecated: Include parsers marked as deprecated
104

105
    Returns:
106
    - List of standard parser module names
107
    """
108

109
def streaming_parser_mod_list(
110
    show_hidden: bool = False,
111
    show_deprecated: bool = False
112
) -> List[str]:
113
    """
114
    Returns a list of streaming parser module names.
115

116
    Parameters:
117
    - show_hidden: Include parsers marked as hidden
118
    - show_deprecated: Include parsers marked as deprecated
119

120
    Returns:
121
    - List of streaming parser module names
122
    """
123

124
def slurpable_parser_mod_list(
125
    show_hidden: bool = False,
126
    show_deprecated: bool = False
127
) -> List[str]:
128
    """
129
    Returns a list of slurpable parser module names (can use --slurp option).
130

131
    Parameters:
132
    - show_hidden: Include parsers marked as hidden
133
    - show_deprecated: Include parsers marked as deprecated
134

135
    Returns:
136
    - List of slurpable parser module names
137
    """
138
```
139

140
### Parser Metadata
141

142
Functions to retrieve detailed information about parsers.
143

144
```python { .api }
145
def parser_info(
146
    parser_mod_name: Union[str, ModuleType],
147
    documentation: bool = False
148
) -> ParserInfoType:
149
    """
150
    Returns dictionary with parser module metadata.
151

152
    Parameters:
153
    - parser_mod_name: Parser module name or Module object (accepts module_name, cli-name, --argument-name variants)
154
    - documentation: Include parser docstring if True
155

156
    Returns:
157
    - Dictionary containing parser metadata including name, version, description, compatibility, tags, etc.
158
    """
159

160
def all_parser_info(
161
    documentation: bool = False,
162
    show_hidden: bool = False,
163
    show_deprecated: bool = False
164
) -> List[ParserInfoType]:
165
    """
166
    Returns list of dictionaries with metadata for all parser modules.
167

168
    Parameters:
169
    - documentation: Include parser docstrings if True
170
    - show_hidden: Include parsers marked as hidden
171
    - show_deprecated: Include parsers marked as deprecated
172

173
    Returns:
174
    - List of parser metadata dictionaries
175
    """
176
```
177

178
### Help and Documentation
179

180
Interactive help functionality for parser modules.
181

182
```python { .api }
183
def get_help(parser_mod_name: Union[str, ModuleType]) -> None:
184
    """
185
    Show help screen for the selected parser.
186

187
    Parameters:
188
    - parser_mod_name: Parser module name or Module object (accepts module_name, cli-name, --argument-name variants)
189

190
    Returns:
191
    - None (displays help to stdout)
192
    """
193
```
194

195
## Usage Examples
196

197
### Basic Parsing
198

199
```python
200
import jc
201
import subprocess
202

203
# Parse dig command output
204
cmd_output = subprocess.check_output(['dig', 'example.com'], text=True)
205
data = jc.parse('dig', cmd_output)
206
print(f"Query ID: {data[0]['id']}")
207

208
# Parse with error suppression
209
data = jc.parse('dig', cmd_output, quiet=True)
210

211
# Get raw (preprocessed) output
212
raw_data = jc.parse('dig', cmd_output, raw=True)
213
```
214

215
### Parser Discovery
216

217
```python
218
import jc
219

220
# Get all available parsers
221
all_parsers = jc.parser_mod_list()
222
print(f"Available parsers: {len(all_parsers)}")
223

224
# Get only streaming parsers
225
streaming_parsers = jc.streaming_parser_mod_list()
226
print(f"Streaming parsers: {streaming_parsers}")
227

228
# Get parser information
229
dig_info = jc.parser_info('dig')
230
print(f"Parser: {dig_info['name']}, Version: {dig_info['version']}")
231
```
232

233
### Direct Parser Usage
234

235
```python
236
import jc
237

238
# Get parser module
239
jc_dig = jc.get_parser('dig')
240
data = jc_dig.parse(cmd_output)
241

242
# Show parser help
243
jc.get_help('dig')
244
```