0
# Script Execution Engine
1

2
Core engine for executing Groovy code programmatically, managing variables and imports, providing code completion, and handling state persistence. The `GroovyEngine` serves as the primary programmatic interface for embedding Groovy REPL functionality in applications.
3

4
## Capabilities
5

6
### Code Execution
7

8
Execute Groovy statements, scripts, and closures with full error handling and result capture.
9

10
```groovy { .api }
11
/**
12
 * Execute a Groovy code statement
13
 * @param statement Groovy code as string
14
 * @return Execution result object
15
 */
16
Object execute(String statement)
17

18
/**
19
 * Execute a Groovy script file with arguments
20
 * @param script File containing Groovy script
21
 * @param args Arguments to pass to script
22
 * @return Execution result object
23
 */
24
Object execute(File script, Object[] args)
25

26
/**
27
 * Execute a Groovy closure with arguments
28
 * @param closure Groovy closure object
29
 * @param args Arguments to pass to closure
30
 * @return Closure execution result
31
 */
32
Object execute(Object closure, Object... args)
33
```
34

35
**Usage Examples:**
36

37
```groovy
38
import org.apache.groovy.groovysh.jline.GroovyEngine
39

40
GroovyEngine engine = new GroovyEngine()
41

42
// Execute simple expressions
43
Object result = engine.execute("2 + 2")
44
println result // 4
45

46
// Execute complex code
47
engine.execute("""
48
    def factorial(n) {
49
        n <= 1 ? 1 : n * factorial(n - 1)
50
    }
51
    factorial(5)
52
""")
53

54
// Execute script file
55
File script = new File("calculator.groovy")
56
Object result = engine.execute(script, [] as Object[])
57
```
58

59
### Variable Management
60

61
Manage variables in the engine's execution context with full lifecycle control.
62

63
```groovy { .api }
64
/**
65
 * Set a variable in the engine scope
66
 * @param name Variable name
67
 * @param value Variable value
68
 */
69
void put(String name, Object value)
70

71
/**
72
 * Get variable value from engine scope
73
 * @param name Variable name
74
 * @return Variable value or null if not found
75
 */
76
Object get(String name)
77

78
/**
79
 * Check if variable exists in engine scope
80
 * @param name Variable name
81
 * @return true if variable exists, false otherwise
82
 */
83
boolean hasVariable(String name)
84

85
/**
86
 * Find variables matching a pattern
87
 * @param name Pattern to match variable names (null returns all variables)
88
 * @return Map of variable names to values
89
 */
90
Map<String, Object> find(String name)
91

92
/**
93
 * Delete specified variables from engine scope
94
 * @param vars Variable names to delete
95
 */
96
void del(String... vars)
97
```
98

99
**Usage Examples:**
100

101
```groovy
102
GroovyEngine engine = new GroovyEngine()
103

104
// Set variables
105
engine.put("username", "alice")
106
engine.put("age", 25)
107
engine.put("active", true)
108

109
// Use variables in code
110
Object greeting = engine.execute("'Hello, ' + username")
111

112
// Check and retrieve variables
113
if (engine.hasVariable("age")) {
114
    Object userAge = engine.get("age")
115
    println "User age: $userAge"
116
}
117

118
// Find variables by pattern
119
Map<String, Object> userVars = engine.find("user*")
120

121
// Delete variables
122
engine.del("username", "age")
123
```
124

125
### State Management
126

127
Control the engine's execution state including buffer, imports, methods, and types.
128

129
```groovy { .api }
130
/**
131
 * Clear all state (imports, variables, methods, types)
132
 */
133
void reset()
134

135
/**
136
 * Get current script buffer content
137
 * @return Current buffer as string
138
 */
139
String getBuffer()
140

141
/**
142
 * Get all imports in the engine
143
 * @return Map of import names to definitions
144
 */
145
Map<String, String> getImports()
146

147
/**
148
 * Get all variables in the engine
149
 * @return Map of variable names to definitions
150
 */
151
Map<String, String> getVariables()
152

153
/**
154
 * Get all method definitions in the engine
155
 * @return Map of method signatures to definitions
156
 */
157
Map<String, String> getMethods()
158

159
/**
160
 * Get all type definitions in the engine
161
 * @return Map of type names to definitions
162
 */
163
Map<String, String> getTypes()
164

165
/**
166
 * Remove specific import statement
167
 * @param importStatement Import to remove
168
 */
169
void removeImport(String importStatement)
170

171
/**
172
 * Remove specific variable
173
 * @param variableName Variable to remove
174
 */
175
void removeVariable(String variableName)
176

177
/**
178
 * Remove specific method
179
 * @param methodName Method to remove
180
 */
181
void removeMethod(String methodName)
182

183
/**
184
 * Remove specific type
185
 * @param typeName Type to remove
186
 */
187
void removeType(String typeName)
188
```
189

190
**Usage Examples:**
191

192
```groovy
193
GroovyEngine engine = new GroovyEngine()
194

195
// Add some state
196
engine.execute("import java.util.Date")
197
engine.put("startTime", new Date())
198
engine.execute("def helper() { 'utility function' }")
199

200
// Inspect state
201
Map<String, String> imports = engine.getImports()
202
Map<String, String> variables = engine.getVariables()
203
Map<String, String> methods = engine.getMethods()
204

205
// Selective cleanup
206
engine.removeVariable("startTime")
207
engine.removeMethod("helper")
208

209
// Complete reset
210
engine.reset()
211
```
212

