0
# Groovy Shell (groovysh)
1

2
Apache Groovy's interactive command-line shell (REPL) that provides a powerful environment for evaluating Groovy expressions, defining classes, and running experiments interactively. Built on JLine3, it offers rich cross-platform line editing capabilities with history, tab completion, ANSI color support, and a robust command system with online help and user alias support.
3

4
## Package Information
5

6
- **Package Name**: org.apache.groovy:groovy-groovysh
7
- **Package Type**: Maven
8
- **Language**: Groovy/Java
9
- **Installation**: `implementation 'org.apache.groovy:groovy-groovysh:5.0.0'`
10

11
## Core Imports
12

13
```groovy
14
import org.apache.groovy.groovysh.jline.GroovyEngine
15
import org.apache.groovy.groovysh.Main
16
```
17

18
For programmatic usage:
19

20
```java
21
import org.apache.groovy.groovysh.jline.GroovyEngine;
22
import org.apache.groovy.groovysh.jline.GroovyConsoleEngine;
23
import org.apache.groovy.groovysh.jline.GroovySystemRegistry;
24
```
25

26
## Basic Usage
27

28
### Command Line Usage
29

30
```bash
31
# Start interactive shell
32
groovysh
33

34
# Execute code and exit
35
groovysh --evaluate "println 'Hello World'"
36

37
# Load script file
38
groovysh --evaluate "load 'script.groovy'"
39
```
40

41
### Programmatic Usage
42

43
```groovy
44
import org.apache.groovy.groovysh.jline.GroovyEngine
45

46
// Create and configure engine
47
GroovyEngine engine = new GroovyEngine()
48

49
// Execute Groovy code
50
Object result = engine.execute("2 + 2")
51
println result // 4
52

53
// Manage variables
54
engine.put("name", "World")
55
Object greeting = engine.execute("'Hello, ' + name")
56
println greeting // "Hello, World"
57

58
// Check and retrieve variables
59
if (engine.hasVariable("name")) {
60
    Object value = engine.get("name")
61
    println "Name: $value"
62
}
63
```
64

65
## Architecture
66

67
Groovysh is built around several key components:
68

69
- **Main Entry Point**: `Main` class provides command-line interface with comprehensive option parsing
70
- **Script Engine**: `GroovyEngine` handles code execution, variable management, and state persistence
71
- **Console System**: `GroovyConsoleEngine` and `GroovySystemRegistry` manage REPL interaction and command processing
72
- **Command Registry**: Built-in commands for file operations, debugging, documentation, and dependency management
73
- **JLine Integration**: Rich terminal support with auto-completion, syntax highlighting, and history
74
- **Utility System**: Helper classes for documentation lookup, object inspection, and class management
75

76
## Capabilities
77

78
### Script Execution Engine
79

80
Core engine for executing Groovy code programmatically, managing variables, imports, and providing code completion. Essential for embedding Groovy REPL functionality in applications.
81

82
```groovy { .api }
83
class GroovyEngine {
84
    Object execute(String statement)
85
    Object execute(File script, Object[] args)
86
    Object execute(Object closure, Object... args)
87
    void put(String name, Object value)
88
    Object get(String name)
89
    boolean hasVariable(String name)
90
    Map<String, Object> find(String name)
91
    void reset()
92
}
93
```
94

95
[Script Engine](./script-engine.md)
96

97
### Interactive Commands
98

99
Built-in shell commands for file operations, object inspection, documentation lookup, dependency management, and state control. These commands provide a rich interactive development environment.
100

101
```groovy { .api }
102
// File operations
103
/load [options] [file]    // Load script file or saved state
104
/save [options] [file]    // Save current state or buffer
105
/slurp [options] file     // Parse structured data files
106

107
// Development tools  
108
/inspect [options] object // Inspect object properties and methods
109
/doc object              // Open documentation in browser
110
/grab coordinates        // Add Maven dependencies
111

112
// State management
113
/vars [name]             // Show or delete variables
114
/imports [name]          // Show or delete imports
115
/reset                   // Clear all state
116
```
117

118
[Interactive Commands](./interactive-commands.md)
119

120
### Console Integration
121

122
Advanced console features including syntax highlighting, auto-completion, custom command registration, and integration with JLine3 terminal capabilities.
123

124
```groovy { .api }
125
class GroovyConsoleEngine {
126
    void println(Map<String, Object> options, Object object)
127
}
128

129
class GroovySystemRegistry {
130
    Object execute(String line)
131
    boolean isCommandOrScript(String command)
132
}
133
```
134

135
[Console Integration](./console-integration.md)
136

137
### Object Inspection and Documentation
138

139
Tools for exploring objects, browsing documentation, and understanding code structure during interactive development sessions.
140

141
```groovy { .api }
142
class ObjectInspector {
143
    // Object introspection utilities
144
}
145

146
class DocFinder {
147
    // Documentation URL resolution
148
}
149
```
150

151
[Documentation and Inspection](./documentation-inspection.md)
152

153
## Types
154

155
```groovy { .api }
156
// Core engine options
157
interface GroovyOptions {
158
    boolean CANONICAL_NAMES
159
    boolean NO_SYNTAX_CHECK  
160
    boolean RESTRICTED_COMPLETION
161
    boolean ALL_METHODS_COMPLETION
162
    boolean ALL_FIELDS_COMPLETION
163
    boolean ALL_CONSTRUCTORS_COMPLETION
164
    boolean IDENTIFIERS_COMPLETION
165
    boolean META_METHODS_COMPLETION
166
    boolean SYNTHETIC_METHODS_COMPLETION
167
}
168

169
// Data serialization formats
170
enum SerializationFormat {
171
    JSON, NONE
172
}
173

174
enum DeserializationFormat {
175
    JSON, GROOVY, NONE
176
}
177
```