0
# Apache Groovy
1

2
Apache Groovy is a powerful, optionally typed and dynamic language, with static-typing and static compilation capabilities, for the Java platform aimed at improving developer productivity thanks to a concise, familiar and easy to learn syntax. It integrates smoothly with any Java program, and immediately delivers to your application powerful features, including scripting capabilities, Domain-Specific Language authoring, runtime and compile-time meta-programming and functional programming.
3

4
## Package Information
5

6
- **Package Name**: org.apache.groovy:groovy
7
- **Package Type**: maven
8
- **Language**: Groovy/Java
9
- **Installation**: Add to Maven `pom.xml`: `<groupId>org.apache.groovy</groupId><artifactId>groovy</artifactId><version>5.0.0</version>`
10
- **Gradle**: `implementation 'org.apache.groovy:groovy:5.0.0'`
11

12
## Core Imports
13

14
```groovy
15
import groovy.lang.*
16
import groovy.util.*
17
```
18

19
For Java interop:
20
```java
21
import groovy.lang.GroovyShell;
22
import groovy.lang.Binding;
23
import groovy.lang.Script;
24
```
25

26
## Basic Usage
27

28
```groovy
29
// Simple script execution
30
def shell = new GroovyShell()
31
def result = shell.evaluate("2 + 2")
32
println result // 4
33

34
// Using closures
35
def multiply = { a, b -> a * b }
36
println multiply(3, 4) // 12
37

38
// Collections and ranges
39
def numbers = [1, 2, 3, 4, 5]
40
def evens = numbers.findAll { it % 2 == 0 }
41
println evens // [2, 4]
42

43
def range = 1..10
44
println range.collect { it * 2 } // [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
45
```
46

47
## Architecture
48

49
Apache Groovy is built around several key components:
50

51
- **Runtime System**: Core language execution engine with dynamic method dispatch and meta-programming
52
- **Script Engine**: Evaluation and compilation of Groovy scripts and expressions
53
- **Meta-Object Protocol**: Comprehensive meta-programming capabilities through MetaClass system
54
- **Extension Modules**: Modular APIs for JSON, XML, SQL, templates, CLI, and more
55
- **AST Transformations**: Compile-time code generation and enhancement
56
- **Java Integration**: Seamless interoperability with existing Java code and libraries
57

58
## Capabilities
59

60
### Core Language Runtime
61

62
Essential classes for the Groovy runtime including dynamic objects, closures, scripts, and the meta-programming system.
63

64
```groovy { .api }
65
// Core interfaces and classes
66
interface GroovyObject {
67
    Object invokeMethod(String name, Object args)
68
    Object getProperty(String propertyName)
69
    void setProperty(String propertyName, Object newValue)
70
    MetaClass getMetaClass()
71
    void setMetaClass(MetaClass metaClass)
72
}
73

74
abstract class Script extends GroovyObjectSupport {
75
    abstract Object run()
76
    Binding getBinding()
77
    void setBinding(Binding binding)
78
}
79

80
abstract class Closure<V> extends GroovyObjectSupport {
81
    V call(Object... args)
82
    Closure<V> curry(Object... args)
83
    Closure<V> memoize()
84
}
85
```
86

87
[Core Language Runtime](./core-runtime.md)
88

89
### Script Execution and Evaluation
90

91
High-level APIs for evaluating Groovy code, managing bindings, and creating reusable scripts.
92

93
```groovy { .api }
94
class GroovyShell {
95
    GroovyShell()
96
    GroovyShell(Binding binding)
97
    Object evaluate(String scriptText)
98
    Object evaluate(File file)
99
    Script parse(String scriptText)
100
    Class parseClass(String text)
101
}
102

103
class Binding {
104
    Object getVariable(String name)
105
    void setVariable(String name, Object value)
106
    Map getVariables()
107
}
108
```
109

110
[Script Execution](./script-execution.md)
111

112
### Meta-Programming System
113

114
Comprehensive meta-programming capabilities for runtime method and property manipulation.
115

116
```groovy { .api }
117
interface MetaClass {
118
    Object invokeMethod(Object object, String methodName, Object[] arguments)
119
    Object getProperty(Object object, String property)
120
    void setProperty(Object object, String property, Object newValue)
121
    List<MetaMethod> getMethods()
122
    List<MetaProperty> getProperties()
123
}
124

125
class ExpandoMetaClass extends MetaClassImpl {
126
    // Allows dynamic addition of methods and properties at runtime
127
}
128
```
129

