/jEdit/tags/jedit-4-0-pre5/doc/users-guide/simple-macros.xml

<!-- jEdit 3.2 Macro Guide, (C) 2001 John Gellene -->

<!-- jEdit buffer-local properties: -->
<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2: -->

<!-- Tue Jun 19 18:36:20 EDT 2001 @983 /Internet Time/ -->

<!-- This file covers the chapter "A few simple macros",        -->
<!-- which introduces BeanShell through a "Hello world" script. -->
<!-- It provides a little background on Java syntax and         -->
<!-- class structure.  A few simple methods and macros are also -->
<!-- discussed.                                                 -->

<chapter id="simple-macros"><title>A Few Simple Macros</title>

 <sect1 id="first-example"><title>The Mandatory First Example</title>
  <informalexample><!-- <title>A first one-line macro</title> -->
   <programlisting>Macros.message(view, "Hello world!");</programlisting>
  </informalexample>
  <para>
   Running this one line script causes jEdit to display a message
   box (more precisely, a <classname>JOptionPane</classname> object) with
   the traditional beginner's message and an <guilabel>OK</guilabel> button.
   Let's see what is happening here.
  </para>
  <para>
   This statement calls a static method (or function) named
   <function>message</function> in jEdit's <classname>Macros</classname>
   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.
  </para>
  <itemizedlist>
   <listitem>
    <para>
     An <glossterm>object</glossterm> is a collection of data that can be
     initialized, accessed and manipulated in certain defined ways.
    </para>
   </listitem>

   <listitem>
    <para>
     A <glossterm>class</glossterm> is a specification of what data an object
     contains and what methods can be used to work with the data. A Java
     application consists of one or more classes (in the case of jEdit over
     200 classes) written by the programmer that defines the application's
     behavior. A BeanShell macro uses these classes, along with built-in
     classes that are supplied with the Java platform, to define its own
     behavior.
    </para>
   </listitem>

   <listitem>
    <para>
     A <glossterm>subclass</glossterm> (or child class) is a class which
     uses (or <quote>inherits</quote>) the data and methods of its parent
     class along with additions or modifications that alter the subclass's
     behavior.  Classes are typically organized in hierarchies of parent
     and child classes to organize program code, to define common
     behavior in shared parent class code, and to specify the types of
     similar behavior that child classes will perform in their own specific ways.
    </para>
   </listitem>

   <listitem>
    <para>
     A <glossterm>method</glossterm> (or function) is a procedure that works
     with data in a particular object, other data (including other objects)
     supplied as <glossterm>parameters</glossterm>, or both. Methods
     typically are applied to a particular object which is an
     <glossterm>instance</glossterm> of the class to which the method
     belongs.
    </para>
   </listitem>

   <listitem>
    <para>
     A <glossterm>static method</glossterm> differs from other methods
     in that it does not deal with the data in a particular object but is
     included within a class for the sake of convenience.
    </para>
   </listitem>

  </itemizedlist>

  <para>
   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 <firstterm>Java classes</firstterm> and <firstterm>jEdit
   classes</firstterm> 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.
  </para>

  <para>
   In our one line script, the static method
   <function>Macros.message()</function> has two parameters because that is
   the way the method is defined in the <classname>Macros</classname>
   class. You must specify both parameters when you call the function. The
   first parameter, <parameter>view</parameter>, is a a variable naming a
   <classname>View</classname> object - an instance of jEdit's
   <classname>View</classname> class. A <classname>View</classname>
   represents a <quote>parent</quote> or top-level frame window that
   contains the various visible components of the program, including the
   text area, menu bar, toolbar, and any docked windows. It is a
   subclass of Java's <classname>JFrame</classname> class.
   With jEdit, you can create and display multiple views simultaneously.
   The variable <varname>view</varname> is predefined for purposes of
   BeanShell as the current, active <classname>View</classname> object.
   This is in fact the variable you want to specify as the first parameter.
   Normally you would not want to associate a message box with anything
   other than the current <classname>View</classname>.
  </para>

  <para>
   The second parameter, which appears to be quoted text, is a
   <glossterm>string literal</glossterm> - 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 <classname>String</classname>
   object. Normally, if you want to create an object in Java or BeanShell,
   you must construct the object using the <function>new</function> keyword
   and a <firstterm>constructor</firstterm> 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 <classname>String</classname>.
  </para>

  <para>
   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 <function>main()</function> method in an anonymous class. That is
   in fact how BeanShell is implemented; the class is derived from
   a BeanShell class called <classname>XThis</classname>. 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.
  </para>

  <para>
    Another missing item from a Java perspective is a
    <function>package</function> 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.
  </para>

  <para>
    Finally, there are no <function>import</function> statements in this
    script. In Java, an <function>import</function> 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.
  </para>

  <para>
   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 <function>import</function>
   statements. For the same reason, most BeanShell scripts you write will
   not require <function>import</function> statements.
  </para>

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

  <para>
    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.
  </para>

  <sidebar>
   <para>
    Here is the full list of packages automatically imported by jEdit:
   </para>
   <programlisting>java.awt
