Got a question that the wiki doesn't answer? Ask on the forum (preferred), or join us on IRC.

# WorldEdit Expression 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
-= 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`.

Block query functions:

• `query(x, y, z, type, data)` - Returns `true`, if the block at the given coordinates has the given type and data value. If possible, the type and data of the block will be assigned to `type` and `data`.
• `queryRel(dx, dy, dz, type, data)` - Like `query`, except with relative world coordinates
• `queryAbs(xp, yp, zp, type, data)` - Like `query`, except with absolute world coordinates

## 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.