Syntax

Simple literals

Bex script uses the same syntax as Java for simple literals. Numeric, character an boolean literals are exactly like in Java. See Java Language Specification for details. Valid literals are for example:

bex> 0xf
15
bex> 1127498877973L
1127498877973
bex> 1.2f
1.2
bex> 1.3e3
1300.0
bex> 'a'
a
bex> true
true

Bex script supports the same syntax for string literals as Java. However in addition to Java like string literals, bex script supports also multiline string literals. For example:

bex> "hello world"
hello world
bex> """hello
multiline
world
"""
hello
multiline
world

Note that the normal character escapes are not supported in multiline string literals.

From version 1.1, bex also supports embedded expressions inside strings. For example:

bex> "Current date is: ${Date.new()}"
Current date is: Sun Oct 01 18:28:46 EEST 2006

Embedded expressions work both with normal strings and with multiline strings.

Bex script has two additional special literals: null and void. Null is the value of a reference that does not refer to any object. Void is the value of an expression that does not have any value.

Variables

The variables in bex script are untyped. A variable has a name and a value. A variable is defined by assigning a value to a name. For example:

bex> a = 5
5
bex> hello = "world"
world
bex> a
5

Variables live inside containers called environments. An environment is basically a Map that maps variable names to values. In addition an environment is associated with a parent environment unless it is the top environment. The parent of the top environment is null.

Special variables

In addition to user defined variables bex script has the following "magic" variables:

Identifiers

Bex script variables are identified by name. Other identifiers in bex script are Java class names and java class member names.

Valid bex script variable names begin with a letter [A-Za-z] or character underscode '_' or dollar sign '$'. The rest of the characters are either letters, digits, underscores or dollars.

The syntax for Java class names differs from Java. The package name separator is double colon '::' and the inner class name separator is the dollar sign '$'. So for example:

bex> java::util::Map$Entry
interface java.util.Map$Entry

The syntax for referencing the members of java objects and classes is the same as in Java, for example:

bex> java::lang::System.out.println("hello")
hello
void

The reason not to use '.' as the separator is that I don't like using the same token for both member access and as a name separator. Having ambiguous tokens like that just feels dirty - and makes the implementation messy.

Expressions

A bex script program is a sequence of expressions. A program is executed by the bex script interpreter by evaluating the expressions in order. Expressions are built from literals, variable names and Java class and class member names by combining them using operators.

Logical operators

Arithmetic operators

Bitwise operators

Assignment operators

For all binary assignment operators the value of the assignment expression is assigned to the left hand side of the expression.

Special operators

Block expressions

Functions are created in bex script by assigning a block expression to a variable. A block expression consists of an optional declaration of unbind variables and a sequence of expressions forming the body of the block expression. For example:

bex> a = |x,y|{ print(x + y) }
bex.Block@67ac19
bex> a("hello","world")
helloworld
void

The unbind variables (arguments) are declared inside a pair of vertical bar '|' characters and separated by commas. The argument declaration is optional. Any arguments that are not declared will be available to the body expressions as special variables $0, $1 and so on. If the last argument ends with token '...' the argument will contain the rest of the arguments as an array. For example:

bex> a = { print($0) }
bex.Block@253498
bex> a("hello")
hello
void
bex> a = |args...|{ args }
bex.Block@9fef6f
bex> b = a(1,2,3,4,5)
[Ljava.lang.Object;@1a457b6
bex> Arrays.asList(b)
[1, 2, 3, 4, 5]

Function call

A block expression can be called with the special operator (). When called like this the block expressions effectively behaves like a regular function: a new environment is created, the unbind variables are bound according to the argument declaration of the block expression and finally the expressions forming the body are evaluated. The following text uses the terms block expression and function interchangeably. Note however that block expressions also support other operations in addition to the call-operation.

Normally the arguments to a block expression are specified as a comma separated list inside the parentheses. In addition to this, bex script provides special syntactic sugar for arguments that are block expressions. They can be specified outsidethe parentheses and commas are not needed between them. If all the arguments are block expressions then the parentheses are not needed at all. This syntactic trick allows writing bex script functions that are syntactically similar to some control flow statements in Java.

The following example illustrates different ways to call a block expression. In the example the construct {void} is just an example function literal.

bex> fun = |args...|{ print(Arrays.asList(args)) }
bex.Block@2b58b0
bex> fun(1,2,3)
[1, 2, 3]
void
bex> fun(1,2,{void})
[1, 2, bex.Block@275860]
void
bex> fun(1,2) {void}
[1, 2, bex.Block@2d8e70]
void
bex> fun {void} (2) {void}
[bex.Block@2d8890, 2, bex.Block@2d8880]
void
bex> fun {void} {void} {void}
[bex.Block@2d8320, bex.Block@2d8310, bex.Block@2d8300]
void

Normally a call terminates when all the expressions of the block expression body have been evaluated. A call can also terminate before that if an expression in the block expression body evaluates to an instance of bex.ReturnControl. The builtin functions return, break and continue evaluate to bex.ReturnControl instances, so they can be used as control flow statements.

Another way a block expression can be evaluated is by inlining it. Inlining a block expression is very much like calling it. The only differences are in the way "this" and "super" are resolved and how it behaves with respect to ReturnControls. In a normal call, if an expression evaluates to an instance of ReturnControl, the interpreter stops evaluating the expressions and the value of the call is the value associated with the ReturnControl. However, when the block expression is being inlined the value of the inlining is not the value associated with the ReturnControl object but the ReturnControl object itself. So if block expression b is being inlined inside a block expression a and b calls return(1), then also a returns and the return value is 1. This feature can be used to implement loops and other control structures that are often implemented as special statements in other languages.

Special variables "this" and "super" are normally resolved so that this resolves to current environment and super to the lexical parent environment. When a block expression is inlined, however, they are resolved to the closest non-inlined environment and its parent. This means that you can do:

if (true) { this.foo = "bar" }
print(this.foo)

There is yet another way to use a block expression which is especially useful when constructing domain specific languages. In addition to calling and inlining a block expression can be just evaluated. This is different from calling/inlining because no new environment is created. The effect is the same as if the body of the block expression was written right there where it is being evaluated. If the block expression had any unbind variables they will be resolved according to normal variable resolution procedure and if they are unresolved an exception is thrown. The builtin function eval can be used to evaluate a block expression.

Scripted objects and meta object protocol

To create a scripted object (i.e. an entity with attributes and functions that manipulate those attributes) one needs to just return (or pass) a reference to an environment. The returned environment behaves like a closure: it contains all the variable bindings that existed before it was returned. Now this is very much like in BeanShell and while extremely useful not particularily exciting. However, bex script also provides a powerful meta object protocol (MOP) that is more flexible than BeanShell's invoke. By using special variables $set, $get and $dir one can extend the regular variable resolution procedure and do all kinds of clever tricks.

For example to make javax.servlet.http.HttpSession to appear as a bex script object, code similar to the following example could be used:

wrapSession = |session|{
	ws = object()
	ws.$get = |name|{ session.getAttribute(name) }
	ws.$set = |name, value|{ session.setAttribute(name, value) }
	ws.$dir = { session.getAttributeNames() }
	ws
}

Builtins

Bex script comes with a bunch of useful builtin functions. These are defined in the script default.bex which is automatically evaluated when the interpreter is started.

array(byte,5)

cast(10, Double.TYPE)

dir(this)

each(list) { print($0) }

eval { foo = "bar" }

if (a < 0) { 
  print("negative") 
} { 
  print("positive") 
}

import("java::awt", javax::awt::event")

lock(obj) { obj.foo++ }

throw(Exception.new())

try { 
	out.write(str.length())
} (NullPointerException) {
	print("null string")
} (IOException) {
	print("write failed: " + $0)
} {
	out.close()
}

while { a < 10 } {
	print(a)
	a++
}

inline(print)

print("hello world")

list(1,2,3,4)

tuple(1,2,3)

hash("name1","value1","name2","value2")

return(1)

break(1)

continue()

object { firstName = "Juha"; lastName = "Lindström" }

implement(Runnable,Iterator,this)

include("script.bex")

Java extensions

Bex script supports registering extension methods to existing Java classes. This functionality can be used to make accessing Java APIs from scripts easier and more natural. The default startup script default.bex contains the following extensions:

bex> list(1,2,3).each |it|{ print("item: void") }
item: 1
item: 2
item: 3
void

bex> list(1,2,3).iterator().each |it|{ print("item: void") }
item: 1
item: 2
item: 3
void

bex> 3.times |i|{ print("count: void") }
count: 0
count: 1
count: 2
void

bex> FileInputStream.new("test.txt").load()
[B@1ea2dfe

bex> FileReader.new("test.txt").load()
hello
world

bex> File.new("test.txt").load()
line: hello
line: world
void

bex> FileInputStream.new("test.txt").eachLine |l|{ print("line: void") }
line: hello
line: world
void

bex> FileReader.new("test.txt").eachLine |l|{ print("line: void") }
line: hello
line: world
void

bex> File.new("test.txt").eachLine |l|{ print("line: void") }
line: hello
line: world
void

FileInputStream.new("test.txt").with |in|{ in.read() }

FileOutputStream.new("test.txt").with |out|{ out.write(1) }

FileReader.new("test.txt").with |in|{ in.read() }

FileWriter.new("test.txt").with |in|{ out.write("foo") }

Socket.new("localhost", 80).with |s|{
	s.outputStream.with { $0.write("GET / HTTP/1.0\r\n\r\n".bytes) }
	s.inputStream.with { InputStreamReader.new($0).eachLine { print($0) } }
}

ServerSocket.new(4314).with |ss|{ handle(ss.accept()) }

Adding new Java extensions is easy: just declare a new function and assign it to a static member of a Java class that does not exist. The first argument to the function will be the object that received the call. For example:

bex> String.toInt=|s|{ Integer.parseInt(s) }
bex.Block@19fcc69
bex> "123".toInt() + 1
124

Interactive use

The bex script interpreter can be started in interactive mode with the following command:

java bex.Interpreter [-q] [-i] [file1] [arg1 arg2 ...]

If there are no command line arguments the interpreter starts in interactive mode. Option -i forces the interpreter to enter interactive mode even if the arguments also specify a file "file1" to be evaluated. The rest of the arguments arg1 arg2 ... are passed to the script as an array of strings with name $args. Option -q tells the interpreter to be quiet and not print any prompts or welcome messages.

Tip: You can get get command history and other shell like features by using a very nice utility program called rlwrap. Just start the interpreter with rlwrap java bex.Interpreter and working with the interpreter will be much more pleasant.

Tip2: When used from the command line, the interpreter evaluates file $HOME/.bexrc if it exists. You use this facility to setup the root environment the way you want (e.g. by adding some functions not provided by the default environment).

Embedded use

The interpreter can be embedded inside a Java application in the following way:

// Create the interpreter
bex.Interpreter i = new bex.Interpreter();

// Sets a variable inside the interpreter
i.put("myname", "bex");

// Evaluate file myscript.bex
FileReader in = new FileReader("myscript.bex");
try { i.eval(fr); } finally { in.close(); }

// Evaluate a string
i.eval("greeting = \"hello \" + myname");

// Print the value of the script variable "greeting"
System.out.println(i.get("greeting"));

Use from within a shell script

The following trick can be used to run a bex script from within a shell script:

#!/bin/bash
export CLASSPATH=/home/jli/projects/bexscript/trunk/dist/bex-1.0.1.jar
java bex.Interpreter -q <<EOF
10.times { print("hello from bexscript") }
EOF

The -q switch causes the interpreter not to output any prompts or welcome messages when reading input from stdin.