java.awt.event
java.net
java.util
java.io
java.lang
javax.swing
javax.swing.event
org.gjt.sp.jedit
org.gjt.sp.jedit.browser
org.gjt.sp.jedit.gui
org.gjt.sp.jedit.io
org.gjt.sp.jedit.msg
org.gjt.sp.jedit.options
org.gjt.sp.jedit.pluginmgr
org.gjt.sp.jedit.search
org.gjt.sp.jedit.syntax
org.gjt.sp.jedit.textarea
org.gjt.sp.util</programlisting>
  </sidebar>
 </sect1>

 <sect1 id="helpful-methods"><title>Helpful Methods in the
  Macros Class</title>

  <para>
   Including <function>message()</function>, there are five static methods
   in the <classname>Macros</classname> class that allow you to converse
   easily with your macros. They all encapsulate calls to methods of the
   Java platform's <classname>JOptionPane</classname> class.
  </para>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
         <funcprototype>
           <funcdef>public static void <function>message</function></funcdef>
           <paramdef>Component <parameter>comp</parameter></paramdef>
           <paramdef>String <parameter>message</parameter></paramdef>
         </funcprototype>
       </funcsynopsis>
     </listitem>

     <listitem>
       <funcsynopsis>
         <funcprototype>
          <funcdef>public static void <function>error</function></funcdef>
          <paramdef>Component <parameter>comp</parameter></paramdef>
          <paramdef>String <parameter>message</parameter></paramdef>
         </funcprototype>
       </funcsynopsis>
     </listitem>

     <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public static String <function>input</function></funcdef>
          <paramdef>Component <parameter>comp</parameter></paramdef>
          <paramdef>String <parameter>prompt</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
     </listitem>

     <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public static String <function>input</function></funcdef>
          <paramdef>Component <parameter>comp</parameter></paramdef>
          <paramdef>String <parameter>prompt</parameter></paramdef>
          <paramdef>String <parameter>defaultValue</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
     </listitem>

     <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public static int <function>confirm</function></funcdef>
          <paramdef>Component <parameter>comp</parameter></paramdef>
          <paramdef>String <parameter>prompt</parameter></paramdef>
          <paramdef>int <parameter>buttons</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
     </listitem>

  </itemizedlist>

  <para>
    The format of these four <glossterm>declarations</glossterm> provides a
    concise reference to the way in which the methods may be used. The
    keyword <function>public</function> means that the method can be used
    outside the <classname>Macros</classname> class. The alternatives are
    <function>private</function> and <function>protected</function>. For
    purposes of BeanShell, you just have to know that BeanShell can only use
    public methods of other Java classes. The keyword
    <function>static</function> we have already discussed. It means that the
    method does not operate on a particular object. You call a static
    function using the name of the class (like
    <classname>Macros</classname>) rather than the name of a particular
    object (like <varname>view</varname>). The third word is the type of the
    value returned by the method. The keyword <function>void</function> is
    Java's way of saying the the method does not have a return value.
  </para>

  <para>
   The <function>error()</function> method works just like
   <function>message()</function> but displays an error icon in the message
   box. The <function>input()</function> method furnishes a text field for
   input, an <guilabel>OK</guilabel> button and a
   <guilabel>Cancel</guilabel> button. If <quote>Cancel</quote> is pressed,
   the method returns <constant>null</constant>. If <guilabel>OK</guilabel>
   is pressed, a <classname>String</classname> containing the contents of
   the text field is returned. Note that there are two forms of the
   <function>input()</function> method; the first form with two parameters
   displays an empty input field, the other lets you specify an initial
   default value.
  </para>

  <para>
   The <function>confirm()</function> method is the trickiest. The
   <varname>buttons</varname> parameter should either be
   <constant>JOptionPane.YES_NO_OPTION</constant>,
   <constant>JOptionPane.YES_NO_CANCEL_OPTION</constant>, or
   <constant>JOptionPane.OK_CANCEL_OPTION</constant>. The return
   value of the method is one of
   <constant>JOptionPane.YES_OPTION</constant>,
   <constant>JOptionPane.NO_OPTION</constant>,
   <constant>JOptionPane.OK_OPTION</constant> or
   <constant>JOptionPane.CANCEL_OPTION</constant>.
  </para>

  <para>
   For those without Java experience, it is important to know that
   <constant>null</constant> is <emphasis>not</emphasis> the same as an
   empty, <quote>zero-length</quote> <classname>String</classname>. It is
   Java's way of saying that there is no object associated with this
   variable. Whenever you seek to use a return value from
   <function>input()</function> in your macro, you should test it to see if
   it is <constant>null</constant>. In most cases, you will
   want to exit gracefully from the script with a
   <function>return</function> statement, because the presence of a null
   value for an input variable usually means that the user intended to
   cancel macro execution. BeanShell will complain if you call any
   methods on a <constant>null</constant> object.
  </para>

  <para>
   We've looked at using <function>Macros.message()</function>. To
   use the other methods, you would write something like the
   following:
  </para>

  <informalexample><!-- <title>Using <function>Macros.error()</function> and
  <function>Macros.input()</function></title> -->
   <programlisting>Macros.error(view, "Goodbye, cruel world!");

