Skip to main content

Method Cascades in Dart

Posted by Gilad Bracha

(UPDATE: Method cascades are now implemented.)

The idea of a cascaded method invocation originates in Smalltalk, and has been proposed for Dart.  The motivation is to make it easier to write more fluent interfaces. 

Usually, fluent interfaces rely on method chaining. Say you want to add a large number of elements to a table:

// many lines elided here
// and here 
// and on and on

You might want to write this as

            // many lines elided here
            // and here 
            // and on and on

but this requires that add() return the receiver, myTokenTable, instead of the element you just added. The API designer has to plan for this, and it may conflict with other use cases. With cascades, no one needs to plan ahead or make this sort of tradeoff.  The add() method can do its usual thing and return its arguments. However, you can get a chaining effect using cascades:

// many lines elided here
// and here 
// and on and on

Here, ".." is the cascaded method invocation operation.  The ".." syntax invokes a method (or setter or getter) but discards the result, and returns the original receiver instead.

In brief, method cascades provide a syntactic sugar for situations where the receiver of a method invocation might otherwise have to be repeated. Instead of writing:

var address = getAddress();
address.setStreet(“Elm”, “13a”); = “Carthage”;
address.state = “Eurasia”, extended: 6666);

One may write

 ..setStreet(“Elm”, “13a”) = “Carthage”
 ..state = “Eurasia”, extended: 6666);

The sugar pays off the more complex the API, the longer the receiver of the cascaded method invocations, and the more methods are being directed toward that receiver. Cascades are expressions, so they also compose better than statements.  A cascade always evaluates to its initial receiver (the details are in the draft specification at the end of this document).

Below you'll find a number of examples, and a draft specification. As always, feedback is welcome. However, I'm about to go on vacation - so don't be offended if it takes a while before I respond to any of your comments.


The examples below show the use of the construct using a couple of indentation styles. All styles place cascaded access on a separate line, which improves readability.

Example 1

Consider using a (modified) String API:

String s = (new StringBuffer()
..add('Jenny ')
..add('I ')
..add('got ')
..add('your ')

Example 2

Another common example would be using a builder API

final addressBook = (new AddressBookBuilder() = 'jenny' = '' = (new PhoneNumberBuilder()
  ..number = '867-5309'
  ..label = 'home'

Example 3

class Point {
num x;
num y;

Point() {
  x = 0;
  y = 0;
void scale(num factor) {
 x *= factor;
 y *= factor;

// Hack to display debugging output while within a cascade. Naturally you can't use
// the regular print statement.
void log(String msg) {
 print ('logged ($x, $y): $msg');


void main(){

num x = 10;
num y = 42; // not used
var p = new Point();
 ..x = x
 ..y = x + p.x + p.y;
print('p.x = ${p.x}, p.y = ${p.y}. x = $x');


logged (0, 0): start
logged (100, 0): scaled
p.x = 101, p.y = 111, x = 10

Example 4

class Node {
String key;
Node left;
Node right;

void main() {
Node right = new Node('e');
Node root = new Node('root')
 ..left = (new Node('a')
   ..left = (new Node('b')
     ..left = new Node('c')
     ..right = Node('d')
 ..right = right;

Example 5

The following example is perhaps more typical of what you might do in a web application.

var dq = document.query('#mypanel').queryAll('TABLE .firstCol');
  ..background = 'red'
  ..border = '2px solid black'
dq.nodes.add(new Element.html('<span>This cell is now red</span>')) // ?

It might be even nicer if cascades nested, but the nesting makes things hard to read. 

document.query('#mypanel').queryAll('TABLE .firstCol')
   ..background = 'red'
   ..border = '2px solid black'
) ..nodes.add(new Element.html('<span>This cell is now red</span>')) // Not legal, just an idea for nesting

Maybe in the future we'll find a way to support such nesting in a truly readable way. For now we defer the issue and stick with one level of cascading.

Example 6

var dq = document.query('#myTable');
var qfc = dq.queryAll('.firstColumn');
   ..background = 'red'
   ..border = '2px solid black'
qfc.text = 'first column';

dq.queryAll('.lastColumn') = 'blue'
  ..text = 'last column';

Example 7
..position = 'absolute'
..left = '${_measuredLeft}px' = '${_measuredTop}px'
..width = '${_measuredWidth}px'
..height = '${_measuredHeight}px'
..zIndex = '${layoutParams.layer}'

Example 8

..fillStyle = penColor
..arc(tx, ty, penWidth/2+2, 0, PI2, true)
..moveTo(wx, wy)
..strokeStyle = "black"
..lineTo(tx, ty)

Example 9

        ..classes.remove('off') // ?
        ..classes.add('on') // ?

Example 10

Array access works as well

      ..['foo'] = bar
      ..['baz'] = bla


Here is an initial take on the specification for this proposal. Places where the current spec changes are highlighted in yellow.

A cascaded method invocation has the form e..suffix

where suffix is a sequence of operator, method, getter or setter invocations.

A cascaded method invocation expression of the form e..suffix is equivalent to the expression (t){t.suffix; return t;}(e).

Grammar Changes

topLevelExpression:      assignableExpression assignmentOperator cascade
   | conditionalExpression ('..' cascadeSection)*

primary:      thisExpression    | super assignableSelector
   | functionExpression
   | literal
   | identifier
   | newExpression
   | constantObjectExpression
'(' topLevelExpression ')'    ;

cascadeSection:     (assignableSelector arguments*)+ (assignmentOperator expression)?


  1. Would not be better to use "->" instead of "..", looks cleaner and more suitable?

    1. ".." is much better, I think.

    2. One of the reason why I dislike ".." is - its more prone for typos/errors. As you write more and more chainned code, you will start to be accustomed with syntax and it will be easier to write ".." instead of ".".

      Language should force to think more about how we are writing.
      ie. manager.add()->set()->set()->set();

    3. Or anything but not ".." or "...".

  2. I like it! I do think '..' is a better choice than '->'; the only thing I don't like about '..' is that I wish DART would add a range operator named '..' so we could avoid the clumsy for(;;) syntax. **

    Another syntax you might consider:{
    .border = '2px solid black';
    oldBackground = .background;
    .background = 'red';

    Which has the advantage that it can be used for destructuring objects as well as building them.

    ** Actually I'm not sure this is the right range operator, the problem being it's not clear whether you should write "for (i in 0..3)" or "for (i in 1..3)" to run a loop 3 times -- same problem as having a range function, really. What's actually needed is two range operators, one inclusive and one exclusive. Possibly "..=" and "..<", with an optional "by" clause.

    *** Now you just need to add "..." to the language for variable length arguments and type arguments and list destructuring. Just don't ever give a meaning to "....", that would just be confusing!

  3. Like this syntax!
    -- non-professional programmer

  4. A suggestion: in some of the cases above, a typed JSON / JavaFX (the language) style object literals would be more natural. Example:

    final addressBook = AddressBook {
    name: 'jenny',
        phone: PhoneNumber {
            number: '867-5309',
            label: 'home'

    var tree = Node('a') {
        left: Node('b') {
            right: Node('c')

    In cases that are not object construction, this would not fit.

  5. Awesome :). These tiny features of a language can make it so enormously nice to work with.

    This builder/fluent interface pattern is accepted now. Let's use it without the boilerplate, no codesize bloat for non-functional API features.


  6. I'm a little confused by the syntax.

    Is this example:
    ..setStreet(“Elm”, “13a”) = “Carthage”
    ..state = “Eurasia”, extended: 6666);

    The same as:
    getAddress().setStreet(“Elm”, “13a”) = “Carthage”
    ..state = “Eurasia”, extended: 6666);

    The same as:
    var address = getAddress()
    ..setStreet(“Elm”, “13a”) = “Carthage”
    ..state = “Eurasia”, extended: 6666);

    If so what about this syntax makes it so that in this example:

    getAddress() = “Carthage”
    ..state = “Eurasia”;

    What determines that the '..state' operation is invoked on the address and not the 'city'?



Post a Comment

Popular posts from this blog

Const, Static, Final, Oh my!

Posted by Seth Ladd

(This is an "oldie but a goodie" post originally written by Bob Nystrom. It is being posted here as the explanations still ring true.)

Bob writes:

"static", "final", and "const" mean entirely distinct things in Dart:

"static" means a member is available on the class itself instead of on instances of the class. That's all it means, and it isn't used for anything else. static modifies *members*.

"final" means single-assignment: a final variable or field *must* have an initializer. Once assigned a value, a final variable's value cannot be changed. final modifies *variables*.

"const" has a meaning that's a bit more complex and subtle in Dart. const modifies *values*. You can use it when creating collections, like const [1, 2, 3], and when constructing objects (instead of new) like const Point(2, 3). Here, const means that the object's entire deep state can be determ…

Dart 1.12 Released, with Null-Aware Operators and more

Dart 1.12.0 is now released! It contains the new null-aware operators language feature, and enhancements to pub, Observatory, dartdoc, and much more.

Null-aware operators

The new null-aware operators help you reduce the amount of code required to work with references that are potentially null. This feature is a collection of syntactic sugar for traversing (potentially null) object calls, conditionally setting a variable, and evaluating two (potentially null) expressions.

Click or tap the red Run button below to see them in action.


  if null operator. `expr1 ?? expr2` evaluates to `expr1` if not `null`, otherwise `expr2`.


  null-aware assignment. `v ??= expr` causes `v` to be assigned `expr` only if `v` is `null`.


  null-aware access. `x?.p` evaluates to `x.p` if `x` is not `null`, otherwise evaluates to `null`.


  null-aware method invocation. `x?.m()` invokes `m` only if `x` is not `null`.

Learn more about Dart's null-aware operators in our Language Tour.

.packages fi…

The new AdWords UI uses Dart — we asked why

Google just announced a re-designed AdWords experience. In case you’re not familiar with AdWords: businesses use it to advertise on and partner websites. Advertising makes up majority of Google’s revenue, so when Google decides to completely redo the customer-facing front end to it, it’s a big deal. The Dart team is proud to say that this new front end is built with Dart and Angular 2. Whenever you asked us whether Google is ‘even using Dart for anything,’ this is what we had in mind but couldn’t say aloud. Until now. We asked Joshy Joseph, the primary technical lead on the project, some questions. Joshy is focusing on things like infrastructure, application latency and development velocity, so he’s the right person to ask about Dart.Q: What exactly did we launch on Monday?It’s a complete redesign of the AdWords customer experience that is rolling out slowly as a test to a small initial set of advertisers. The most noticeable thing is probably the Material Design look and f…