0
# Core Language Runtime
1

2
Essential classes for the Groovy runtime including dynamic objects, closures, scripts, and the core language features that enable Groovy's dynamic behavior.
3

4
## Capabilities
5

6
### GroovyObject Interface
7

8
The fundamental interface that all Groovy objects implement, providing the foundation for dynamic method dispatch and property access.
9

10
```groovy { .api }
11
/**
12
 * Core interface that all Groovy objects implement, providing meta-programming capabilities
13
 */
14
interface GroovyObject {
15
    /** Invoke a method dynamically by name */
16
    Object invokeMethod(String name, Object args)
17
    
18
    /** Get a property value dynamically by name */
19
    Object getProperty(String propertyName)
20
    
21
    /** Set a property value dynamically by name */
22
    void setProperty(String propertyName, Object newValue)
23
    
24
    /** Get the MetaClass for this object */
25
    MetaClass getMetaClass()
26
    
27
    /** Set the MetaClass for this object */
28
    void setMetaClass(MetaClass metaClass)
29
}
30
```
31

32
### GroovyObject Support
33

34
Base implementation providing default behavior for GroovyObject.
35

36
```groovy { .api }
37
/**
38
 * Base implementation of GroovyObject providing default behavior
39
 */
40
abstract class GroovyObjectSupport implements GroovyObject {
41
    // Default implementations for GroovyObject methods
42
}
43
```
44

45
### Script Base Class
46

47
Base class for all Groovy scripts, providing execution context and variable binding.
48

49
```groovy { .api }
50
/**
51
 * Base class for all Groovy scripts
52
 */
53
abstract class Script extends GroovyObjectSupport {
54
    /** Execute the script and return the result */
55
    abstract Object run()
56
    
57
    /** Get a property (variable) from the script binding */
58
    Object getProperty(String property)
59
    
60
    /** Set a property (variable) in the script binding */
61
    void setProperty(String property, Object newValue)
62
    
63
    /** Get the variable binding context */
64
    Binding getBinding()
65
    
66
    /** Set the variable binding context */
67
    void setBinding(Binding binding)
68
}
69
```
70

71
### Closure Class
72

73
Represents closures - executable code blocks that can capture variables from their surrounding scope.
74

75
```groovy { .api }
76
/**
77
 * Represents closures in Groovy - executable code blocks
78
 */
79
abstract class Closure<V> extends GroovyObjectSupport {
80
    /** Call the closure with the given arguments */
81
    V call(Object... args)
82
    
83
    /** Call the closure with no arguments */
84
    V call()
85
    
86
    /** Create a curried closure by fixing some arguments */
87
    Closure<V> curry(Object... args)
88
    
89
    /** Create an n-curried closure fixing arguments from position n */
90
    Closure<V> ncurry(int n, Object... args)
91
    
92
    /** Create a right-curried closure fixing arguments from the right */
93
    Closure<V> rcurry(Object... args)
94
    
95
    /** Create a memoized version that caches results */
96
    Closure<V> memoize()
97
    
98
    /** Create a trampolined closure for tail recursion optimization */
99
    Closure<V> trampoline()
100
}
101
```
102

103
**Usage Examples:**
104

105
```groovy
106
// Basic closure usage
107
def multiply = { a, b -> a * b }
108
println multiply(3, 4) // 12
109

110
// Closure with single parameter (implicit 'it')
111
def square = { it * it }
112
println square(5) // 25
113

114
// Currying
115
def add = { a, b -> a + b }
116
def addFive = add.curry(5)
117
println addFive(3) // 8
118

119
// Memoization for expensive operations
120
def fibonacci
121
fibonacci = { n ->
122
    n <= 1 ? n : fibonacci(n-1) + fibonacci(n-2)
123
}.memoize()
124
```
125

126
### GString (Interpolated Strings)
127

128
Groovy's interpolated string implementation allowing embedded expressions.
129

