0
# Groovy Shell (groovysh)
1

2
Groovy Shell is a command-line REPL (Read-Eval-Print Loop) tool for the Groovy programming language that provides an interactive environment for evaluating Groovy expressions, executing scripts, and exploring APIs. It features advanced shell capabilities including multi-line editing, command history, tab completion, and an extensible command system.
3

4
## Package Information
5

6
- **Package Name**: groovy-groovysh
7
- **Package Type**: gradle subproject / jar
8
- **Language**: Groovy/Java
9
- **Installation**: Part of Apache Groovy distribution
10
- **Maven Coordinates**: `org.apache.groovy:groovy-groovysh`
11

12
## Core Imports
13

14
```groovy
15
import org.apache.groovy.groovysh.Main
16
import org.apache.groovy.groovysh.Groovysh
17
import org.apache.groovy.groovysh.Shell
18
import org.apache.groovy.groovysh.Command
19
import org.apache.groovy.groovysh.CommandSupport
20
```
21

22
Legacy imports (deprecated but supported):
23
```groovy
24
import org.codehaus.groovy.tools.shell.Groovysh
25
import org.codehaus.groovy.tools.shell.IO
26
```
27

28
## Basic Usage
29

30
```groovy
31
import org.apache.groovy.groovysh.Groovysh
32
import org.apache.groovy.groovysh.Main
33
import org.codehaus.groovy.tools.shell.IO
34

35
// Create and run interactive shell
36
def shell = new Groovysh()
37
shell.run()
38

39
// Create shell with custom I/O
40
def io = new IO()
41
def customShell = new Groovysh(io)
42

43
// Run shell from main entry point
44
def main = new Main(io)
45
main.startGroovysh(null, [])
46

47
// Execute single command
48
shell.execute("println 'Hello World'")
49

50
// Register custom command
51
class CustomCommand extends CommandSupport {
52
    CustomCommand(shell) {
53
        super(shell, ':custom', ':c')
54
    }
55
    
56
    Object execute(List<String> args) {
57
        shell.io.out.println("Custom command executed!")
58
        return "result"
59
    }
60
}
61
shell.register(new CustomCommand(shell))
62
```
63

64
## Architecture
65

66
Groovy Shell is built around several key architectural components:
67

68
- **Main Entry Point**: `Main` class handles CLI arguments and bootstraps the shell environment
69
- **Shell Framework**: Core `Shell` and `Groovysh` classes provide command execution and REPL functionality
70
- **Command System**: Extensible command registry with 15+ built-in commands for shell operations
71
- **Parser/Interpreter**: Multi-pass parsing with support for incomplete expressions and code evaluation
72
- **Completion Engine**: Advanced tab completion system with 20+ specialized completers
73
- **Interactive Runner**: JLine integration for readline, history, and terminal control
74
- **Buffer Management**: Multi-buffer editing system for complex code input
75

76
## Capabilities
77

78
### Main Entry Points
79

80
Primary application entry points and shell initialization.
81

82
```groovy { .api }
83
class Main {
84
    static void main(String[] args)
85
    static void setTerminalType(String type, boolean suppressColor)
86
    static void installAnsi()
87
    protected void startGroovysh(String evalString, List<String> filenames)
88
    
89
    Main(IO io)
90
    Main(IO io, CompilerConfiguration configuration)
91
    
92
    final Groovysh groovysh
93
}
94
```
95

96
### Core Shell Classes
97

98
Base shell functionality and the main Groovy REPL implementation.
99

100
```groovy { .api }
101
abstract class Shell {
102
    Command findCommand(String line, List<String> parsedArgs = null)
103
    boolean isExecutable(String line)
104
    Object execute(String line)
105
    Command register(Command command)
106
    def leftShift(String line)
107
    Command leftShift(Command command)
108
    
109
    Shell(IO io)
110
    Shell()
111
    
112
    final CommandRegistry registry
113
    final IO io
114
}
115

116
class Groovysh extends Shell {
117
    static final String COLLECTED_BOUND_VARS_MAP_VARNAME = 'groovysh_collected_boundvars'
118
    static final String INTERPRETER_MODE_PREFERENCE_KEY = 'interpreterMode'
119
    static final String AUTOINDENT_PREFERENCE_KEY = 'autoindent'
120
    static final String COLORS_PREFERENCE_KEY = 'colors'
121
    static final String SANITIZE_PREFERENCE_KEY = 'sanitizeStackTrace'
122
    static final String SHOW_LAST_RESULT_PREFERENCE_KEY = 'showLastResult'
123
    static final String METACLASS_COMPLETION_PREFIX_LENGTH_PREFERENCE_KEY = 'meta-completion-prefix-length'
124
    
125
    Object execute(String line)
126
    void displayBuffer(List buffer)
127
    String getImportStatements()
128
    String renderPrompt()
129
    File getUserStateDirectory()
130
    int run(String evalString, List<String> filenames)
131
    int run(String commandLine)
132
    void displayWelcomeBanner(InteractiveShellRunner runner)
133
    String getIndentPrefix()
134
    static boolean isTypeOrMethodDeclaration(List<String> buffer)
135
    
136
    final BufferManager buffers
137
    final Parser parser
138
    final Interpreter interp
139
    final List<String> imports
140
    int indentSize
141
    InteractiveShellRunner runner
142
    FileHistory history
143
    boolean historyFull
144
    String evictedLine
145
    PackageHelper packageHelper
146
}
147
```
148

149
[Shell Features](./shell-features.md)
150

