0
# Parser Nodes
1

2
Parser nodes provide data format conversion utilities for working with JSON, XML, CSV, HTML, and YAML formats. These nodes enable seamless transformation between different data representations commonly used in APIs, configuration files, and data exchange.
3

4
## Capabilities
5

6
### JSON Node
7

8
Parse JSON strings to objects and stringify objects to JSON with formatting options.
9

10
```javascript { .api }
11
/**
12
 * JSON node for JSON parsing and stringification
13
 * Registers as node type: "json"
14
 */
15
function JSONNode(config) {
16
    RED.nodes.createNode(this, config);
17
    
18
    // Configuration properties:
19
    // config.property - Property to convert (default: "payload")
20
    // config.action - Action: "obj" (to object), "str" (to string), "" (auto-detect)
21
    // config.pretty - Pretty print JSON strings
22
}
23
```
24

25
**Usage Examples:**
26

27
```javascript
28
// Parse JSON string to object
29
{
30
    "property": "payload",
31
    "action": "obj"
32
}
33

34
// Convert object to pretty JSON string
35
{
36
    "property": "payload", 
37
    "action": "str",
38
    "pretty": true
39
}
40

41
// Auto-detect conversion direction
42
{
43
    "property": "payload",
44
    "action": ""
45
}
46

47
// Example message transformations:
48
// Input:  { payload: '{"name":"John","age":30}' }
49
// Output: { payload: { name: "John", age: 30 } }
50

51
// Input:  { payload: { name: "John", age: 30 } }  
52
// Output: { payload: '{"name":"John","age":30}' }
53
```
54

55
### XML Node
56

57
Parse XML strings to JavaScript objects and convert objects back to XML format.
58

59
```javascript { .api }
60
/**
61
 * XML node for XML parsing and generation
62
 * Registers as node type: "xml"
63
 */
64
function XMLNode(config) {
65
    RED.nodes.createNode(this, config);
66
    
67
    // Configuration properties:
68
    // config.property - Property to convert (default: "payload")
69
    // config.attr - Attribute prefix (default: "$")
70
    // config.chr - Text content key (default: "_")
71
    // config.action - Action: "obj" (to object), "str" (to string), "" (auto-detect)
72
}
73
```
74

75
**Usage Examples:**
76

77
```javascript
78
// Parse XML to object with custom attribute prefix
79
{
80
    "property": "payload",
81
    "action": "obj", 
82
    "attr": "@",
83
    "chr": "#text"
84
}
85

86
// Convert object to XML string
87
{
88
    "property": "payload",
89
    "action": "str"
90
}
91

92
// Example transformations:
93
// Input:  { payload: '<user id="123"><name>John</name><age>30</age></user>' }
94
// Output: { payload: { user: { $: { id: "123" }, name: ["John"], age: ["30"] } } }
95

96
// Input:  { payload: { user: { name: "John", age: 30 } } }
97
// Output: { payload: '<user><name>John</name><age>30</age></user>' }
98
```
99

100
### CSV Node
101

102
Parse CSV strings to arrays/objects and convert arrays back to CSV format with configurable delimiters and headers.
103

104
```javascript { .api }
105
/**
106
 * CSV node for CSV parsing and generation
107
 * Registers as node type: "csv"
108
 */
109
function CSVNode(config) {
110
    RED.nodes.createNode(this, config);
111
    
112
    // Configuration properties:
113
    // config.property - Property to convert (default: "payload")
114
    // config.sep - Field separator (default: ",")
115
    // config.quo - Quote character (default: '"')
116
    // config.esc - Escape character  
117
    // config.ret - Return format: "\\n" (newline), "\\r" (carriage return), etc.
118
    // config.temp - Column template/headers
119
    // config.skip - Lines to skip at start
120
    // config.hdrin - Include headers in input
121
    // config.hdrout - Include headers in output
122
    // config.multi - Multi-line mode
123
    // config.unescape - Unescape characters
124
}
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
// Parse CSV with headers to objects
131
{
132
    "property": "payload",
133
    "sep": ",",
134
    "quo": '"',
135
    "hdrin": true,
136
    "temp": "name,age,email",
137
    "ret": "\\n"
138
}
139

140
// Convert array to CSV with custom separator
141
{
142
    "property": "payload",
143
    "sep": ";", 
144
    "hdrout": true,
145
    "temp": "Name,Age,Email"
146
}
147

148
// Example transformations:
149
// Input:  { payload: "name,age\\nJohn,30\\nJane,25" }
150
// Output: { payload: [{name:"John",age:"30"},{name:"Jane",age:"25"}] }
151

152
// Input:  { payload: [{name:"John",age:30},{name:"Jane",age:25}] }
153
// Output: { payload: "name,age\\nJohn,30\\nJane,25" }
154
```
155

156
### HTML Node
157

158
Extract data from HTML using CSS selectors, similar to jQuery selection.
159

160
```javascript { .api }
161
/**
162
 * HTML node for HTML parsing with CSS selectors
163
 * Registers as node type: "html"
164
 */
165
function HTMLNode(config) {
166
    RED.nodes.createNode(this, config);
167
    
168
    // Configuration properties:
169
    // config.property - Property containing HTML (default: "payload")
170
    // config.outproperty - Output property (default: "payload")  
171
    // config.tag - CSS selector
172
    // config.ret - Return type: "html", "text", "attr"
173
    // config.as - Return as: "single", "multi"
174
}
175
```
176

177
**Usage Examples:**
178