130
```groovy { .api }
131
/**
132
 * Groovy's interpolated string implementation
133
 */
134
abstract class GString extends GroovyObjectSupport {
135
    /** Convert to regular String */
136
    String toString()
137
    
138
    /** Get the interpolated values */
139
    Object[] getValues()
140
    
141
    /** Get the string parts (between interpolations) */
142
    String[] getStrings()
143
}
144
```
145

146
**Usage Examples:**
147

148
```groovy
149
def name = "World"
150
def count = 42
151
def message = "Hello $name, count is ${count * 2}"
152
println message // "Hello World, count is 84"
153

154
// Multiline GStrings
155
def sql = """
156
    SELECT * FROM users 
157
    WHERE name = '$name' 
158
    AND age > ${count}
159
"""
160
```
161

162
### Range Types
163

164
Range implementations for sequences and iterations.
165

166
```groovy { .api }
167
/**
168
 * Interface for range types (e.g., 1..10)
169
 */
170
interface Range<T extends Comparable> {
171
    /** Check if the range contains the given object */
172
    boolean contains(Object o)
173
    
174
    /** Get the start value of the range */
175
    T getFrom()
176
    
177
    /** Get the end value of the range */
178
    T getTo()
179
    
180
    /** Check if this is a reverse range */
181
    boolean isReverse()
182
}
183

184
/**
185
 * Integer range implementation
186
 */
187
class IntRange implements Range<Integer> {
188
    IntRange(int from, int to)
189
    IntRange(Integer from, Integer to)
190
}
191

192
/**
193
 * Generic object range implementation
194
 */
195
class ObjectRange implements Range<Comparable> {
196
    ObjectRange(Comparable from, Comparable to)
197
}
198
```
199

200
**Usage Examples:**
201

202
```groovy
203
// Integer ranges
204
def range1 = 1..5      // inclusive range: 1, 2, 3, 4, 5
205
def range2 = 1..<5     // exclusive range: 1, 2, 3, 4
206
def range3 = 5..1      // reverse range: 5, 4, 3, 2, 1
207

208
// Iteration
209
(1..3).each { println it }  // prints 1, 2, 3
210

211
// Collection operations
212
def squares = (1..5).collect { it * it }  // [1, 4, 9, 16, 25]
213

214
// Character ranges
215
('a'..'d').each { print it }  // prints abcd
216
```
217

218
### System Utilities
219

220
System-level Groovy operations and information.
221

222
```groovy { .api }
223
/**
224
 * System-level Groovy operations and information
225
 */
226
class GroovySystem {
227
    /** Get the Groovy version */
228
    static String getVersion()
229
    
230
    /** Get the global MetaClass registry */
231
    static MetaClassRegistry getMetaClassRegistry()
232
}
233
```
234

235
### Exception Types
236

237
Core exception classes for Groovy runtime errors.
238

239
```groovy { .api }
240
/**
241
 * Base runtime exception for Groovy
242
 */
243
class GroovyRuntimeException extends RuntimeException {
244
    GroovyRuntimeException(String message)
245
    GroovyRuntimeException(String message, Throwable cause)
246
}
247

248
/**
249
 * Thrown when a method cannot be found
250
 */
251
class MissingMethodException extends GroovyRuntimeException {
252
    MissingMethodException(String method, Class type, Object[] arguments)
253
}
254

255
/**
256
 * Thrown when a property cannot be found
257
 */
258
class MissingPropertyException extends GroovyRuntimeException {
259
    MissingPropertyException(String property, Class type)
260
}
261

262
/**
263
 * Thrown when attempting to modify a read-only property
264
 */
265
class ReadOnlyPropertyException extends GroovyRuntimeException {
266
    ReadOnlyPropertyException(String property, Class clazz)
267
}
268
```
269

270
## Tuple Classes
271

272
Immutable tuple implementations for structured data.
273