151
### Command System
152

153
Extensible command framework with built-in commands for shell operations.
154

155
```groovy { .api }
156
interface Command {
157
    String getName()
158
    String getShortcut()
159
    Completer getCompleter()
160
    String getDescription()
161
    String getUsage()
162
    String getHelp()
163
    List getAliases()
164
    Object execute(List<String> args)
165
    boolean getHidden()
166
}
167

168
abstract class CommandSupport implements Command {
169
    protected static final String NEWLINE = System.lineSeparator()
170
    
171
    final String name
172
    final String shortcut
173
    final List aliases
174
    boolean hidden
175
    
176
    CommandSupport(Groovysh shell, String name, String shortcut)
177
}
178

179
class CommandRegistry {
180
    Command register(Command command)
181
    Command find(String name)
182
    void remove(Command command)
183
    List<Command> commands()
184
    Command getProperty(String name)
185
    Iterator iterator()
186
    
187
    final List<Command> commandList
188
}
189
```
190

191
[Command System](./command-system.md)
192

193
### Tab Completion System
194

195
Advanced completion engine supporting Groovy syntax, commands, and contextual completions.
196

197
```groovy { .api }
198
class GroovySyntaxCompleter implements Completer {
199
    enum CompletionCase { DOT_LAST, NO_DOT_PREFIX, NO_DOT_SOME_PREFIX }
200
    
201
    int complete(String bufferLine, int cursor, List<CharSequence> candidates)
202
    static CompletionCase getCompletionCase(List<GroovySourceToken> tokens)
203
    static boolean isCommand(String bufferLine, CommandRegistry registry)
204
}
205

206
class CommandsMultiCompleter extends AggregateCompleter {
207
    def add(Command command)
208
    void refresh()
209
    int complete(String buffer, int pos, List cand)
210
}
211
```
212

213
[Completion System](./completion-system.md)
214

215
### Parser and Interpreter
216

217
Code parsing and evaluation system with support for incomplete expressions.
218

219
```groovy { .api }
220
interface Parsing {
221
    ParseStatus parse(Collection<String> buffer)
222
}
223

224
class Parser implements Parsing {
225
    static final String NEWLINE = System.lineSeparator()
226
    
227
    ParseStatus parse(Collection<String> buffer)
228
    Parser()
229
}
230

231
final class ParseCode {
232
    static final ParseCode COMPLETE
233
    static final ParseCode INCOMPLETE
234
    static final ParseCode ERROR
235
}
236

237
final class ParseStatus {
238
    final ParseCode code
239
    final Throwable cause
240
    
241
    ParseStatus(ParseCode code, Throwable cause)
242
    ParseStatus(ParseCode code)
243
    ParseStatus(Throwable cause)
244
}
245

246
interface Evaluator {
247
    Object evaluate(Collection<String> strings)
248
}
249

250
class Interpreter implements Evaluator {
251
    static final String SCRIPT_FILENAME = 'groovysh_evaluate'
252
    
253
    Object evaluate(Collection<String> buffer)
254
    GroovyClassLoader getClassLoader()
255
    Binding getContext()
256
    GroovyShell getShell()
257
    
258
    Interpreter(ClassLoader classLoader, Binding binding, CompilerConfiguration configuration = null)
259
}
260
```
261

262
### Utility Classes
263

264
Helper classes for command processing, package navigation, and shell utilities.
265

266
```groovy { .api }
267
class BufferManager {
268
    void reset()
269
    List<String> current()
270
    void select(int index)
271
    int create(boolean select)
272
    void delete(int index)
273
    int size()
274
    void deleteSelected()
275
    void clearSelected()
276
    void updateSelected(List buffer)
277
    
278
    final List<List<String>> buffers
279
    int selected
280
}
281

282
class CommandArgumentParser {
283
    static List<String> parseLine(String line)
284
    static List<String> parseLine(String line, int maxTokens)
285
}
286

287
interface PackageHelper {
288
    Set<String> getContents(String packagename)
289
}
290

291
class ScriptVariableAnalyzer {
292
    static Set<String> getBoundVars(String scriptText, ClassLoader classLoader)
293
}
294
```
295

296
[Utilities](./utilities.md)
297

298
## Exception Types
299

300
```groovy { .api }
301
class CommandException extends Exception {
302
    CommandException(Command command, String message)
303
    CommandException(Command command, String message, Throwable cause)
304
}
305

306
class ExitNotification extends Error {
307
    final int code
308
    ExitNotification(int code)
309
}
310
```
311

312
## Package Structure
313

314
The groovy-groovysh project maintains two parallel package hierarchies:
315

316
### Primary Package Structure (Current)
317
- `org.apache.groovy.groovysh` - Main shell classes and core functionality
318
- `org.apache.groovy.groovysh.commands` - Built-in shell commands  
319
- `org.apache.groovy.groovysh.completion` - Tab completion system
320
- `org.apache.groovy.groovysh.util` - Utility classes and helpers
321
- `org.apache.groovy.groovysh.antlr4` - ANTLR4-specific implementations
322

323
### Legacy Package Structure (Deprecated)
324
- `org.codehaus.groovy.tools.shell` - Deprecated shell classes (maintained for backward compatibility)
325
- `org.codehaus.groovy.tools.shell.commands` - Deprecated command implementations
326
- `org.codehaus.groovy.tools.shell.completion` - Deprecated completion classes
327
- `org.codehaus.groovy.tools.shell.util` - Deprecated utility classes