0
# Command Line Interface
1

2
XML to JSON conversion via command line tool supporting all xmljson conventions with customizable input/output files and conversion dialects.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
Primary command-line interface function for XML to JSON conversion.
9

10
```python { .api }
11
def main(*test_args):
12
    """
13
    Main CLI entry point for xml2json conversion.
14
    
15
    Parameters:
16
    - *test_args: For testing purposes, bypasses command line argument parsing
17
    
18
    Functionality:
19
    - Parses command line arguments
20
    - Reads XML from input file or stdin
21
    - Converts using specified dialect
22
    - Outputs JSON to file or stdout
23
    """
24
```
25

26
### Argument Parsing
27

28
Parses command-line arguments for XML to JSON conversion configuration.
29

30
```python { .api }
31
def parse_args(args=None, in_file=sys.stdin, out_file=sys.stdout):
32
    """
33
    Parse command-line arguments for XML to JSON conversion.
34
    
35
    Parameters:
36
    - args: list, command line arguments (None for sys.argv)
37
    - in_file: file, default input file (default: stdin)
38
    - out_file: file, default output file (default: stdout)
39
    
40
    Returns:
41
    tuple: (in_file, out_file, dialect) - configured file handles and dialect instance
42
    """
43
```
44

45
## Usage Patterns
46

47
### Command Line Usage
48

49
**Module invocation:**
50
```bash
51
python -m xmljson [options] [input_file]
52
```
53

54
**Console script (after pip install):**
55
```bash
56
xml2json [options] [input_file]
57
```
58

59
### Arguments
60

61
- `input_file`: Input XML file (optional, defaults to stdin)
62
- `-o, --out_file`: Output JSON file (optional, defaults to stdout)
63
- `-d, --dialect`: Conversion dialect (default: parker)
64

65
### Supported Dialects
66

67
```python { .api }
68
dialects = {
69
    'abdera': Abdera,
70
    'badgerfish': BadgerFish,
71
    'cobra': Cobra,
72
    'gdata': GData,
73
    'parker': Parker,
74
    'xmldata': XMLData,
75
    'yahoo': Yahoo
76
}
77
```
78

79
Available dialect options:
80
- `abdera`: Abdera convention
81
- `badgerfish`: BadgerFish convention  
82
- `cobra`: Cobra convention
83
- `gdata`: GData convention
84
- `parker`: Parker convention (default)
85
- `xmldata`: Base XMLData class (default configuration)
86
- `yahoo`: Yahoo convention
87

88
### Usage Examples
89

90
**Basic conversion (parker dialect, default):**
91
```bash
92
python -m xmljson data.xml
93
```
94

95
**Specify output file:**
96
```bash
97
python -m xmljson -o output.json data.xml
98
```
99

100
**Use different dialect:**
101
```bash
102
python -m xmljson -d badgerfish data.xml
103
```
104

105
**From stdin to stdout:**
106
```bash
107
cat data.xml | python -m xmljson
108
```
109

110
**Badgerfish with output file:**
111
```bash
112
xml2json -d badgerfish -o result.json input.xml
113
```
114

115
**Pipeline usage:**
116
```bash
117
curl -s http://example.com/api.xml | xml2json -d gdata | jq '.response.data'
118
```
119

120
### Help Output
121

122
```bash
123
python -m xmljson -h
124
```
125

126
```
127
usage: xmljson [-h] [-o OUT_FILE] [-d {abdera,badgerfish,cobra,gdata,parker,xmldata,yahoo}] [in_file]
128

129
positional arguments:
130
  in_file               defaults to stdin
131

132
optional arguments:
133
  -h, --help            show this help message and exit
134
  -o OUT_FILE, --out_file OUT_FILE
135
                        defaults to stdout
136
  -d {abdera,badgerfish,cobra,gdata,parker,xmldata,yahoo}, --dialect {abdera,badgerfish,cobra,gdata,parker,xmldata,yahoo}
137
                        defaults to parker
138
```
139

140
## Implementation Details
141

142
### File Handling
143

144
The CLI uses context managers for proper file handling:
145

146
```python
147
from contextlib import closing
148

149
with closing(in_file) as in_file, closing(out_file) as out_file:
150
    json.dump(dialect.data(parse(in_file).getroot()), out_file, indent=2)
151
```
152

153
### XML Parsing
154

155
Uses xml.etree.cElementTree (or lxml.etree if available) for XML parsing:
156

157
```python
158
try:
159
    from lxml.etree import parse
160
except ImportError:
161
    from xml.etree.cElementTree import parse
162
```
163

164
### JSON Output
165

166
Output is formatted with 2-space indentation for readability:
167

168
```python
169
json.dump(result, out_file, indent=2)
170
```
171

172
## Error Handling
173

174
- **Invalid Dialect**: Raises TypeError for unknown dialect names
175
- **File Errors**: Standard file I/O error handling
176
- **XML Parse Errors**: Propagates XML parsing exceptions
177
- **JSON Errors**: Propagates JSON serialization exceptions
178

179
## Use Cases
180

181
- **Batch Processing**: Convert multiple XML files to JSON
182
- **Pipeline Integration**: Part of data processing pipelines
183
- **API Development**: Quick XML-to-JSON conversion for API responses
184
- **Data Migration**: Converting XML data stores to JSON format
185
- **Testing**: Comparing XML-to-JSON conversion results across dialects