manual/syntax.html

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

<head>
    <title>Basic Syntax</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="quickstart.html#Quick_Start"><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="methods.html#Scripted_Methods"><img
                        src="images/forwardbutton.png" /><br />Next
                </a></td>
        </tr>
    </table>
    <h1>Basic Syntax</h1>


    BeanShell is, foremost, a Java interpreter. So you probably already know
    most of what you need to start scripting with BeanShell. This
    section describes specifically what portion of the Java language BeanShell
    interprets and how BeanShell extends it or "loosens" it to be more
    scripting-language-like.
    <p CLEAR="ALL" />

    <h2><a name="Standard_Java_Syntax"> Standard Java Syntax </a></h2>

    In a BeanShell script (and on the command line) you can type normal
    Java statements and expressions and display the results.
    Statements and expressions are the kinds of things you normally find
    inside of a Java method: variable assignments, method calls, math
    expressions, for-loops, etc.

    <p CLEAR="ALL" />

    Here are some examples:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
/*
    Standard Java syntax
*/

// Use a hashtable
Hashtable hashtable = new Hashtable();
Date date = new Date();
hashtable.put( "today", date );

// Print the current clock value
print( System.currentTimeMillis() );

// Loop
for (int i=0; i&lt;5; i++)
    print(i);

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

    You can also define your own methods and use them just as you would inside a
    Java class. We'll get to that in a moment.

    <h2><a name="Loosely_Typed_Java_Syntax">Loosely Typed Java Syntax </a></h2>

    In the examples above, all of our variables have declared types. e.g.
    "JButton button". Beanshell will enforce these types, as you will see if
    you later try to assign something other than a JButton to the variable
    "button" (you will get an error message).
    However BeanShell also supports "loose" or dynamically typed variables.
    That is, you can refer to
    variables without declaring them first and without specifying any type.
    In this case BeanShell will do type checking where appropriate at runtime.
    So, for example, we could have left off the types in the above example and
    written all of the above as:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
/*
    Loosely Typed Java syntax
*/

// Use a hashtable
hashtable = new Hashtable();
date = new Date();
hashtable.put( "today", date );

// Print the current clock value
print( System.currentTimeMillis() );

// 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 />

    This may not seem like it has saved us a great deal of work. But you will
    see the difference when you come to rely on scripting as part of your
    development and testing process; especially for in interactive use.
    <p CLEAR="ALL" />

    When a "loose" variable is used you are free to reassign it to another type of
    Java object later. Untyped BeanShell variables can also freely hold Java
    primitive values like <b>int</b>
    and <b>boolean</b>. Don't worry, BeanShell always knows the real types and
    only lets you use the values where appropriate. For primitive types this
    includes doing the
    correct numeric promotion that the real Java language would do when you use
    them in an expression.
    <p CLEAR="ALL" />

    <h2><a name="Exception_Handling">Exception Handling</a></h2>

    Exception handling using try/catch blocks works just as it does in Java.
    For example:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
try {
    int i = 1/0;
} catch ( ArithmeticException e ) {
    print( e );
}
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    But you can loosely type your catch blocks if you wish:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
try {
    ...
} catch ( e ) { 
    print( "caught exception: "+e );
}
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Basic_Scoping_of_Variables">Basic Scoping of Variables</a></h2>

    <p />
    <center>
        <table cellpadding="5" border="1" width="90%">
            <tr>
                <td bgcolor="#eeeebb"><strong>Note:</strong><br CLEAR="ALL" />
                    As of BeanShell version 1.3 the default scoping of loosely typed variables was
                    changed to be more consistent with Java. BeanShell still supports an alternate
                    scoping used in earlier versions. This mode can be enabled for legacy code by
                    setting the system property "localscoping" to true.
                    See appendix "Local Scoping".
                </td>
            </tr>
        </table>
    </center>
    <p />

    Variable scoping in BeanShell behaves, wherever possible, just like that in
    Java. Ordinary Java, however, does not offer "loose" variables
    (variables that can be used without being declared first).
    So we must define their behavior within BeanShell.
    We'll see in the next section that untyped variables - variables that are not
    declared and not assigned a value elsewhere - default to the
    <em>local</em> scope.
    This means that, in general, if you assign a value to a variable without first
    declaring it, you are creating a new local variable in the current scope.
    <p CLEAR="ALL" />

    <h3>Blocks</h3>

    Blocks are statements between curly braces {}. In BeanShell, as in Java,
    blocks define a level of scope for typed variables: typed variables declared
    within a block are local to the block. Other assignments within the block
    occur, as always, wherever the variable was defined.
    <p CLEAR="ALL" />

    Untyped variables in BeanShell, however, are not constrained by blocks.
    Instead they act as if they were declared at the outer (enclosing)
    scope's level.
    With this in mind, BeanShell code looks just like Java code.

    In BeanShell if you declare a typed variable within a block it is local to the
    block. But if you use an untyped variable (which looks just like an ordinary
    assignment in Java) it behaves as an assignment to the enclosing scope.
    <p CLEAR="ALL" />

    This will make sense with a few examples:
    <p CLEAR="ALL" />

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
// Arbitrary code block
{
    y = 2;      // Untyped variable assigned
    int x = 1;  // Typed variable assigned
}
print( y ); // 2
print( x ); // Error! x is undefined.

