0
# Configuration and Data Processing
1

2
Configuration file parsing, XML processing, command-line interface building, and data structure utilities. These tools provide essential infrastructure for application configuration, data transformation, and user interface components.
3

4
## Capabilities
5

6
### Configuration Parsing
7

8
ConfigSlurper provides a flexible way to parse configuration files written in Groovy syntax.
9

10
```java { .api }
11
class ConfigSlurper {
12
    /**
13
     * Creates a ConfigSlurper with no environment set.
14
     */
15
    ConfigSlurper();
16
    
17
    /**
18
     * Creates a ConfigSlurper for the specified environment.
19
     */
20
    ConfigSlurper(String environment);
21
    
22
    /**
23
     * Parses configuration from a string.
24
     */
25
    ConfigObject parse(String text);
26
    
27
    /**
28
     * Parses configuration from a URL.
29
     */
30
    ConfigObject parse(URL location);
31
    
32
    /**
33
     * Parses configuration from a file.
34
     */
35
    ConfigObject parse(File file);
36
    
37
    /**
38
     * Parses configuration from a Reader.
39
     */
40
    ConfigObject parse(Reader reader);
41
    
42
    /**
43
     * Parses configuration from a Properties object.
44
     */
45
    ConfigObject parse(Properties properties);
46
    
47
    /**
48
     * Sets the environment for conditional configuration.
49
     */
50
    void setEnvironment(String environment);
51
    
52
    /**
53
     * Gets the current environment.
54
     */
55
    String getEnvironment();
56
    
57
    /**
58
     * Sets the binding for the configuration script.
59
     */
60
    void setBinding(Binding binding);
61
    
62
    /**
63
     * Gets the binding for the configuration script.
64
     */
65
    Binding getBinding();
66
}
67

68
class ConfigObject extends LinkedHashMap<String, Object> implements Writable {
69
    /**
70
     * Creates an empty ConfigObject.
71
     */
72
    ConfigObject();
73
    
74
    /**
75
     * Flattens nested configuration into dot-separated keys.
76
     */
77
    ConfigObject flatten();
78
    
79
    /**
80
     * Flattens with a custom key separator.
81
     */
82
    ConfigObject flatten(String separator);
83
    
84
    /**
85
     * Merges another ConfigObject into this one.
86
     */
87
    ConfigObject merge(ConfigObject other);
88
    
89
    /**
90
     * Converts to Properties object.
91
     */
92
    Properties toProperties();
93
    
94
    /**
95
     * Converts to Properties with a prefix.
96
     */
97
    Properties toProperties(String prefix);
98
    
99
    /**
100
     * Writes the configuration to a Writer.
101
     */
102
    Writer writeTo(Writer writer);
103
    
104
    /**
105
     * Checks if this ConfigObject is empty of meaningful values.
106
     */
107
    boolean isEmpty();
108
    
109
    /**
110
     * Gets a nested value using dot notation.
111
     */
112
    Object getProperty(String key);
113
    
114
    /**
115
     * Sets a nested value using dot notation.
116
     */
117
    void setProperty(String key, Object value);
118
}
119
```
120

121
### Command Line Interface Building
122

123
CliBuilder provides a fluent API for parsing command line arguments.
124

