jEdit Console plugin user's guide

Version 5.1.2 (May 31 2013)

Slava Pestov

Alan Ezust

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections", "Front-Cover Texts" or "Back-Cover Texts", each as defined in the license. A copy of the license can be found in the file COPYING.DOC.txt included with jEdit.

Table of Contents

Chapter 1. Introduction

The jEdit Console plugin has four main functions:

  • Running external programs and commands.

  • Parsing the output of external programs for errors in a variety of formats, and reporting those errors using the ErrorList plugin.

  • The Commando feature provides graphical front-ends, specified using an XML file, to command-line tools.

  • Providing an extensible framework for other plugins that need to display streamed output.

This plugin includes a library, jcfunc which is used for parsing ANSI vt100 color codes.

ProjectViewer Integration

Console has an optional dependency on ProjectViewer. What this means is that it has some extra features which you can see if you have also installed ProjectViewer plugin. In particular they are:

  1. Actions Compile Project and Run Project which are configured from ProjectViewer's Console properties pane.

  2. The ability to listen to node change events from the ProjectViewer and make changes to the System shell's current directory.

  3. The ability to query the ProjectViewer for the "current project root" to run commands from. This is used by the Console commandos, as well as the build/run project commands.

Chapter 2.  Setup/Options

Option Panes

By selecting Plugin Options - Console , you will notice a number of options. It is recommended you browse through them to get a full idea of what Console (and your other plugins) can do.

Console - General Options

Here, you can set general options that apply to all shells, such as default shell, showing the welcome message, character encoding to use, scrollback buffer size, colors to use, etc.

In addition, you can choose to parse, ignore, or strip out the ANSI escape sequences that cause color changes in the console.

  • Show Welcome Message - suppress welcome message on shells.

  • Character Encoding - If you want to display characters in a different language, change the encoding here.