// Same with any block statement: if, while, try/catch, etc.
if ( true ) {
    y = 2;      // Untyped variable assigned
    int x = 1;  // Typed variable assigned
}
print( y ); // 2
print( x ); // Error! x is undefined.
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    Variables declared in the for-init area of a for-loop follow the same
    rules as part of the block:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
for( int i=0; i&lt;10; i++ ) {  // typed for-init variable
    j=42;
}
print( i ); // Error! 'i' is undefined.
print( j ); // 42

for( z=0; z&lt;10; z++ ) { }   // untyped for-init variable
print( z ); // 10
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Variable_Modifiers">Variable Modifiers</a></h2>

    The standard Java variable modifiers may be used on typed variables:
    private / protected / public, final, transient, volatile, static.
    Only 'final' is currently implemented. The others are currently ignored.
    <p CLEAR="ALL" />
    Modifiers may not be applied to untyped variables.

    <h2><a name="Convenience_Syntax">Convenience Syntax</a></h2>

    In BeanShell you may access JavaBean properties as if they were fields:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
button = new java.awt.Button();
button.label = "my button";  // Equivalent to: b.setLabel("my button");
print( button.label );       // Equivalent to print( b.getLabel() );
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    JavaBean properties are simply pairs of "setter" and "getter" methods that
    adhere to a naming convention. In the above example BeanShell located
    a "setter" method with the name "setLabel()" and used it to assign the string
    value. It then found the method named getLabel() to retrieve the value.
    <p CLEAR="ALL" />

    Boolean properties may optionally use the syntax "is" for their "getter".
    e.g.

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
Float f = new Float(42f);
print( f.infinite );  // Equivalent to print( f.isInfinite() ); // false
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    If there is any ambiguity with an actual Java field name of the object
    (e.g. label in the above example) then the actual field name takes precedence.

    If you wish to avoid any ambiguity BeanShell provides an additional,
    uniform syntax for accessing both Java Bean properties and Hashtable or Map
    entries. You may use the "{}" curly brace construct with a
    String identifier as a qualifier on any variable of the appropriate type:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <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>
                </td>
            </tr>
        </table>
    </center>
    <p />

    Where the java.util.Collections API is available, Maps are also supported.
    <p CLEAR="ALL" />

    <h3>Enhanced 'for' Loop</h3>

    BeanShell supports the Java 1.5 style enhanced for-loop for iterating over
    collections and array types. (Note that you do not have to be running Java 1.5
    to use this feature).

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

for ( untypedElement : foo ) 
	print( untypedElement ); 

for ( Object typedElement: foo ) 
	print( typedElement );

int [] array = new int [] { 1, 2, 3 };

for( i : array ) 
	print(i);

for( char c : "a string" )
	print( c ); 
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    Supported iterable types include all the obvious things.

    <ul>
        <li>JDK 1.1+ - (no collections): Enumeration, arrays, Vector, String, StringBuffer</li>
        <li>JDK 1.2+ - (w/collections): Collections, Iterator</li>
    </ul>

    See also the BshIterator API which supports the ehanced for-loop and allows
    iteration over these types using the dynamically loaded BeanShell Collection
    manager.
    <p CLEAR="ALL" />

    <h3>Switch Statements</h3>

    In BeanShell, the switch statement may be used not only with numeric types
    but with objects. For example, you may switch on Dates and Strings which
    are compared for equality with their equals() methods:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
dateobj = new Date();

switch( dateobj ) 
{
	case newYears:
		break;
	case christmas:
		break;
	default:
}
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />


    <h2><a name="Auto_Boxing_and_Unboxing">Auto Boxing and Unboxing</a></h2>

    "Boxing" and "Unboxing" are the terms used to describe automatically wrapping
    a primitive type in a wrapper class and unwrapping it as necessary. Boxing
    is a feature of Java (SDK1.5) and has been supported in BeanShell for many
    years.
    <p CLEAR="ALL" />

    BeanShell supports boxing and unboxing of primitive types. For example:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
int i=5;
Integer iw = new Integer(5);
print( i * iw );  // 25

Vector v = new Vector();
v.put(1); 
int x = v.getFirstElement();
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Importing_Classes_and_Packages">Importing Classes and Packages</a></h2>

    In BeanShell as in Java, you can either refer to classes by their fully
    qualified names, or you can <strong>import</strong> one or more classes
    from a Java package.
    <p CLEAR="ALL" />

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
// Standard Java
import javax.xml.parsers.*;
import mypackage.MyClass;
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />
    <p CLEAR="ALL" />

    In BeanShell import statements may appear anywhere, even inside a method,
    not just at the top of a file. In the event of a conflict, later imports take
    precedence over earlier ones.
    <p CLEAR="ALL" />

    A somewhat experimental feature is the "super import". With it you may
    automatically import the entire classpath, like so:

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

    The first time you do this BeanShell will map out your entire classpath;
    so this is primarily intended for interactive use. Note that importing every
    class in your classpath can be time consuming. It can also result in a lot
    of ambiguities. Currently BeanShell will report an error when resolving an
    an ambiguous import from mapping the entire classpath. You may disambiguate
    it by importing the class you intend.
    <p CLEAR="ALL" />

    <p />
    <center>
        <table cellpadding="5" border="1" width="100%">
            <tr>
                <td><strong>Tip:</strong><br CLEAR="ALL" />
                    The BeanShell which() command will use the classpath mapping capability to
                    tell you where exactly in your classpath a specified class is located:
                    <pre>