274
```groovy { .api }
275
/**
276
 * Base class for tuples
277
 */
278
class Tuple {
279
    // Base functionality for all tuple types
280
}
281

282
/**
283
 * Tuple with two elements
284
 */
285
class Tuple2<T1, T2> extends Tuple {
286
    T1 getV1()
287
    T2 getV2()
288
}
289

290
/**
291
 * Tuple with three elements  
292
 */
293
class Tuple3<T1, T2, T3> extends Tuple {
294
    T1 getV1()
295
    T2 getV2()
296
    T3 getV3()
297
}
298

299
// Additional tuple classes: Tuple0 through Tuple16
300
```
301

302
**Usage Examples:**
303

304
```groovy
305
def pair = new Tuple2("hello", 42)
306
println pair.v1  // "hello"
307
println pair.v2  // 42
308

309
def triple = new Tuple3("name", 25, true)
310
println "${triple.v1} is ${triple.v2} years old, active: ${triple.v3}"
311
```
312

313
### Writable Interface
314

315
Interface for objects that can efficiently write themselves to text streams, particularly useful for templates and large content generation.
316

317
```groovy { .api }
318
/**
319
 * Interface for objects that can write themselves to a text stream
320
 */
321
interface Writable {
322
    /** 
323
     * Write this object to the given writer 
324
     * @param out the Writer to output data to
325
     * @return the Writer that was passed
326
     */
327
    Writer writeTo(Writer out) throws IOException
328
}
329
```
330

331
**Usage Examples:**
332

333
```groovy
334
// Creating a custom Writable
335
class MyContent implements Writable {
336
    String data
337
    
338
    Writer writeTo(Writer out) {
339
        out.write("Content: ${data}")
340
        return out
341
    }
342
}
343

344
def content = new MyContent(data: "Hello World")
345
def writer = new StringWriter()
346
content.writeTo(writer)
347
println writer.toString() // "Content: Hello World"
348
```
349

350
### Interceptor Interface
351

352
Interface for intercepting method calls on objects managed by ProxyMetaClass, enabling AOP-style programming.
353

354
```groovy { .api }
355
/**
356
 * Interface for intercepting method calls
357
 */
358
interface Interceptor {
359
    /** 
360
     * Called before method execution
361
     * @param object receiver object
362
     * @param methodName name of method to call
363
     * @param arguments method arguments
364
     * @return arbitrary result that may replace original method result
365
     */
366
    Object beforeInvoke(Object object, String methodName, Object[] arguments)
367
    
368
    /** 
369
     * Called after method execution
370
     * @param object receiver object
371
     * @param methodName name of called method
372
     * @param arguments method arguments
373
     * @param result result of method call or beforeInvoke
374
     * @return arbitrary result that can replace original method result
375
     */
376
    Object afterInvoke(Object object, String methodName, Object[] arguments, Object result)
377
    
378
    /** 
379
     * @return whether the target method should be invoked at all
380
     */
381
    boolean doInvoke()
382
}
383
```
384

385
**Usage Examples:**
386

387
```groovy
388
// Logging interceptor
389
class LoggingInterceptor implements Interceptor {
390
    Object beforeInvoke(Object object, String methodName, Object[] arguments) {
391
        println "Before calling ${methodName} on ${object.class.name}"
392
        return null
393
    }
394
    
395
    Object afterInvoke(Object object, String methodName, Object[] arguments, Object result) {
396
        println "After calling ${methodName}, result: ${result}"
397
        return result
398
    }
399
    
400
    boolean doInvoke() { return true }
401
}
402
```
403

404
### Property Access Interceptor
405

406
Specialized interceptor for property access operations.
407

408
```groovy { .api }
409
/**
410
 * Interface for intercepting property access
411
 */
412
interface PropertyAccessInterceptor extends Interceptor {
413
    /** 
414
     * Called before getting a property
415
     * @param object the receiver object
416
     * @param property the property name
417
     */
418
    Object beforeGet(Object object, String property)
419
    
420
    /** 
421
     * Called before setting a property
422
     * @param object the receiver object
423
     * @param property the property name
424
     * @param newValue the new property value
425
     */
426
    Object beforeSet(Object object, String property, Object newValue)
427
}
428
```