125
```java { .api }
126
class CliBuilder {
127
    /**
128
     * Creates a CliBuilder with default settings.
129
     */
130
    CliBuilder();
131
    
132
    /**
133
     * Creates a CliBuilder with usage text.
134
     */
135
    CliBuilder(String usage);
136
    
137
    /**
138
     * Defines a command line option.
139
     */
140
    void addOption(String opt, String longOpt, boolean hasArg, String description);
141
    
142
    /**
143
     * Defines an option using builder pattern.
144
     */
145
    OptionBuilder option(String opt);
146
    
147
    /**
148
     * Defines an option with short name only.
149
     */
150
    void opt(String name, String description);
151
    
152
    /**
153
     * Defines an option with argument.
154
     */
155
    void opt(String name, String argName, String description);
156
    
157
    /**
158
     * Defines an option with long name.
159
     */
160
    void opt(String name, String longName, String description);
161
    
162
    /**
163
     * Parses command line arguments.
164
     */
165
    OptionAccessor parse(String[] args);
166
    
167
    /**
168
     * Parses command line arguments with error handling.
169
     */
170
    OptionAccessor parse(String[] args, boolean stopAtNonOption);
171
    
172
    /**
173
     * Prints usage information.
174
     */
175
    void usage();
176
    
177
    /**
178
     * Gets the usage formatter.
179
     */
180
    HelpFormatter getFormatter();
181
    
182
    /**
183
     * Sets the usage formatter.
184
     */
185
    void setFormatter(HelpFormatter formatter);
186
    
187
    /**
188
     * Sets the header text for usage.
189
     */
190
    void setHeader(String header);
191
    
192
    /**
193
     * Sets the footer text for usage.
194
     */
195
    void setFooter(String footer);
196
    
197
    /**
198
     * Sets the program name for usage.
199
     */
200
    void setProgramName(String programName);
201
}
202

203
interface OptionAccessor {
204
    /**
205
     * Checks if an option was provided.
206
     */
207
    boolean hasOption(String opt);
208
    
209
    /**
210
     * Gets the value of an option.
211
     */
212
    String getOptionValue(String opt);
213
    
214
    /**
215
     * Gets the value of an option with default.
216
     */
217
    String getOptionValue(String opt, String defaultValue);
218
    
219
    /**
220
     * Gets all values for a multi-value option.
221
     */
222
    String[] getOptionValues(String opt);
223
    
224
    /**
225
     * Gets the list of non-option arguments.
226
     */
227
    List<?> getArgList();
228
    
229
    /**
230
     * Gets non-option arguments as array.
231
     */
232
    String[] getArgs();
233
    
234
    /**
235
     * Gets all option properties as a Properties object.
236
     */
237
    Properties getOptionProperties(String opt);
238
}
239
```
240

241
### XML Parsing and Navigation
242

243
XmlSlurper provides GPath-based XML parsing and navigation.
244

245
```java { .api }
246
class XmlSlurper {
247
    /**
248
     * Creates an XmlSlurper with default settings.
249
     */
250
    XmlSlurper();
251
    
252
    /**
253
     * Creates an XmlSlurper with validation enabled/disabled.
254
     */
255
    XmlSlurper(boolean validating);
256
    
257
    /**
258
     * Creates an XmlSlurper with validation and namespace awareness.
259
     */
260
    XmlSlurper(boolean validating, boolean namespaceAware);
261
    
262
    /**
263
     * Parses XML from a string.
264
     */
265
    GPathResult parseText(String text);
266
    
267
    /**
268
     * Parses XML from a file.
269
     */
270
    GPathResult parse(File file);
271
    
272
    /**
273
     * Parses XML from a URL.
274
     */
275
    GPathResult parse(URL url);
276
    
277
    /**
278
     * Parses XML from an InputStream.
279
     */
280
    GPathResult parse(InputStream input);
281
    
282
    /**
283
     * Parses XML from a Reader.
284
     */
285
    GPathResult parse(Reader reader);
286
    
287
    /**
288
     * Sets the XML parser to use.
289
     */
290
    void setXMLReader(XMLReader reader);
291
    
292
    /**
293
     * Gets the XML parser being used.
294
     */
295
    XMLReader getXMLReader();
296
    
297
    /**
298
     * Sets an entity resolver.
299
     */
300
    void setEntityResolver(EntityResolver resolver);
301
    
302
    /**
303
     * Sets an error handler.
304
     */
305
    void setErrorHandler(ErrorHandler handler);
306
}
307

308
abstract class GPathResult implements Iterable<GPathResult>, Writable {
309
    /**
310
     * Gets the text content of this node.
311
     */
312
    String text();
313
    
314
    /**
315
     * Gets the number of child nodes.
316
     */
317
    int size();
318
    
319
    /**
320
     * Checks if this result is empty.
321
     */
322
    boolean isEmpty();
323
    
324
    /**
325
     * Gets all child nodes.
326
     */
327
    GPathResult children();
328
    
329
    /**
330
     * Gets the parent node.
331
     */
332
    GPathResult parent();
333
    
334
    /**
335
     * Finds child nodes matching the closure condition.
336
     */
337
    GPathResult find(Closure closure);
338
    
339
    /**
340
     * Finds all child nodes matching the closure condition.
341
     */
342
    GPathResult findAll(Closure closure);
343
    
344
    /**
345
     * Gets an attribute value.
346
     */
347
    String attribute(String name);
348
    
349
    /**
350
     * Gets all attributes.
351
     */
352
    Map<String, String> attributes();
353
    
354
    /**
355
     * Gets the local name of this node.
356
     */
357
    String name();
358
    
359
    /**
360
     * Gets the namespace URI of this node.
361
     */
362
    String namespaceURI();
363
    
364
    /**
365
     * Converts to a Node object.
366
     */
367
    Node convertToNode();
368
    
369
    /**
370
     * Gets child by index.
371
     */
372
    GPathResult getAt(int index);
373
    
374
    /**
375
     * Gets child by name.
376
     */
377
    GPathResult getProperty(String name);
378
}
379
```
380

