or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

command-system.mdcompletion-system.mdindex.mdshell-features.mdutilities.md
tile.json

tessl/maven-org-codehaus-groovy--groovy-groovysh

Interactive command-line shell (REPL) for evaluating Groovy expressions with advanced editing, completion, and command features

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.codehaus.groovy/groovy-groovysh@3.0.x

To install, run

npx @tessl/cli install tessl/maven-org-codehaus-groovy--groovy-groovysh@3.0.0

index.mddocs/

Groovy Shell (groovysh)

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.

Package Information

  • Package Name: groovy-groovysh
  • Package Type: gradle subproject / jar
  • Language: Groovy/Java
  • Installation: Part of Apache Groovy distribution
  • Maven Coordinates: org.apache.groovy:groovy-groovysh

Core Imports

import org.apache.groovy.groovysh.Main
import org.apache.groovy.groovysh.Groovysh
import org.apache.groovy.groovysh.Shell
import org.apache.groovy.groovysh.Command
import org.apache.groovy.groovysh.CommandSupport

Legacy imports (deprecated but supported):

import org.codehaus.groovy.tools.shell.Groovysh
import org.codehaus.groovy.tools.shell.IO

Basic Usage

import org.apache.groovy.groovysh.Groovysh
import org.apache.groovy.groovysh.Main
import org.codehaus.groovy.tools.shell.IO

// Create and run interactive shell
def shell = new Groovysh()
shell.run()

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

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

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

// Register custom command
class CustomCommand extends CommandSupport {
    CustomCommand(shell) {
        super(shell, ':custom', ':c')
    }
    
    Object execute(List<String> args) {
        shell.io.out.println("Custom command executed!")
        return "result"
    }
}
shell.register(new CustomCommand(shell))

Architecture

Groovy Shell is built around several key architectural components:

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

Capabilities

Main Entry Points

Primary application entry points and shell initialization.

class Main {
    static void main(String[] args)
    static void setTerminalType(String type, boolean suppressColor)
    static void installAnsi()
    protected void startGroovysh(String evalString, List<String> filenames)
    
    Main(IO io)
    Main(IO io, CompilerConfiguration configuration)
    
    final Groovysh groovysh
}

Core Shell Classes

Base shell functionality and the main Groovy REPL implementation.

abstract class Shell {
    Command findCommand(String line, List<String> parsedArgs = null)
    boolean isExecutable(String line)
    Object execute(String line)
    Command register(Command command)
    def leftShift(String line)
    Command leftShift(Command command)
    
    Shell(IO io)
    Shell()
    
    final CommandRegistry registry
    final IO io
}

class Groovysh extends Shell {
    static final String COLLECTED_BOUND_VARS_MAP_VARNAME = 'groovysh_collected_boundvars'
    static final String INTERPRETER_MODE_PREFERENCE_KEY = 'interpreterMode'
    static final String AUTOINDENT_PREFERENCE_KEY = 'autoindent'
    static final String COLORS_PREFERENCE_KEY = 'colors'
    static final String SANITIZE_PREFERENCE_KEY = 'sanitizeStackTrace'
    static final String SHOW_LAST_RESULT_PREFERENCE_KEY = 'showLastResult'
    static final String METACLASS_COMPLETION_PREFIX_LENGTH_PREFERENCE_KEY = 'meta-completion-prefix-length'
    
    Object execute(String line)
    void displayBuffer(List buffer)
    String getImportStatements()
    String renderPrompt()
    File getUserStateDirectory()
    int run(String evalString, List<String> filenames)
    int run(String commandLine)
    void displayWelcomeBanner(InteractiveShellRunner runner)
    String getIndentPrefix()
    static boolean isTypeOrMethodDeclaration(List<String> buffer)
    
    final BufferManager buffers
    final Parser parser
    final Interpreter interp
    final List<String> imports
    int indentSize
    InteractiveShellRunner runner
    FileHistory history
    boolean historyFull
    String evictedLine
    PackageHelper packageHelper
}

Shell Features

Command System

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

