Hello World

Let us start with a simple "Hello World" example. In Xtend, that reads as

class HelloWorld {
  def static void main(String[] args) {
    println("Hello World")
  }
}

The Xtend code resembles Java a lot. You can already see how the syntactic noise is reduced: No semicolons, no return types etc. An Xtend class resides in a plain Java project. As soon as the SDK is installed, Eclipse will automatically translate it to Java code. You'll find it in a source folder xtend-gen. The hello world example is translated to the following Java code:

import org.eclipse.xtext.xbase.lib.InputOutput;

public class HelloWorld {
  public static void main(final String[] args) {
    InputOutput.<String>println("Hello World");
  }
}

The Runtime Library

The only surprising fact in the generated Java code may be the library class InputOutput. Many features of Xtend are not built into the language itself but provided via the library org.eclipse.xtend2.lib. The library is available from a Maven repository (check the website for details) and provides a lot of useful functionality annotating existing types from Java's SDK.It provides means to create collections in a readable way:

val myList = newArrayList(1, 2, 3)
val mySet = newHashSet(4, 5, 6)
val myMap = newHashMap(1 -> 'one', 2 -> 'two', 3 -> 'three')

It also extends the collection types with a lot of very useful functions. One example is the ubiquitous map function:

val listOfNames = myList.map( e | myMap.get(e) )

Operators to concat collections or to do arithmetics with types like BigDecimal are also available.

The Xtend Tutorial

The best way to get acquainted with the language is to materialize the Xtend Tutorial example project in your workspace. You will find it in the New > Project.. wizard dialog.The project contains a couple of sample Xtend files which show the different language concepts in action. Looking into the xtend-gen folder which holds the compiled Java code will help you understand the concepts better.

Maven Support

The runtime library as well as a plugin to run the compiler in a Maven build can be be obtained from the following maven repository: http://build.eclipse.org/common/xtend/maven/. We are working on having these artifacts in Maven Central soon.Here's the XML for the library dependency:

<dependency>
  <groupId>org.eclipse.xtend2</groupId>
  <artifactId>org.eclipse.xtend2.lib</artifactId>
  <version>2.2.0</version>
</dependency>

And this is the XML for the plugin:

<plugin>
  <groupId>org.eclipse.xtend2</groupId>
  <artifactId>xtend-maven-plugin</artifactId>
  <version>2.2.0</version>
  <executions>
    <execution>
      <goals>
        <goal>compile</goal>
        <goal>testCompile</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Overriding Methods

Methods can override other methods from the super class or implemented interface methods using the keyword override. If a method overrides a method from a super type, the override keyword is mandatory and replaces the keyword def. As in Java final methods cannot be overridden by subclasses.Example:

override String first(List<String> elements) {
  elements.get(0);
}

Declared Exceptions

Xtend does not force you to catch checked exceptions. Instead, they are rethrown in a way the compiler does not complain about a missing throws clause, using the sneaky-throw technique introduced by Lombok. Nevertheless, you can still declare the exceptions thrown in a method's body using the same throws clause as in Java.

/*
 * throws an Exception
 */
def void throwException() throws Exception {
   throw new Exception()
}

/*
 * throws an Exception without declaring it
 */
def void sneakyThrowException() {
   throw new Exception()
}

Inferred Return Types

If the return type of a method can be inferred from its body it does not have to be declared. That is the method

def String first(List<String> elements) {
  elements.get(0);
}

could be declared like this:

def first(List<String> elements) {
  elements.get(0);
}

This does not work for abstract method declarations as well as if the return type of a method depends on a recursive call of the same method. The compiler tells the user when it needs to be specified.

Dispatch Methods

Generally, method binding works just like method binding in Java. Method calls are bound based on the static types of arguments. Sometimes this is not what you want. Especially in the context of extension methods you would like to have polymorphic behavior.Dispatch methods make a set of overloaded methods polymorphic. That is the runtime types of all given arguments are used to decide which of the overloaded methods is being invoked. This essentially removes the need for the quite invasive visitor pattern.A dispatch method is marked using the keyword dispatch.

def dispatch printType(Number x) { 
  "it's a number" 
}

def dispatch printType(Integer x) { 
  "it's an int" 
}

For a set of visible dispatch methods in the current type hierarchy, the compiler infers a common signature using the common super type of all declared arguments and generates a Java method made up of if instanceof else cascades. It dispatches to the different available methods. The actually declared methods are all compiled to Java methods that are prefixed with an underscore.For the two dispatch methods in the example above the following Java code would be generated:

protected String _printType(final Number x) {
  return "it\'s a number";
}

protected String _printType(final Integer x) {
  return "it\'s an int";
}

public String printType(final Number x) {
  if (x instanceof Integer) {
    return _printType((Integer)x);
  } else {
    return _printType(x);
  }
}