179
```javascript
180
// Extract text from all paragraphs
181
{
182
    "property": "payload",
183
    "tag": "p",
184
    "ret": "text", 
185
    "as": "multi"
186
}
187

188
// Extract href attributes from links
189
{
190
    "property": "payload",
191
    "tag": "a",
192
    "ret": "attr",
193
    "as": "multi"
194
}
195

196
// Extract single element HTML
197
{
198
    "property": "payload", 
199
    "tag": "#content .title",
200
    "ret": "html",
201
    "as": "single"
202
}
203

204
// Example transformations:
205
// Input:  { payload: '<div><p>Hello</p><p>World</p></div>' }
206
// Selector: "p", ret: "text", as: "multi"  
207
// Output: { payload: ["Hello", "World"] }
208

209
// Input:  { payload: '<a href="/home">Home</a><a href="/about">About</a>' }
210
// Selector: "a", ret: "attr", as: "multi"
211
// Output: { payload: ["/home", "/about"] }
212
```
213

214
### YAML Node
215

216
Parse YAML strings to JavaScript objects and convert objects to YAML format.
217

218
```javascript { .api }
219
/**
220
 * YAML node for YAML parsing and generation
221
 * Registers as node type: "yaml"
222
 */
223
function YAMLNode(config) {
224
    RED.nodes.createNode(this, config);
225
    
226
    // Configuration properties:
227
    // config.property - Property to convert (default: "payload")
228
}
229
```
230

231
**Usage Examples:**
232

233
```javascript
234
// Parse YAML to object (auto-detect)
235
{
236
    "property": "payload"
237
}
238

239
// Example transformations:
240
// Input:  { payload: 'name: John\\nage: 30\\nhobbies:\\n  - reading\\n  - coding' }
241
// Output: { payload: { name: "John", age: 30, hobbies: ["reading", "coding"] } }
242

243
// Input:  { payload: { name: "John", age: 30, active: true } }
244
// Output: { payload: 'name: John\\nage: 30\\nactive: true\\n' }
245
```
246

247
## Common Processing Patterns
248

249
All parser nodes follow similar message processing patterns:
250

251
```javascript { .api }
252
// Standard parser node input handler
253
this.on("input", function(msg, send, done) {
254
    try {
255
        var property = RED.util.getMessageProperty(msg, config.property || "payload");
256
        var result;
257
        
258
        // Determine conversion direction (auto-detect or configured)
259
        if (shouldParseToObject(property, config)) {
260
            result = parseToObject(property);
261
        } else {
262
            result = convertToString(property);
263
        }
264
        
265
        // Set result back to message
266
        RED.util.setMessageProperty(msg, config.outproperty || config.property || "payload", result);
267
        
268
        send(msg);
269
        done();
270
    } catch (error) {
271
        done(error);
272
    }
273
});
274
```
275

276
## Error Handling
277

278
Parser nodes handle various error conditions:
279

280
```javascript { .api }
281
// Common error scenarios handled by parser nodes:
282

283
// Invalid JSON
284
// Input:  { payload: '{"invalid": json}' }
285
// Result: Error message sent to catch nodes
286

287
// Invalid XML  
288
// Input:  { payload: '<unclosed><tag>' }
289
// Result: Error with parsing details
290

291
// CSV parsing errors
292
// Input:  { payload: 'unclosed,"quote' }
293
// Result: Error indicating malformed CSV
294

295
// HTML selector errors
296
// Input:  Invalid CSS selector syntax
297
// Result: Error with selector details
298

299
// YAML parsing errors
300
// Input:  { payload: 'invalid: yaml: structure:' }
301
// Result: Error with line/column information
302
```
303

304
## Advanced Configuration
305

306
### CSV Advanced Options
307

308
```javascript
309
// Complex CSV configuration
310
{
311
    "sep": ",",              // Field separator
312
    "quo": '"',              // Quote character  
313
    "esc": "\\",             // Escape character
314
    "ret": "\\n",            // Line ending
315
    "skip": 2,               // Skip first 2 lines
316
    "hdrin": true,           // First line contains headers
317
    "hdrout": true,          // Include headers in output
318
    "multi": true,           // Handle multi-line fields
319
    "unescape": true,        // Unescape characters
320
    "temp": "Name,Age,City"  // Column template
321
}
322
```
323

324
### XML Advanced Options
325

326
```javascript
327
// Custom XML parsing configuration
328
{
329
    "attr": "@",             // Attribute prefix
330
    "chr": "#text",          // Text content key
331
    "action": "obj"          // Force conversion direction
332
}
333
```
334

335
### HTML Selector Examples
336

337
```javascript
338
// Advanced CSS selectors
339
{
340
    "tag": "table tr:nth-child(2n) td.price",  // Even table rows, price cells
341
    "ret": "text"
342
}
343

344
{
345
    "tag": "div[data-type='product'] .title",   // Products with title class
346
    "ret": "html"
347
}
348

349
{
350
    "tag": "img",                               // All images
351
    "ret": "attr",                              // Get src attributes
352
    "as": "multi"
353
}
354
```
355

356
## Data Type Conversions
357

358
Parser nodes handle various data type conversions automatically:
359

360
```javascript { .api }
361
// Automatic type detection and conversion
362
interface TypeConversion {
363
    // String to Object parsing
364
    jsonString: string → object;
365
    xmlString: string → object;  
366
    csvString: string → Array<object>;
367
    yamlString: string → object;
368
    
369
    // Object to String generation  
370
    object → jsonString: string;
371
    object → xmlString: string;
372
    Array<object> → csvString: string;
373
    object → yamlString: string;
374
    
375
    // HTML extraction
376
    htmlString + selector → Array<string> | string;
377
}
378
```