213
### Data Serialization
214

215
Handle data conversion and persistence with support for multiple formats.
216

217
```groovy { .api }
218
/**
219
 * Deserialize data from string representation
220
 * @param value Serialized data string
221
 * @param format Deserialization format (JSON, GROOVY, NONE)
222
 * @return Deserialized object
223
 */
224
Object deserialize(String value, String format)
225

226
/**
227
 * Persist object to file
228
 * @param file Target file path
229
 * @param object Object to persist
230
 */
231
void persist(Path file, Object object)
232

233
/**
234
 * Convert object to JSON string
235
 * @param obj Object to serialize
236
 * @return JSON representation
237
 */
238
String toJson(Object obj)
239

240
/**
241
 * Convert object to string representation
242
 * @param obj Object to convert
243
 * @return String representation
244
 */
245
String toString(Object obj)
246

247
/**
248
 * Convert object to map representation
249
 * @param obj Object to convert
250
 * @return Map representation
251
 */
252
Map toMap(Object obj)
253

254
/**
255
 * Get supported serialization formats
256
 * @return List of supported formats
257
 */
258
List<String> getSerializationFormats()
259

260
/**
261
 * Get supported deserialization formats
262
 * @return List of supported formats
263
 */
264
List<String> getDeserializationFormats()
265
```
266

267
**Usage Examples:**
268

269
```groovy
270
GroovyEngine engine = new GroovyEngine()
271

272
// Data conversion
273
def user = [name: "Alice", age: 25, active: true]
274
String json = engine.toJson(user)
275
Map userMap = engine.toMap(user)
276

277
// Deserialization
278
Object userData = engine.deserialize('{"name":"Bob","age":30}', "JSON")
279

280
// Persistence
281
Path dataFile = Paths.get("user-data.json")
282
engine.persist(dataFile, user)
283

284
// Check supported formats
285
List<String> serFormats = engine.getSerializationFormats()
286
List<String> deserFormats = engine.getDeserializationFormats()
287
```
288

289
### Code Completion and Introspection
290

291
Advanced features for IDE-like functionality including auto-completion and code analysis.
292

293
```groovy { .api }
294
/**
295
 * Get script completer for auto-completion
296
 * @return Completer instance for code completion
297
 */
298
Completer getScriptCompleter()
299

300
/**
301
 * Get description for script or method
302
 * @param line Command line to describe
303
 * @return Description string
304
 */
305
String scriptDescription(CmdLine line)
306

307
/**
308
 * Get engine name identifier
309
 * @return Engine name ("GroovyEngine")
310
 */
311
String getEngineName()
312

313
/**
314
 * Get supported file extensions
315
 * @return List of extensions (["groovy"])
316
 */
317
List<String> getExtensions()
318

319
/**
320
 * Get method names defined in the engine
321
 * @return Set of method names
322
 */
323
Set<String> getMethodNames()
324

325
/**
326
 * Purge class cache with optional regex filter
327
 * @param regex Regular expression to match class names (null clears all)
328
 */
329
void purgeClassCache(String regex)
330

331
/**
332
 * Refresh engine state and syntax highlighting
333
 * @return true if refresh succeeded
334
 */
335
boolean refresh()
336

337
/**
338
 * Set object cloner for variable copying
339
 * @param cloner Cloner implementation
340
 */
341
void setObjectCloner(Cloner cloner)
342

343
/**
344
 * Get current object cloner
345
 * @return Current cloner implementation
346
 */
347
Cloner getObjectCloner()
348
```
349

350
### Configuration Options
351

352
Configure engine behavior through various options affecting completion, syntax checking, and execution.
353

354
```groovy { .api }
355
/**
356
 * Get engine configuration options
357
 * @return Map of configuration options
358
 */
359
Map<String, Object> groovyOptions()
360
```
361

362
**Available Options:**
363
- `CANONICAL_NAMES`: Use canonical class names in completion
364
- `NO_SYNTAX_CHECK`: Disable syntax validation
365
- `RESTRICTED_COMPLETION`: Limit completion suggestions
366
- `ALL_METHODS_COMPLETION`: Include all methods in completion
367
- `ALL_FIELDS_COMPLETION`: Include all fields in completion
368
- `ALL_CONSTRUCTORS_COMPLETION`: Include all constructors in completion
369
- `IDENTIFIERS_COMPLETION`: Include identifiers in completion
370
- `META_METHODS_COMPLETION`: Include meta-methods in completion
371
- `SYNTHETIC_METHODS_COMPLETION`: Include synthetic methods in completion
372

373
**Usage Examples:**
374

375
```groovy
376
GroovyEngine engine = new GroovyEngine()
377

378
// Configure options
379
Map<String, Object> options = engine.groovyOptions()
380
options.put("ALL_METHODS_COMPLETION", true)
381
options.put("RESTRICTED_COMPLETION", false)
382

383
// Use completion
384
Completer completer = engine.getScriptCompleter()
385

386
// Get engine info
387
String engineName = engine.getEngineName()
388
List<String> extensions = engine.getExtensions()
389
Set<String> methodNames = engine.getMethodNames()
390
```
391

392
## Types
393

394
```groovy { .api }
395
/**
396
 * Supported data serialization formats
397
 */
398
enum Format {
399
    JSON,    // JSON format
400
    GROOVY,  // Groovy object format  
401
    NONE     // No formatting
402
}
403
```