PageRenderTime 26ms CodeModel.GetById 11ms app.highlight 9ms RepoModel.GetById 2ms app.codeStats 0ms

/jEdit/tags/jedit-4-5-pre1/doc/users-guide/bsh-commands.xml

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