Note that the instanceof cascade is ordered such that more specific types come first.The default visibility of the underscore methods is protected. If all dispatch methods explicitly declare the same visibility, this will be the visibility of the inferred dispatcher, too. Otherwise it is public. In case there is no single most general signature, one is computed and the different overloaded methods are matched in the order they are declared within the class file. Example:

def dispatch printTypes(Number x, Integer y) { 
  "it's some number and an int" 
}

def dispatch printTypes(Integer x, Number y) { 
  "it's an int and a number" 
}

generates the following Java code :

public String printTypes(final Number x, final Number y) {
  if (x instanceof Integer) {
    return _printTypes((Integer)x, y);
  } else if (y instanceof Integer) {
    return _printTypes(x, (Integer)y);
  } else {
    throw new IllegalArgumentException("Unhandled parameter types: " +
      Arrays.<Object>asList(x, y).toString());
  }
}

As you can see a null reference is never a match. If you want to fetch null you can declare a parameter using the type java.lang.Void.

def dispatch printType(Number x) { 
  "it's some number" 
}

def dispatch printType(Integer x) { 
  "it's an int" 
}

def dispatch printType(Void x) { 
  "it's null" 
}

Which compiles to the following Java code:

public String printType(final Number x) {
  if (x instanceof Integer) {
    return _printType((Integer)x);
  } else if (x instanceof Number) {
    return _printType((Number)x);
  } else if (x == null) {
    return _printType((Void)null);
  } else {
    throw new IllegalArgumentException("Unhandled parameter types: " +
      Arrays.<Object>asList(x).toString());
  }
}

public abstract class AbstractLabelProvider {
   protected String _label(Object o) {
      // some generic implementation
   }
}

class MyLabelProvider extends AbstractLabelProvider {
   def dispatch label(Entity it)  {
     name
   }
     
   def dispatch label(Method it) { 
     name+"("+params.join(",")+"):"+type
   }
   
   def dispatch label(Field it) { 
     name+type
   }
}

public String label(final Object it) {
  if (it instanceof Entity) {
    return _label((Entity)it);
  } else if (it instanceof Field) {
    return _label((Field)it);
  } else if (it instanceof Method) {
    return _label((Method)it);
  } else {
    return _label(it);
  }
}

Local Extension Methods

All methods of the current Xtend class are automatically available in extension syntax. For example

class MyClass {
  def doSomething(Object obj) {
    // do something with obj
  }
  
  def extensionCall(Object obj) {
    obj.doSomething()  // calls this.doSomething(obj)
  }
}

Library Extensions

The static methods methods of the classes in the Xtend runtime library are automatically available as extensions, e.g.

newArrayList()       // CollectionLiterals.newArrayList()
"hello".toFirstUpper // StringExtensions.toFirstUpper(String)

Extension Imports

In Java, you would usually write a helper class with static methods to decorate an exisiting class with additional behavior. In order to integrate such static helper classes, Xtend allows to put the keyword extension after the static keyword of a static import thus making all imported static functions available as extensions methods.The following import declaration

import static extension java.util.Collections.*

allows to use its methods like this:

new MyClass().singletonList() 
  // calls Collections.singletonList(new MyClass())

Although this is supported it is generally much nicer to use extension fields, because they allow to change the actual implementation easily.

Extension Fields

You can make the instance methods provided by the field available as extension methods, by adding the keyword extension to the field declaration.Imagine you want to add a method fullName() to a closed type Person. With extension methods, you could declare the following class

class PersonExtensions {
  def getFullName(Person p) {
    p.forename + " " + p.name
  }
}

And if you have an instance of this class injected as extension like this:

class PersonPrinter {
  @Inject extension PersonExtensions
  ...
}

The method is available on the extension scope of the class Person. This is why you can skip the field's name. You can now write the following

def print(Person myPerson) {
  myPerson.getFullName()
}

which is translated to the Java method

public String print(final Person myPerson) {
  String _fullName = this._personExtensions.getFullName(myPerson);
  return _fullName;
}

where _personExtensions is the default name of the field. Of course the property shorthand (see section on property access) is still available.

myPerson.fullName

Using dependency injection in combination with the extension modifier has a significant advantage over to static extension imports: You can simply exchange the component that provides the referenced extension with another implementation without touching the client code. You will only have to change the binding in your dependency injection configuration. Also this gives you a general hook for any AOP-like thing you would want to do, or allows you to write against an SPI, where the concrete implementation can be provided by a third party.

String Literals

A string literal is a valid expression and returns an instance of java.lang.String of the given value. String literals are enclosed by a pair of single quotes or double quotes allowing to use the respective other unquoted inside the string. Special characters can be quoted with a backslash or defined using Java's unicode notation. On the contrary to Java, Xtend's strings can span multiple lines without the need to quote newline characters.

