PageRenderTime 148ms CodeModel.GetById 136ms app.highlight 7ms RepoModel.GetById 1ms app.codeStats 0ms

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

#
XML | 603 lines | 435 code | 62 blank | 106 comment | 0 complexity | 7eec6f29332ffc2ad1032cf3fc72c2b0 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    <listitem>
 28      <funcsynopsis>
 29        <funcprototype>
 30          <funcdef>void <function>print</function></funcdef>
 31          <paramdef><parameter>arg</parameter></paramdef>
 32        </funcprototype>
 33      </funcsynopsis>
 34      <para>
 35        Writes the string value of the argument to the activity log,
 36        or if run from the <application>Console</application> plugin,
 37        to the current output window.  If <parameter>arg</parameter> is
 38        an array, <function>print</function> runs itself recursively
 39        on the array's elements.
 40      </para>
 41    </listitem>
 42
 43    <!-- one day jEdit will provide its own error() implementation -->
 44    <!-- <listitem>
 45      <funcsynopsis>
 46        <funcprototype>
 47          <funcdef>void <function>error</function></funcdef>
 48          <paramdef>String <parameter>errorMsg</parameter></paramdef>
 49        </funcprototype>
 50      </funcsynopsis>
 51      <para>
 52        Writes the string represented by <parameter>errorMsg</parameter>
 53        to the error stream of the current process.
 54      </para>
 55    </listitem> -->
 56
 57    <listitem>
 58      <funcsynopsis>
 59        <funcprototype>
 60          <funcdef>void <function>cat</function></funcdef>
 61          <paramdef>String <parameter>filename</parameter></paramdef>
 62        </funcprototype>
 63      </funcsynopsis>
 64      <para>
 65        Writes the contents of <parameter>filename</parameter>
 66        to the activity log.
 67      </para>
 68    </listitem>
 69
 70    <listitem>
 71      <funcsynopsis>
 72        <funcprototype>
 73          <funcdef>void <function>javap</function></funcdef>
 74          <paramdef>String | Object | Class <parameter>target</parameter></paramdef>
 75        </funcprototype>
 76      </funcsynopsis>
 77      <para>
 78        Writes the public fields and methods of the specified class to
 79        the output stream of the current process.  Requires Java 2
 80        version 1.3 or greater.
 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>dir</function></funcdef>
 96          <paramdef>String <parameter>dirname</parameter></paramdef>
 97        </funcprototype>
 98      </funcsynopsis>
 99      <para>
