PageRenderTime 16ms CodeModel.GetById 2ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
XML | 617 lines | 408 code | 63 blank | 146 comment | 0 complexity | 1a1cd19e4c4869c229b9625c8659347d 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
  7<chapter id="beanshell-commands"><title>BeanShell Commands</title>
  8
  9<para>
 10  BeanShell includes a set of <firstterm>commands</firstterm>;
 11  subroutines that
 12  can be called from any script or macro.  The following is a summary of
 13  those commands which may be useful within jEdit.
 14</para>
 15
 16<note>
 17 <para>
 18  Plugins, because they are written in Java and not BeanShell,
 19  cannot make use of BeanShell commands.
 20 </para>
 21</note>
 22
 23<sect1 id="beanshell-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="beanshell-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>dir</function></funcdef>
109          <paramdef>String <parameter>dirname</parameter></paramdef>
110        </funcprototype>
111      </funcsynopsis>
112      <para>
113        Displays the contents of directory <parameter>dirname</parameter>.
114        The format of the display is similar to the Unix
115        <function>ls -l</function> command.
116      </para>
117    </listitem>
118
119    <listitem>
120      <funcsynopsis>
121        <funcprototype>
122          <funcdef>void <function>mv</function></funcdef>
123          <paramdef>String <parameter>fromFile</parameter></paramdef>
124          <paramdef>String <parameter>toFile</parameter></paramdef>
125        </funcprototype>
126      </funcsynopsis>
127      <para>
128        Moves the file named by <parameter>fromFile</parameter> to
129        <parameter>toFile</parameter>.
130      </para>
131    </listitem>
132
133    <listitem>
134      <funcsynopsis>
135        <funcprototype>
136          <funcdef>File <function>pathToFile</function></funcdef>
137          <paramdef>String <parameter>filename</parameter></paramdef>
138        </funcprototype>
139      </funcsynopsis>
140      <para>
141        Create a <classname>File</classname> object corresponding to
142        <function>filename</function>.  Relative paths are resolved with
143        reference to the BeanShell interpreter's working
144        directory.
145      </para>
146    </listitem>
147
148    <listitem>
149      <funcsynopsis>
150        <funcprototype>
151          <funcdef>void <function>pwd</function></funcdef>
152          <void/>
153        </funcprototype>
154      </funcsynopsis>
155      <para>
156        Writes the current working directory of the BeanShell interpreter
157        to the output stream of the current process.
158      </para>
159    </listitem>
160
161    <listitem>
162      <funcsynopsis>
163        <funcprototype>
164          <funcdef>void <function>rm</function></funcdef>
165          <paramdef>String <parameter>pathname</parameter></paramdef>
166        </funcprototype>
167      </funcsynopsis>
168      <para>
169        Deletes the file name by <parameter>pathname</parameter>.
170      </para>
171    </listitem>
172
173  </itemizedlist>
174
175</sect1>
176<sect1 id="beanshell-commands-serial"><title>Component Commands</title>
177
178  <itemizedlist>
179
180    <listitem>
181      <funcsynopsis>
182        <funcprototype>
183          <funcdef>JFrame <function>frame</function></funcdef>
184          <paramdef>Component <parameter>frame</parameter></paramdef>
185        </funcprototype>
186      </funcsynopsis>
187      <para>
188        Displays the component in a top-level <classname>JFrame</classname>,
189        centered and packed.  Returns the <classname>JFrame</classname> object.
190      </para>
191    </listitem>
192
193    <listitem>
194      <funcsynopsis>
195        <funcprototype>
196          <funcdef>Object <function>load</function></funcdef>
197          <paramdef>String <parameter>filename</parameter></paramdef>
198        </funcprototype>
199      </funcsynopsis>
200      <para>
201        Loads and returns a serialized Java object from
202        <parameter>filename</parameter>.
203      </para>
204    </listitem>
205
206    <listitem>
207      <funcsynopsis>
208        <funcprototype>
209          <funcdef>void <function>save</function></funcdef>
210          <paramdef>Component <parameter>component</parameter></paramdef>
211          <paramdef>String <parameter>filename</parameter></paramdef>
212        </funcprototype>
213      </funcsynopsis>
214      <para>
215        Saves <parameter>component</parameter> in serialized form
216        to <parameter>filename</parameter>.
217      </para>
218    </listitem>
219
220    <listitem>
221      <funcsynopsis>
222        <funcprototype>
223          <funcdef>Font <function>setFont</function></funcdef>
224          <paramdef>Component <parameter>comp</parameter></paramdef>
225          <paramdef>int <parameter>ptsize</parameter></paramdef>
226        </funcprototype>
227      </funcsynopsis>
228      <para>
229        Set the font size of <parameter>component</parameter> to
230        <parameter>ptsize</parameter> and returns the new
231        font.
232      </para>
233    </listitem>
234
235  </itemizedlist>
236
237</sect1>
238
239
240<sect1 id="beanshell-commands-resource">
241<title>Resource Management Commands</title>
242
243  <itemizedlist>
244
245    <listitem>
246      <funcsynopsis>
247        <funcprototype>
248          <funcdef>URL <function>getResource</function></funcdef>
249          <paramdef>String <parameter>path</parameter></paramdef>
250        </funcprototype>
251      </funcsynopsis>
252      <para>
253        Returns the resource specified by <parameter>path</parameter>.
254        A absolute path must be used to return any resource available in
255        the current classpath.
256      </para>
257    </listitem>
258
259    <!-- bsh.classpath not supported in jEdit -->
260    <!--
261    <listitem>
262      <funcsynopsis>
263        <funcprototype>
264          <funcdef>void <function>addClassPath</function></funcdef>
265          <paramdef>String <parameter>path</parameter></paramdef>
266        </funcprototype>
267      </funcsynopsis>
268    </listitem>
269
270    <listitem>
271      <funcsynopsis>
272        <funcprototype>
273          <funcdef>void <function>addClassPath</function></funcdef>
274          <paramdef>URL <parameter>path</parameter></paramdef>
275        </funcprototype>
276      </funcsynopsis>
277      <para>
278        Adds the directory or jar archive file specified by
279        <parameter>path</parameter> to the classpath used by the
280        interpreter.
281      </para>
282    </listitem>
283
284    <listitem>
285      <funcsynopsis>
286        <funcprototype>
287          <funcdef>void <function>setClassPath</function></funcdef>
288          <paramdef>URL[] <parameter>paths</parameter></paramdef>
289        </funcprototype>
290      </funcsynopsis>
291      <para>
292        Changes the classpath for the BeanShell interpreter to the specified
293        array of directories and/or archives.
294      </para>
295    </listitem>
296
297    <listitem>
298      <funcsynopsis>
299        <funcprototype>
300          <funcdef>URL[] <function>getClassPath</function></funcdef>
301          <void/>
302        </funcprototype>
303      </funcsynopsis>
304      <para>
305        Returns an array containing the current classpath.
306      </para>
307    </listitem>
308
309    <listitem>
310      <funcsynopsis>
311        <funcprototype>
312          <funcdef>void <function>reloadClasses</function></funcdef>
313          <paramdef>String <parameter>packagename</parameter></paramdef>
314        </funcprototype>
315      </funcsynopsis>
316    </listitem>
317
318    <listitem>
319      <funcsynopsis>
320        <funcprototype>
321          <funcdef>void <function>reloadClasses</function></funcdef>
322          <void/>
323        </funcprototype>
324      </funcsynopsis>
325      <para>
326        Reloads the class or package specified by
327        <parameter>packagename</parameter> in the BeanShell interpreter.
328        If called without a parameter, reloads all classes
329        in the interpreter's classpath.
330      </para>
331    </listitem>
332
333    <listitem>
334      <funcsynopsis>
335        <funcprototype>
336          <funcdef>Class <function>getClass</function></funcdef>
337          <paramdef>String <parameter>classname</parameter></paramdef>
338        </funcprototype>
339      </funcsynopsis>
340      <para>
341        This method is similar to the <function>Class.forName()</function>
342        method of the Java platform, but it uses the classpath of the
343        current BeanShell interpreter, which can contain additional
344        classes and packages as well as reloaded classes.
345      </para>
346    </listitem> -->
347
348  </itemizedlist>
349
350</sect1>
351
352<sect1 id="beanshell-commands-script"><title>Script Execution Commands</title>
353
354  <itemizedlist>
355
356    <listitem>
357      <funcsynopsis>
358        <funcprototype>
359          <funcdef>Thread <function>bg</function></funcdef>
360          <paramdef>String <parameter>filename</parameter></paramdef>
361        </funcprototype>
362      </funcsynopsis>
363      <para>
364        Run the BeanShell script named by <parameter>filename</parameter>
365        in a copy of the existing namespace and in a separate thread.  Returns
366        the <classname>Thread</classname> object so created.
367      </para>
368    </listitem>
369
370    <listitem>
371      <funcsynopsis>
372        <funcprototype>
373          <funcdef>void <function>exec</function></funcdef>
374          <paramdef>String <parameter>cmdline</parameter></paramdef>
375        </funcprototype>
376      </funcsynopsis>
377      <para>
378        Start the external process by calling
379        <function>Runtime.exec()</function> on
380        <parameter>cmdline</parameter>. Any output is directed to the
381        output stream of the calling process.
382      </para>
383    </listitem>
384
385    <listitem>
386      <funcsynopsis>
387        <funcprototype>
388          <funcdef>Object <function>eval</function></funcdef>
389          <paramdef>String <parameter>expression</parameter></paramdef>
390        </funcprototype>
391      </funcsynopsis>
392      <para>
393        Evaluates the string <parameter>expression</parameter> as
394        a BeanShell script in the interpreter's current namespace.
395        Returns the result of the evaluation of <constant>null</constant>.
396      </para>
397    </listitem>
398
399    <listitem>
400      <funcsynopsis>
401        <funcprototype>
402          <funcdef>bsh.This <function>run</function></funcdef>
403          <paramdef>String <parameter>filename</parameter></paramdef>
404        </funcprototype>
405      </funcsynopsis>
406      <para>
407        Run the BeanShell script named by <parameter>filename</parameter>
408        in a copy of the existing namespace.  The return value represent
409        the object context of the script, allowing you to access its variables
410        and methods.
411      </para>
412    </listitem>
413
414    <!-- <listitem>
415      <funcsynopsis>
416        <funcprototype>
417          <funcdef>void <function>server</function></funcdef>
418          <paramdef>int <parameter>port</parameter></paramdef>
419        </funcprototype>
420      </funcsynopsis>
421      <para>
422        Creates a <quote>server</quote> version of the BeanShell
423        interpreter that shares the same namespace as the current
424        interpreter.  The server interpreter listens on the designated
425        port.
426      </para>
427      <para>
428        This requires the <classname>bsh.util</classname> package, which
429        is not included with jEdit. It can be found in the stand-alone
430        BeanShell distribution, available from <ulink
431        url="http://www.beanshell.org">http://www.beanshell.org</ulink>.
432      </para>
433      <caution><para>
434        Security of this port is not guaranteed.  Use this command
435        with extreme caution.
436      </para></caution>
437    </listitem> -->
438
439    <listitem>
440      <funcsynopsis>
441        <funcprototype>
442          <funcdef>void <function>source</function></funcdef>
443          <paramdef>String <parameter>filename</parameter></paramdef>
444        </funcprototype>
445      </funcsynopsis>
446      <para>
447        Evaluates the contents of <parameter>filename</parameter>
448        as a BeanShell script in the interpreter's current namespace.
449      </para>
450    </listitem>
451
452  </itemizedlist>
453
454</sect1>
455
456<sect1 id="beanshell-commands-object">
457<title>BeanShell Object Management Commands</title>
458
459  <itemizedlist>
460
461    <listitem>
462      <funcsynopsis>
463        <funcprototype>
464          <funcdef><function>bind</function></funcdef>
465          <paramdef>bsh.This <parameter>ths</parameter></paramdef>
466          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
467        </funcprototype>
468      </funcsynopsis>
469      <para>
470        Binds the scripted object <parameter>ths</parameter> to
471        <parameter>namespace</parameter>.
472      </para>
473    </listitem>
474
475    <listitem>
476      <funcsynopsis>
477        <funcprototype>
478          <funcdef>void <function>clear</function></funcdef>
479          <void/>
480        </funcprototype>
481      </funcsynopsis>
482      <para>
483        Clear all variables, methods, and imports from this namespace.
484        If this namespace is the root, it will be reset to the default
485        imports.
486      </para>
487    </listitem>
488
489    <listitem>
490      <funcsynopsis>
491        <funcprototype>
492          <funcdef>bsh.This <function>extend</function></funcdef>
493          <paramdef>bsh.This <parameter>object</parameter></paramdef>
494        </funcprototype>
495      </funcsynopsis>
496      <para>
497        Creates a new BeanShell <classname>This</classname> scripted object
498        that is a child of the parameter <parameter>object</parameter>.
499      </para>
500    </listitem>
501
502    <listitem>
503      <funcsynopsis>
504        <funcprototype>
505          <funcdef>bsh.This <function>object</function></funcdef>
506          <void/>
507        </funcprototype>
508      </funcsynopsis>
509      <para>
510        Creates a new BeanShell <classname>This</classname> scripted object which
511        can hold data members. You can use this to create an object for
512        storing miscellaneous crufties, like so:
513      </para>
514      <informalexample><programlisting>crufties = object();
515crufties.foo = "hello world";
516crufties.counter = 5;
517...</programlisting></informalexample>
518    </listitem>
519
520    <listitem>
521      <funcsynopsis>
522        <funcprototype>
523          <funcdef><function>setNameSpace</function></funcdef>
524          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
525        </funcprototype>
526      </funcsynopsis>
527      <para>
528        Set the namespace of the current scope to
529        <parameter>namespace</parameter>.
530      </para>
531    </listitem>
532
533    <listitem>
534      <funcsynopsis>
535        <funcprototype>
536          <funcdef>bsh.This <function>super</function></funcdef>
537          <paramdef>String <parameter>scopename</parameter></paramdef>
538        </funcprototype>
539      </funcsynopsis>
540      <para>
541        Returns a reference to the BeanShell <classname>This</classname>
542        object representing the enclosing method scope specified
543        by <parameter>scopename</parameter>.  This method work similar to
544        the <function>super</function> keyword but can refer to enclosing
545        scope at higher levels in a hierarchy of scopes.
546      </para>
547    </listitem>
548
549    <listitem>
550      <funcsynopsis>
551        <funcprototype>
552          <funcdef>void <function>unset</function></funcdef>
553          <paramdef>String <parameter>name</parameter></paramdef>
554        </funcprototype>
555      </funcsynopsis>
556      <para>
557        Removes the variable named by <parameter>name</parameter> from
558        the current interpreter namespace.  This has the effect of
559        <quote>undefining</quote> the variable.
560      </para>
561    </listitem>
562
563  </itemizedlist>
564
565</sect1>
566
567<sect1 id="beanshell-commands-other"><title>Other Commands</title>
568
569  <itemizedlist>
570    <!-- <listitem>
571      <funcsynopsis>
572        <funcprototype>
573          <funcdef>void <function>exit</function></funcdef>
574          <void/>
575        </funcprototype>
576      </funcsynopsis>
577      <para>
578        Calls <function>System.exit(0)</function>.
579      </para>
580      <caution><para>
581        While this command is available, you should always call
582        <function>jEdit.exit()</function> instead so the application will
583        shutdown in an orderly fashion.
584      </para></caution>
585    </listitem> -->
586
587    <listitem>
588      <funcsynopsis>
589        <funcprototype>
590          <funcdef>void <function>debug</function></funcdef>
591          <void/>
592        </funcprototype>
593      </funcsynopsis>
594      <para>
595        Toggles BeanShell's internal debug reporting to the
596        output stream of the current process.
597      </para>
598    </listitem>
599
600    <listitem>
601      <funcsynopsis>
602        <funcprototype>
603          <funcdef><function>getSourceFileInfo</function></funcdef>
604          <void/>
605        </funcprototype>
606      </funcsynopsis>
607      <para>
608        Returns the name of the file or other source from which the
609        BeanShell interpreter is reading.
610      </para>
611    </listitem>
612
613  </itemizedlist>
614
615</sect1>
616
617</chapter>