String result = Macros.input(view, "Type something here.");

String result = Macros.input(view, "What is your name?",
    "John Gellene");</programlisting>
  </informalexample>

  <para>
    In the last two examples, placing the word <classname>String</classname>
    before the variable name <varname>result</varname> tells BeanShell that
    the variable refers to a <classname>String</classname> object, even
    before a particular <classname>String</classname> object is assigned to
    it. In BeanShell, this <glossterm>declaration</glossterm> of the
    <glossterm>type</glossterm> of <varname>result</varname> is not
    necessary; BeanShell can figure it out when the macro runs. This can be
    helpful if you are not comfortable with types and classes; just use your
    variables and let BeanShell worry about it.
  </para>

  <para>
    Without an explicit <glossterm>type declaration</glossterm> like
    <classname>String</classname> <varname>result</varname>, BeanShell
    variables can change their type at runtime depending on the object or
    data assigned to it. This dynamic typing allows you to write code like
    this (if you really wanted to):
  </para>

  <informalexample><!-- <title>Dynamic typing of variables</title> -->
   <programlisting>// note: no type declaration
result = Macros.input(view, <quote>Type something here.</quote>);

// this is our predefined, current View
result = view;

// this is an <quote>int</quote> (for integer);
// in Java and BeanShell, int is one of a small number
// of <quote>primitive</quote> data types which are not classes
result = 14;</programlisting>
  </informalexample>

  <para>
    However, if you first declared <varname>result</varname> to be type
    <classname>String</classname> and and then tried these reassignments,
    BeanShell would complain.
  </para>

  <para>
    One last thing before we bury our first macro. The double slashes in the
    examples just above signify that everything following them on that line
    should be ignored by BeanShell as a comment. As in Java and C/C++, you
    can also embed comments in your BeanShell code by setting them off with
    pairs of <userinput>/* */</userinput>, as in the following example:
  </para>


  <informalexample>
   <programlisting>/* This is a long comment that covers several lines
and will be totally ignored by BeanShell regardless of how
many lines it covers */</programlisting>
  </informalexample>
 </sect1>

 <sect1 id="something-useful"><title>Now For Something Useful</title>

  <para>
    Here is a macro that inserts the path of the current buffer in
    the text:
  </para>


  <informalexample>
  <!-- <title>Insert buffer path in text</title> -->
   <programlisting>String newText = buffer.getPath();
textArea.setSelectedText(newText);</programlisting>
  </informalexample>

  <para>
    Two of the new names we see here, <varname>buffer</varname> and
    <varname>textArea</varname>, are predefined variables like
    <varname>view</varname>. The variable <varname>buffer</varname>
    represents a jEdit <varname>Buffer</varname> object, and
    <varname>textArea</varname> represents a
    <classname>JEditTextArea</classname> object.
  </para>

  <itemizedlist>
    <listitem>
      <para>
        A <classname>Buffer</classname> represents the contents of an open text
        file. It is derived from Java's <classname>PlainDocument</classname>
        class. The variable <varname>buffer</varname> is predefined as the
        current buffer.
      </para>
    </listitem>
    <listitem>
      <para>
        A <classname>JEditTextArea</classname> is the visible component that
        displays the file being edited. It is derived from the
        <classname>JComponent</classname> class. The variable
        <varname>textArea</varname> represents the current
        <classname>JEditTextArea</classname> object, which in turn displays
        the current buffer.
      </para>
    </listitem>
  </itemizedlist>

  <para>
    Unlike in our first macro example, here we are calling class methods on
    particular objects. First, we call <function>getPath()</function> on the
    current <classname>Buffer</classname> object to get the full path of the
    text file currently being edited. Next, we call
    <function>setSelectedText()</function> on the current text display
    component, specifying the text to be inserted as a parameter.
  </para>

  <para>
    In precise terms, the <function>setSelectedText()</function> method
    substitutes the contents of the <classname>String</classname>
    parameter for a range of selected text that includes the current caret
    position. If no text is selected at the caret position, the effect
    of this operation is simply to insert the new text at that position.
  </para>

  <para>
    Here's a few alternatives to the full file path that you could
    use to insert various useful things:
  </para>


  <informalexample><!-- <title>Items to use with
  <function>setSelectedText()</function></title> -->