381
### Tree-based XML Parsing
382

383
XmlParser creates Node trees for XML processing.
384

385
```java { .api }
386
class XmlParser {
387
    /**
388
     * Creates an XmlParser with default settings.
389
     */
390
    XmlParser();
391
    
392
    /**
393
     * Creates an XmlParser with validation enabled/disabled.
394
     */
395
    XmlParser(boolean validating);
396
    
397
    /**
398
     * Creates an XmlParser with validation and namespace awareness.
399
     */
400
    XmlParser(boolean validating, boolean namespaceAware);
401
    
402
    /**
403
     * Parses XML from a string.
404
     */
405
    Node parseText(String text);
406
    
407
    /**
408
     * Parses XML from a file.
409
     */
410
    Node parse(File file);
411
    
412
    /**
413
     * Parses XML from a URL.
414
     */
415
    Node parse(URL url);
416
    
417
    /**
418
     * Parses XML from an InputStream.
419
     */
420
    Node parse(InputStream input);
421
    
422
    /**
423
     * Parses XML from a Reader.
424
     */
425
    Node parse(Reader reader);
426
    
427
    /**
428
     * Sets trimming of whitespace-only text nodes.
429
     */
430
    void setTrimWhitespace(boolean trimWhitespace);
431
    
432
    /**
433
     * Gets whether whitespace-only text nodes are trimmed.
434
     */
435
    boolean isTrimWhitespace();
436
    
437
    /**
438
     * Sets whether to keep ignorable whitespace.
439
     */
440
    void setKeepIgnorableWhitespace(boolean keepIgnorableWhitespace);
441
}
442
```
443

444
### Node Tree Structure
445

446
Node represents XML elements in a tree structure.
447

448
```java { .api }
449
class Node implements Serializable {
450
    /**
451
     * Creates a Node with the given name.
452
     */
453
    Node(String name);
454
    
455
    /**
456
     * Creates a Node with name and value.
457
     */
458
    Node(String name, Object value);
459
    
460
    /**
461
     * Creates a Node with name and attributes.
462
     */
463
    Node(String name, Map<String, String> attributes);
464
    
465
    /**
466
     * Creates a Node with name, attributes, and value.
467
     */
468
    Node(String name, Map<String, String> attributes, Object value);
469
    
470
    /**
471
     * Gets the name of this node.
472
     */
473
    Object name();
474
    
475
    /**
476
     * Gets the value of this node.
477
     */
478
    Object value();
479
    
480
    /**
481
     * Sets the value of this node.
482
     */
483
    void setValue(Object value);
484
    
485
    /**
486
     * Gets the attributes of this node.
487
     */
488
    Map<String, String> attributes();
489
    
490
    /**
491
     * Gets an attribute value.
492
     */
493
    Object attribute(String key);
494
    
495
    /**
496
     * Gets all child nodes.
497
     */
498
    List<Node> children();
499
    
500
    /**
501
     * Gets the parent node.
502
     */
503
    Node parent();
504
    
505
    /**
506
     * Gets the text content of this node.
507
     */
508
    String text();
509
    
510
    /**
511
     * Gets child nodes with the given name.
512
     */
513
    NodeList get(String key);
514
    
515
    /**
516
     * Gets child node at the given index.
517
     */
518
    Object get(int index);
519
    
520
    /**
521
     * Appends a child node.
522
     */
523
    Node append(Node child);
524
    
525
    /**
526
     * Removes a child node.
527
     */
528
    boolean remove(Node child);
529
    
530
    /**
531
     * Adds a child node.
532
     */
533
    void add(Node child);
534
    
535
    /**
536
     * Replaces this node with another.
537
     */
538
    void replaceNode(Node replacement);
539
}
540

541
class NodeList extends ArrayList<Node> {
542
    /**
543
     * Gets the text content of all nodes.
544
     */
545
    String text();
546
    
547
    /**
548
     * Gets the local text content (direct children only).
549
     */
550
    List<String> localText();
551
    
552
    /**
553
     * Removes and returns the last element.
554
     */
555
    Node pop();
556
}
557
```
558

