Writing Commando files

Writing Commando files
Prev	Chapter 5. Commando	Next

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>

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

</CAPTION>

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

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"
    EVAL="buffer.getPath()"/>

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 - Of "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".

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:

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

Prev	Up	Next
The Commando window	Home	Chapter 6. Invoking compilers and interpreters