PageRenderTime 31ms CodeModel.GetById 13ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
XML | 719 lines | 614 code | 88 blank | 17 comment | 0 complexity | ef4ebe3dd45fc483380b4cf8bfde79c0 MD5 | raw file
  1<!-- jEdit 4.0 Macro Guide, (C) 2001, 2002 John Gellene -->
  2
  3<!-- jEdit buffer-local properties: -->
  4<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2: -->
  5
  6<!-- Tue Jun 19 18:36:20 EDT 2001 @983 /Internet Time/ -->
  7
  8<!-- This file covers the chapter "A few simple macros",        -->
  9<!-- which introduces BeanShell through a "Hello world" script. -->
 10<!-- It provides a little background on Java syntax and         -->
 11<!-- class structure.  A few simple methods and macros are also -->
 12<!-- discussed, as well as one-time macro execution features    -->
 13
 14<chapter id="simple-macros"><title>A Few Simple Macros</title>
 15
 16 <sect1 id="first-example" ><title>The Mandatory First Example</title>
 17  <informalexample><!-- <title>A first one-line macro</title> -->
 18   <programlisting>Macros.message(view, "Hello world!");</programlisting>
 19  </informalexample>
 20  <para>
 21   Running this one line script causes jEdit to display a message
 22   box (more precisely, a <classname>JOptionPane</classname> object) with
 23   the traditional beginner's message and an <guilabel>OK</guilabel> button.
 24   Let's see what is happening here.
 25  </para>
 26  <para>
 27   This statement calls a static method (or function) named
 28   <function>message</function> in jEdit's <classname>Macros</classname>
 29   class. If you don't know anything about classes or static methods or
 30   Java (or C++, which employs the same concept), you will need to gain
 31   some understanding of a few terms. Obviously this is not the place for
 32   academic precision, but if you are entirely new to object-oriented
 33   programming, here are a few skeleton ideas to help you with BeanShell.
 34  </para>
 35  <itemizedlist>
 36   <listitem>
 37    <para>
 38     An <glossterm>object</glossterm> is a collection of data that can be
 39     initialized, accessed and manipulated in certain defined ways.
 40    </para>
 41   </listitem>
 42
 43   <listitem>
 44    <para>
 45     A <glossterm>class</glossterm> is a specification of what data an object
 46     contains and what methods can be used to work with the data. A Java
 47     application consists of one or more classes (in the case of jEdit ,over
 48     500 classes) written by the programmer that defines the application's
 49     behavior. A BeanShell macro uses these classes, along with built-in
 50     classes that are supplied with the Java platform, to define its own
 51     behavior.
 52    </para>
 53   </listitem>
 54
 55   <listitem>
 56    <para>
 57     A <glossterm>subclass</glossterm> (or child class) is a class which
 58     uses (or <quote>inherits</quote>) the data and methods of its parent
 59     class along with additions or modifications that alter the subclass's
 60     behavior.  Classes are typically organized in hierarchies of parent
 61     and child classes to organize program code, to define common
 62     behavior in shared parent class code, and to specify the types of
 63     similar behavior that child classes will perform in their own specific ways.
 64    </para>
 65   </listitem>
 66
 67   <listitem>
 68    <para>
 69     A <glossterm>method</glossterm> (or function) is a procedure that works
 70     with data in a particular object, other data (including other objects)
 71     supplied as <glossterm>parameters</glossterm>, or both. Methods
 72     typically are applied to a particular object which is an
 73     <glossterm>instance</glossterm> of the class to which the method
 74     belongs.
 75    </para>
 76   </listitem>
 77
 78   <listitem>
 79    <para>
 80     A <glossterm>static method</glossterm> differs from other methods
 81     in that it does not deal with the data in a particular object but is
 82     included within a class for the sake of convenience.
 83    </para>
 84   </listitem>
 85
 86  </itemizedlist>
 87
 88  <para>
 89   Java has a rich set of classes defined as part of the Java platform.
 90   Like all Java applications, jEdit is organized as a set of classes that
 91   are themselves derived from the Java platform's classes. We will refer
 92   to <firstterm>Java classes</firstterm> and <firstterm>jEdit
 93   classes</firstterm> to make this distinction. Some of jEdit's classes
 94   (such as those dealing with regular expressions and XML) are derived
 95   from or make use of classes in other open-source Java packages. Except
 96   for BeanShell itself, we won't be discussing them in this guide.
 97  </para>
 98
 99  <para>
100   In our one line script, the static method
101   <function>Macros.message()</function> has two parameters because that is
102   the way the method is defined in the <classname>Macros</classname>
103   class. You must specify both parameters when you call the function. The
104   first parameter, <parameter>view</parameter>, is a a variable naming a
105   <classname>View</classname> object - an instance of jEdit's
106   <classname>View</classname> class. A <classname>View</classname>
107   represents a <quote>parent</quote> or top-level frame window that
108   contains the various visible components of the program, including the
109   text area, menu bar, toolbar, and any docked windows. It is a
110   subclass of Java's <classname>JFrame</classname> class.
111   With jEdit, you can create and display multiple views simultaneously.
112   The variable <varname>view</varname> is predefined for purposes of
113   BeanShell scripts as the current, active <classname>View</classname> object.
114   This is in fact the variable you want to specify as the first parameter.
115   Normally you would not want to associate a message box with anything
116   other than the current <classname>View</classname>.
117  </para>
118
119  <para>
120   The second parameter, which appears to be quoted text, is a
121   <glossterm>string literal</glossterm> - a sequence of characters of
122   fixed length and content. Behind the scenes, BeanShell and Java take
123   this string literal and use it to create a <classname>String</classname>
124   object. Normally, if you want to create an object in Java or BeanShell,
125   you must construct the object using the <function>new</function> keyword
126   and a <firstterm>constructor</firstterm> method that is part of the
127   object's class. We'll show an example of that later. However, both Java
128   and BeanShell let you use a string literal anytime a method's parameter
129   calls for a <classname>String</classname>.
130  </para>
131
132  <para>
133   If you are a Java programmer, you might wonder about a few things
134   missing from this one line program. There is no class definition, for
135   example. You can think of a BeanShell script as an implicit definition
136   of a <function>main()</function> method in an anonymous class. That is
137   in fact how BeanShell is implemented; the class is derived from
138   a BeanShell class called <classname>XThis</classname>. If you
139   don't find that helpful, just think of a script as one or more blocks of
140   procedural statements conforming to Java syntax rules. You will also get
141   along fine (for the most part) with C or C++ syntax if you leave out
142   anything to do with pointers or memory management - Java and BeanShell
143   do not have pointers and deal with memory management automatically.
144  </para>
145
146  <para>
147    Another missing item from a Java perspective is a
148    <function>package</function> statement. In Java, such a statement is
149    used to bundle together a number of files so that their classes become
150    visible to one another. Packages are not part of BeanShell,
151    and you don't need to know anything about them to write
152    BeanShell macros.
153  </para>
154
155  <para>
156    Finally, there are no <function>import</function> statements in this
157    script. In Java, an <function>import</function> statement makes public
158    classes from other packages visible within the file in which the
159    statement occurs without having to specify a fully
160    qualified class name. Without an import statement or a fully qualified
161    name, Java cannot identify most classes using a single name as an identifier.
162  </para>
163
164  <para>
165   jEdit automatically imports a number of commonly-used packages into the
166   namespace of every BeanShell script. Because of this, the script output
167   of a recorded macro does not contain <function>import</function>
168   statements. For the same reason, most BeanShell scripts you write will
169   not require <function>import</function> statements.
170  </para>
171
172  <para>
173    Java requires <literal>import</literal> statement at the beginning of a
174    source file. BeanShell allows you to place <literal>import</literal>
175    statements anywhere in a script, including inside a block of
176    statements. The <literal>import</literal> statement will cover all names
177    used following the statement in the enclosing block.
178  </para>
179
180  <para>
181    If you try to use a class that is not imported without its
182    fully-qualified name, the BeanShell interpreter will complain with an
183    error message relating to the offending line of code.
184  </para>
185
186  <sidebar>
187   <para>
188    Here is the full list of packages automatically imported by jEdit:
189   </para>
190   <programlisting>java.awt
191java.awt.event
192java.net
193java.util
194java.io
195java.lang
196javax.swing
197javax.swing.event
198org.gjt.sp.jedit
199org.gjt.sp.jedit.browser
200org.gjt.sp.jedit.buffer
201org.gjt.sp.jedit.gui
202org.gjt.sp.jedit.io
203org.gjt.sp.jedit.msg
204org.gjt.sp.jedit.options
205org.gjt.sp.jedit.pluginmgr
206org.gjt.sp.jedit.search
207org.gjt.sp.jedit.syntax
208org.gjt.sp.jedit.textarea
209org.gjt.sp.util</programlisting>
210  </sidebar>
211 </sect1>
212
213 <sect1 id="helpful-methods"><title>Helpful Methods in the
214  Macros Class</title>
215
216  <para>
217   Including <function>message()</function>, there are five static methods
218   in the <classname>Macros</classname> class that allow you to converse
219   easily with your macros. They all encapsulate calls to methods of the
220   Java platform's <classname>JOptionPane</classname> class.
221  </para>
222
223  <itemizedlist>
224
225    <listitem>
226      <funcsynopsis>
227         <funcprototype>
228           <funcdef>public static void <function>message</function></funcdef>
229           <paramdef>Component <parameter>comp</parameter></paramdef>
230           <paramdef>String <parameter>message</parameter></paramdef>
231         </funcprototype>
232       </funcsynopsis>
233     </listitem>
234
235     <listitem>
236       <funcsynopsis>
237         <funcprototype>
238          <funcdef>public static void <function>error</function></funcdef>
239          <paramdef>Component <parameter>comp</parameter></paramdef>
240          <paramdef>String <parameter>message</parameter></paramdef>
241         </funcprototype>
242       </funcsynopsis>
243     </listitem>
244
245     <listitem>
246      <funcsynopsis>
247        <funcprototype>
248          <funcdef>public static String <function>input</function></funcdef>
249          <paramdef>Component <parameter>comp</parameter></paramdef>
250          <paramdef>String <parameter>prompt</parameter></paramdef>
251        </funcprototype>
252      </funcsynopsis>
253     </listitem>
254
255     <listitem>
256      <funcsynopsis>
257        <funcprototype>
258          <funcdef>public static String <function>input</function></funcdef>
259          <paramdef>Component <parameter>comp</parameter></paramdef>
260          <paramdef>String <parameter>prompt</parameter></paramdef>
261          <paramdef>String <parameter>defaultValue</parameter></paramdef>
262        </funcprototype>
263      </funcsynopsis>
264     </listitem>
265
266     <listitem>
267      <funcsynopsis>
268        <funcprototype>
269          <funcdef>public static int <function>confirm</function></funcdef>
270          <paramdef>Component <parameter>comp</parameter></paramdef>
271          <paramdef>String <parameter>prompt</parameter></paramdef>
272          <paramdef>int <parameter>buttons</parameter></paramdef>
273        </funcprototype>
274      </funcsynopsis>
275     </listitem>
276
277  </itemizedlist>
278
279  <para>
280    The format of these four <glossterm>declarations</glossterm> provides a
281    concise reference to the way in which the methods may be used. The
282    keyword <function>public</function> means that the method can be used
283    outside the <classname>Macros</classname> class. The alternatives are
284    <function>private</function> and <function>protected</function>. For
285    purposes of BeanShell, you just have to know that BeanShell can only use
286    public methods of other Java classes. The keyword
287    <function>static</function> we have already discussed. It means that the
288    method does not operate on a particular object. You call a static
289    function using the name of the class (like
290    <classname>Macros</classname>) rather than the name of a particular
291    object (like <varname>view</varname>). The third word is the type of the
292    value returned by the method. The keyword <function>void</function> is
293    Java's way of saying the the method does not have a return value.
294  </para>
295
296  <para>
297   The <function>error()</function> method works just like
298   <function>message()</function> but displays an error icon in the message
299   box. The <function>input()</function> method furnishes a text field for
300   input, an <guilabel>OK</guilabel> button and a
301   <guilabel>Cancel</guilabel> button. If <guilabel>Cancel</guilabel> is pressed,
302   the method returns <constant>null</constant>. If <guilabel>OK</guilabel>
303   is pressed, a <classname>String</classname> containing the contents of
304   the text field is returned. Note that there are two forms of the
305   <function>input()</function> method; the first form with two parameters
306   displays an empty input field, the other forms lets you specify an initial,
307   default input value.
308  </para>
309
310  <para>
311   For those without Java experience, it is important to know that
312   <constant>null</constant> is <emphasis>not</emphasis> the same as an
313   empty, <quote>zero-length</quote> <classname>String</classname>. It is
314   Java's way of saying that there is no object associated with this
315   variable. Whenever you seek to use a return value from
316   <function>input()</function> in your macro, you should test it to see if
317   it is <constant>null</constant>. In most cases, you will
318   want to exit gracefully from the script with a
319   <function>return</function> statement, because the presence of a null
320   value for an input variable usually means that the user intended to
321   cancel macro execution. BeanShell will complain if you call any
322   methods on a <constant>null</constant> object.
323  </para>
324
325  <para>
326   The <function>confirm()</function> method in the
327   <classname>Macros</classname> class is a little more complex. The
328   <varname>buttons</varname> parameter has an <classname>int</classname>
329   type, and the usual way to supply a value is to use one of
330   the predefined values taken from Java's
331   <classname>JOptionPane</classname> class. You can choose among
332   <constant>JOptionPane.YES_NO_OPTION</constant>,
333   <constant>JOptionPane.YES_NO_CANCEL_OPTION</constant>, or
334   <constant>JOptionPane.OK_CANCEL_OPTION</constant>. The return
335   value of the method is also an <classname>int</classname>, and should be tested
336   against the value of other predefined constants:
337   <constant>JOptionPane.YES_OPTION</constant>,
338   <constant>JOptionPane.NO_OPTION</constant>,
339   <constant>JOptionPane.OK_OPTION</constant> or
340   <constant>JOptionPane.CANCEL_OPTION</constant>.
341  </para>
342
343  <para>
344   We've looked at using <function>Macros.message()</function>. To
345   use the other methods, you would write something like the
346   following:
347  </para>
348
349  <informalexample><!-- <title>Using <function>Macros.error()</function> and
350  <function>Macros.input()</function></title> -->
351   <programlisting>Macros.error(view, "Goodbye, cruel world!");
352
353String result = Macros.input(view, "Type something here.");
354
355String result = Macros.input(view, "When were you born?",
356    "I don't remember, I was very young at the time");
357
358int result = Macros.confirm("Do you really want to learn"
359    + " about BeanShell?",JOptionPane.YES_NO_OPTION);
360    </programlisting>
361  </informalexample>
362
363  <para>
364    In the last three examples, placing the word <classname>String</classname>
365    or <classname>int</classname>
366    before the variable name <varname>result</varname> tells BeanShell that
367    the variable refers to an integer or a <classname>String</classname> object, even
368    before a particular value is assigned to the variable.
369    In BeanShell, this <glossterm>declaration</glossterm> of the
370    <glossterm>type</glossterm> of <varname>result</varname> is not
371    necessary; BeanShell can figure it out when the macro runs. This can be
372    helpful if you are not comfortable with specifying types and classes;
373    just use your variables and let BeanShell worry about it.
374  </para>
375
376  <para>
377    Without an explicit <glossterm>type declaration</glossterm> like
378    <classname>String</classname> <varname>result</varname>, BeanShell
379    variables can change their type at runtime depending on the object or
380    data assigned to it. This dynamic typing allows you to write code like
381    this (if you really wanted to):
382  </para>
383
384  <informalexample><!-- <title>Dynamic typing of variables</title> -->
385   <programlisting>// note: no type declaration
386result = Macros.input(view, <quote>Type something here.</quote>);
387
388// this is our predefined, current View
389result = view;
390
391// this is an <quote>int</quote> (for integer);
392// in Java and BeanShell, int is one of a small number
393// of <quote>primitive</quote> data types which are not classes
394result = 14;</programlisting>
395  </informalexample>
396
397  <para>
398    However, if you first declared <varname>result</varname> to be type
399    <classname>String</classname> and and then tried these reassignments,
400    BeanShell would complain. While avoiding explicit type declaration makes
401    writing macro code simpler, using them can act as a check to make sure you are
402    not using the wrong variable type of object at a later point in your
403    script. It also makes it easier (if you are so inclined) to take a
404    BeanShell <quote>prototype</quote> and incorporate it in a Java program.
405  </para>
406
407  <para>
408    One last thing before we bury our first macro. The double slashes in the
409    examples just above signify that everything following them on that line
410    should be ignored by BeanShell as a comment. As in Java and C/C++, you
411    can also embed comments in your BeanShell code by setting them off with
412    pairs of <userinput>/* */</userinput>, as in the following example:
413  </para>
414
415
416  <informalexample>
417   <programlisting>/* This is a long comment that covers several lines
418and will be totally ignored by BeanShell regardless of how
419many lines it covers */</programlisting>
420  </informalexample>
421 </sect1>
422
423 <sect1 id="something-useful"><title>Now For Something Useful</title>
424
425  <para>
426    Here is a macro that inserts the path of the current buffer in
427    the text:
428  </para>
429
430
431  <informalexample>
432  <!-- <title>Insert buffer path in text</title> -->
433   <programlisting>String newText = buffer.getPath();
434textArea.setSelectedText(newText);</programlisting>
435  </informalexample>
436
437  <para>
438    Two of the new names we see here, <varname>buffer</varname> and
439    <varname>textArea</varname>, are predefined variables like
440    <varname>view</varname>. The variable <varname>buffer</varname>
441    represents a jEdit <varname>Buffer</varname> object, and
442    <varname>textArea</varname> represents a
443    <classname>JEditTextArea</classname> object.
444  </para>
445
446  <itemizedlist>
447    <listitem>
448      <para>
449        A <classname>Buffer</classname> object represents the contents of an open text
450        file. The variable <varname>buffer</varname> is predefined as the
451        current, visible buffer being edited.
452      </para>
453    </listitem>
454    <listitem>
455      <para>
456        A <classname>JEditTextArea</classname> is the visible component that
457        displays the file being edited. It is derived from the
458        <classname>JComponent</classname> class. The variable
459        <varname>textArea</varname> represents the current
460        <classname>JEditTextArea</classname> object, which in turn displays
461        the current buffer.
462      </para>
463    </listitem>
464  </itemizedlist>
465
466  <para>
467    Unlike in our first macro example, here we are calling class methods on
468    particular objects. First, we call <function>getPath()</function> on the
469    current <classname>Buffer</classname> object to get the full path of the
470    text file currently being edited. Next, we call
471    <function>setSelectedText()</function> on the current text display
472    component, specifying the text to be inserted as a parameter.
473  </para>
474
475  <para>
476    In precise terms, the <function>setSelectedText()</function> method
477    substitutes the contents of the <classname>String</classname>
478    parameter for a range of selected text that includes the current caret
479    position. If no text is selected at the caret position, the effect
480    of this operation is simply to insert the new text at that position.
481  </para>
482
483  <para>
484    Here's a few alternatives to the full file path that you could
485    use to insert various useful things:
486  </para>
487
488
489  <informalexample><!-- <title>Items to use with
490  <function>setSelectedText()</function></title> -->
491<programlisting>// the file name (without full path)
492String newText = buffer.getName();
493
494// today's date
495import java.text.DateFormat;
496
497String newText = DateFormat.getDateInstance()
498    .format(new Date());
499
500// a line count for the current buffer
501String newText = "This file contains "
502    + textArea.getLineCount() + " lines.";</programlisting>
503</informalexample>
504
505  <para>
506    Here are brief comments on each:
507  </para>
508
509  <itemizedlist>
510   <listitem>
511    <para>
512      In the first, the call to <function>getName()</function> invokes
513      another method of the <classname>Buffer</classname> class.
514    </para>
515   </listitem>
516
517   <listitem>
518    <para>
519      The syntax of the second example chains the results of
520      several methods. You could write it this way:
521    </para>
522
523<programlisting>import java.text.DateFormat;
524Date d = new Date();
525DateFormat df = DateFormat.getDateInstance();
526String result = df.format(d);
527</programlisting>
528
529   <para>
530	  Taking the pieces in order:
531   </para>
532
533   <itemizedlist>
534	   <listitem>
535	     <para>
536         A Java <classname>Date</classname> object is created using the
537         <function>new</function> keyword. The empty parenthesis after
538         <classname>Date</classname> signify a call on the <glossterm>
539         constructor method</glossterm> of <classname>Date</classname> having no
540         parameters; here, a <classname>Date</classname> is created representing
541         the current date and time.
542       </para>
543	   </listitem>
544
545	   <listitem>
546	     <para>
547         <function>DateFormat.getDateInstance()</function> is a static method
548         that creates and returns a <classname>DateFormat</classname> object. As
549         the name implies, <classname>DateFormat</classname> is a Java class
550         that takes <classname>Date</classname> objects and produces readable
551         text. The method <function>getDateInstance()</function> returns a
552         <classname>DateFormat</classname> object that parses and formats dates.
553         It will use the default <glossterm>locale</glossterm> or text format
554         specified in the user's Java installation.
555       </para>
556	  </listitem>
557
558	  <listitem>
559	    <para>
560        Finally, <classname>DateFormat.format()</classname> is called on the
561        new <classname>DateFormat</classname> object using the
562        <classname>Date</classname> object as a parameter. The result is a
563        <classname>String</classname> containing the date in the default
564        locale.
565      </para>
566	  </listitem>
567
568    <listitem>
569      <para>
570        Note that the <classname>Date</classname> class is contained in
571        the <literal>java.util</literal> package, so an explicit import
572        statement is not required. However, <classname>DateFormat</classname>
573        is part of the <literal>java.text</literal> package, which is
574        not automatically imported, so an explicit
575        <function>import</function> statement must be used.
576      </para>
577    </listitem>
578	</itemizedlist>
579
580   </listitem>
581
582   <listitem>
583    <para>
584    The third example shows three items of note:
585	 <itemizedlist>
586	  <listitem>
587	   <para>
588       <function>getLineCount()</function> is a method in jEdit's
589       <classname>JEditTextArea</classname> class. It returns an
590       <classname>int</classname> representing the number of lines in the
591       current text buffer. We call it on <varname>textArea</varname>, the
592       pre-defined, current <classname>JEditTextArea</classname> object.
593      </para>
594	  </listitem>
595
596	  <listitem>
597	   <para>
598       The use of the <function>+</function> operator (which can be chained,
599       as here) appends objects and string
600       literals to return a single, concatenated <classname>String</classname>.
601       </para>
602	  </listitem>
603	 </itemizedlist>
604   </para>
605   </listitem>
606  </itemizedlist>
607
608  <sidebar><title>The other pre-defined variable</title>
609   <para>
610    In addition to <varname>view</varname>, <varname>buffer</varname> and
611    <varname>textArea</varname>, there is one more pre-defined variable
612    available for use in macros -- <varname>editPane</varname>. That
613    variable is set to the current <classname>EditPane</classname> instance.
614    An <classname>EditPane</classname> object contains a text area and
615    buffer switcher. A view can be split to display multiple
616    buffers, each in its own edit pane. Among other things, the
617    <classname>EditPane</classname> class contains methods for selecting
618    the buffer to edit.
619   </para>
620   <para>
621    Most of the time your macros will manipulate the <varname>buffer</varname>
622    or the <varname>textArea</varname>. Sometimes you will need to use
623    <varname>view</varname> as a parameter in a method call. You will probably
624    only need to use <varname>editPane</varname> if your macros work with
625    split views.
626   </para>
627  </sidebar>
628 </sect1>
629
630<!-- moved from introductory chapter in 3.2 macro guide -->
631
632 <sect1 id="single-macros"><title>Single Execution Macros</title>
633  <para>
634   At this point, we have covered some basic techniques for writing
635   one-line or other short macros. As noted earlier, you can save a BeanShell
636   script of any length as a text file with the <filename>.bsh</filename>
637   extension. There are three other ways jEdit lets you use BeanShell quickly,
638   without saving a script to storage, on a <quote>one time only</quote>
639   basis. You will find them in the <guimenu>Utilities</guimenu> menu.
640  </para>
641
642  <para>
643   <guimenu>Utilities</guimenu>&gt;<guisubmenu>BeanShell</guisubmenu>&gt;<guimenuitem>Evaluate BeanShell
644   Expression</guimenuitem> displays a text input dialog
645   that asks you to type a single line of BeanShell commands. You can type
646   more than one BeanShell statement so long as each of them ends with a
647   semicolon. If BeanShell successfully interprets your input, a message
648   box will appear with the return value of the last statement. You can do
649   the same thing using the BeanShell interpreter provided with the
650   <application>Console</application> plugin; the return value will appear
651   in the output window.
652  </para>
653
654  <para>
655   <guimenu>Utilities</guimenu>&gt;<guisubmenu>BeanShell</guisubmenu>&gt;<guimenuitem>Evaluate For Selected
656   Lines</guimenuitem> displays a text input dialog that asks you to
657   type a single line of BeanShell commands. The commands are evaluated
658   for each line of the selection. In addition to the standard set of
659   variables, this command defines the following:
660  </para>
661
662  <itemizedlist>
663   <listitem><para><varname>line</varname> - the line number, from the
664   start of the buffer. The first line is numbered 0.
665   </para></listitem>
666   <listitem><para><varname>index</varname> - the line number, from the
667   start of the selection. The first line is numbered 0.
668   </para></listitem>
669   <listitem><para><varname>text</varname> - the text of the line.
670   </para></listitem>
671  </itemizedlist>
672
673  <informalexample>
674   <para>
675    Try typing an expression like <userinput>(line + 1) + ": " + text</userinput>
676    in the <guimenuitem>Evaluate For Selected Lines</guimenuitem> dialog
677    box. This will add a line number to each selected line beginning with
678    the number <userinput>1</userinput>.
679   </para>
680  </informalexample>
681
682  <para>
683    The BeanShell expression you enter will be evaluated and substituted in place of
684    the entire text of a selected line.  If you want to leave the line's current
685    text as an element of the modified line, you must include the defined variable
686    <userinput>text</userinput> as part of the BeanShell expression that you enter.
687  </para>
688
689  <para>
690   <guimenu>Utilities</guimenu>&gt;<guisubmenu>BeanShell</guisubmenu>&gt;<guimenuitem>Evaluate Selection</guimenuitem>
691   evaluates the selected text as a BeanShell script and
692   replaces it with the return value of the statement.
693  </para>
694
695  <para>
696    Using <guimenuitem>Evaluate Selection</guimenuitem> is an
697    easy way to do arithmetic calculations inline while editing. BeanShell
698    uses numbers and arithmetic operations in an ordinary, intuitive way.
699  </para>
700
701  <informalexample>
702   <para>
703    Try typing an expression like <userinput>(3745*856)+74</userinput>
704    in the buffer, select it, and choose
705    <guimenu>Utilities</guimenu>&gt;<guisubmenu>BeanShell</guisubmenu>&gt;<guimenuitem>Evaluate
706    Selection</guimenuitem>. The selected text will be replaced by the
707    answer, <userinput>3205794</userinput>.
708
709    <!-- Irrelevant? -->
710    <!-- Since this is a text file
711    and not a spreadsheet, the original values that BeanShell evaluated are
712    not retained or saved as part of the buffer's contents. -->
713   </para>
714  </informalexample>
715
716 </sect1>
717
718</chapter>
719