Console - System Shell Options
  • Shell Prefix - This string is inserted before the command you type whenever a command is executed. Console itself does parse and preprocess your commands in its own way, but you have the option of having the commands subsequently evaluated by your native command line shell, which will in turn execute your command.

    Console can choose a sensible os-specific shell prefix for you, by setting it to osdefault. If this field is blank, or if none is used, Console will execute commands directly (without a prefix). I prefer using a native shell for its functions, aliases, and redirection, but you can try different values here to see which works best for you.

    In addition, if you like to use a different shell from the OS-default (4NT, or cygwin's bash), you can add it to this list and see if it works.

  • Merge stdout and stderr - this option will only affect users of "make", where Console needs to merge the streams in order to resolve pathnames of files of errors inbetween "make entering..leaving" messages.

  • Subshell extra PATH - This option prepends directories to the environment before spawning subprocesses. If you want your jedit console to be able to find some files in the path, add those directories here.

  • Append extra dirs to PATH - if checked, append instead of prepend the extra directories.

Chdir Events

Console can change its directory in response to a variety of events. From here you can decide which events it should listen to.

  • Tree Node Selection (File System Browser, or ProjectViewer)

  • A combination of EditPaneUpdate, ViewUpdate, and BufferUpdate messages that indicate the current EditPane is looking at a different buffer.

  • ProjectViewer project change messages

Commando Options

Console has an optional toolbar that displays commando commands. You can check and un-check which commands show up in the menus and toolbars.

Error Parsing Options

This option dialog allows you fine grained control over Console's error parsing capabilities.

Each line of output that is generated by a program that is run in the Console System (and ssh) shells is checked against a number of error patterns to determine if the line is part of an error message. If the error message is found, pieces of information are extracted from it to get the line number and filename. This information is in turn fed into Error List to give you a convenient way to send the editor to the location of an error message.

Each error pattern is a set of regular expressions. To edit, test, add, or remove error patterns from Console's output parsing module, you can select this option dialog. Keep in mind, you must "test/commit" each error pattern before clicking 'ok'. This helps avoid accidentally committing invalid regular expressions that may cause parse errors.

Removing unused patterns.

Since many of the error patterns are similar, it is possible that one of the existing patterns is getting triggered before Console sees the one you are developing. For this reason, it is suggested you remove or disable the error patterns you are not using, and place the error patterns for the tools you use most often at the top of the list.

Compile and Run Options

For each edit mode, you can choose a command that is used to compile or run a buffer. This can be either a commando command or a custom command. These commands are executed in the System shell.

Chapter 3. The console window

Table of Contents

Plugins -> Console -> Console displays the console window. This window is floating by default, but can be made to dock into the view in the Docking pane of the Global Options dialog box.

The console window consists of a popup for choosing the current shell, a series of icon buttons, and a shell input/output area that occupies the remaining space of the window.

The Console plugin allows arbitrary shells to be plugged in; one shell included with the plugin is called the "System" shell and it runs external programs and commands; another built-in shell is the "BeanShell" shell, which runs commands in jEdit's BeanShell interpreter. Some plugins add their own shells; for example, the SshConsole plugin adds a shell for running shell commands remotely over ssh. without leaving jEdit.

Each button shows a tooltip if the mouse pointer is held over it long enough. Here is a description of each button:

  • Run last command - runs the most recently entered command.

  • Run - runs the currently-entered command. This has the same effect as pressing Enter in the text field.

  • Run to buffer - runs the currently-entered command, but shows the output in a new buffer, instead of in the console window. This has the same effect as pressing Ctrl-Enter from the text field.

  • Stop - stops the currently running process, if any.

  • Clear - clears the console window's output area.


A quick way to switch between shells from the keyboard is by entering the shell name prefixed with ":". For example, ":BeanShell" or ":System". In addition, each shell has its own toggle and switch shortcut defined from Global Options - Shortcuts - Plugin: Console - Shell Switchers .

Keyboard Shortcuts

While Console has focus, the following keyboard shortcuts work:

  • Ctrl+P or Up-Arrow: Previous entered history command.

  • Ctrl+N or Down-Arrow: Next entered history command.

  • Ctrl+C: Copy to clipboard.

  • Ctrl+V: Paste from clipboard.

  • Ctrl+U: Clear current line.

  • Ctrl+Z: Detach foreground process.

  • Ctrl+Enter: Shell command to new untitled buffer.

Chapter 4. The system shell

This section assumes at least basic familiarity with the command-line interpreter of a Unix, Windows or similar operating system.

As with most other command lines, spaces are used to separate command-line parameters to programs. If a string containing spaces needs to be passed as a single parameter, it should be enclosed with double quotes ("), for example:

javac "C:\Source Code\"

Not all commands result in an external process being spawned; the system shell supports "built-ins", which are handled by the Console plugin itself. Built-ins are prefixed with "%" to distinguish them from external commands.

Currently selected text is passed to the program on standard input. In conjunction with the Run to buffer button, this allows quick filtering of buffer text using shell tools.

Pressing Tab in the console's command input field will attempt to complete the filename or command before the caret. If there is more than one possible completion, they will be listed in the output area.

Processes that read from standard input might work. You can press Control+D to send an end-of-file. Note that since the plugin does not provide a pseudo-terminal, so some programs, such as shells that use getline() or curses(), might not behave properly inside a console window.

Error parsing

Each line of output produced by an external program is fed through several successive ErrorMatcher objects. Each ErrorMatcher corresponds to a different style of error messages, and holds onto an three regular expressions - for errors, warnings, and extra lines.

The order of patterns on this list matters: more specific patterns (for applications that you use) should be earlier on the list. Patterns for applications you do not use can be safely removed from this list, and this can speed things up during output parsing.

If the output of a line matches the error pattern, then file name, line number and error message are extracted from it; if not, the line is then optionally matched against another regular expression to determine if it is a warning.

If an error pattern specifies a filename of "$f", the current buffer's path is used; otherwise, the filename is resolved relative to the current directory.

It is also possible to specify an "extra" regular expression, against which lines subsequent to an error or warning are checked and added to the message if there is a match. This can be used to handle compilers which produce compiler errors and warnings that span several lines. For this pattern, the string to be appended to the error message must be in a back-reference (round braces).

Parsed error and warning messages are shown in the Plugins>Error List>Error List window; this window is used to display errors from several other plugins as well.

The Console plugin includes error patterns that match errors produced by the following tools:

  • Generic errors matching the following format, produced by many tools, including javac and gcc:

  • Generic errors matching the so called "Emacs" format:

          file:start line:end line:start column:end column:message

    The jikes Java compiler will produce errors in this form if given if the +E command-line option. Otherwise, it will output errors in a non-standard format which cannot be parsed by the Console plugin.

  • Errors output by the javac compiler found in Java 2 version 1.3 and later. Earlier versions are also supported, because they output errors in the generic format documented above.

  • Errors produced by python.

  • Errors output by the javac compiler when it is being run from the Ant project build tool.

  • Microsoft Visual C++ and Microsoft .Net compiler errors.

  • Perl errors.

  • Errors output by the Jade and OpenJade document generation tools.

Error patterns can be customized in the Console>Error Patterns pane of the Plugin Options dialog box; you should familiarize yourself with regular expressions first, the syntax of which is documented in the jEdit user's guide.

Changing directories

To change the current working directory, simply enter its name, as if you were going to execute a command. Relative paths are resolved automatically.

The following system shell built-ins relate to the current working directory:

  • pwd - prints the current working directory. Note that unlike other built-ins, this one is not prefixed with "%" for convenience and consistency with other command lines.

  • cd directory : does the same thing as just entering directory .

  • - or cd -: goes to the directory that was current before this one.

  • %pushd [newDir] : pushes the current directory, and optionally changes to newDir.

  • %popd: sets the current working directory to the one stored at the top of the directory stack, then removes that entry from the stack.

  • %dirstack: lists all directories in the directory stack.

Process management

Each console window has an associated "foreground process"; output produced by the foreground process is shown in that console window. Commands that are not built-in, typed into the Console window while a foreground process is running are sent to the subprocess.

The %kill built-in can also be used to terminate the currently running foreground process. Clicking the Stop button in the console window has the same effect.

A process can be started in the "background" by adding "&" to the end of its command line. After a process is started in the background, it continues running until it exits. Output is not shown in the console window, and starting other processes has no effect on already-running background processes.

Each process started from the System Shell shows up as a task in the the Task Monitor (Utilities - TroubleShooting - Task Monitor). Therefore, this is another way to do job control.

Pressing Control+Z detaches the foreground process. In the System shell, the process continues running in the background, and no longer shows output in the console, which is not very *nix-like, but oh well.

Environment variables

When running on Unix and Windows NT/2000/XP, the system shell lets you access and change operating system-specific environment variables. On other systems, you can define and use variables, but they are console-specific.

To accommodate both Windows and Unix users, three forms of variable syntax are supported by the system shell:

  • %name%

  • $name

  • ${name}

The following variables are defined under all circumstances, independent of operating system-specific environment variables being available or not:

  • ${c} - if the current buffer is a Java file, the current buffer's fully qualified class name, including the package (if the buffer contains a package statement).

  • ${d} - the current buffer's directory.

  • ${f} - the current buffer's path name.

  • ${l} - the current TextArea's cursor's line number.

  • ${n} - the current buffer's name.

  • ${BROWSER_DIR} - the current directory displayed in the file system browser, or an empty string if the file system browser is not visible.

  • ${JEDIT_HOME} - the full path of the directory where jEdit is installed.

  • ${JEDIT_SETTINGS} - the full path of the jEdit settings directory.

  • ${PKG} - if the current buffer is a Java file, the current buffer's package name (or if the buffer doesn't contain a package statement, an empty string).

  • ${PWD} - the current working directory.

  • ${ROOT} - the package root of the current buffer. For example, if the current buffer's fully qualified class name is org.gjt.sp.jedit.jEdit and it is contained in the /home/slava/jEdit/org/gjt/sp/jedit/ directory, this will return /home/slava/jEdit/.

  • ${p} - the root directory of the current project, if there is one active in ProjectViewer.

  • ~ - this is not a "variable" per-se, and it is specified using a different syntax, but it makes sense to mention it here. It expands to the full path of the user's home directory.

The following system shell built-ins deal with environment variables:

  • %env: prints a list of all environment variables, excluding the dynamic ones documented above.

  • %set name value : sets the value of the specified environment variable. Note that if the desired value contains whitespace, you will need to quote it, otherwise it will be treated as several arguments.

  • %unset name : clears the value of the specified environment variable.

To insert a "$" or "%" literally in the command string, you can write "$$" and "%%".

jEdit integration built-ins

A few system shell built-ins invoke jEdit features:

  • %browse [-n|--new-window] directory : opens the specified directory in jEdit's file system browser. If -n or --new-window is specified, opens a new floating instance of the file system browser.

  • %edit files ... : opens the specified files in jEdit.

  • %run scripts ... : runs the specified script files. You can run BeanShell scripts, or any script type supported by an installed plugin (for example you can run Python scripts if JythonInterpreter is installed).

Chapter 5.  The Console BeanShell

One of jEdit's best kept secrets is the interactive Console BeanShell, which provides a command line interface into the current running JVM, allowing you to inspect or invoke methods on objects in memory, or create instances of any class loaded in the JVM. This makes the Console BeanShell a powerful debugging tool for jEdit or plugin development.

There are many predefined variables you can use from this shell. Be sure to check BeanShell Commands for more details.

Chapter 6. Commando

As mentioned previously, the Commando feature creates graphical front-ends to command-line tools from XML files.

Commando XML files are stored in two locations:

  • A few are stored in the Console.jar itself.

  • User-specific commando files are loaded from the console/commando subdirectory of the jEdit settings directory.

    You can find out the location of the settings directory by entering the following command in the system shell of the console window:

    %echo ${JEDIT_SETTINGS}

    Plugins>Console>Rescan Commando Directory should be called after files are added or removed in the user-specific commando directory.

    Plugins>Console>Browse Commando Directory opens the user-specific commando directory in jEdit's file system browser.

Plugins > Console > Commando displays the commando window. A menu item for each known commando file is also shown in the Plugins > Console > Commands menu; invoking one of these menu items opens the Commando window with that commando file pre-selected.

The Commando tool bar

The commando tool bar, which can be enabled in the Console>General pane of Plugin Options has one button for each commando file. Clicking a button opens the commando window for that file.

By right-clicking on the commando button, you can Hide or Customize it.

If you select customize, the xml file will be opened into your current editor. If it's the first time you customized the button, and it was one of the default commandos from from inside the Console.jar, then the file will be copied from the jar into your user settings ${JEDIT_SETTINGS}/console/commando/ directory. Subsequent times, it will just edit that file.

At this point, if you want to define a new commando (cmake, for example), just "save as" cmake.xml, and then select Regen Dynamic Menus.

If you wish to un-hide buttons that are hidden, you can bring them back from Plugin Options > Console > Toolbar Options pane.

The Commando window

The commando window consists of a combo box for selecting a commando file, and two tabs; the first contains GUI controls for specifying command-line settings, the second shows the resulting command line (or command lines, if the commando file defines more than one command to be run).

Currently, settings specified in the commando window are remembered for the duration of the current jEdit session. In the future, integration with a project management plugin will be provided, for specifying command line tool settings on a per-project basis.

One you have configured the necessary settings, click OK to run each command specified in the commando file in turn. Most commando files will only specify one command to run.

Some commands will be executed automatically, others will ask for confirmation; if a command fails, you will always be asked for confirmation before running the next one, no matter what. Some commando files, such as the diff file included with the Console plugin, show their output in a new buffer, rather than the console window.

Writing Commando files

Commando files are written in XML. A commando file must have a certain preamble, along with a root element:

<?xml version="1.0"?>


The UI element

Each command file must define one and only one UI element inside the COMMANDO element. The UI element does not have any defined attributes.

Each child element of the UI element except for the CAPTION element defines a user interface control, and supports the following attributes:

  • LABEL - the control's caption. This attribute is required.

  • VARNAME - the value entered by the user will be stored in the BeanShell variable with this name. This attribute is required.

  • DEFAULT - for specifying the default value literally.

  • EVAL - for specifying the default value to be the result of evaluating this BeanShell script. Note that only one of DEFAULT and EVAL should be specified.

The CAPTION element

A CAPTION element adds a labeled box to the commando panel that other UI elements can be added to. It must be placed inside the UI element. The only defined attribute is LABEL. It is required.

Any UI control can be placed inside the CAPTION element.

Here is an example of the CAPTION element:

<CAPTION LABEL="File specification">

  <ENTRY LABEL="Original file" VARNAME="from"
   EVAL="buffer.getPath() + '~'" />
  <ENTRY LABEL="Changed file" VARNAME="to"
   EVAL="buffer.getPath()" />

  <TOGGLE LABEL="Recursively compare directories"
   VARNAME="recursive" />
  <ENTRY LABEL="Ignore files regexp" VARNAME="ignore" />

The CHOICE element

A CHOICE element adds a combo box to the commando panel. It must be placed inside the UI element.

Possible options are specified in OPTION elements inside the CHOICE element. Here is an example CHOICE element:

<CHOICE LABEL="Output format" VARNAME="output"
   <OPTION LABEL="Brief" VALUE="brief" />
   <OPTION LABEL="Context" VALUE="context" />
   <OPTION LABEL="ED script" VALUE="ed" />
   <OPTION LABEL="Side by side" VALUE="sideBySide" />
   <OPTION LABEL="Unified" VALUE="unified" />
The DIR_ENTRY element

A DIR_ENTRY element adds a text field with a button on the right for displaying a directory chooser dialog. This dialog lets you pick a directory, then inserts the directory's full path in the text field.

Here is an example DIR_ENTRY element:

<DIR_ENTRY LABEL="Output directory" VARNAME="output" />
The ENTRY element

An ENTRY element adds a text field to the commando panel. It must be placed inside the UI element.

Here is an example ENTRY element:

<ENTRY LABEL="File name" VARNAME="file"
   EVAL="buffer.getPath()" />
The FILE_ENTRY element

A FILE_ENTRY element adds a text field with a button on the right for displaying a file chooser dialog. This dialog lets you pick a file, then inserts the file's full path in the text field.

Here is an example FILE_ENTRY element:

<FILE_ENTRY LABEL="Source file" VARNAME="source" />
The LONG_ENTRY element

A LONG_ENTRY element adds a multiple line text area to the commando panel. It must be placed inside the UI element.

Here is an example LONG_ENTRY element:

<LONG_ENTRY LABEL="Comments" VARNAME="comments" />
The TOGGLE element

A TOGGLE element adds a check box to the commando panel. It must be placed inside the UI element.

Here is an example TOGGLE element:

<TOGGLE LABEL="Ignore case" VARNAME="ignoreCase" />
The TOGGLE_ENTRY element

A TOGGLE_ENTRY element adds a text field with a check box to the commando panel. Toggling the check box enables and disables the text field. It must be placed inside the UI element. Note that the text field's value is stored in the variable named by the VARNAME attribute, and the toggle state is stored in the variable with that name suffixed with Toggle. For example, if VARNAME is path then the variables path and pathToggle will be defined.

Here is an example TOGGLE_ENTRY element:

<TOGGLE_ENTRY LABEL="Additional file" VARNAME="ignoreCase"
The COMMANDS element

The COMMANDS element must be contained in the root COMMANDO element.

One or more COMMAND elements can be defined inside the COMMANDS element. Each COMMAND element defines a command to execute. The following attributes are supported:

  • CONFIRM - If "TRUE", a confirmation dialog will be shown before running this command.

  • SHELL - The name of the shell to run this command in.

  • TO_BUFFER - If "TRUE", the command output will be shown in a new buffer.

  • BUFFER_MODE - If TO_BUFFER is "TRUE", this parameter can be used to specify the edit mode of the new buffer. The default value is "text".

  • DIR - An optional BeanShell snippet that will be evaluated to get the directory the command will be run in. For example, to make sure it runs in the same directory as the buffer, this can be set to "buffer.getDirectory();".

A BeanShell script placed between the start and end COMMAND tags should construct a command line using the values of the variables set by the UI controls. The final command line should be returned by the last statement in the script.

Here is an example COMMAND element:

    buf = new StringBuffer("jmk");

     buf.append(" -f \"");

     buf.append(' ');

     buf.append(" -d");

     buf.append(" -n");

     buf.append(" -w");

     buf.append(" -s");

    // return value
Chapter 7. Invoking compilers and interpreters

Plugins>Console>Compile Current Buffer opens a mode-specific commando that should invoke a compiler suitable for compiling the current buffer.

Plugins>Console>Run Current Buffer opens a mode-specific commando that should invoke an interpreter suitable for running the current buffer.

Commandos can be associated with edit modes in the Console>Compile & Run pane of Plugin Options.

Chapter 8. Macros and the Console plugin

The Console plugin defines three BeanShell convenience methods that can be called from macros:

void runCommandInConsole (View view ,
 String shell ,
 String command );

Runs command in the shell named shell. Will open a console window if one is not already open.

void runCommandToBuffer (View view ,
 String shell ,
 String command );

Runs command in the shell named shell, placing the command's output in a new buffer. Will open a console window if one is not already open.

void runInSystemShell (View view ,
 String command );

Equivalent to calling:

void waitForConsole (View view );

Waits until the currently executing command finishes before returning.

void clearConsole (View view );

Clear's the console's output area.

void getenv (String name );

Returns the specified environment variable.

void setenv (String name ,
 String value );

Sets the specified environment variable to a new value.

If a command is run from the console while macro recording is in progress, a call to one of these methods is recorded automatically.

Chapter 9.  Using Console with svn or git

When you commit via the command line versions of git or svn, the tool spawns an external editor for you to enter text with the commit log. The editor that is spawned can be specified by the VISUAL (for svn) or EDITOR (for git) environment variables. When the editor starts, you are editing a temporary file. When the editor sub-process exits, the commit tool retrieves the temporary file's contents.

A batch file or shellscript that runs jEdit can be used as the VISUAL and EDITOR that is called by command line programs like git and svn, even when run from inside jEdit's Console plugin. Here are some command line options that you should consider passing jEdit when it is started by another program such as svn:

  • -wait - waits until the buffer is closed before allowing the spawning process to 'exit' - this way you don't have to exit the main jEdit process when you are ready to commit.

  • -noplugins - if this is a new view (jedit is not already running), don't load all the plugins.

  • -norestore - don't restore the previously open files.

  • -newplainview - open a new window (if jEdit is already running). Some people might prefer -reuseview here, depending on the expected behavior of your previous editor.

So I have a shell script called jeditcommit that looks like this:

exec java -jar "$JEDIT_HOME/jedit.jar" -wait -noplugins -reuseview -norestore $@

And I have a windows batch file called jeditcommit.bat that looks like this:

javaw -jar "%JEDIT_HOME%\jedit.jar" -wait -norestore -noplugins -reuseview %*

I set my EDITOR and VISUAL to jeditcommit from my regular jEdit startup script, so it is used only from jEdit.

In summary, if your batch file includes these options, you use it as the EDITOR when you commit from the regular command line, or from jEdit's console, and svn will wait until you close the buffer before sending the log message and your changes to the repository.

Chapter 10. Extending the Console plugin

To add a shell to the console, a plugin must specify that it requires the Console plugin, and register a Shell implementation in the plugin's services.xml file.

Specifying dependencies

In order to give the user a helpful error message if the Console plugin is not installed, your plugin should specify dependency properties. If your plugin's core class is named MyPlugin, the corresponding dependencies might look like so:

plugin.MyPlugin.depend.2=plugin console.ConsolePlugin 4.2

Note that the current version of the Console plugin requires jEdit 4.2 final or later, so your plugin should also require at least that jEdit version. If a newer version of the Console plugin is available, you can specify higher version numbers than in the example above. However, all the API calls in this chapter are guaranteed to work with the above version, so in most cases you shouldn't worry about it.

Registering the plugin shells

(new to Jedit 4.2) To make the Console plugin aware of your plugin's shell, define a services.xml file containing a service element with these attributes:

  1. class="console.Shell"

  2. NAME=YourPlugin

The element itself should contain BeanShell code which creates a new instance of your Shell-derived class. Here is an example of how the SshConsole plugin registers a shell with Console:

<?xml version="1.0"?>
    <SERVICE CLASS="console.Shell" NAME="ssh">
         new console.ssh.Shell();
The Shell interface

Shell is an abstract class. It contains a constructor that takes one parameter, which is the name of the shell to display in the console window and various other places:

  • public Shell (String name );

A singleton Shell instance, shared by all Views and Consoles is created by the Console once at the plugin load-time, for each Shell service found. Most of the Shell methods have a first parameter which provides the Console instance, to distinguish between multiple consoles. This class defines the following abstract methods, which your shell must override:

  • public void printInfoMessage (Console console );

    This method is invoked by the console when the user selects the shell in question. It should print a short informational message, outlining the main capabilities of the shell.

  • public void execute (Console console ,
     String input ,
     Output output ,
     Output error ,
     String command );

    The execute() method is called when the user enters a command. The complete command line is passed in as one string; how it is parsed is entirely up to you.

    The output object provided is either an instance of ShellState or a special BufferOutput object if the user elected to have the command output go into a new buffer.

    As a convention, fatal errors (for example, parse errors in shell commands) should be sent to the error stream.

  • public void stop (Console console );

    If your shell executes commands in a separate thread, this method should stop the currently running thread, if any.

  • public boolean waitFor (Console console );

    This method should block until the currently running command has completed, and return true if the command executed successfully, false otherwise. If no command is currently running, it should return the status of the most recently run command.

The Output interface

The Output interface consists of the following three methods:

  • public void write (Color color ,
     String msg );

    This method writes a string to the output instance in question. Note that not all outputs support color - those that don't just ignore the color parameter.

  • public void print (Color color ,
     String msg );

    This method writes a string, followed by a newline.

  • public void commandDone (void); 

    Your shell should call this when a command has finished executing. The console window's implementation of this method stops the little animation.

In your own plugin, it is normally not necessary to extend or instantiate Outputs. Normally, plugins just use the instance passed to Shell.exec().

Where does the Output come from?

The Console maintains a shellStateMap, a 1:1 mapping of shell names to Console.ShellState instances. Console.ShellState is a concrete instance of Output which stores the Console's scrollback buffer. This is what gets passed to exec().

When you call console.setShell(String name), the shellState for that shell is automatically created and set. If you need an Output instance for a specific shell, from another part of your plugin, you can call console.getOutput() immediately after console.setShell().

Useful methods in the Console class

The following methods in the Console class can be used to obtain some useful default colors you can use in output:

  • public Color getErrorColor (void); 
  • public Color getWarningColor (void); 
  • public Color getInfoColor (void); 
Custom shells and error parsing

Most plugin shells will need to report compiler errors and such. To do this, you will first need to create and register an ErrorSource; see the ErrorList plugin documentation for details. You will also need to add the errors to the error source at some stage. There are two ways of doing this:

  • Manually, by having the shell check for appropriate error conditions, and add errors as necessary.

  • What is #2?

Appendix A. Change log

Click here to see the full changelog.