CtrlK
BlogDocsLog inGet started
Tessl Logo

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

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

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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

docs

command-system.md

completion-system.md

index.md

shell-features.md

utilities.md

tile.json