The Mandatory First Example

Macros.message(view, "Hello world!");

Running this one line script causes jEdit to display a message box (more precisely, a JOptionPane object) with the traditional beginner's message and an OK button. Let's see what is happening here.

This statement calls a static method (or function) named message in jEdit's Macros class. If you don't know anything about classes or static methods or Java (or C++, which employs the same concept), you will need to gain some understanding of a few terms. Obviously this is not the place for academic precision, but if you are entirely new to object-oriented programming, here are a few skeleton ideas to help you with BeanShell.

Java has a rich set of classes defined as part of the Java platform. Like all Java applications, jEdit is organized as a set of classes that are themselves derived from the Java platform's classes. We will refer to Java classes and jEdit classes to make this distinction. Some of jEdit's classes (such as those dealing with regular expressions and XML) are derived from or make use of classes in other open-source Java packages. Except for BeanShell itself, we won't be discussing them in this guide.

In our one line script, the static method Macros.message() has two parameters because that is the way the method is defined in the Macros class. You must specify both parameters when you call the function. The first parameter, view, is a variable naming the current, active View object. Information about pre-defined variables can be found in the section called “Predefined Variables in BeanShell”.

The second parameter, which appears to be quoted text, is a string literal - a sequence of characters of fixed length and content. Behind the scenes, BeanShell and Java take this string literal and use it to create a String object. Normally, if you want to create an object in Java or BeanShell, you must construct the object using the new keyword and a constructor method that is part of the object's class. We'll show an example of that later. However, both Java and BeanShell let you use a string literal anytime a method's parameter calls for a String.

If you are a Java programmer, you might wonder about a few things missing from this one line program. There is no class definition, for example. You can think of a BeanShell script as an implicit definition of a main() method in an anonymous class. That is in fact how BeanShell is implemented; the class is derived from a BeanShell class called XThis. If you don't find that helpful, just think of a script as one or more blocks of procedural statements conforming to Java syntax rules. You will also get along fine (for the most part) with C or C++ syntax if you leave out anything to do with pointers or memory management - Java and BeanShell do not have pointers and deal with memory management automatically.

Another missing item from a Java perspective is a package statement. In Java, such a statement is used to bundle together a number of files so that their classes become visible to one another. Packages are not part of BeanShell, and you don't need to know anything about them to write BeanShell macros.

Finally, there are no import statements in this script. In Java, an import statement makes public classes from other packages visible within the file in which the statement occurs without having to specify a fully qualified class name. Without an import statement or a fully qualified name, Java cannot identify most classes using a single name as an identifier.

jEdit automatically imports a number of commonly-used packages into the namespace of every BeanShell script. Because of this, the script output of a recorded macro does not contain import statements. For the same reason, most BeanShell scripts you write will not require import statements.

Java requires import statement to be located at the beginning of a source file. BeanShell allows you to place import statements anywhere in a script, including inside a block of statements. The import statement will cover all names used following the statement in the enclosing block.

If you try to use a class that is not imported without its fully-qualified name, the BeanShell interpreter will complain with an error message relating to the offending line of code.