1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
|
<!-- Originally written by Paul Kinnucan for JDE, licensed under GPL.
Modified for bsh Debian package by
Ruud de Rooij <ruud@debian.org> Sun, 11 Jul 1999 13:59:16 +0200 -->
<HTML>
<HEAD>
<TITLE>BeanShell User's Guide</TITLE>
</HEAD>
<BODY>
<H1>
BeanShell User's Guide</H1>
<H2>
<A NAME="Introduction"></A>Introduction</H2>
This guide explains how to use the BeanShell Java interpreter. This guide
contains the following
sections:
<BR>
<BR>
<TABLE BORDER=0 WIDTH="100%" >
<TR>
<TD><A HREF="#About">About the BeanShell</A> </TD>
<TD>Brief overview of the BeanShell </TD>
</TR>
<TR>
<TD VALIGN=TOP><A HREF="#Using">Using the BeanShell</A> </TD>
<TD>Explains how to start and shut down the BeanShell, enter statements,
and show results.</TD>
</TR>
<TR>
<TD VALIGN=TOP><A HREF="#LanguageRef">The BeanShell Language</A> </TD>
<TD>Describes the Java constructs and scripting extensions supported by
the BeanShell</TD>
</TR>
<TR>
<TD><A HREF="#CommandRef">BeanShell Commands</A> </TD>
<TD>Describes the commands supported by the BeanShell</TD>
</TR>
</TABLE>
<H2>
<A NAME="About"></A>About the BeanShell</H2>
The BeanShell is a Java interpreter that evaluates Java statements directly
(without first compiling them).
<P>The BeanShell can operate as a stand-alone application or as a part
of another application. When running as a stand-alone application, the
interpreter accepts input from the command line of the shell in which it
runs. The BeanShell distribution includes a shell for running the interpreter.
It can, however, be run from other shells, such as bash.
<H2>
<A NAME="Using"></A>Using the BeanShell</H2>
<H3>
<A NAME="Starting"></A>Starting the BeanShell</H3>
To start the BeanShell, type <TT>bsh</TT> for the command-line version, or
<TT>xbsh</TT> for the windowed version. To use the Swing interface, make sure
that the Swing libraries are included in your <TT>CLASSPATH</TT> environment
variable before starting xbsh.
<H3>
<A NAME="Evaluating"></A>Evaluating Statements</H3>
To evaluate a Java statement, type it at the BeanShell prompt and press
the <B><FONT SIZE=-1>Enter</FONT></B> key. The BeanShell evaluates the
statement. When it is done, it redisplays the the BeanShell command prompt.
You can then enter another statement.
<P>Statements must conform to Java syntax. For example, simple statements
must end in a semicolon. Compound statements, such as if-then constructs,
must end in a right brace. Statements may span multiple lines. To continue
a statement on a new line, press the <B><FONT SIZE=-1>Enter</FONT></B>
key. The BeanShell does not evaluate the statement until you have entered
the last line of the statement.
<H3>
<A NAME="Displaying"></A>Displaying Results</H3>
You can display the results of evaluating Java statements via the BeanShell
<TT>print</TT> and <TT>show</TT> commands. The print command accepts any
Java expression as an argument and displays the result of evaluating that
expression in the BeanShell window. For example,
<BLOCKQUOTE><TT>print(2+2);</TT></BLOCKQUOTE>
displays
<BLOCKQUOTE><TT>4</TT></BLOCKQUOTE>
in the BeanShell window. Note that <TT>print(expr)</TT> is equivalent to
<TT>System.out.println(expr)</TT> and you can use either method to print
a Java expression.
<P>The <TT>show();</TT> command toggles automatic display of the results
of evaluating statements as they are entered.
<H3>
<A NAME="Exiting"></A>Exiting the Shell</H3>
To exit the BeanShell, enter
<BLOCKQUOTE><TT>exit();</TT></BLOCKQUOTE>
at the commmand prompt.
<H2>
<A NAME="LanguageRef"></A>The BeanShell Language</H2>
<H3>
<A NAME="JavaSupport"></A>Java Language Support</H3>
The BeanShell language includes most of the constructs of the Java language.
Standard Java constructs supported by the BeanShell include variable
assignments, method calls, math expressions, for-loops, etc.. Here are
some examples:
<PRE> // Use a hashtable
Hashtable h = new Hashtable();
Date d = new Date();
h.put("today", d);
// Print the current clock value
print( System.currentTimeMillis() );
// Loop
for (int i=0; i<5; i++)
print(i);
// Pop up an AWT frame with a button in it
Button b = new Button("My Button");
Frame f = new Frame("My Frame");
f.add(b, "Center");
f.pack();
f.show();</PRE>
By default, the BeanShell imports the Java core classes at startup. You
can import additional classes, using standard Java import syntax, for example,
<BLOCKQUOTE><TT>import mypackage.*;</TT></BLOCKQUOTE>
or
<PRE> import mypackage.MyClass;</PRE>
<H3>
<A NAME="ScriptExtensions"></A>Scripting Extensions</H3>
The BeanShell defines a number of extensions to the Java language designed
to facilitate creation of scripts. The scripting extensions include
<UL>
<LI>
Script Variables</LI>
<LI>
Script Methods</LI>
<LI>
Implicit Objects</LI>
<LI>
Syntax for accessing Bean properties and Hashtable entries</LI>
</UL>
<H3>
<A NAME="ScriptVariables"></A>Script Variables</H3>
The BeanShell allows you to create a special type of variable named a script
variable. Unlike a standard Java variable, which can reference objects
only of a specified type, a script variable can be defined to reference
any type of object, including primitive types, such as <TT>int</TT> and
<TT>boolean</TT>. You create a script variable by declaring it with or
without a type specifier. If you include a type specifier, the variable
can reference only values of the specified type. If you do not specify
a type, the variable can reference values of any type. For example, the
following statement
<PRE> foo = new Button("Another Button");</PRE>
creates an untyped script variable named <TT>foo</TT> and assigns it a
Button object. You are free to subsequently assign <TT>foo</TT> to
any other type of object.
<H4>
Predefined Variables</H4>
<UL>
<LI>
<B>$_</B> - the value of the last expression evaluated.</LI>
<LI>
<B>bsh.Console bsh.console</B> - The primary console, if one exists.</LI>
<LI>
<B>java.awt.AppletContext bsh.appletcontext</B> - the applet context, if
one exists.</LI>
<LI>
<B>String bsh.cwd</B> - used by the cd() and dir() commands.</LI>
<LI>
<B>boolean bsh.show</B> - used by the show() command.</LI>
<LI>
<B>boolean bsh.interactive</B> - is this interpreter running in an interactive
mode or sourcing a file?</LI>
<LI>
<B>boolean bsh.evalOnly</B> - Does this interpreter have an input stream
or is it only serving as a bag for eval() operations.</LI>
</UL>
<H4>
Undefined variables</H4>
You can test to see if a variable is "undefined" with the value <TT>void</TT>,
e.g.:
<PRE> if ( foobar == void )
// undefined</PRE>
You can return a defined variable to the undefined state using the unset()
command:
<BLOCKQUOTE><TT>a == void; // true</TT>
<BR><TT>a=5;</TT>
<BR><TT>unset("a"); // note the quotes</TT>
<BR><TT>a == void; // true</TT></BLOCKQUOTE>
<H3>
<A NAME="ScriptMethods"></A>Script Methods</H3>
BeanShell lets you define and use a special type of method called a script
method. Script methods differ from standard Java methods in the following
ways:
<UL>
<LI>
Script methods are methods of an implicit, typeless object</LI>
<LI>
Script methods can be defined to accept and return values of any type</LI>
<LI>
Script methods can define other script methods</LI>
</UL>
You use standard Java syntax to declare a script method that accepts
and returns specific types. For example, the following code
<PRE> int addTwoNumbers( int a, int b ) {
return a + b;
}</PRE>
defines a BeanShell method called <TT>addTwoNumbers</TT> that accepts and
returns values of type <TT>int</TT>. The next example
<PRE> int a = addTwoNumbers( 5, 7 );</PRE>
uses the newly defined method to add two values of type <TT>int</TT>.
<P>You define an untyped script method by omitting type specifications.
For example, the following statement
<PRE> add( a, b ) {
return a + b;
}</PRE>
defines a script method that accepts arguments of any type. When you invoke
an untyped script method, BeanShell interprets the method based on the
types of the arguments that you pass to the method. Consider, for example,
the following invocations of the untyped add method defined in the preceding
example:
<PRE> foo = add(1, 2);
print( foo ); // 3
foo = add("Oh", " baby");
print( foo ); // Oh baby</PRE>
The first invocation returns the result of adding, the second, of concatenating
the arguments.
<P>Methods with unspecified return types may return any type of object
or no object. A return statement is optional. If omitted, the method returns
the value of the last statement or expression in the method body.
<H4>
Method Namespace</H4>
The namespaces of script methods and variables are separate. Thus, you
can define a method and a variable having the same name.
<H4>
Nested Methods</H4>
Script methods may define methods, for example,
<PRE> foo() {
bar() {
...
}
}</PRE>
Method may be nested in this way to an arbitrary depth. Within a nested
method, locally declared variables and methods shadow identically
named variables and methods declared in outer methods. Otherwise, variables
and methods are visible to an arbitrary depth of scope. Outer methods can
invoke methods defined by inner methods that return a <TT>this</TT> object,
for example,
<H3>
<A NAME="ImplicitObjects"></A>Implicit Objects</H3>
The methods and variables defined by a script method are considered to
be methods and fields of an implicit object. The reserved identifiers,
<TT>this</TT>, <TT>super</TT>, and <TT>global</TT>, refer, respectively,
to the current object, the calling object, and the global object. A method
can access any variable or method in these scopes by qualifying the variable's
name with the name of the appropriate implicit object.
<PRE> a = 42;
foo() {
a = 97;
print( a );
print( this.a );
print( super.a );
}
foo(); // prints 97, 97, 42</PRE>
A script method can return its implicit object, thereby allowing the invoking
script to access variables and methods defined by the method, using standard
Java "." notation. For example,
<PRE> foo() {
int a = 42;
bar() {
print("The bar is open!");
}
bar();
return this;
}
obj = foo(); // prints "the bar is open!"
print ( obj.a ) // 42
obj.bar(); // prints "the bar is open!"</PRE>
<H4>
Using Implicit Objects as AWT Event Handlers</H4>
Implicit method objects can serve as AWT event handlers. To handle an AWT
event, a script method defines the appropriate event-handling method and
then registering its implicit (<TT>this</TT>) object with the object in
which the event originates. For example, the following script
<PRE> button = new java.awt.Button("foo!");
actionPerformed( event ) {
print( event );
}
button.addActionListener( this );
frame( button ); // show it</PRE>
defines an Action event handler and registers it with a button.
<P>Remember that you don't have to define all of your event handlers globally.
You can handle events in any bsh object scope. For example, the following
method creates a button that displays a message when pushed:
<PRE> messageButton( message ) {
b = new Button("Press Me");
b.addActionListener( this );
frame(b);
actionPerformed( e ) {
print( message );
}
}
messageButton("Hey you!");
messageButton("Another message...");</PRE>
The above will create two buttons and each will display its own message
when pushed. Each has a separate instance of the event handler object.
Note too that we could return a 'this' reference from the handler method
and use it in other contexts to register listeners...
<H4>
Using Implicit Objects as Threads</H4>
'This' type references also implement the standard Runnable interface,
so you can declare a "run()" method in your objects:
<BLOCKQUOTE> <TT> foo() {</TT>
<BR><TT> run() {</TT>
<BR><TT>
// do work...</TT>
<BR><TT> }</TT>
<BR><TT> return this;</TT>
<P><TT> }</TT>
<BR><TT> </TT>
<BR><TT> foo = foo();</TT>
<BR><TT> new Thread( foo ).start();</TT>
<BR> </BLOCKQUOTE>
<H4>
Implicit Object Members</H4>
Implicit objects have four "magic" members:
<BLOCKQUOTE>
<DIR>
<LI>
<TT>this.interpreter</TT> refers to the currently executing BeanShell Interpreter
object.</LI>
<LI>
<TT>this.namespace</TT> refers to the BeanShell NameSpace object of the
current context.</LI>
<LI>
<TT>this.variables</TT> refers to an array of strings listing the variables
defined in this namespace.</LI>
<LI>
<TT>this.methods</TT> refers to an array of strings listing the methods
defined in this namespace.</LI>
</DIR>
</BLOCKQUOTE>
These are mainly for internal use by BeanShell commands. Note that there
are certain special situations in which the <TT>this.interpreter</TT> reference
may not be available, such as in AWT event handlers.
<H3>
<A NAME="PropSyntax"></A>Extended Syntax for Accessing Bean Properties
and Hashtables Entries</H3>
You may use the following syntax
<BLOCKQUOTE><TT>x{name}</TT></BLOCKQUOTE>
to access properties of Java beans and Hashtable entries, where <TT>x</TT>
is a bean or Hashtable and <TT>name</TT> is a String that identifies a
bean property or hashtable entry, for example:
<PRE> b = new java.awt.Button();
b{"label"} = "my button";
// Equivalent to: b.setLabel("my button");
h = new Hashtable();
h{"foo"} = "bar";
// Equivalent to: h.put("foo", "bar");</PRE>
<H2>
<A NAME="CommandRef"></A>BeanShell Commands</H2>
The BeanShell provides a set of commands for displaying data, invoking
system utilities, and performing various other tasks. See the BeanShell
Command Reference for a description of the syntax and usage of each command.
The current crop of bsh commands follow. These are, for the most part,
just very short bsh scripts, supplied in the bsh.jar file. See <A HREF="#making">making
bsh commands</A> below for more details on adding to the "built-in" bsh
command set.
<BR>
<BR>
<HR>
<H3>
<A NAME="bgCommand"></A>bg</H3>
<TT>bg( String script )</TT>
<P>This is like <TT>run()</TT> except that it runs the command in its own
thread. Returns the thread object (for <TT>stop()</TT>ing, <TT>join()</TT>ing,
etc.)
<BR>
<HR>
<H3>
<A NAME="BrowseClassCommand"></A>browseClass</H3>
<TT>void browseClass(String classname);</TT>
<P>Displays a class browser. The browser enables you to browse the contents
of any packages packaged as <TT>jar</TT> files on the classpath.
<BR>
<BR>
<HR>
<H3>
<A NAME="catCommand"></A>cat</H3>
<TT>void cat( String filename )</TT>
<P>Print the contents of filename (like Unix cat)
<BR>
<HR>
<H3>
<A NAME="cdCommand"></A>cd</H3>
<TT>void cd(String dirname);</TT>
<P>Change working directory for the <TT>dir()</TT> command (like Unix <TT>cd</TT>).
<BR>
<BR>
<HR>
<H3>
<A NAME="consoleCommand"></A>console</H3>
<TT>bsh.Console console()</TT>
<P>Create a console window attached to the current interpreter. Returns
the console Frame.
<BR>
<HR>
<H3>
<A NAME="dirCommand"></A>dir</H3>
<TT>void dir(String dirname)</TT>
<P>Display the contets of directory dirname. The format is similar to the
Unix ls -l command.
<BR>
<HR>
<H3>
<A NAME="debugCommand"></A>debug</H3>
<TT>void debug()</TT>
<P>Toggle on and off debug mode... Note: debug output is verbose and gross.
<BR>
<HR>
<H3>
<A NAME="EditorCommand"></A>editor</H3>
<DL>
<DT>
<TT>Frame Frame editor();</TT></DT>
</DL>
<P>Create an editor window with an "eval" button. This is primarily useful
for typing multi-line commands and experimenting with methods when running
the BeanShell outside of the Emacs environment. Returns the editor Frame.
<BR>
<HR>
<H3>
<A NAME="evalCommand"></A>eval</H3>
<TT>void eval( String expression )</TT>
<P>Evaluate the string in the current interpreter (see <TT>source</TT>).
<BR>
<HR>
<H3>
<A NAME="execCommand"></A><B>exec</B></H3>
<DL>
<DT>
<TT>exec(String process);</TT></DT>
</DL>
<P>Get the Java Runtime and start the external process, display any output.
<BR>
<HR>
<H3>
<A NAME="exitCommand"></A>exit</H3>
<TT>void exit()</TT>
<P>Call System.exit(0);
<BR>
<HR>
<H3>
<A NAME="FrameCommand"></A>frame</H3>
<DL>
<DT>
<TT>Frame frame(Component component);</TT></DT>
</DL>
<P>Display the component, centered and packed, in a top level Frame. Returns
the frame. Frame takes additional steps to handle the WindowClosing AWT
event and dispose of the frame, so that you an close the window normally.
<BR>
<HR>
<H3>
<A NAME="getResourceCommand"></A>getResource</H3>
<TT>URL getResource( String path )</TT>
<P>The equivalent of calling getResource() on the interpreter class in
the bsh package. Use absolute paths to get stuff in the classpath.
<BR>
<HR>
<H3>
<A NAME="LoadCommand"></A>load</H3>
<DL>
<DT>
<TT>Object load( String filename )</TT></DT>
</DL>
<P>Load a serialized Java object from filename. Returns the object.
<BR>
<HR>
<H3>
<A NAME="pathToFileCommand"></A>pathToFile</H3>
<TT>File pathToFile( String filename )</TT>
<P>Create a File object corresponding to the specified file path name,
taking into account the bsh current working directory (bsh.cwd)
<BR>
<HR>
<H3>
<A NAME="PrintCommand"></A>print</H3>
<TT>void print(item);</TT>
<P>Print the string value of the item. item may be of any type.
<BR>
<HR>
<H3>
<A NAME="pwdCommand"></A><B>pwd</B></H3>
<DL>
<DT>
<TT>void pwd();</TT></DT>
</DL>
<P>Print the bsh working directory. This is the cwd obeyed by all the unix
like bsh comands.
<BR>
<HR>
<H3>
<A NAME="rmCommand"></A>rm</H3>
<TT>void rm();</TT>
<P>Remove the file (like Unix rm)
<BR>
<HR>
<H3>
<A NAME="runCommand"></A>run</H3>
<TT>run( String script )</TT>
<P>run() is like source() except that it runs the command in a new, subordinate
and prune()'d namespace. So it's like "running" a command instead of "sourcing"
it ;)
<BR>
<HR>
<H3>
<A NAME="SaveCommand"></A>save</H3>
<TT>void save(Component component, String filename);</TT>
<P>Save a serializable Java object to filename.
<P>Since the AWT Button class happens to be serializable, we could test
drive the save() command.
<PRE> save(foo, "myButton.ser");</PRE>
If we did save our button, we could revive it later with the load() command.
<BR> <TT>bar = load("myButton.ser");</TT>
<BR><TT>frame(bar);</TT>
<BR>
<HR>
<H3>
<A NAME="serverCommand"></A>server</H3>
<TT>void server( int port )</TT>
<P>Create a Server Mode
server attached to the current interpreter, listening on the specified
port.
<BR>
<HR>
<H3>
<A NAME="setFontCommand"></A>setFont</H3>
<TT>Font setFont( Component comp, int ptsize )</TT>
<P>Change the point size of the font on the specified component, to ptsize.
<BR>
<HR>
<H3>
<A NAME="ShowCommand"></A>show</H3>
<TT>void show();</TT>
<P>Toggle on or off the display of the value of expressions evalauted on
the command line. Show mode may be useful if you find yourself typing print()
a lot.
<BR>
<HR>
<H3>
<A NAME="sourceCommand"></A>source</H3>
<TT>void source( String filename )</TT>
<P>Read filename into the interpreter and evaluate it in the current namespace.
Like Bourne Shell "." command.
<BR>
<HR>
<H3>
<A NAME="unsetCommand"></A>unset</H3>
<TT>void unset(String name);</TT>
<P>"undefine" the variable specified by 'name' (So that it tests == void).
<BR>
<H2>
<A NAME="MakeCommands"></A>Making BeanShell Commands</H2>
Adding to the set of "prefab" commands supplied with bsh can be about as
easy as writing any other bsh methods. You simply have to place your bsh
scripts in a bsh/commands/ directory in the classpath (or inside the JAR
file).
<P>
<BR>
</BODY>
</HTML>
|