'Hello World !'
"Hello World !"
'Hello "World" !'
"Hello \"World\" !"
'\u00a1Hola el mundo!'
"Hello 

  World !"

Integer Literals

An integer literal creates an int. There is no signed integer. If you put a minus operator in front of an integer literal it is taken as a UnaryOperator with one argument (the positive integer literal).

42
234254
-1 // an expression consisting of the unary - operator and an integer literal

Boolean Literals

There are two boolean literals, true and false which correspond to their Java counterpart of type boolean.

Null Literal

The null pointer literal is null. It is a member of any reference type and the only member of the type java.lang.Void.

Type Literals

Type literals are specified using the keyword typeof :

typeof(java.lang.String) // yields java.lang.String.class

Function Types

Xbase introduces closures, and therefore an additional function type signature. On the Java level a closure (or more generally any function object) is just an instance of one of the types in org.eclipse.xtext.xbase.lib.Functions, depending on the number of arguments. However, as closures are a very important language feature, a special syntax for function types has been introduced. So instead of writing

Function1<String,Boolean>

one can write

(String)=>boolean

Short-Circuit Boolean Operators

If the operators || and && are used in a context where the left hand operand is of type boolean, the operation is evaluated in short circuit mode, which means that the right hand operand might not be evaluated at all in the following cases:

1. in the case of || the operand on the right hand side is not evaluated if the left operand evaluates to true.
2. in the case of && the operand on the right hand side is not evaluated if the left operand evaluates to false.

Examples

my.property = 23
myList += 23
x > 23 && y < 23
x && y || z
1 + 3 * 5 * (- 23)
!(x)

Assignments

Local variables can be reassigned using the = operator. Also properties can be set using this operator given the following expression:

myObj.myProperty = "foo"

The compiler first looks up whether there is an accessible Java Field called myProperty on the type of myObj. If there exists such a field it translates to the following Java expression:

myObj.myProperty = "foo";

Remember in Xtend everything is an expression and has to return something. In the case of simple assignments the return value is the value returned from the corresponding Java expression, which is the assigned value.If there is no accessible field on the left operand's type, a method called setMyProperty (JavaBeans setter method) is looked up. It has to take one argument of the type (or a super type) of the right hand operand. The return value will be whatever the setter method returns (which usually is void). As a result the compiler translates to:

myObj.setMyProperty("foo")

Typing

The return type of a variable declaration expression is always void. The type of the variable itself can either be explicitly declared or be inferred from the right hand side expression. Here is an example for an explicitly declared type:

var List<String> msg = new ArrayList();

In such cases, the type of the right hand expression must conform to the type of the expression on the left side. Alternatively the type can be left out and will be inferred from the initialization expression:

var msg = new ArrayList<String>(); // -> type ArrayList<String>

Property Access

Feature calls are directly translated to their Java equivalent with the exception, that for calls to properties an equivalent rule as described in applies. That is, for the following expression

myObj.myProperty

the compiler first looks for an accessible field in the type of myObj. If no such field exists it looks for a method called myProperty() before it looks for the getter methods getMyProperty(). If none of these members can be found the expression is unbound and a compiliation error is indicated.

Implicit Variables this and it

If the current scope contains a variable named this or it, the compiler will make all its members available to the scope. That is one of

it.myProperty
this.myProperty

is a valid expression

myProperty

is valid as well and is equivalent, as long as there is no local variable 'myProperty' on the scope, which would have higher precedence. As this is bound to the surrounding object in Java, it can be used in finer-grained constructs such as function parameters. That is why it.myProperty has higher precedence than this.myProperty. it is also the default parameter name in closures.

Null-Safe Feature Call

Checking for null references can make code very unreadable. In many situations it is ok for an expression to return null if a receiver was null. Xtend supports the safe navigation operator ?. to make such code better readable.Instead of writing

if (myRef != null) myRef.doStuff()

one can write

myRef?.doStuff()

Typing

Closures are expressions which produce Function objects. The type is a function type, consisting of the types of the parameters as well as the return type. The return type is never specified explicitly but is always inferred from the expression. The parameter types can be inferred if the closure is used in a context where this is possible.For instance, given the following Java method signature:

public <T> T find(List<T> list, Function1<T,Boolean> predicate)

the type of the parameter can be inferred. Which allows users to write:

newArrayList("Foo", "Bar").find(e | e=="Bar")

instead of

newArrayList("Foo", "Bar").find(String e | e=="Bar")

Here are some more examples:

[| "foo"]   // closure without parameters
[String s | s.toUpperCase()] // explicit argument type
[a,b,c | a+b+c] // inferred argument types

Function Mapping

