DART: syntax of future then

I will attempt to elaborate more on Matt's answer, hopefully to give more insights.

What then() requires is a function (callback), whose signature matches the future's type.

For example, given a Future<String> myFuture and doSomething being any function that accepts a String input, you can call myFuture.then(doSomething). Now, there are several ways to define a function that takes a String in Dart:

Function(String) doSomething1 = (str) => /* do something with str */  // only one command
Function(String) doSomething2 = (str) { /* do something with str */ } // several commands
Function(String) doSomething3 = myFunction;
myFunction(String) { // Dart will auto imply return type here
  /* do something with str */ // several commands
}

Any of those 3 function definitions (the right hand side of =) could go inside then(). The first two definitions are called lambda functions, they are created at runtime and cannot be reused unless you manually copy the code. Lambda functions can potentially yield language-like expressions, i.e. (connection) => connection.connect(). The third approach allows the function to be reused. Lambda functions are common in many languages, you can read more about it here: https://medium.com/@chineketobenna/lambda-expressions-vs-anonymous-functions-in-javascript-3aa760c958ae.

The reason why you can't put callHandler2(erg) inside then() is because callHandler2(erg) uses an undefined variable erg. Using the lambda function, you will be able to tell then() that the erg in callHandler2(erg) is the output of the future, so it knows where to get erg value.

1) The Fat Arrow is syntactic sugar for short anonymous functions. The two functions below are the same:

someFuture(arg).then((erg) => print(erg));
// is the same as
someFuture(arg).then((erg) { return print(erg); });

Basically the fat arrow basically automatically returns the evaluation of the next expression.

If your callHandler2 has the correct signature, you can just pass the function name. The signature being that it accept the number of parameters as the future will pass to the then clause, and returns null/void.

For instance the following will work:

void callHandler2(someArg) { ... }
// .. elsewhere in the code
someFuture(arg).then(callHandler);

2) See answer 1). The fat arrow is just syntactic sugar equivalent to:

myFuture(5).then( (erg){ callHandler(erg);}, onError: (e){ print(e); });

3) catchError allows you to chain the error handling after a series of futures. First its important to understand that then calls can be chained, so a then call which returns a Future can be chained to another then call. The catchError will catch errors both synchronous and asynchronous from all Futures in the chain. Passing an onError argument will only deal with an error in the Future its an argument for and for any synchronous code in your then block. Any asynchronous code in your then block will remain uncaught.

Recent tendency in most Dart code is to use catchError and omit the onError argument.