<programlisting>// the file name (without full path)
String newText = buffer.getName();

// today's date
import java.text.DateFormat;

String newText = DateFormat.getDateInstance()
    .format(new Date());

// a line count for the current buffer
String newText = "This file contains "
    + textArea.getLineCount() + " lines.";</programlisting>
</informalexample>

  <para>
    Here are brief comments on each:
  </para>

  <itemizedlist>
   <listitem>
    <para>
      In the first, the call to <function>getName()</function> invokes
      another method of the <classname>Buffer</classname> class.
    </para>
   </listitem>

   <listitem>
    <para>
      The syntax of the second example chains the results of
      several methods. You could write it this way:
    </para>

<programlisting>import java.text.DateFormat;
Date d = new Date();
DateFormat df = DateFormat.getDateInstance();
String result = df.format(d);
</programlisting>

   <para>
	  Taking the pieces in order:
   </para>

   <itemizedlist>
	   <listitem>
	     <para>
         A Java <classname>Date</classname> object is created using the
         <function>new</function> keyword. The empty parenthesis after
         <classname>Date</classname> signify a call on the <glossterm>
         constructor method</glossterm> of <classname>Date</classname> having no
         parameters; here, a <classname>Date</classname> is created representing
         the current date and time.
       </para>
	   </listitem>

	   <listitem>
	     <para>
         <function>DateFormat.getDateInstance()</function> is a static method
         that creates and returns a <classname>DateFormat</classname> object. As
         the name implies, <classname>DateFormat</classname> is a Java class
         that takes <classname>Date</classname> objects and produces readable
         text. The method <function>getDateInstance()</function> returns a
         <classname>DateFormat</classname> object that parses and formats dates.
         It will use the default <glossterm>locale</glossterm> or text format
         specified in the user's Java installation.
       </para>
	  </listitem>

	  <listitem>
	    <para>
        Finally, <classname>DateFormat.format()</classname> is called on the
        new <classname>DateFormat</classname> object using the
        <classname>Date</classname> object as a parameter. The result is a
        <classname>String</classname> containing the date in the default
        locale.
      </para>
	  </listitem>

    <listitem>
      <para>
        Note that the <classname>Date</classname> class is contained in
        the <literal>java.util</literal> package, so an explicit import
        statement is not required. However, <classname>DateFormat</classname>
        is part of the <literal>java.text</literal> package, which is
        not automatically imported, so an explicit
        <function>import</function> statement must be used.
      </para>
    </listitem>
	</itemizedlist>

   </listitem>

   <listitem>
    <para>
    The third example shows three items of note:
	 <itemizedlist>
	  <listitem>
	   <para>
       <function>getLineCount()</function> is a method in jEdit's
       <classname>JEditTextArea</classname> class. It returns an
       <type>int</type> representing the number of lines in the
       current text buffer. We call it on <varname>textArea</varname>, the
       pre-defined, current <classname>JEditTextArea</classname> object.
      </para>
	  </listitem>

	  <listitem>
	   <para>
       The use of the <function>+</function> operator (which can be chained,
       as here) appends objects and string
       literals to return a single, concatenated <classname>String</classname>.
       </para>
	  </listitem>
	 </itemizedlist>
   </para>
   </listitem>
  </itemizedlist>

  <sidebar><title>The other pre-defined variable</title>
   <para>
    In addition to <varname>view</varname>, <varname>buffer</varname> and
    <varname>textArea</varname>, there is one more pre-defined variable
    available for use in macros -- <varname>editPane</varname>. That
    variable is set to the current <classname>EditPane</classname> instance.
    An <classname>EditPane</classname> object contains a text area and
    buffer switcher. A view can be split to display multiple
    buffers, each in its own edit pane. Among other things, the
    <classname>EditPane</classname> class contains methods for selecting
    the buffer to edit.
   </para>
   <para>
    Most of the time your macros will manipulate the <varname>buffer</varname>
    or the <varname>textArea</varname>. Sometimes you will need to use
    <varname>view</varname> as a parameter in a method call. You will probably
    only need to use <varname>editPane</varname> if your macros work with
    split views.
   </para>
  </sidebar>
 </sect1>
</chapter>