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:

myTokenTable.add("aToken");
myTokenTable.add("anotherToken");
// many lines elided here
// and here 
// and on and on
myTokenTable.add("theUmpteenthToken");

You might want to write this as

myTokenTable.add("aToken")
            .add("anotherToken").  
            // many lines elided here
            // and here 
            // and on and on
            .add("theUmpteenthToken");

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:

myTokenTable
  ..add("aToken");
  ..add("anotherToken");
// many lines elided here
// and here 
// and on and on
  ..add("theUmpteenthToken");


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”);
address.city = “Carthage”;
address.state = “Eurasia”
address.zip(66666, extended: 6666);

One may write

getAddress()
 ..setStreet(“Elm”, “13a”)
 ..city = “Carthage”
 ..state = “Eurasia”
 ..zip(66666, 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.

Examples


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 ')
..add('number')
).toString();


Example 2


Another common example would be using a builder API

final addressBook = (new AddressBookBuilder()
..name = 'jenny'
..email = 'jenny867@aol.com'
..phone = (new PhoneNumberBuilder()
  ..number = '867-5309'
  ..label = 'home'
 ).build()
).build();


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();
p..log('start')
 ..x = x
 ..scale(10)
 ..log('scaled')
 ..x++
 ..y = x + p.x + p.y;
print('p.x = ${p.x}, p.y = ${p.y}. x = $x');
}



Output:


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




Example 4


class Node {
String key;
Node(this.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;
print(root);
}



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');
dq.classes.remove('firstCol');
dq.style
  ..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')
..classes.remove('firstCol');
..(style
   ..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');
qfc.style
   ..background = 'red'
   ..border = '2px solid black'
  ;
qfc.text = 'first column';

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


Example 7


view.node.style
..position = 'absolute'
..left = '${_measuredLeft}px'
..top = '${_measuredTop}px'
..width = '${_measuredWidth}px'
..height = '${_measuredHeight}px'
..zIndex = '${layoutParams.layer}'
;



Example 8


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




Example 9


document.queryAll('myDiv')
        ..classes.remove('off') // ?
        ..classes.add('on') // ?
;





Example 10

Array access works as well


element.attributes
      ..['foo'] = bar
      ..['baz'] = bla
;



Specification



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)?
   ;

Popular posts from this blog

Dart in 2016: The fastest growing programming language at Google, 2nd fastest growing in TIOBE Index

Dart was the fastest growing programming language at Google in 2016 with millions of lines of code written. It also made it to TIOBE Index Top 20 this month (see TIOBE's methodology).

It takes time to build something as ambitious as Dart and, in some ways, Dart is still in its infancy. But we're glad the hard work is starting to pay off.

Many thanks to our amazing community!

We're going to celebrate by ... releasing 1.22 next week (as per our usual 6 week release schedule).

The new Google AdSense user interface: built with AngularDart

AdSense is a free, simple way to earn money by placing ads on your website. The team just launched a completely new version of their app for publishers. Read all about it here. We asked Daniel White, the tech lead for the project, some questions because the new UI happens to be built with Dart and Angular2.


AdSense launched way back in 2003. How long is it since the last big redesign?
Last big redesign was called ‘AdSense 3’ and launched about 6 years ago. It was written in Google Web Toolkit (GWT) and the UI has evolved through several iterations - but this is the first ground-up redesign in 6 years. There are a number of long-standing UX issues that we’ve taken the opportunity to solve. A big shout-out to our UX team who’ve been 100% behind this project. We couldn’t have done it without them!

How many software engineers worked on the project?
Purely on the AdSense applications, we have a team of close to 100. Around 25% of them write Dart.

How many lines of code?
We have around 160K LO…

AngularDart 2.1 and new Components

AngularDart got its own dedicated team 5 months ago. Last month, we launched 2.0 final on the Dart Developer Summit. Today, we’re releasing the first minor release after that: 2.1.

Since the focus of AngularDart is Productivity, Performance, Stability, there are no major breaking changes (see the changelog) — but a lot of behind-the-scenes improvements. Your apps will get slightly smaller and faster (even relative to 2.0 which already made huge strides in size and performance since the compiled-from-TypeScript days).

Many features that AngularJS had to implement for JavaScript and TypeScript are not needed in Dart (because Dart already has those features out-of-the-box). So we’re removing them from AngularDart. Renderer is deprecated in favor of plain-old dart:html. NgPlural is going away — Dart programs can use the package:intl library.

New components

On the Dart Developer Summit, we launched AngularDart Components — the material design widgets Google is using in customer-facing apps …