100        Displays the contents of directory <parameter>dirname</parameter>.
101        The format of the display is similar to the Unix
102        <function>ls -l</function> command.
103      </para>
104    </listitem>
105
106    <listitem>
107      <funcsynopsis>
108        <funcprototype>
109          <funcdef>File <function>pathToFile</function></funcdef>
110          <paramdef>String <parameter>filename</parameter></paramdef>
111        </funcprototype>
112      </funcsynopsis>
113      <para>
114        Create a <classname>File</classname> object corresponding to
115        <function>filename</function>.  Relative paths are resolved with
116        reference to the BeanShell interpreter's working
117        directory.
118      </para>
119    </listitem>
120
121    <listitem>
122      <funcsynopsis>
123        <funcprototype>
124          <funcdef>void <function>cd</function></funcdef>
125          <paramdef>String <parameter>dirname</parameter></paramdef>
126        </funcprototype>
127      </funcsynopsis>
128      <para>
129        Changes the working directory of the BeanShell interpreter
130        to <parameter>dirname</parameter>.
131      </para>
132    </listitem>
133
134    <listitem>
135      <funcsynopsis>
136        <funcprototype>
137          <funcdef>void <function>pwd</function></funcdef>
138          <void/>
139        </funcprototype>
140      </funcsynopsis>
141      <para>
142        Writes the current working directory of the BeanShell interpreter
143        to the output stream of the current process.
144      </para>
145    </listitem>
146
147    <listitem>
148      <funcsynopsis>
149        <funcprototype>
150          <funcdef><function>mv</function></funcdef>
151          <paramdef>String <parameter>fromFile</parameter></paramdef>
152          <paramdef>String <parameter>toFile</parameter></paramdef>
153        </funcprototype>
154      </funcsynopsis>
155      <para>
156        Moves the file named by <parameter>fromFile</parameter> to
157        <parameter>toFile</parameter>.
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>Object <function>load</function></funcdef>
184          <paramdef>String <parameter>filename</parameter></paramdef>
185        </funcprototype>
186      </funcsynopsis>
187      <para>
188        Loads and returns a serialized Java object from
189        <parameter>filename</parameter>.
190      </para>
191    </listitem>
192
193    <listitem>
194      <funcsynopsis>
195        <funcprototype>
196          <funcdef>void <function>save</function></funcdef>
197          <paramdef>Component <parameter>component</parameter></paramdef>
198          <paramdef>String <parameter>filename</parameter></paramdef>
199        </funcprototype>
200      </funcsynopsis>
201      <para>
202        Saves <parameter>component</parameter> in serialized form
203        to <parameter>filename</parameter>.
204      </para>
205    </listitem>
206
207    <listitem>
208      <funcsynopsis>
209        <funcprototype>
210          <funcdef>JFrame <function>frame</function></funcdef>
211          <paramdef>Component <parameter>frame</parameter></paramdef>
212        </funcprototype>
213      </funcsynopsis>
214      <para>
215        Displays the component in a top-level <classname>JFrame</classname>,
216        centered and packed.  Returns the <classname>JFrame</classname> object.
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        Retruns 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, releads 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><function>exec</function></funcdef>
360          <paramdef>String <parameter>cmdline</parameter></paramdef>
361        </funcprototype>
362      </funcsynopsis>
363      <para>
364        Start the external process by calling
365        <function>Runtime.exec()</function> on
366        <parameter>cmdline</parameter>. Any output is directed to the
367        output stream of the calling process.
368      </para>
369    </listitem>
370
371    <listitem>
372      <funcsynopsis>
373        <funcprototype>
374          <funcdef>void <function>source</function></funcdef>
375          <paramdef>String <parameter>filename</parameter></paramdef>
376        </funcprototype>
377      </funcsynopsis>
378      <para>
379        Evaluates the contents of <parameter>filename</parameter>
380        as a BeanShell script in the interpreter's current namespace.
381      </para>
382    </listitem>
383
384    <listitem>
385      <funcsynopsis>
386        <funcprototype>
387          <funcdef>Object <function>eval</function></funcdef>
388          <paramdef>String <parameter>expression</parameter></paramdef>
389        </funcprototype>
390      </funcsynopsis>
391      <para>
392        Evaluates the string <parameter>expression</parameter> as
393        a BeanShell script in the interpreter's current namespace.
394        Returns the result of the evaluation of <constant>null</constant>.
395      </para>
396    </listitem>
397
398    <listitem>
399      <funcsynopsis>
400        <funcprototype>
401          <funcdef>bsh.This <function>run</function></funcdef>
402          <paramdef>String <parameter>filename</parameter></paramdef>
403        </funcprototype>
404      </funcsynopsis>
405      <para>
406        Run the BeanShell script named by <parameter>filename</parameter>
407        in a copy of the existing namespace.  The return value represent
408        the object context of the script, allowing you to access its variables
409        and methods.
410      </para>
411    </listitem>
412
413    <listitem>
414      <funcsynopsis>
415        <funcprototype>
416          <funcdef>Thread <function>bg</function></funcdef>
417          <paramdef>String <parameter>filename</parameter></paramdef>
418        </funcprototype>
419      </funcsynopsis>
420      <para>
421        Run the BeanShell script named by <parameter>filename</parameter>
422        in a copy of the existing namespace and in a separate thread.  Returns
423        the <classname>Thread</classname> object so created.
424      </para>
425    </listitem>
426
427    <listitem>
428      <funcsynopsis>
429        <funcprototype>
430          <funcdef>void <function>server</function></funcdef>
431          <paramdef>int <parameter>port</parameter></paramdef>
432        </funcprototype>
433      </funcsynopsis>
434      <para>
435        Createes a <quote>server</quote> version of the BeanShell
436        interpreter that shares the same namespace as the current
437        interpreter.  The server interpreter listens on the designated
438        port.
439      </para>
440      <para>
441        This requires the <classname>bsh.util</classname> package, which
442        is not included with jEdit. It can be found in the stand-alone
443        BeanShell distribution, available from <ulink
444        url="http://www.beanshell.org">http://www.beanshell.org</ulink>.
445      </para>
446      <caution><para>
447        Security of this port is not guaranteed.  Use this command
448        with extreme caution.
449      </para></caution>
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>bsh.This <function>object</function></funcdef>
465          <void/>
466        </funcprototype>
467      </funcsynopsis>
468      <para>
469        Creates a new BeanShell <classname>This</classname> scripted object which
470        can hold data members. You can use this to create an object for
471        storing miscellaneous crufties, like so:
472      </para>
473      <informalexample><programlisting>crufties = object();
474crufties.foo = "hello world";
475crufties.counter = 5;
476...</programlisting></informalexample>
477    </listitem>
478
479    <listitem>
480      <funcsynopsis>
481        <funcprototype>
482          <funcdef>bsh.This <function>extend</function></funcdef>
483          <paramdef>bsh.This <parameter>object</parameter></paramdef>
484        </funcprototype>
485      </funcsynopsis>
486      <para>
487        Creates a new BeanShell <classname>This</classname> scripted object
488        that is a child of the parameter <parameter>object</parameter>.
489      </para>
490    </listitem>
491
492    <listitem>
493      <funcsynopsis>
494        <funcprototype>
495          <funcdef>bsh.This <function>super</function></funcdef>
496          <paramdef>String <parameter>scopename</parameter></paramdef>
497        </funcprototype>
498      </funcsynopsis>
499      <para>
500        Returns a refernece to the BeanShell <classname>This</classname>
501        object representing the enclosing method scope specified
502        by <parameter>scopename</parameter>.  This method work similar to
503        the <function>super</function> keyword but can refer to enclosing
504        scope at higher levels in a hierarchy of scopes.
505      </para>
506    </listitem>
507
508    <listitem>
509      <funcsynopsis>
510        <funcprototype>
511          <funcdef><function>bind</function></funcdef>
512          <paramdef>bsh.This <parameter>ths</parameter></paramdef>
513          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
514        </funcprototype>
515      </funcsynopsis>
516      <para>
517        Binds the scripted object <parameter>ths</parameter> to
518        <parameter>namespace</parameter>.
519      </para>
520    </listitem>
521
522    <listitem>
523      <funcsynopsis>
524        <funcprototype>
525          <funcdef>void <function>unset</function></funcdef>
526          <paramdef>String <parameter>name</parameter></paramdef>
527        </funcprototype>
528      </funcsynopsis>
529      <para>
530        Removes the variable named by <parameter>name</parameter> from
531        the current interpreter namespace.  This has the effect of
532        <quote>undefining</quote> the variable.
533      </para>
534    </listitem>
535
536    <listitem>
537      <funcsynopsis>
538        <funcprototype>
539          <funcdef><function>setNameSpace</function></funcdef>
540          <paramdef>bsh.Namespace <parameter>namespace</parameter></paramdef>
541        </funcprototype>
542      </funcsynopsis>
543      <para>
544        Set the namespace of the current scope to
545        <parameter>namespace</parameter>.
546      </para>
547    </listitem>
548
549  </itemizedlist>
550
551</sect1>
552
553<sect1 id="BeanShell-commands-other"><title>Other Commands</title>
554
555  <itemizedlist>
556    <listitem>
557      <funcsynopsis>
558        <funcprototype>
559          <funcdef>void <function>exit</function></funcdef>
560          <void/>
561        </funcprototype>
562      </funcsynopsis>
563      <para>
564        Calls <function>System.exit(0)</function>.
565      </para>
566      <caution><para>
567        While this command is available, you should always call
568        <function>jEdit.exit()</function> instead so the application will
569        shutdown in an orderly fashion.
570      </para></caution>
571    </listitem>
572
573    <listitem>
574      <funcsynopsis>
575        <funcprototype>
576          <funcdef>void <function>debug</function></funcdef>
577          <void/>
578        </funcprototype>
579      </funcsynopsis>
580      <para>
581        Toggles BeanShell's internal debug reporting to the
582        output stream of the current process.
583      </para>
584    </listitem>
585
586    <listitem>
587      <funcsynopsis>
588        <funcprototype>
589          <funcdef><function>getSourceFileInfo</function></funcdef>
590          <void/>
591        </funcprototype>
592      </funcsynopsis>
593      <para>
594        Returns the name of the file or other source from which the
595        BeanShell interpreter is reading.
596      </para>
597    </listitem>
598
599  </itemizedlist>
600
601</sect1>
602
603</chapter>