559
## Usage Examples
560

561
### Configuration File Parsing
562

563
```java
564
import groovy.util.ConfigSlurper;
565
import groovy.util.ConfigObject;
566

567
// Parse configuration from string
568
ConfigSlurper slurper = new ConfigSlurper("development");
569
String configText = """
570
    database {
571
        host = 'localhost'
572
        port = 5432
573
        username = 'admin'
574
    }
575
    
576
    environments {
577
        development {
578
            database.host = 'dev-server'
579
        }
580
        production {
581
            database.host = 'prod-server'
582
        }
583
    }
584
""";
585

586
ConfigObject config = slurper.parse(configText);
587
System.out.println("Database host: " + config.getProperty("database.host"));
588

589
// Flatten configuration
590
ConfigObject flattened = config.flatten();
591
Properties props = flattened.toProperties();
592
```
593

594
### Command Line Parsing
595

596
```java
597
import groovy.util.CliBuilder;
598
import groovy.util.OptionAccessor;
599

600
// Build command line parser
601
CliBuilder cli = new CliBuilder("myapp [options] files...");
602
cli.setHeader("My Application");
603

604
cli.addOption("h", "help", false, "Show usage information");
605
cli.addOption("v", "verbose", false, "Enable verbose output");
606
cli.addOption("o", "output", true, "Output file name");
607
cli.addOption("c", "config", true, "Configuration file");
608

609
// Parse arguments
610
String[] args = {"-v", "-o", "result.txt", "input1.txt", "input2.txt"};
611
OptionAccessor options = cli.parse(args);
612

613
if (options.hasOption("help")) {
614
    cli.usage();
615
    return;
616
}
617

618
boolean verbose = options.hasOption("verbose");
619
String outputFile = options.getOptionValue("output", "default.out");
620
List<?> inputFiles = options.getArgList();
621

622
System.out.println("Verbose: " + verbose);
623
System.out.println("Output: " + outputFile);
624
System.out.println("Input files: " + inputFiles);
625
```
626

627
### XML Processing with XmlSlurper
628

629
```java
630
import groovy.util.XmlSlurper;
631
import groovy.util.slurpersupport.GPathResult;
632

633
// Parse XML
634
XmlSlurper slurper = new XmlSlurper();
635
String xml = """
636
<catalog>
637
    <book id="1">
638
        <title>Groovy in Action</title>
639
        <author>Dierk König</author>
640
        <price>45.99</price>
641
    </book>
642
    <book id="2">
643
        <title>Programming Groovy</title>
644
        <author>Venkat Subramaniam</author>
645
        <price>39.99</price>
646
    </book>
647
</catalog>
648
""";
649

650
GPathResult catalog = slurper.parseText(xml);
651

652
// Navigate and extract data
653
System.out.println("Catalog has " + catalog.book.size() + " books");
654

655
for (GPathResult book : catalog.book) {
656
    String id = book.attribute("id");
657
    String title = book.title.text();
658
    String author = book.author.text();
659
    String price = book.price.text();
660
    
661
    System.out.println("Book " + id + ": " + title + " by " + author + " - $" + price);
662
}
663

664
// Find specific books
665
GPathResult expensiveBooks = catalog.book.findAll { book ->
666
    Double.parseDouble(book.price.text()) > 40.0;
667
};
668

669
System.out.println("Found " + expensiveBooks.size() + " expensive books");
670
```
671

672
### XML Processing with XmlParser
673

674
```java
675
import groovy.util.XmlParser;
676
import groovy.util.Node;
677
import groovy.util.NodeList;
678

679
// Parse XML into Node tree
680
XmlParser parser = new XmlParser();
681
Node catalog = parser.parseText(xml);
682

683
// Navigate using Node API
684
System.out.println("Root name: " + catalog.name());
685

686
NodeList books = catalog.get("book");
687
for (Node book : books) {
688
    Map<String, String> attrs = book.attributes();
689
    String id = attrs.get("id");
690
    
691
    String title = ((Node) book.get("title").get(0)).text();
692
    String author = ((Node) book.get("author").get(0)).text();
693
    
694
    System.out.println("Book " + id + ": " + title + " by " + author);
695
}
696
```