manual/quickstart.html

<?xml version="1.0" encoding="UTF-8"?>
<html>

<head>
    <title>Quick Start</title>
</head>

<body bgcolor="ffffff">
    <table cellspacing="10">
        <tr>
            <td align="center"><a href="http://www.beanshell.org/"><img src="images/homebutton.png" /><br />Home</a>
            </td>
            <td><a href="intro.html#Introduction"><img src="images/backbutton.png" /><br />Back
                </a></td>
            <td align="center"><a href="contents.html"><img src="images/upbutton.png" /><br />Contents</a></td>
            <td align="center"><a href="syntax.html#Basic_Syntax"><img src="images/forwardbutton.png" /><br />Next
                </a></td>
        </tr>
    </table>
    <h1>Quick Start</h1>


    Welcome to BeanShell.
    This is a crash course to get you going. We'll leave out many
    important options and details. Please see the rest of the user's guide
    for more information.
    <p CLEAR="ALL" />

    <h2><a name="Download_and_Run_BeanShell">
            Download and Run BeanShell
        </a></h2>

    Download the latest JAR file from http://www.beanshell.org
    and start up BeanShell either in the graphical desktop mode or on
    the command line.
    <p CLEAR="ALL" />

    If you just want to start playing around you may be able to launch the
    BeanShell desktop by simply double clicking on the BeanShell JAR file. More
    generally however you'll want to add the jar to your classpath so that you
    can work with your own classes and applications easily.
    <p CLEAR="ALL" />

    To do this you can either drop the BeanShell JAR file into your Java
    extensions folder or add it to your classpath. (Important: If you put
    BeanShell in the extensions folder and wish to use it with BSF applications
    like Jakarta Ant you must install the bsf.jar in the same location).

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
To install as an extension place the bsh.jar file in your 
$JAVA_HOME/jre/lib/ext folder.  (OSX users: place the bsh.jar in 
/Library/Java/Extensions or ~/Library/Java/Extensions for individual users.)

Or add BeanShell to your classpath like this:

unix:     export CLASSPATH=$CLASSPATH:bsh-xx.jar
windows:  set classpath %classpath%;bsh-xx.jar
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <p />
    <center>
        <table cellpadding="5" border="1" width="100%">
            <tr>
                <td><strong>Tip:</strong><br CLEAR="ALL" />
                    You can modify the classpath from within BeanShell using the addClassPath()
                    and setClassPath() commands.
                </td>
            </tr>
        </table>
    </center>
    <p />

    You can then run BeanShell in either a GUI or command line mode:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
    java bsh.Console       // run the graphical desktop
or
    java bsh.Interpreter   // run as text-only on the command line
or
    java bsh.Interpreter filename [ args ] // run script file
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    It's also possible to call BeanShell from within your own Java applications,
    to reach it in a remote server mode for debugging, to use it as a servlet,
    or even in an applet. See "BeanShell Modes of Operation" for more details.

    <h2><a name="The_BeanShell_GUI">
            The BeanShell GUI
        </a></h2>

    The BeanShell GUI desktop is meant to allow some experimentation with the
    features of BeanShell. It is not intended to be a replacement for a full
    featured IDE. Please check out the
    <a href="http://www.jedit.org/">jEdit editor</a> for an example of a full
    featured development environment based in part on BeanShell scripting
    capabilities.
    <p CLEAR="ALL" />

    Upon starting the BeanShell in GUI mode a console window will open.
    By right clicking on the desktop background you can open additional
    console windows and other tools such as a simple class browser.
    <p CLEAR="ALL" />

    Each console window runs a separate instance of the BeanShell interpreter.
    The graphical console supports basic command history, line editing,
    cut and paste, and even class and variable name completion. From the console
    you can open a simple editor window. In it you can write
    scripts and use the 'eval' option to evaluate the text in the attached
    console's workspace or a new workspace.
    <p CLEAR="ALL" />

    <h2><a name="Java_Statements_and_Expressions">
            Java Statements and Expressions
        </a></h2>

    BeanShell understands standard Java statements, expressions, and
    method declarations.
    Statements and expressions are all of the normal things that you'd say
    inside a Java method such as variable declarations and assignments,
    method calls, loops, and conditionals.
    <p CLEAR="ALL" />

    You can use these exactly as they would appear in Java,
    however in BeanShell you also have the option of working with "loosely typed"
    variables. That is, you can simply omit the types of variables that you use
    (both primitives and objects). BeanShell will only
    signal an error if you attempt to misuse the actual type of the variable.
    <p CLEAR="ALL" />

    Here are some examples:
    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
foo = "Foo";    
four = (2 + 2)*2/2;
print( foo + " = " + four );  // print() is a BeanShell command

// Do a loop
for (i=0; i&lt;5; i++)
    print(i);   