130
[Meta-Programming](./meta-programming.md)
131

132
### Collections and Utilities
133

134
Enhanced collection operations, builder patterns, configuration management, and utility classes.
135

136
```groovy { .api }
137
class Expando extends GroovyObjectSupport {
138
    // Dynamic object that allows adding properties and methods at runtime
139
}
140

141
abstract class BuilderSupport {
142
    protected abstract Object createNode(Object name)
143
    protected abstract Object createNode(Object name, Object value)
144
    protected abstract Object createNode(Object name, Map attributes)
145
}
146

147
class ConfigObject implements Map<String, Object> {
148
    // Configuration object supporting hierarchical properties
149
}
150
```
151

152
[Collections and Utilities](./collections-utilities.md)
153

154
### JSON Processing
155

156
Complete JSON parsing and generation with builder patterns and streaming support.
157

158
```groovy { .api }
159
class JsonSlurper {
160
    Object parseText(String text)
161
    Object parse(Reader reader)
162
    Object parse(File file)
163
}
164

165
class JsonBuilder {
166
    Object call(Closure closure)
167
    String toString()
168
    String toPrettyString()
169
}
170

171
class JsonOutput {
172
    static String toJson(Object object)
173
    static String prettyPrint(String jsonPayload)
174
}
175
```
176

177
[JSON Processing](./json-processing.md)
178

179
### XML Processing
180

181
Comprehensive XML parsing, building, and manipulation with GPath expressions.
182

183
```groovy { .api }
184
class XmlSlurper {
185
    Object parseText(String text)
186
    Object parse(File file)
187
    Object parse(Reader reader)
188
}
189

190
class MarkupBuilder extends BuilderSupport {
191
    // Builder for creating XML/HTML markup
192
}
193

194
class XmlParser {
195
    Node parseText(String text)
196
    Node parse(File file)
197
    Node parse(Reader reader)
198
}
199
```
200

201
[XML Processing](./xml-processing.md)
202

203
### SQL Database Access
204

205
Database operations with enhanced result sets and fluent query building.
206

207
```groovy { .api }
208
class Sql {
209
    static Sql newInstance(String url, String user, String password, String driver)
210
    void eachRow(String sql, Closure closure)
211
    List<GroovyRowResult> rows(String sql)
212
    int executeUpdate(String sql)
213
    boolean execute(String sql)
214
    void call(String sql, Closure closure)
215
}
216

217
class DataSet {
218
    void each(Closure closure)
219
    DataSet findAll(Closure closure)
220
    void add(Map<String, Object> values)
221
}
222
```
223

224
[SQL Database Access](./sql-database.md)
225

226
### Template Processing
227

228
Template engines for code generation and text processing.
229

230
```groovy { .api }
231
class SimpleTemplateEngine {
232
    Template createTemplate(String text)
233
    Template createTemplate(Reader reader)
234
}
235

236
class StreamingTemplateEngine {
237
    Template createTemplate(String text)
238
    Template createTemplate(Reader reader)
239
}
240
```
241

242
[Template Processing](./template-processing.md)
243

244
### Command-Line Interface
245

246
CLI building and option parsing utilities.
247

248
```groovy { .api }
249
class CliBuilder {
250
    OptionAccessor parse(String[] args)
251
    void usage()
252
}
253

254
class OptionAccessor {
255
    // Accessor for parsed command-line options
256
}
257
```
258

259
[Command-Line Interface](./cli-interface.md)
260

261
## Types
262

263
```groovy { .api }
264
// Core range types
265
interface Range<T extends Comparable> {
266
    boolean contains(Object o)
267
    T getFrom()
268
    T getTo()
269
    boolean isReverse()
270
}
271

272
class IntRange implements Range<Integer> {
273
    // Integer range implementation (e.g., 1..10)
274
}
275

276
// String interpolation
277
abstract class GString extends GroovyObjectSupport {
278
    String toString()
279
    Object[] getValues()
280
    String[] getStrings()
281
}
282

283
// Tuple types
284
class Tuple extends Object {
285
    // Base class for immutable tuples
286
}
287

288
// Utility types
289
class MapEntry<K, V> implements Map.Entry<K, V> {
290
    K getKey()
291
    V getValue()
292
    V setValue(V value)
293
}
294
```