0
# jc - JSON Convert
1

2
A comprehensive command-line utility and Python library that converts the output of popular CLI tools, file formats, and common string patterns to JSON format for easier parsing and processing in scripts and automation workflows. It supports over 240 different parsers for commands like dig, ps, ls, netstat, and many others, enabling seamless integration with JSON processing tools like jq.
3

4
## Package Information
5

6
- **Package Name**: jc
7
- **Language**: Python  
8
- **Installation**: `pip install jc`
9
- **Version**: 1.25.5
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import jc
16
```
17

18
For direct parser access:
19

20
```python
21
import jc.parsers.dig  # Example: access dig parser directly
22
```
23

24
For CLI usage:
25

26
```python
27
from jc import cli
28
```
29

30
## Basic Usage
31

32
### Library Usage
33

34
```python
35
import jc
36
import subprocess
37

38
# Parse command output using high-level API
39
cmd_output = subprocess.check_output(['dig', 'example.com'], text=True)
40
data = jc.parse('dig', cmd_output)
41
print(data[0]['id'])  # Access parsed data
42

43
# Get parser module for direct use
44
jc_dig = jc.get_parser('dig')
45
data = jc_dig.parse(cmd_output)
46

47
# Direct parser module access
48
import jc.parsers.dig
49
data = jc.parsers.dig.parse(cmd_output)
50
```
51

52
### CLI Usage
53

54
```bash
55
# Parse command output via pipe
56
dig example.com | jc --dig
57

58
# Use magic syntax for direct command execution
59
jc dig example.com
60

61
# Stream processing for large datasets
62
tail -f /var/log/syslog | jc --syslog-s
63
```
64

65
## Architecture
66

67
The jc library is organized around a plugin-based parser system:
68

69
- **Core API**: High-level functions for parsing and parser discovery
70
- **Parser Registry**: Centralized system managing 240+ built-in parsers
71
- **Plugin System**: User-extensible parser loading from custom directories
72
- **Streaming Support**: Real-time processing of continuous data streams
73
- **CLI Interface**: Full command-line tool with magic syntax and formatting options
74
- **Type System**: Comprehensive type definitions for all components
75

76
## Capabilities
77

78
### Core API Functions
79

80
High-level parsing functions and parser discovery utilities that provide the main interface for using jc programmatically.
81

82
```python { .api }
83
def parse(parser_mod_name: Union[str, ModuleType], data: Union[str, bytes, Iterable[str]], quiet: bool = False, raw: bool = False, ignore_exceptions: Optional[bool] = None, **kwargs) -> Union[JSONDictType, List[JSONDictType], Iterator[JSONDictType]]: ...
84

85
def get_parser(parser_mod_name: Union[str, ModuleType]) -> ModuleType: ...
86

87
def parser_mod_list(show_hidden: bool = False, show_deprecated: bool = False) -> List[str]: ...
88

89
def slurpable_parser_mod_list(show_hidden: bool = False, show_deprecated: bool = False) -> List[str]: ...
90

91
def parser_info(parser_mod_name: Union[str, ModuleType], documentation: bool = False) -> ParserInfoType: ...
92
```
93

94
[Core API](./core-api.md)
95

96
### Individual Parsers
97

98
Over 240 specialized parsers for converting output from specific commands, file formats, and data patterns to structured JSON.
99

100
```python { .api }
101
# Each parser module contains:
102
def parse(data: str, quiet: bool = False, raw: bool = False) -> Union[Dict, List[Dict]]: ...
103

104
# Parser information object
105
info = ParserInfoType  # Contains metadata, version, compatibility info
106
```
107

108
[Parsers](./parsers.md)
109

110
### Streaming Parsers
111

112
Real-time parsing capabilities for processing continuous data streams, with built-in error handling and metadata generation.
113

114
```python { .api }
115
def streaming_input_type_check(data: Iterable[Union[str, bytes]]) -> None: ...
116

117
def stream_success(output_line: JSONDictType, ignore_exceptions: bool) -> JSONDictType: ...
118

119
def add_jc_meta(func: F) -> F: ...  # Decorator for streaming parsers
120
```
121

122
[Streaming](./streaming.md)
123

124
### CLI Interface
125

126
Full command-line interface with extensive options, magic syntax, and multiple output formats.
127

128
```python { .api }
129
class JcCli:
130
    def __init__(self) -> None: ...
131
    # Handles all CLI operations, argument parsing, and output formatting
132

133
def main() -> None: ...  # CLI entry point
134
```
135

136
[CLI Interface](./cli.md)
137

138
### Utilities and Types
139

140
Utility functions for text processing, validation, and type definitions used throughout the library.
141

142
```python { .api }
143
# Exception classes
144
class ParseError(Exception): ...
145
class LibraryNotInstalled(Exception): ...
146

147
# Type definitions
148
JSONDictType = Dict[str, Any]
149
ParserInfoType = TypedDict  # Comprehensive parser metadata structure
150
```
151

152
[Utilities](./utilities.md)
153

154
## Types
155

156
```python { .api }
157
from typing import Dict, List, Union, Optional, Iterable, Iterator, TypedDict, Any
158
from types import ModuleType
159

160
JSONDictType = Dict[str, Any]
161
CustomColorType = Dict[Any, str]
162
StreamingOutputType = Iterator[Union[JSONDictType, Tuple[BaseException, str]]]
163

164
# Parser metadata structure (Python 3.8+)
165
ParserInfoType = TypedDict('ParserInfoType', {
166
    "name": str,
167
    "argument": str,
168
    "version": str,
169
    "description": str,
170
    "author": str,
171
    "author_email": str,
172
    "compatible": List[str],
173
    "magic_commands": List[str],
174
    "tags": List[str],
175
    "documentation": str,
176
    "streaming": bool,
177
    "plugin": bool,
178
    "hidden": bool,
179
    "deprecated": bool
180
}, total=False)
181
```