bsh % which( java.lang.String );
Jar: file:/usr/java/j2sdk1.4.0/jre/lib/rt.jar
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    See "Class Path Management" for information about modifying the BeanShell
    classpath at run-time with the addClassPath() or setClassPath() commands.
    <p CLEAR="ALL" />
    Also see "BeanShell Commands" for information about importing new BeanShell
    commands from the classpath.
    <p CLEAR="ALL" />

    <h3>Default Imports</h3>

    By default, common Java core and extension packages are imported for
    you. They are, in the order in which they are imported:

    <ul>
        <li>javax.swing.event</li>
        <li>javax.swing</li>
        <li>java.awt.event</li>
        <li>java.awt</li>
        <li>java.net</li>
        <li>java.util</li>
        <li>java.io</li>
        <li>java.lang</li>
    </ul>
    <p CLEAR="ALL" />

    Two BeanShell package classes are also imported by default:
    <p CLEAR="ALL" />

    <ul>
        <li>bsh.EvalError</li>
        <li>bsh.Interpreter</li>
    </ul>
    <p CLEAR="ALL" />

    Finally, we should mention that BeanShell commands may be imported from the
    classpath. The default commands are imported in the following way:

    <p />
    <center>
        <table border="1" cellpadding="5" width="100%">
            <tr>
                <td bgcolor="#dfdfdc">
                    <pre>
importCommands("/bsh/commands");
</pre>
                </td>
            </tr>
        </table>
    </center>
    <p />

    We will discuss how to import your own commands in a later section.

    <p />
    <center>
        <table cellpadding="5" border="1" width="100%">
            <tr>
                <td><strong>Tip:</strong><br CLEAR="ALL" />
                    The classes java.awt.List and java.util.List are both imported by default.
                    Because java.util.List is imported later, as part of the java.util package,
                    it takes precedence. To access java.awt.List simply import it in, or the
                    java.awt package again your script. Later imports take precedence.
                </td>
            </tr>
        </table>
    </center>
    <p />

    <h2><a name="Document_Friendly_Entities">Document Friendly Entities</a></h2>

    BeanShell supports special overloaded text forms of all common operators
    to make it easier to embed BeanShell scripts inside other kinds of documents
    (e.g XML).
    <p CLEAR="ALL" />

    <table border="1" cellpadding="5">
        <tr>
            <td><strong>@gt</strong></td>
            <td>&gt;</td>
        </tr>
        <tr>
            <td><strong>@lt</strong></td>
            <td>&lt;</td>
        </tr>
        <tr>
            <td><strong>@lteq</strong></td>
            <td>&lt;=</td>
        </tr>
        <tr>
            <td><strong>@gteq</strong></td>
            <td>&gt;=</td>
        </tr>
        <tr>
            <td><strong>@or</strong></td>
            <td>||</td>
        </tr>
        <tr>
            <td><strong>@and</strong></td>
            <td>&amp;&amp;</td>
        </tr>
        <tr>
            <td><strong>@bitwise_and</strong></td>
            <td>&amp;</td>
        </tr>
        <tr>
            <td><strong>@bitwise_or</strong></td>
            <td>|</td>
        </tr>
        <tr>
            <td><strong>@left_shift</strong></td>
            <td>&lt;&lt;</td>
        </tr>
        <tr>
            <td><strong>@right_shift</strong></td>
            <td>&gt;&gt;</td>
        </tr>
        <tr>
            <td><strong>@right_unsigned_shift</strong></td>
            <td>&gt;&gt;&gt;</td>
        </tr>
        <tr>
            <td><strong>@and_assign</strong></td>
            <td>&amp;=</td>
        </tr>
        <tr>
            <td><strong>@or_assign</strong></td>
            <td>|=</td>
        </tr>
        <tr>
            <td><strong>@left_shift_assign</strong></td>
            <td>&lt;&lt;=</td>
        </tr>
        <tr>
            <td><strong>@right_shift_assign</strong></td>
            <td>&gt;&gt;=</td>
        </tr>
        <tr>
            <td><strong>@right_unsigned_shift_assign</strong></td>
            <td>&gt;&gt;&gt;=</td>
        </tr>
    </table>

    <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="quickstart.html#Quick_Start"><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="methods.html#Scripted_Methods"><img
                        src="images/forwardbutton.png" /><br />Next
                </a></td>
        </tr>
    </table>
</body>

</html>