/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
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
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>