An Xtend closure is a Java object of one of the Function interfaces shipped with the runtime library of Xtend. There is an interface for each number of parameters (current maximum is six parameters). The names of the interfaces are

1. Function0<ReturnType> for zero parameters,
2. Function1<Param1Type, ReturnType> for one parameters,
3. Function2<Param1Type, Param2Type, ReturnType> for two parameters,
4. ...
5. Function6<Param1Type, Param2Type, Param3Type, Param4Type, Param5Type, Param6Type, ReturnType> for six parameters,

1. Procedure0 for zero parameters,
2. Procedure1<Param1Type> for one parameters,
3. Procedure2<Param1Type, Param2Type> for two parameters,
4. ...
5. Procedure6<Param1Type, Param2Type, Param3Type, Param4Type, Param5Type, Param6Type> for six parameters,

newArrayList( 'aaa', 'bb', 'c' ).sort(
  e1, e2 | if ( e1.length > e2.length ) {
        -1 
       } else if ( e1.length < e2.length ) { 
        1
       } else { 
        0
       })

Implicit Parameter it

If a closure has a single parameter whose type can be inferred, the declaration of the parameter can be ommitted. Use it to refer to the parameter inside the closure's body.

val (String)=>String function = [toUpperCase]  // equivalent to [it | it.toUpperCase]

Exceptions in Closures

Checked exceptions that are thrown in the body of a closure are rethrown using the sneaky-throw technique, i.e. you do not have to declare them explicitly.

Builder Syntax

If the last argument of a function call is a closure, it can be appended after the parenthesized parameter list. In combination with the implicit it parameter, skipping empty parentheses, and extension methods, this yields a very concise syntax.

val fruit = newArrayList('apple', 'pear', 'lemon')
fruit.map[toUpperCase]  // same as fruit.map([it | it.toUpperCase])

This feature is especially useful when you are building object trees. A common pattern is to provide a set of extension functions taking two parameters: the parent object and a closure to initialize the new child. Here is an example for creating a simple tree of Nodes:

class Node {
  String label
  List<Node> children
  
  def createNode(Node parent, (Node)=>void initializer) {
    val child=new Node()
    initializer.apply(child)
    child
  }

  def tree() {
    createNode(null) [
      label="root"
      children += createNode [
        label="child0"
      ]
      children += createNode [
        label="child1"
      ]
    ]
  }
}

Type guards

In addition to the case guards one can add a so called Type Guard which is syntactically just a type reference preceding an optional case keyword. The compiler will use that type for the switch expression in subsequent expressions. Example:

var Object x = ...;
switch x {
  String case x.length()>0 : x.length()
  List<?> : x.size()
  default : -1
					}

Only if the switch value passes a type guard, i.e. an instanceof operation returns true, the case's guard expression is executed using the same semantics explained previously. If the switch expression contains an explicit declaration of a local variable or the expression references a local variable, the type guard acts like a cast, that is all references to the switch value will be of the type specified in the type guard.

Conditions in Templates

There is a special IF to be used within templates which is identical in syntax and meaning to the old IF from Xpand. Note that you could also use the if expression, but since it has not an explicit terminal token, it is not as readable in that context.

Loops in Templates

Also the FOR statement is available and can only be used in the context of a template. It also supports the SEPARATOR from Xpand. In addition, a BEFORE expression can be defined that is only evaluated if the loop is at least evaluated once before the very first iteration. Consequently AFTER is evaluated after the last iteration if there is any element.

Typing

The rich string is translated to an efficient string concatenation and the return type of a rich string is java.lang.CharSequence which allows room for efficient implementation.

White Space Handling

One of the key features of templates is the smart handling of white space in the template output. The white space is not written into the output data structure as is but preprocessed. This allows for readable templates as well as nicely formatted output. This can be achieved by applying three simple rules when the rich string is evaluated.

1. An evaluated rich string as part of another string will be prefixed with the current indentation of the caller before it is inserted into the result.
2. Indentation in the template that is relative to a control structure will not be propagated to the output string. A control structure is a FOR-loop or a condition (IF) as well as the opening and closing marks of the rich string itself. The indentation is considered to be relative to such a control structure if the previous line ends with a control structure followed by optional white space. The amount of white space is not taken into account but the delta to the other lines.
3. Lines that do not contain any static text which is not white space but do contain control structures or invocations of other templates which evaluate to an empty string, will not appear in the output.

class Template {
  print(Node n) '''
    node «n.name» {}
  '''
}

node NodeName {}

class Template {
  print(Node n) '''
    node «n.name» {
      «IF hasChildren»
        «n.children.map[print]»
      «ENDIF»
    }
  '''
}

node Parent{
  node FirstChild {
  }
  node SecondChild {
    node Leaf {
    }
  }
}