// Pop up a frame with a button in it
button = new JButton( "My Button" );
frame = new JFrame( "My Frame" );
frame.getContentPane().add( button, "Center" );
frame.pack();
frame.setVisible(true);
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    <h2><a name="Useful_BeanShell_Commands">
            Useful BeanShell Commands
        </a></h2>

    In the previous example we used a convenient "built-in" BeanShell command
    called print(), to display values. print() does pretty
    much the same thing as System.out.println() except that it insures that the
    output always goes to the command line. print() also displays some types
    of objects (such as arrays) more verbosely than Java would.

    Another related command is show(), which toggles on and off automatic
    display of the result of every line you type.
    <p CLEAR="ALL" />

    Here are a few other examples of BeanShell commands:

    <ul>
        <li> <strong>source(), run()</strong>
            - Read a bsh script into this interpreter, or run it
            in a new interpreter</li>

        <li> <strong>frame()</strong>
            - Display a GUI component in a Frame or JFrame.</li>

        <li> <strong>load(), save()</strong>
            - Load or save serializable objects to a file.</li>

        <li> <strong>cd(), cat(), dir(), pwd(), etc.</strong>
            - Unix-like shell commands</li>

        <li> <strong>exec()</strong> - Run a native application </li>

        <li><strong>javap()</strong> - Print the methods and fields of an object,
            similar to the output of the Java javap command.</li>

        <li> <strong>setAccessibility()</strong>
            - Turn on unrestricted access to private and protected components.</li>

    </ul>

    <p CLEAR="ALL" />
    See the complete list of <a href="bshcommands.html">BeanShell Commands</a>
    for more information.
    <p CLEAR="ALL" />

    <p />
    <center>
        <table cellpadding="5" border="1" width="100%">
            <tr>
                <td><strong>Tip:</strong><br CLEAR="ALL" />
                    BeanShell commands are not really "built-in" but are simply BeanShell scripts
                    that are automatically loaded from the classpath. You can add your
                    own scripts to the classpath to extend the basic command set.
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Scripted_Methods">
            Scripted Methods
        </a></h2>

    You can declare and use methods in BeanShell just as you would in a Java class.

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
int addTwoNumbers( int a, int b ) {
    return a + b;
}

sum = addTwoNumbers( 5, 7 );  // 12
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />


    Bsh methods may also allow dynamic (loose) argument and return types.

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
add( a, b ) {
    return a + b;
}

foo = add(1, 2);            // 3
foo = add("Oh", " baby");   // "Oh baby"
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Implementing_Interfaces">Implementing Interfaces</a></h2>

    <em>Note: implementing arbitrary interfaces requires BeanShell be run
        under a Java 1.3 or higher environment.</em>
    <p CLEAR="ALL" />

    You can use the standard Java anonymous inner class syntax to implement an
    interface type with a script. For example:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
ActionListener scriptedListener = new ActionListener() {
    actionPerformed( event ) { ... }
}
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    You don't have to script all of the methods of an interface. You can opt to
    script only those that you intend to call if you want to.
    The calling code will simply throw an exception if it tries to
    invoke a method that isn't defined.
    If you wish to override the behavior of a large number of methods - say to
    produce a "dummy" adapter for logging - you can implement a special method
    signature: invoke(name, args) in your scripted object. The invoke() method
    is called to handle any undefined method invocations:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
ml = new MouseListener() {
    mousePressed( event ) { ... }
    // handle the rest
    invoke( name, args ) { print("Method: "+name+" invoked!");
}
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Scripted_Objects">
            Scripted Objects
        </a></h2>

    In BeanShell, as in JavaScript and Perl, method "closures" allow you to create
    scripted objects. You can turn the results of a method call into an object
    reference by having the method return the special value <strong>this</strong>.
    You can then use the reference to refer to any variables set during the method
    call. Useful objects need methods of course, so in BeanShell scripted methods
    may also contain methods at any level. For example:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
foo() {
    print("foo");
    x=5;

    bar() {
        print("bar");
    }

    return this;
}

myfoo = foo();    // prints "foo"
print( myfoo.x ); // prints "5"
myfoo.bar();      // prints "bar"
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    If this "closure" thing seems strange to don't worry. It's just an
    evolutionary step that languages acquired along the path to Objects.
    Please see the user's manual for a more thorough explanation.
    <p CLEAR="ALL" />

    Within your scripts, BeanShell scripted objects
    (i.e. any <em>'this'</em> type reference like myFoo in the previous example)
    can automatically implement any Java interface type. When Java code calls
    methods on the interface the corresponding scripted methods will be invoked to
    handle them. BeanShell will automatically "cast" your scripted object
    when you attempt to pass it as an argument to a method that takes an interface
    type.
    For passing script references outside of BeanShell, you can perform an
    explicit cast where necessary. Please see the user manual for full details.
    <p CLEAR="ALL" />

    <h2><a name="Calling_BeanShell_From_Your_Application">Calling BeanShell From Your Application</a></h2>

    You can evaluate text and run scripts from within your application by
    creating an instance of the BeanShell interpreter and using the eval()
    or source() commands. You may pass in variable references to objects you
    wish to use in scripts via the set() method and retrieve results with the
    get() method.

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
import bsh.Interpreter;

Interpreter i = new Interpreter();  // Construct an interpreter
i.set("foo", 5);                    // Set variables
i.set("date", new Date() ); 

Date date = (Date)i.get("date");    // retrieve a variable

// Eval a statement and get the result
i.eval("bar = foo*10");             
System.out.println( i.get("bar") );

// Source an external script file
i.source("somefile.bsh");
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <p />
    <center>
        <table cellpadding="5" border="1" width="100%">
            <tr>
                <td><strong>Tip:</strong><br CLEAR="ALL" />In the above example the Interpreter's eval() method also
                    returned the
                    value of bar as the result of the evaluation.</td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Conclusion">Conclusion</a></h2>

    We hope this brief introduction gets you started. Please see the full user
    manual for more details. Please consult the mailing list archives for
    more useful information. http://www.beanshell.org/

    <table cellspacing="10">
        <tr>
            <td align="center"><a href="http://www.beanshell.org/"><img src="images/homebutton.png" /><br />Home</a>
            </td>
            <td><a href="intro.html#Introduction"><img src="images/backbutton.png" /><br />Back
                </a></td>
            <td align="center"><a href="contents.html"><img src="images/upbutton.png" /><br />Contents</a></td>
            <td align="center"><a href="syntax.html#Basic_Syntax"><img src="images/forwardbutton.png" /><br />Next
                </a></td>
        </tr>
    </table>
</body>

</html>