WorldEditExpression syntax

The WorldEdit expression parser is supposed to work like Java and related languages, with a few subtle differences:

• Final semicolons can be omitted in most cases.
• The last value in a sequence is always returned, even without a return statement.
• The binary infix ^ operator is a power operator instead of an xor operator and has an according priority as well.
• There is a postfix factorial operator (!).
• There is a binary infix near operator (~=).
• No objects :)

Operators

The expression parser uses Java's precedence rules, with the following exceptions and additions:

• The binary power operator (^) is between priority 2 and 3
• The postfix factorial operator (!) has a priority of 2
• The near operator (~=) has a priority of 7

Binary infix

These operators are put between their two operands.

Arithmetic

+ Addition
- Subtraction
* Multiplication
/ Division
% Modulo
^ Power

Bitwise

These operators interpret their operands as 32 bit integers and operate on their bits.

<< Left-shift
>> Right-shift

Logical

These operators interpret everything greater than zero as true and everything else as false.
They return 1 for true and 0 for false.

&& Logical and
|| Logical or

Comparison

These operators compare their operands and return 1 for true and 0 for false.

< less than
> greater than
<= less or equal
>= greater or equal
== equal
!= not equal
~= near

Assignment

These operators require a variable on the left side.
Using the simple assignment operator (=) to assign to a non-existant variable creates a temporary variable.

= simple assignment
+= addition+assignment
-= subtraction+assignment
*= multiplication+assignment
/= division+assignment
%= modulo+assignment
^= power+assignment

Prefix

These operators precede the expression they apply to.

-x (negation)
~x Bitwise complement (see bitwise binary operators)
!x Logical complement (see logical binary operators)
++x Pre-increment
--x Pre-decrement

Postfix

These operators succeed the expression they apply to.

x! Factorial
x++ Post-increment
x-- Post-decrement

Ternary infix

The ternary operator is used to represent a conditional expression in a compact way.

<condition> ? <true-branch> : <false-branch>

It works exactly like the if/else statement, except that the branches can only be single expressions.

Functions

The expression parser provides the following functions from the Java Math library:

• abs - Returns the absolute value of a number.
• acos - Returns the arc cosine of a value; the returned angle is in the range 0.0 through pi.
• asin - Returns the arc sine of a value; the returned angle is in the range -pi/2 through pi/2.
• atan2 - Returns the angle theta from the conversion of rectangular coordinates (x, y) to polar coordinates (r, theta).
• atan - Returns the arc tangent of a value; the returned angle is in the range -pi/2 through pi/2.
• cbrt - Returns the cube root of a value.
• ceil - Returns the smallest (closest to negative infinity) value that is greater than or equal to the argument and is equal to a mathematical integer.
• cos - Returns the trigonometric cosine of an angle.
• cosh - Returns the hyperbolic cosine of a value.
• exp - Returns Euler's number e raised to the power of a value.
• floor - Returns the largest (closest to positive infinity) value that is less than or equal to the argument and is equal to a mathematical integer.
• ln - Returns the natural logarithm (base e) of a value.
• log - Returns the natural logarithm (base e) of a value.
• log10 - Returns the base 10 logarithm (base e) of a value.
• max - Returns the greatest of the values. (supports 2 and 3 arguments)
• min - Returns the smallest of the values. (supports 2 and 3 arguments)
• rint - Returns the number that is closest in value to the argument and is equal to a mathematical integer.
• round - Returns the closest number to the argument
• sin - Returns the trigonometric sine of an angle.
• sinh - Returns the hyperbolic sine of a value.
• sqrt - Returns the correctly rounded positive square root of a value.
• tan - Returns the trigonometric tangent of an angle.
• tanh - Returns the hyperbolic tangent of a value.

Additionally, it provides the following functions:

• rotate(x, y, angle) - Rotates the given coordinate pair by the given angle.
• swap(x, y) - Swaps the contents of the 2 given variables.
• random() - Returns a random positive number less than 1.0.
• randint(max) - Returns a random positive integer less than max.

Constants

• e = 2.7182818284590452354 - The base of the natural logarithm
• pi = 3.14159265358979323846 - The ratio between circumference and diameter of a circle
• true = 1 - for boolean operations
• false = 0 - for boolean operations

Block statements

Block statements are groups of statements enclosed in braces.

Example:
{ x=5; y=6; }

They are mostly used in conjunction with control structures.

if/else

if (<condition>) <true-branch>
if (<condition>) <true-branch> else <false-branch>

• <condition> is evaluated to decide which branch to execute.
  Everything greater than zero is interpreted as true and everything else as false.
• <true-code> and <false-code> can either be single statements delimited with a semicolon or block statements.

Note:
An else keyword is always associated with the last if.
This allows elseif constructs like these:

if (<condition 1>) <true-code 1> else if (<condition 2>) <true-code 2> else <false-code>

Loops

Loops can at most loop 256 times.

While

while (<condition>) <body>
do <body> while (<condition>);

• <condition> is evaluated to decide whether to continue looping.
• <body> can either be a single statement delimited with a semicolon or a block statement.
• do-while checks the condition after executing the body.

Java/C-style for

for (<init>; <condition>; <increment>) <body>

• <init>, <condition> and <increment> are single expressions.
  
• <body> can either be a single statement delimited with a semicolon or a block statement.

Execution steps

First, <init> is evaluated once, then, each iteration follows these steps:

• If <condition> evaluates as less than or equal to zero (i.e. false), the loop is aborted.
• <body> is executed.
• <increment> is executed.

Simple for

for (<counter> = <first>, <last>) <body>

• <counter> is a variable used to count the iterations.
  
• <first> and <last> are single expressions.
  
• <body> can either be a single statement delimited with a semicolon or a block statement.

Execution steps

First, an internal counter is set to <first>. Then, each iteration follows these steps:

• If the internal counter exceeds <last>, the loop is aborted.
• <counter> is set to the internal counter.
• <body> is executed.
• <counter> is incremented by 1.0.

<first> and <last> are only evaluated once.