interface Command {
    String getName()
    String getShortcut()
    Completer getCompleter()
    String getDescription()
    String getUsage()
    String getHelp()
    List getAliases()
    Object execute(List<String> args)
    boolean getHidden()
}

abstract class CommandSupport implements Command {
    protected static final String NEWLINE = System.lineSeparator()
    
    final String name
    final String shortcut
    final List aliases
    boolean hidden
    
    CommandSupport(Groovysh shell, String name, String shortcut)
}

class CommandRegistry {
    Command register(Command command)
    Command find(String name)
    void remove(Command command)
    List<Command> commands()
    Command getProperty(String name)
    Iterator iterator()
    
    final List<Command> commandList
}

Command System

Tab Completion System

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

class GroovySyntaxCompleter implements Completer {
    enum CompletionCase { DOT_LAST, NO_DOT_PREFIX, NO_DOT_SOME_PREFIX }
    
    int complete(String bufferLine, int cursor, List<CharSequence> candidates)
    static CompletionCase getCompletionCase(List<GroovySourceToken> tokens)
    static boolean isCommand(String bufferLine, CommandRegistry registry)
}

class CommandsMultiCompleter extends AggregateCompleter {
    def add(Command command)
    void refresh()
    int complete(String buffer, int pos, List cand)
}

Completion System

Parser and Interpreter

Code parsing and evaluation system with support for incomplete expressions.

interface Parsing {
    ParseStatus parse(Collection<String> buffer)
}

class Parser implements Parsing {
    static final String NEWLINE = System.lineSeparator()
    
    ParseStatus parse(Collection<String> buffer)
    Parser()
}

final class ParseCode {
    static final ParseCode COMPLETE
    static final ParseCode INCOMPLETE
    static final ParseCode ERROR
}

final class ParseStatus {
    final ParseCode code
    final Throwable cause
    
    ParseStatus(ParseCode code, Throwable cause)
    ParseStatus(ParseCode code)
    ParseStatus(Throwable cause)
}

interface Evaluator {
    Object evaluate(Collection<String> strings)
}

class Interpreter implements Evaluator {
    static final String SCRIPT_FILENAME = 'groovysh_evaluate'
    
    Object evaluate(Collection<String> buffer)
    GroovyClassLoader getClassLoader()
    Binding getContext()
    GroovyShell getShell()
    
    Interpreter(ClassLoader classLoader, Binding binding, CompilerConfiguration configuration = null)
}

Utility Classes

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

class BufferManager {
    void reset()
    List<String> current()
    void select(int index)
    int create(boolean select)
    void delete(int index)
    int size()
    void deleteSelected()
    void clearSelected()
    void updateSelected(List buffer)
    
    final List<List<String>> buffers
    int selected
}

class CommandArgumentParser {
    static List<String> parseLine(String line)
    static List<String> parseLine(String line, int maxTokens)
}

interface PackageHelper {
    Set<String> getContents(String packagename)
}

class ScriptVariableAnalyzer {
    static Set<String> getBoundVars(String scriptText, ClassLoader classLoader)
}

Utilities

Exception Types

class CommandException extends Exception {
    CommandException(Command command, String message)
    CommandException(Command command, String message, Throwable cause)
}

class ExitNotification extends Error {
    final int code
    ExitNotification(int code)
}

Package Structure

The groovy-groovysh project maintains two parallel package hierarchies:

Primary Package Structure (Current)

  • org.apache.groovy.groovysh - Main shell classes and core functionality
  • org.apache.groovy.groovysh.commands - Built-in shell commands
  • org.apache.groovy.groovysh.completion - Tab completion system
  • org.apache.groovy.groovysh.util - Utility classes and helpers
  • org.apache.groovy.groovysh.antlr4 - ANTLR4-specific implementations

Legacy Package Structure (Deprecated)

  • org.codehaus.groovy.tools.shell - Deprecated shell classes (maintained for backward compatibility)
  • org.codehaus.groovy.tools.shell.commands - Deprecated command implementations
  • org.codehaus.groovy.tools.shell.completion - Deprecated completion classes
  • org.codehaus.groovy.tools.shell.util - Deprecated utility classes