jEdit Console plugin user's guide

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 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:

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.

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:

Each console window has an associated "foreground process"; output produced by the foreground process is shown in that console window. Starting a new process while one is already running in the foreground will terminate the existing process.

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.

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.

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:

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

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

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

A few system shell built-ins invoke jEdit features:

The commando tool bar, which can be enabled in the Console>General pane of the Plugin Options dialog box, 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 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.

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

<?xml version="1.0"?>

<!DOCTYPE COMMANDO SYSTEM "commando.dtd">

<COMMANDO>
    ...
</COMMANDO>

<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" />

</CAPTION>

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

<DIR_ENTRY LABEL="Output directory" VARNAME="output" />

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

<FILE_ENTRY LABEL="Source file" VARNAME="source" />

<LONG_ENTRY LABEL="Comments" VARNAME="comments" />

<TOGGLE LABEL="Ignore case" VARNAME="ignoreCase" />

<TOGGLE_ENTRY LABEL="Additional file" VARNAME="ignoreCase"
    EVAL="buffer.getPath()"/>

<COMMAND CONFIRM="FALSE" SHELL="System">
    buf = new StringBuffer("jmk");

    if(!makefile.equals(""))
    {
     buf.append(" -f \"");
     buf.append(makefile);
     buf.append('"');
    }

    if(!targets.equals(""))
    {
     buf.append(' ');
     buf.append(targets);
    }

    if(debug)
     buf.append(" -d");

    if(norun)
     buf.append(" -n");

    if(output.equals("awt"))
     buf.append(" -w");

    if(output.equals("swing"))
     buf.append(" -s");

    // return value
    buf;
</COMMAND>

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.0=jedit 04.02.99.00
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.

(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:

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"?>
<!DOCTYPE SERVICES SYSTEM "services.dtd">
<SERVICES>
    <SERVICE CLASS="console.Shell" NAME="ssh">
         new console.ssh.Shell();
    </SERVICE>
 </SERVICES>

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:

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:

The Output interface consists of the following three methods:

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().

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

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: