PageRenderTime 95ms CodeModel.GetById 85ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 1ms

/jEdit/tags/jedit-4-3-pre5/doc/users-guide/bsh-commands.xml

#
XML | 673 lines | 459 code | 67 blank | 147 comment | 0 complexity | 41316f49473f95c1e6b164566d6fd002 MD5 | raw file
  1<!-- jEdit 3.2 Macro Guide, (C) 2001 John Gellene                -->
  2<!-- Thu Jun 21 23:49:14 EDT 2001 @200 /Internet Time/           -->
  3<!--                                                             -->
  4<!-- jEdit buffer-local properties:                              -->
  5<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2:           -->
  6<!-- :xml.root=users-guide.xml:                                  -->
  7
  8<chapter id="bsh-commands"><title>BeanShell Commands</title>
  9
 10<para>
 11  BeanShell includes a set of <firstterm>commands</firstterm>;
 12  subroutines that
 13  can be called from any script or macro.  The following is a summary of
 14  those commands which may be useful within jEdit.
 15</para>
 16
 17<note>
 18 <para>
 19  Java classes in plugins cannot make use of BeanShell commands directly. However, these commands can be called from BeanShell code that is part of a plugin, for example the snippets in <filename>actions.xml</filename>, or any BeanShell scripts shipped with the plugin and loaded on startup.
 20 </para>
 21</note>
 22
 23<sect1 id="bsh-commands-output"><title>Output Commands</title>
 24
 25  <itemizedlist>
 26
 27    <!-- one day jEdit will provide its own error() implementation -->
 28    <!-- <listitem>
 29      <funcsynopsis>
 30        <funcprototype>
 31          <funcdef>void <function>error</function></funcdef>
 32          <paramdef>String <parameter>errorMsg</parameter></paramdef>
 33        </funcprototype>
 34      </funcsynopsis>
 35      <para>
 36        Writes the string represented by <parameter>errorMsg</parameter>
 37        to the error stream of the current process.
 38      </para>
 39    </listitem> -->
 40
 41    <listitem>
 42      <funcsynopsis>
 43        <funcprototype>
 44          <funcdef>void <function>cat</function></funcdef>
 45          <paramdef>String <parameter>filename</parameter></paramdef>
 46        </funcprototype>
 47      </funcsynopsis>
 48      <para>
 49        Writes the contents of <parameter>filename</parameter>
 50        to the activity log.
 51      </para>
 52    </listitem>
 53
 54    <listitem>
 55      <funcsynopsis>
 56        <funcprototype>
 57          <funcdef>void <function>javap</function></funcdef>
 58          <paramdef>String | Object | Class <parameter>target</parameter></paramdef>
 59        </funcprototype>
 60      </funcsynopsis>
 61      <para>
 62        Writes the public fields and methods of the specified class to
 63        the output stream of the current process.  Requires Java 2
 64        version 1.3 or greater.
 65      </para>
 66    </listitem>
 67
 68    <listitem>
 69      <funcsynopsis>
 70        <funcprototype>
 71          <funcdef>void <function>print</function></funcdef>
 72          <paramdef><parameter>arg</parameter></paramdef>
 73        </funcprototype>
 74      </funcsynopsis>
 75      <para>
 76        Writes the string value of the argument to the activity log,
 77        or if run from the <application>Console</application> plugin,
 78        to the current output window.  If <parameter>arg</parameter> is
 79        an array, <function>print</function> runs itself recursively
 80        on the array's elements.
 81      </para>
 82    </listitem>
 83
 84  </itemizedlist>
 85
 86</sect1>
 87
 88<sect1 id="bsh-commands-file"><title>File Management Commands</title>
 89
 90  <itemizedlist>
 91
 92    <listitem>
 93      <funcsynopsis>
 94        <funcprototype>
 95          <funcdef>void <function>cd</function></funcdef>
 96          <paramdef>String <parameter>dirname</parameter></paramdef>
 97        </funcprototype>
 98      </funcsynopsis>
 99      <para>
100        Changes the working directory of the BeanShell interpreter
101        to <parameter>dirname</parameter>.
102      </para>
103    </listitem>
104
105    <listitem>
106      <funcsynopsis>
107        <funcprototype>
108          <funcdef>void <function>cp</function></funcdef>
109          <paramdef>String <parameter>fromFile</parameter></paramdef>
110          <paramdef>String <parameter>toFile</parameter></paramdef>
111        </funcprototype>
112      </funcsynopsis>
113      <para>
114        Copy <parameter>fromFile</parameter> to <parameter>toFile</parameter>.
115      </para>
116    </listitem>
117
118    <listitem>
119      <funcsynopsis>
120        <funcprototype>
121          <funcdef>void <function>dir</function></funcdef>
122          <paramdef>String <parameter>dirname</parameter></paramdef>
123        </funcprototype>
124      </funcsynopsis>
125      <para>
126        Displays the contents of directory <parameter>dirname</parameter>.
127        The format of the display is similar to the Unix
128        <function>ls -l</function> command.
129      </para>
130    </listitem>
131
132    <listitem>
133      <funcsynopsis>
134        <funcprototype>
135          <funcdef>void <function>mv</function></funcdef>
136          <paramdef>String <parameter>fromFile</parameter></paramdef>
137          <paramdef>String <parameter>toFile</parameter></paramdef>
138        </funcprototype>
139      </funcsynopsis>
140      <para>
141        Moves the file named by <parameter>fromFile</parameter> to
142        <parameter>toFile</parameter>.
143      </para>
144    </listitem>
145
146    <listitem>
147      <funcsynopsis>
148        <funcprototype>
149          <funcdef>File <function>pathToFile</function></funcdef>
150          <paramdef>String <parameter>filename</parameter></paramdef>
151        </funcprototype>
152      </funcsynopsis>
153      <para>
154        Create a <classname>File</classname> object corresponding to
155        <function>filename</function>.  Relative paths are resolved with
156        reference to the BeanShell interpreter's working
157        directory.
158      </para>
159    </listitem>
160
161    <listitem>
162      <funcsynopsis>
163        <funcprototype>
164          <funcdef>void <function>pwd</function></funcdef>
165          <void/>
166        </funcprototype>
167      </funcsynopsis>
168      <para>
169        Writes the current working directory of the BeanShell interpreter
170        to the output stream of the current process.
171      </para>
172    </listitem>
173
174    <listitem>
175      <funcsynopsis>
176        <funcprototype>
177          <funcdef>void <function>rm</function></funcdef>
178          <paramdef>String <parameter>pathname</parameter></paramdef>
179        </funcprototype>
180      </funcsynopsis>
181      <para>
182        Deletes the file name by <parameter>pathname</parameter>.
183      </para>
184    </listitem>
185
186  </itemizedlist>
187
188</sect1>
189<sect1 id="bsh-commands-serial"><title>Component Commands</title>
190
191  <itemizedlist>
192
193    <listitem>
194      <funcsynopsis>
195        <funcprototype>
196          <funcdef>JFrame <function>frame</function></funcdef>
197          <paramdef>Component <parameter>frame</parameter></paramdef>
198        </funcprototype>
199      </funcsynopsis>
200      <para>
201        Displays the component in a top-level <classname>JFrame</classname>,
202        centered and packed.  Returns the <classname>JFrame</classname> object.
203      </para>
204    </listitem>
205
206    <listitem>
207      <funcsynopsis>
208        <funcprototype>
209          <funcdef>Object <function>load</function></funcdef>
210          <paramdef>String <parameter>filename</parameter></paramdef>
211        </funcprototype>
212      </funcsynopsis>
213      <para>
214        Loads and returns a serialized Java object from
215        <parameter>filename</parameter>.
216      </para>
217    </listitem>
218
219    <listitem>
220      <funcsynopsis>
221        <funcprototype>
222          <funcdef>void <function>save</function></funcdef>
223          <paramdef>Component <parameter>component</parameter></paramdef>
224          <paramdef>String <parameter>filename</parameter></paramdef>
225        </funcprototype>
226      </funcsynopsis>
227      <para>
228        Saves <parameter>component</parameter> in serialized form
229        to <parameter>filename</parameter>.
230      </para>
231    </listitem>
232
233    <listitem>
234      <funcsynopsis>
235        <funcprototype>
236          <funcdef>Font <function>setFont</function></funcdef>
237          <paramdef>Component <parameter>comp</parameter></paramdef>
238          <paramdef>int <parameter>ptsize</parameter></paramdef>
239        </funcprototype>
240      </funcsynopsis>
241      <para>
242        Set the font size of <parameter>component</parameter> to
243        <parameter>ptsize</parameter> and returns the new
244        font.
245      </para>
246    </listitem>
247
248  </itemizedlist>
249
250</sect1>
251
252
253<sect1 id="bsh-commands-resource">
254<title>Resource Management Commands</title>
255
256  <itemizedlist>
257
258    <listitem>
259      <funcsynopsis>
260        <funcprototype>
261          <funcdef>URL <function>getResource</function></funcdef>
262          <paramdef>String <parameter>path</parameter></paramdef>
263        </funcprototype>
264      </funcsynopsis>
265      <para>
266        Returns the resource specified by <parameter>path</parameter>.
267        An absolute path must be used to return any resource available in
268        the current classpath.
269      </para>
270    </listitem>
271
272    <!-- bsh.classpath not supported in jEdit -->
273    <!--
274    <listitem>
275      <funcsynopsis>
276        <funcprototype>
277          <funcdef>void <function>addClassPath</function></funcdef>
278          <paramdef>String <parameter>path</parameter></paramdef>
279        </funcprototype>
280      </funcsynopsis>
281    </listitem>
282
283    <listitem>
284      <funcsynopsis>
285        <funcprototype>
286          <funcdef>void <function>addClassPath</function></funcdef>
287          <paramdef>URL <parameter>path</parameter></paramdef>
288        </funcprototype>
289      </funcsynopsis>
290      <para>
291        Adds the directory or jar archive file specified by
292        <parameter>path</parameter> to the classpath used by the
293        interpreter.
294      </para>
295    </listitem>
296
297    <listitem>
298      <funcsynopsis>
299        <funcprototype>
300          <funcdef>void <function>setClassPath</function></funcdef>
301          <paramdef>URL[] <parameter>paths</parameter></paramdef>
302        </funcprototype>
303      </funcsynopsis>
304      <para>
305        Changes the classpath for the BeanShell interpreter to the specified
306        array of directories and/or archives.
307      </para>
308    </listitem>
309
310    <listitem>
311      <funcsynopsis>
312        <funcprototype>
313          <funcdef>URL[] <function>getClassPath</function></funcdef>
314          <void/>
315        </funcprototype>
316      </funcsynopsis>
317      <para>
318        Returns an array containing the current classpath.
319      </para>
320    </listitem>
321
322    <listitem>
323      <funcsynopsis>
324        <funcprototype>
325          <funcdef>void <function>reloadClasses</function></funcdef>
326          <paramdef>String <parameter>packagename</parameter></paramdef>
327        </funcprototype>
328      </funcsynopsis>
329    </listitem>
330
331    <listitem>
332      <funcsynopsis>
333        <funcprototype>
334          <funcdef>void <function>reloadClasses</function></funcdef>
335          <void/>
336        </funcprototype>
337      </funcsynopsis>
338      <para>
339        Reloads the class or package specified by
340        <parameter>packagename</parameter> in the BeanShell interpreter.
341        If called without a parameter, reloads all classes
342        in the interpreter's classpath.
343      </para>
344    </listitem>
345
346    <listitem>
347      <funcsynopsis>
348        <funcprototype>
349          <funcdef>Class <function>getClass</function></funcdef>
350          <paramdef>String <parameter>classname</parameter></paramdef>
351        </funcprototype>
352      </funcsynopsis>
353      <para>
354        This method is similar to the <function>Class.forName()</function>
355        method of the Java platform, but it uses the classpath of the
356        current BeanShell interpreter, which can contain additional
357        classes and packages as well as reloaded classes.
358      </para>
359    </listitem> -->
360
361  </itemizedlist>
362
363</sect1>
364
365<sect1 id="bsh-commands-script"><title>Script Execution Commands</title>
366
367  <itemizedlist>
368
369    <listitem>
370      <funcsynopsis>
371        <funcprototype>
372          <funcdef>Thread <function>bg</function></funcdef>
373          <paramdef>String <parameter>filename</parameter></paramdef>
374        </funcprototype>
375      </funcsynopsis>
376      <para>
377        Run the BeanShell script named by <parameter>filename</parameter>
378        in a copy of the existing namespace and in a separate thread.  Returns
379        the <classname>Thread</classname> object so created.
380      </para>
381    </listitem>
382
383    <listitem>
384      <funcsynopsis>
385        <funcprototype>
386          <funcdef>void <function>exec</function></funcdef>
387          <paramdef>String <parameter>cmdline</parameter></paramdef>
388        </funcprototype>
389      </funcsynopsis>
390      <para>
391        Start the external process by calling
392        <function>Runtime.exec()</function> on
393        <parameter>cmdline</parameter>. Any output is directed to the
394        output stream of the calling process.
395      </para>
396    </listitem>
397
398    <listitem>
399      <funcsynopsis>
400        <funcprototype>
401          <funcdef>Object <function>eval</function></funcdef>
402          <paramdef>String <parameter>expression</parameter></paramdef>
403        </funcprototype>
404      </funcsynopsis>
405      <para>
406        Evaluates the string <parameter>expression</parameter> as
407        a BeanShell script in the interpreter's current namespace.
408        Returns the result of the evaluation of <constant>null</constant>.
409      </para>
410    </listitem>
411
412    <listitem>
413      <funcsynopsis>
414        <funcprototype>
415          <funcdef>bsh.This <function>run</function></funcdef>
416          <paramdef>String <parameter>filename</parameter></paramdef>
417        </funcprototype>
418      </funcsynopsis>
419      <para>
420        Run the BeanShell script named by <parameter>filename</parameter>
421        in a copy of the existing namespace.  The return value represent
422        the object context of the script, allowing you to access its variables
423        and methods.
424      </para>
425    </listitem>
426
427    <listitem>
428      <funcsynopsis>
429        <funcprototype>
430          <funcdef>void <function>setAccessibility</function></funcdef>
431          <paramdef>boolean <parameter>flag</parameter></paramdef>
432        </funcprototype>
433      </funcsynopsis>
434      <para>
435        If <parameter>flag</parameter> is <literal>true</literal>,
436        BeanShell scripts are allowed to change and modify private variables, and call private methods. The default is <literal>false</literal>.
437      </para>
438    </listitem>
439
440    <listitem>
441      <funcsynopsis>
442        <funcprototype>
443          <funcdef>void <function>setStrictJava</function></funcdef>
444          <paramdef>boolean <parameter>flag</parameter></paramdef>
445        </funcprototype>
446      </funcsynopsis>
447      <para>
448        If <parameter>flag</parameter> is <literal>true</literal>,
449        BeanShell scripts must follow a much more strict, Java-like syntax, and are not able to use the convenience features described in <xref linkend="macro-tips-BeanShell-convenience" />.
450      </para>
451    </listitem>
452
453    <!-- <listitem>
454      <funcsynopsis>
455        <funcprototype>
456          <funcdef>void <function>server</function></funcdef>
457          <paramdef>int <parameter>port</parameter></paramdef>
458        </funcprototype>
459      </funcsynopsis>
460      <para>
461        Creates a <quote>server</quote> version of the BeanShell
462        interpreter that shares the same namespace as the current
463        interpreter.  The server interpreter listens on the designated
464        port.
465      </para>
466      <para>
467        This requires the <classname>bsh.util</classname> package, which
468        is not included with jEdit. It can be found in the stand-alone
469        BeanShell distribution, available from <ulink
470        url="http://www.beanshell.org">http://www.beanshell.org</ulink>.
471      </para>
472      <caution><para>
473        Security of this port is not guaranteed.  Use this command
474        with extreme caution.
475      </para></caution>
476    </listitem> -->
477
478    <listitem>
479      <funcsynopsis>
480        <funcprototype>
481          <funcdef>void <function>source</function></funcdef>
482          <paramdef>String <parameter>filename</parameter></paramdef>
483        </funcprototype>
484      </funcsynopsis>
485      <para>
486        Evaluates the contents of <parameter>filename</parameter>
487        as a BeanShell script in the interpreter's current namespace.
488      </para>
489    </listitem>
490
491  </itemizedlist>
492
493</sect1>
494
495<sect1 id="bsh-commands-object">
496<title>BeanShell Object Management Commands</title>
497
498  <itemizedlist>
499
500    <listitem>
501      <funcsynopsis>
502        <funcprototype>
503          <funcdef><function>bind</function></funcdef>
504          <paramdef>bsh.This <parameter>ths</parameter></paramdef>
505          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
506        </funcprototype>
507      </funcsynopsis>
508      <para>
509        Binds the scripted object <parameter>ths</parameter> to
510        <parameter>namespace</parameter>.
511      </para>
512    </listitem>
513
514    <listitem>
515      <funcsynopsis>
516        <funcprototype>
517          <funcdef>void <function>clear</function></funcdef>
518          <void/>
519        </funcprototype>
520      </funcsynopsis>
521      <para>
522        Clear all variables, methods, and imports from this namespace.
523        If this namespace is the root, it will be reset to the default
524        imports.
525      </para>
526    </listitem>
527
528    <listitem>
529      <funcsynopsis>
530        <funcprototype>
531          <funcdef>bsh.This <function>extend</function></funcdef>
532          <paramdef>bsh.This <parameter>object</parameter></paramdef>
533        </funcprototype>
534      </funcsynopsis>
535      <para>
536        Creates a new BeanShell <classname>This</classname> scripted object
537        that is a child of the parameter <parameter>object</parameter>.
538      </para>
539    </listitem>
540
541    <listitem>
542      <funcsynopsis>
543        <funcprototype>
544          <funcdef>void <function>importObject</function></funcdef>
545           <paramdef>Object <parameter>object</parameter></paramdef>
546        </funcprototype>
547      </funcsynopsis>
548      <para>
549        Import an object into this namespace. This is somewhat similar to Java 1.5 static class imports, except you can import the methods and fields of a Java object instance into
550        a BeanShell namespace, for example:
551      </para>
552      <informalexample><programlisting><![CDATA[Map map = new HashMap();
553    importObject( map );
554    put("foo", "bar");
555    print( get("foo") ); // "bar"]]></programlisting></informalexample>
556    </listitem>
557
558    <listitem>
559      <funcsynopsis>
560        <funcprototype>
561          <funcdef>bsh.This <function>object</function></funcdef>
562          <void/>
563        </funcprototype>
564      </funcsynopsis>
565      <para>
566        Creates a new BeanShell <classname>This</classname> scripted object which
567        can hold data members. You can use this to create an object for
568        storing miscellaneous crufties, like so:
569      </para>
570      <informalexample><programlisting>crufties = object();
571crufties.foo = "hello world";
572crufties.counter = 5;
573...</programlisting></informalexample>
574    </listitem>
575
576    <listitem>
577      <funcsynopsis>
578        <funcprototype>
579          <funcdef><function>setNameSpace</function></funcdef>
580          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
581        </funcprototype>
582      </funcsynopsis>
583      <para>
584        Set the namespace of the current scope to
585        <parameter>namespace</parameter>.
586      </para>
587    </listitem>
588
589    <listitem>
590      <funcsynopsis>
591        <funcprototype>
592          <funcdef>bsh.This <function>super</function></funcdef>
593          <paramdef>String <parameter>scopename</parameter></paramdef>
594        </funcprototype>
595      </funcsynopsis>
596      <para>
597        Returns a reference to the BeanShell <classname>This</classname>
598        object representing the enclosing method scope specified
599        by <parameter>scopename</parameter>.  This method work similar to
600        the <function>super</function> keyword but can refer to enclosing
601        scope at higher levels in a hierarchy of scopes.
602      </para>
603    </listitem>
604
605    <listitem>
606      <funcsynopsis>
607        <funcprototype>
608          <funcdef>void <function>unset</function></funcdef>
609          <paramdef>String <parameter>name</parameter></paramdef>
610        </funcprototype>
611      </funcsynopsis>
612      <para>
613        Removes the variable named by <parameter>name</parameter> from
614        the current interpreter namespace.  This has the effect of
615        <quote>undefining</quote> the variable.
616      </para>
617    </listitem>
618
619  </itemizedlist>
620
621</sect1>
622
623<sect1 id="bsh-commands-other"><title>Other Commands</title>
624
625  <itemizedlist>
626    <!-- <listitem>
627      <funcsynopsis>
628        <funcprototype>
629          <funcdef>void <function>exit</function></funcdef>
630          <void/>
631        </funcprototype>
632      </funcsynopsis>
633      <para>
634        Calls <function>System.exit(0)</function>.
635      </para>
636      <caution><para>
637        While this command is available, you should always call
638        <function>jEdit.exit()</function> instead so the application will
639        shutdown in an orderly fashion.
640      </para></caution>
641    </listitem> -->
642
643    <listitem>
644      <funcsynopsis>
645        <funcprototype>
646          <funcdef>void <function>debug</function></funcdef>
647          <void/>
648        </funcprototype>
649      </funcsynopsis>
650      <para>
651        Toggles BeanShell's internal debug reporting to the
652        output stream of the current process.
653      </para>
654    </listitem>
655
656    <listitem>
657      <funcsynopsis>
658        <funcprototype>
659          <funcdef><function>getSourceFileInfo</function></funcdef>
660          <void/>
661        </funcprototype>
662      </funcsynopsis>
663      <para>
664        Returns the name of the file or other source from which the
665        BeanShell interpreter is reading.
666      </para>
667    </listitem>
668
669  </itemizedlist>
670
671</sect1>
672
673</chapter>