Seth Ladd's Blog

Booleans in Dart

2012-02-07T22:48:00.000-08:00

(This is part 11 in an ongoing series about Dart. Read part 10, Numbers in Dart.)

Intro

This post will cover what is true, and false, in Dart. If you are coming from JavaScript, hopefully this short explanation about booleans in Dart will come as welcome relief.

Dart has a formal boolean type, named bool. There are only two objects of type bool: true and false.

Examples:

bool registered = false;
var verified = true;

True

The only value that is true is the boolean value true. Unlike JavaScript, other values such as 1 or non-null object are not treated as true.

False

In a boolean context, everything that is not true is converted to false. JavaScript has six other falsey values such as empty string, zero, null object, undefined, or NaN. In Dart, if an object is not the boolean value true, it is evaluated as false.

Boolean conversion

What happens when you write the following code?

var name = 'Bob';
if (name) {
print("you have a name!");
}

In JavaScript, the above will print "you have a name!" because name is a non-null object. However, in Dart, the above will not print because name is converted to false due to boolean conversion.

The conversion rules to boolean are quite simple. The spec outlines the logic as:

(bool v){
assert(v != null);
return v === true;
}(o)

In other words, that which is not true is false. If the value is not equal to and of the same type as true, then the value is converted to false.

This means that the following code will work in JavaScript but will not work in Dart:

// this won't print in Dart
if (1) {
print("1 is converted to false in Dart, as is everything that is not the value true");
}

Compensating

Coming from JavaScript, you may be wondering how to check for conditions such as empty string or zero. The long form checks will still work.

Check for empty string:

var fullName = '';
if (fullName.isEmpty()) {
print("Please enter a full name");
}

Checking for zero:

var hitPoints = 0;
if (hitPoints == 0) {
print("Uh oh! Looks like you died.");
}

Checking for null:

var unicorn = null;
if (unicorn == null) {
print("You didn't wish hard enough. Wish harder.");
}

Checking for NaN:

var iMeantToDoThis = 0 / 0;
if (iMeantToDoThis.isNaN()) {
print("it's all on purpose");
}

JavaScript puzzler

Dart also differs from JavaScript with respect to its treatment of boolean expressions.

In JavaScript, boolean expressions will resolve to the value of the object that stops the evaluation. For instance:

var yourName = 'Bob';
var myName = '';
var someName = yourName && myName;
console.log(someName);
// prints '' (empty string!)

Both yourName and myName will be evaluated, and because yourName is truthy the next value must be evaluated. myName is an empty string, which is falsey, but that doesn't matter to the value of someName. The last value that is evaluated is returned, so someName is set to an empty string.

Dart answer

Dart simplifies the behavior, because the result of a boolean expression is a boolean. Therefore, the following Dart code reads more logically.

main() {

var firstName = 'Bob';

var middleName = '';

var name = firstName && middleName;

print(name); // false, because boolean conversion turns

// firstName into false

print(name is bool); // true!

}

Assigning default values

Dart's simplified boolean handling also means a few tricks from JavaScript or Ruby don't work.

For example, assigning a default value in Ruby is as simple as:

# ruby code which assigns 25 to hit_points if it was null

hit_points ||= 25

Assigning a default value in JavaScript looks like:

// works in JavaScript

var hitPoints = hitPoints || 25;

However, because Dart boolean expressions return a boolean, and not the last value, we need to write:

var hitPoints = (hitPoints != null) ? hitPoints : 25;

This is a bit easier in Dart with functions, as default values are supported with function arguments:

grabADrink([size='pint']) {

print(size);

}

grabADrink(); // prints 'pint'

Summary

Dart has a true boolean type named bool, with only two values: true and false (and, I suppose, null). Due to Dart's boolean conversion rules, all values expect true are converted to false. Dart's boolean expressions return the actual boolean result, not the last encountered value.

Next Steps

Read more of my Dart posts, try Dart in your browser, browse the API docs, or file an issue request. Dart is getting ready, please send us your feedback!

Numbers in Dart

2012-02-04T12:30:00.000-08:00

(This is part 10 in an ongoing series about Dart. Check out part 9, a Dart SDK quick tour.)

Intro

It's time to look at numbers in Dart. Wait, where are you going? Come back, numbers are cool! This will be interesting, for reals. I can at least promise this will be easy and quick, for numbers in Dart aren't complicated. If you're compiling to JavaScript, though, there are a few edge cases (bugs?) so I encourage you to not skip this episode.

The Basics

Like everything else in Dart, numbers are objects. In fact, numbers are specified as interfaces.

Numbers come in two flavors in Dart: integers of arbitrary size and decimal 64 bit doubles as specified by the IEEE 754 standard. Both int and double are subinterfaces of num.

num is the supertype, int and double extend num.

The num interface defines the basics like +, -, /, and *. Num is where you'll also find abs(), ceil(), and floor(), among other methods.

Int

Integers are numbers without a decimal point. For example:

  var x = 1;
  print(x);
  print(x is num); // true in both Dart VM and JS
  print(x is int); // true in both Dart VM and JS

You may also specify hexadecimals with the 0x prefix.

  var hex = 0xDEADBEEF;
  print(hex); // 873735928559
  print(hex is num); // true in both Dart VM and JS
  print(hex is int); // true in both Dart VM and JS
  print(hex is! double); // true in Dart VM, FALSE in JavaScript

Alert: the last line in the above sample, the result is different between the Dart VM and Dart compiled to JavaScript. I've opened a bug to see if this is by design.

Integers can be of arbitrary precision. For example:

  var bigInt = 346538465234590347592847298346243459756895347698465298346583746592374652378462347569234765834765947569827346583465243765923847659234765928347659567398475647495873984572947593470294387093493456870849216348723763945678236420938467345762304958724596873045876234572037862934765294365243652548673456705673465273465246734506873456729457623845623456234650457693475603768922346728346256;
  print(bigInt); // correct in Dart VM, Infinity in JavaScript
  print(bigInt is num); // true in both Dart VM and JS
  print(bigInt is int); // true in both Dart VM and JS

While the above will work in the Dart VM, when compiled to JavaScript, the large number becomes Infinity.

Alert: JavaScript only supports +/- 9007199254740992 for integers and (at least in V8) 1.7976931348623157e+308 for Number.MAX_VALUE. I've opened a bug to discuss this, as the above code functions differently in Dart VM and JavaScript.

You might see Dart code that explicitly adds a + prefix to the number, though it isn't necessary.

  var positive = +12345;
  print(positive); // 12345
  print(positive is num); // true
  print(positive is int); // true

Double

If the number includes a decimal, it is a 64 bit double that follows IEEE 754 standard.

A simple example:

  var y = 1.1;
  print(y);
  print(y is num); // true in both Dart VM and JS
  print(y is double); // true in both Dart VM and JS

Exponent notation is supported:

  var exponents = 1.42e5;
  print(exponents); // prints 142000.0 in Dart VM, 142000 in JavaScript
  print(exponents is num); // true in both Dart VM and JS
  print(exponents is! int); // true in both Dart VM, FALSE in JS
  print(exponents is double); // true in both Dart VM and JS

Here again you can see slight differences between what Dart VM and JavaScript will do. The generated JavaScript code looks like this:

  // generated JavaScript from Frog, as of 2012-02-04
  var exponents = (142000.0);
  print(exponents);
  print((typeof(exponents) == 'number'));
  print((typeof(exponents) != 'number')); // this is FALSE, see corresponding Dart code above
  print((typeof(exponents) == 'number'));

NaN

Dividing zero by zero will result in "not a number" in Dart, similar to JavaScript but unlike Java.

The num interface provides a simple check for isNaN().

  var nan = 0 / 0;
  print(nan.isNaN()); // true in both Dart VM and JS

Converting to and from a String

A common requirement is to turn a number into a String, or a String into a number.

Parsing a String to an int uses the Math class:

  var one = Math.parseInt("1");
  print(one);  // 1
  print(one is int);  // true

Parsing a String into a double is similar:

  var onePointOne = Math.parseDouble("1.1");
  print(onePointOne); // 1.1
  print(onePointOne is double); // true

Attempting to format a string that isn't a number will throw a BadNumberFormatException.

  try {
    var gook = Math.parseInt("foo");
  } catch(BadNumberFormatException e) {
    print(e); // BadNumberFormatException: 'foo'
  }

Going the other way, converting numbers to Strings, is also very easy thanks to toString().

  String oneAsString = 1.toString();
  print(oneAsString); // 1
  print(oneAsString is String);

For doubles, toStringAsFixed(int fractionDigits) will truncate the decimal digits:

  print(3.14159.toStringAsFixed(2)); // 3.14

Misc methods

A potentially unfamiliar change is the methods like ceil() and abs() are found on the num interface, and not in Math.

  // absolute value is a method on num
  print((-4).abs() == 4);
  
  // ceil and floor are also methods on num
  print(3.25.ceil() == 4.0);
  print(3.25.floor() == 3.0);
  
  // round will round up if .5 or greater, otherwise will round down
  print(3.25.round() == 3);
  print(3.89.round() == 4);
  print(3.5.round() == 4);
  print(3.49.round() == 3);
  
  // truncates the decimal digits
  print(3.24532.truncate() == 3.0);
  
  // convert a double to an int
  print(3.24.toInt() == 3);

Bit manipulating

The num interface also specifies the traditional bit shifting, and'ing, and or'ing. Some simple examples:

  print(3<<1 == 6); // 0011 << 1 == 0110
  print(3>>1 == 1); // 0011 >> 1 == 0001
  
  print((3|4) == 7); // 0011 | 0100 == 0111

Summary

Dart supplies a num interface with two subinterfaces: int and double. Integers are arbitrary precision, meaning they have arbitrary size. Doubles are 64 bit decimals that follow IEEE 754 spec.

Generally speaking, numbers function the same across native Dart and Dart compiled to JavaScript, but there are some subtle differences. For example, watch out for very large numbers and checking the difference between int and double in JavaScript (currently everything is checked against number in JavaScript from the Frog compiler.)

Next Steps

Read more of my Dart posts, try Dart in your browser, browse the API docs, or file an issue request. Dart is getting ready, please send us your feedback!

Chromium and Dart with Dev Tools

2012-01-24T22:30:00.000-08:00

There is a public branch of Chromium that embeds the Dart virtual machine, allowing you to run native Dart code directly in the browser. Unfortunately, only the Dartium source is available right now, but if you search hard enough, you might find an enterprisingly fellow providing pre-built binaries (warning: these may blow up your machine.)

The engineers have begun to add Developer Tools support with Dart, which starts to tell the debugging story. With a very recent build of Dartium (2012-01-24) you can try this for yourself. I found breakpoints are working, with a few caveats (eg not working with function callbacks yet.)

To see Chromium + Dart + Dev tools + breakpoints in action:

Dart is getting ready, please do try it out by learning more, browsing the API, using the Editor, or downloading the SDK. I also have a series of posts on Dart. Please let us know what you think!

Dart SDK Quick Tour

2012-01-22T10:57:00.000-08:00

(This is part 9 in an ongoing series about Dart. Check out part 8, This is this in Dart.)

The Dart team quietly started to provide binary Dart SDKs for download. Without compiling or syncing large source repositories, you can now compile your Dart code to JavaScript with Frog, run the Dart VM, and browse the Dart libraries.

Download

There are two options for downloading the Dart SDK: continuous nightlies or integration releases.

Choose the continuous builds if you want to live on the edge, or choose the integration builds if you want more tested releases.

For the SDK, look for either dart-linux.zip, dart-macos.zip, or dart-win32.zip. The other files (starting with DartBuild) are the Dart Editor.

After you download and unzip the archive, you'll have a dart-sdk directory. The bin directory has dart, which is the Dart VM, and frogc, the Frog compiler.

The Frog compiler

When Dart was initially announced, we shipped a DartC compiler which turned your Dart code into JavaScript code. DartC is written in Java, and is the compiler behind the Dart Editor. DartC supported incremental compilation (making the editor faster) but generated large JavaScript.

Some time later, the team released an experiment: a Dart to JavaScript compiler written in Dart itself. This compiler would generate essentially human readable, and terse, JavaScript. This Frog compiler (named after the Dart Frog) will generate only the JavaScript required to run the program, resulting in smaller output.

Running Frog

Assuming you have the following test.dart file:

main() => print("hello from dart!");

you can then compile it to JavaScript with the following command:

$DART_SDK/bin/frogc test.dart

which will generate the following JavaScript code:

//  ********** Library dart:core **************
//  ********** Natives dart:core **************
// ********** Code for Object **************
Object.defineProperty(Object.prototype, "toString$0", { value: function() {
  return this.toString();
}, enumerable: false, writable: true, configurable: true });
// ********** Code for top level **************
function print(obj) {
  return _print(obj);
}
function _print(obj) {
  if (typeof console == 'object') {
    if (obj) obj = obj.toString();
    console.log(obj);
  } else {
    write(obj);
    write('\n');
  }
}
//  ********** Library dart:coreimpl **************
// ********** Code for NumImplementation **************
NumImplementation = Number;
// ********** Code for StringImplementation **************
StringImplementation = String;
// ********** Code for _Worker **************
// ********** Code for top level **************
//  ********** Library test **************
// ********** Code for top level **************
function main() {
  return print("hello from dart!");
}
main();

The Dart virtual machine

One of Dart's primary language design constraints is that it must compile to effective and performant JavaScript. However, Dart is also designed to run in its own virtual machine, and a Dart VM is shipped inside the Dart SDK. You can use the Dart VM to run Dart code on the server or directly in a browser (with Chrome + Dart integration coming soon.)

Using the same test.dart file from above, we can run it directly on the command line with:

$ ~/Downloads/dart-sdk/bin/dart test.dart
hello from dart!

Startup for the Dart VM is very fast, too.

The libraries

The source code for the Dart libraries is also included in the SDK. You can browse the API docs at api.dartlang.org, but it's still fun to check out the actual source.

You'll find directories for the core libs, the DOM and HTML libs, and the frog compiler. You'll also see a directory named builtin, which includes runtime libraries like directories, file, sockets, and streams.

Summary

You can play with Dart today, without having to compile any code. The Dart SDK is now available for download, bundling the Frog compiler, the Dart virtual machine, and the source code for the libraries.

Next steps

Continue to part 10, Numbers in Dart.

Read more of my Dart posts, try Dart in your browser, browse the API docs, or file an issue request. Dart is getting ready, please send us your feedback!

JavaScript WAT moments and Dart

2012-01-21T22:22:00.000-08:00

There's a very funny 5 minute video by Gary Bernhardt from CodeMash 2012 which highlights a few WAT??!?! moments with some of our favoriate languages like Ruby and JavaScript. If you haven't seen this yet, take a few minutes and give yourself a chuckle.

Back? Cool. Let's map some of those JavaScript WAT moments to Dart and see how we do.

Example 1: Adding two empty arrays

Behold, the JavaScript:

[] + []

> "" // ?!?!?!

Not expected.

Behold, the Dart:

(note, List does not have a + operator, so here's the best we can do)

var result = [];
result.addAll([]);

print(result is List); // true.

Expected.

Example 2: Adding an empty array and empty map

Behold, the JavaScript:

[] + {};

> "[object Object]"  // ?!?!?!

That's right, a string. Not expected.

Behold, the Dart:

(note, Map does not extend collection, so not only can't we use the + operator, it doesn't make sense to directly add a Map to a List.)

var result = [];

[].addAll({}); // NoSuchMethodException: Map is not a Collection! Expected!

Not being allowed to add a map and array is expected. I am thankful the program stops if I try to do this.

Example 3: Adding an empty map and empty array

Behold, the JavaScript:

{} + []

> 0

The number zero. Not expected.

Behold, the Dart:

// nothing even close

There's no way to simply add a Map and a List. This makes sense, it is expected you can't just add a list to a map.

Example 4: Adding an object to an object

Behold, the JavaScript:

{} + {}

> NaN

Which, as the video says, is probably right. :) However, still unexpected that this is allowed to run.

Behold, the Dart:

// nothing comes close

Neither Map nor Object have implemented the + operator, so it's impossible to try to add two objects or two maps together. It is expected that you can't simply add two arbitrary objects.

(Note: Dart does support the ability to define an operator method on a class. You are free to add plus or minus, for example, to your classes.)

Example 5: Subtracting a number from a string

Behold, the JavaScript:

"wat" - 1
> NaN

One could argue that yes, indeed, the result of subtracting a number from a string is not a number. I will grant you this. However, the fact that this line is even allowed to run and return a result is not expected.

Behold, the Dart:

var result = "wat" - 1;

// analysis will generate warning: string has no operator method '-'

// attempting to execute this will throw NoSuchMethodException

Dart will warn you that string does not have an operator method '-', but it will let you execute the program (due to types not affecting the runtime semantics of the code, because Dart embrases optional types.)

If you don't heed the warning, the above code will fail with a NoSuchMethodException, because string doesn't have a minus operator. This is expected.

Summary

The point of this post isn't to pick on JavaScript specifically, as every language eventually ends up with odd puzzlers. The point of this post is to instead remind you that there are people working very hard to reduce and remove these subtle and confusing situations from your next web programming language.

We can indeed demand more expected results from our languages and tools, and we should demand more early errors from obvious mistakes. We need to demand less WAT?!?! moments in web development.

(BTW if anyone knows of the ES6 aka JavaScript.next aka Harmony versions of the above code, I'll be happy to include them. I'm curious if the latest work on the future of JavaScript addresses the above issues.)

This is this in Dart

2012-01-21T00:20:00.000-08:00

(This is part 8 in an ongoing series about Dart. Check out part 7, Strings in Dart.)

One of the things that's always confused me about JavaScript is the changing definition of this. This post will show how Dart avoids the confusion with more logical bindings.

The Problem

Here's some JavaScript code:

function Awesome() {
}

Awesome.prototype.cool = function() {
    alert("inside awesome");
}

Awesome.prototype.init = function(button) {
    button.addEventListener("click", function() {
        this.cool(); // this won't work!
    });
}

var button = document.getElementById("b");
var a = new Awesome();
a.init(button);

As you can see, I've created a simple Awesome object with two methods. The cool() method prints a simple message. The init() method adds an event listener to a button, which calls cool() when clicked.

At first glance, this seems like it will work. However, because the definition of this is relative to the current context of executing code, it does not refer to the instance of Awesome. When inside the event callback, this refers to the button!

A common pattern to address this problem in JavaScript is to declare a new variable in the function which points to this before the context is changed.

For example, the following code fixes the problem:

Awesome.prototype.init = function(button) {
    var _this = this;
    button.addEventListener("click", function() {
        _this.cool(); // this works now
    });
}

This is not intuitive to developers coming from other platforms, and requires more ceremony than is probably necessary.

Dart's Solution

The following Dart code is more clear and hopefully more logical. You can see the same structure, but the main difference is that there's no changing definition of this.

#import('dart:html');

class Awesome {

  cool() {
    window.alert("inside cool");
  }

  init(button) {
    button.on.click.add((e) => cool());
  }

}

void main() {
  new Awesome().init(document.query("#button"));
}

First, the use of this is optional. Typing less code is good.

Second, because Dart doesn't change the context, or the definition of this, the cool() method resolves to the lexical scope.

Next Steps

Read more of my Dart posts, try Dart in your browser, browse the API docs, or file an issue request. Dart is getting ready, please send us your feedback!

Read part 9, the Dart SDK Quick Tour.

Strings in Dart

2012-01-18T00:15:00.000-08:00

(This is part 7 in an ongoing series about Dart. Check out part 6, For loops in Dart.)

Dart brings some new ideas to Strings. If you think you know Strings, keep reading for a few surprises.

From the API docs: "A string is represented by a list of 32-bit Unicode scalar character codes."

Immutable

String are immutable objects, which means you can create them but you can't change them. You can of course build a new string out of other strings, but once created, the string's contents are fixed.

This is an optimization, as two strings with the same characters in the same order can be the same object.

var s11 = "strings are immutable";
var s21 = "strings are immutable";

print(s11 == s21); // true, contain the same characters
print(s11 === s21); // true, are the same object in memory

If you look closely at the String API docs, you'll notice that none of the methods on String actually change the state of a String. For example, the method replaceAll() returns a new String and doesn't exchange the original String.

var greetingTemplate = 'Hello NAME, nice to meet you!';
var greeting = greetingTemplate.replaceFirst(new RegExp("NAME"), 'Bob');

print(greetingTemplate != greeting); // true

Note: As of 2011-01-18, the above code doesn't work in Dart VM. See bug 429 for the status. The above code should work in Dartboard, see http://try.dartlang.org/s/yhoo for an example.

Creating

Both single and double quotes can be used to declare a String.

print('single quotes work easily');

print("double quotes work just as well");

Multi-line strings are now supported! Just use a triple quote (''' or """), with either single quote or double quote. Note the initial newline is ignored, but the last newline is not ignored!

print( '''
the initial newline is ignored
but the last newline is not ignored
''');

// is the same as

print("""the initial newline is ignored
but the last newline is not ignored\n""");

Escaping

Some languages interpret single quotes as a "literal" string, but not Dart.

print('single quotes \n don\'t make a string literal');

> single quotes 
 don't make a string literal

You can make a "raw" string by prefixing it with @. For example:

print(@'prefixing with a @ turns a string into a \n literal or "raw" string');

> prefixing with a @ turns a string into a \n literal or "raw" string

Interpolation

Dart improves on other web programming languages by introducing string interpolation. Building and joining strings is much easier now:

var s = 'string interpolation';

print('dart has ${s} which is very handy');

print("you can nest ${s + ' for fun and ${"profit"}'} with Dart");

print("concatenating strings" + " " + "is also possible with the plus sign, but we don't recommend it");

> dart has string interpolation which is very handy
> you can nest string interpolation for fun and profit with Dart
> concatenating strings is also possible with the plus sign, but we don't recommend it

Building from parts

Programmatically generating a String is best accomplished with a StringBuffer. A StringBuffer doesn't generate a new String object until toString() is called.

var sb = new StringBuffer();

sb.add("Use a StringBuffer");
sb.addAll(["for ", "efficient ", "string ", "creation "]);
sb.add("if you are ").add("building lots of strings");

var fullString = sb.toString();

print(fullString); // Use a StringBufferfor efficient string creation if you are building lots of strings

sb.clear(); // all gone!

You might be thinking, "Pffft, typing StringBuffer is so many characters. The performance difference can't be that big of a deal!" to which I reply, "The numbers don't lie."

// use new hotness: StringBuffer
buildWithStringBuffer() {
  var sb = new StringBuffer();

  for (var i = 9999; i > 0; i--) {
    sb.add(i.toString());
    sb.add(" beers on the wall\n");
  }

  var finalString = sb.toString();
}

// use old school + for string concatenation
buildWithConcat() {
  var s = '';

  for (var i = 9999; i > 0; i--) {
    s += i.toString();
    s += " beers on the wall\n";
  }

  var finalString = s;
}

// wrap a function fn with the Stopwatch class to time execution
measure(fn) {
  var sw = new Stopwatch.start();
  fn();
  return sw.elapsedInMs();
}

// the following timings are from the Dart VM
// smaller is faster is better

measure(buildWithStringBuffer); // 20

measure(buildWithConcat); // 3574 !!

As you can see, using old school + concatenation for Strings is much slower than using StringBuffer.

Note: the above times were measured in the Dart VM. When compiled to JavaScript, you will see different numbers. There is a bug for JavaScript and StringBuffer performance.

Matching

Thanks to the core Dart libraries, it's fairly easy to determine if a strings starts with, ends with, or contains another string.

var fullName = 'Cuthbert Musgrave Girdlestone, III';


fullName.startsWith('Cuthbert');            // true

fullName.endsWith('III');                   // true

fullName.contains(new RegExp('Musgrave'));  // true

Notice how the contains() method takes a RegExp object for the pattern.

Summary

Strings are immutable lists of 32 bit Unicode scalar character codes. They can be multi-line with triple quotes, or "raw" and unfiltered with a @ prefix.

Strings can be interpolated, which is preferable to concatenation via the + operator. If you must programmatically build up a String, do so with StringBuffer, which is much faster.

Strings can do a lot more than we showed here. For instance, you can split a string, create a substring, trim it, and lots more.

Next Steps

Like what you see? Learn more about Dart, its HTML libraries, and join the discussion. File a new issue if you see something missing.

Also, follow @dart_lang and +Dart Bits for more info!

Read Part 8, This is this in Dart, in which we no longer have to assign this to _this for closures.

For loops in Dart, or, Fresh bindings for sane closures

2012-01-11T01:46:00.000-08:00

(This is Part 6 of an ongoing series about Dart. Check out Part 5, Generics in Dart.)

Dart has two forms of the for loop. While you may familiar with this form of iteration, the JavaScript developer will find one (surprisingly refreshing) difference. Read on!

Dart supports the typical for loop form:

for (var i = 0; i < 3; i++) {
  print(i);
}

As well as the for-in form:

var collection = [0,1,2];
for (var x in collection) {
  print(x);
}

The for-in form is sugar for the longer code which involves an iterator:

// this is the long form of for-in

var n0 = collection.iterator();

while (n0.hasNext()) {
   final x = n0.next();
   print(x);
}

// where n0 is an identifier that does not occur anywhere in the program.

This means that any object which implements Iterable can be used via for-in.

Hopefully this looks familiar so far. You might even be yawning. But wake up!

There is a subtle semantic difference between how Dart runs the for loop and how JavaScript runs the for loop.

To start, let's look at the following JavaScript code:

When this runs, what do you expect to be printed to the console? If you said 01 you'd be incorrect. This will, in fact, print 22. Go ahead, give it a shot.

What is happening here? JavaScript is binding the same variable to each of the anonymous functions inside the first for loop. Every callback sees the same i. This is certainly non-obvious to the beginning JavaScript developer.

The solution is to remember that JavaScript has function level scoping (not block level scoping). Wrapping the anonymous functions inside their own anonymous, yet immediately executed, function will create a "private" copy of the variable. For example:

We can do better! We should demand better!

Dart makes this a whole lot easier and arguably more approachable. Consider the following Dart code:

main() {
  var callbacks = [];
  for (var i = 0; i < 2; i++) {
    callbacks.add(() => print(i));
  }
  callbacks.forEach((c) => c());
}

> 0, 1

The above code is syntacticly similar to our first JavaScript example, yet behaves like the second JavaScript example. Yes, that means this prints 0 and then 1! Hurray!

Note: the for-in style loop will also get a fresh binding for i, just like the standard for loop.

If you squint, the Dart language spec specifies this exact behavior, with the following quote:

[it is] intended to prevent the common error where users create a closure inside a for loop, intending to close over the current binding of the loop variable, and find (usually after a painful process of debugging and learning) that all the created closures have captured the same value - the one current in the last iteration executed.

Warning: As of the time of this writing (2012-01-10), only the Dart VM does the right thing for the for loop. Unfortunately, DartC and Frog (the two Dart -> JavaScript compilers) are broken. Track bug 333 to follow this bug.

Further good news: ECMAScript 6 should allow for simplified syntax thanks to block scoping:

let callbacks = [];
for (let i = 0; i < 10; i++) {
  let j = i;
  callbacks.push(function() { print(j) });
}
callbacks.forEach(function(c) { c() });

Summary

Dart has two familiar forms of the for loop for iteration. In both forms, a fresh copy of the variable created by the loop is generated. Closures and anonymous functions inside of for loops will see individual variables, which is generally a more expected behavior.

Special thanks to +Bob Nystrom and his informative Dart posts on Reddit, such as this gem which provided the inspiration for this post.

Next Steps

Learn more about Dart, play with Dart in your browser, browse the API docs, enter feature requests and bugs, and join the discussion. And remember, Dart is in Technology Preview right now, things are changing and we'd like to hear your feedback!

Also, read Part 7: Strings in Dart.

Comparing Dart, jQuery, CoffeeScript, CoffeeScript+jQuery, and JavaScript

2012-01-05T18:06:00.001-08:00

UPDATE: Thanks to Ayose Cazorla we now have CoffeeScript+jQuery examples. And thanks to js2coffee.org we have vanilla CoffeeScript.

A neat comparison between jQuery and vanilla JavaScript hit Google+ via +Eric Bidelman, so I thought it would be fun to add vanilla Dart to the mix.

This is a fun experiment, but please don't base your decision to use one option or another based on this isolated blog post. Take a holistic approach to your evaluation.

Document is ready

// jQuery

$(document).ready(function() {
  // code…
});


// vanilla JavaScript

document.addEventListener("DOMContentLoaded", function() {
  // code…
});


// vanilla Dart

window.on.contentLoaded.add((e) => code);


// CoffeeScript+jQuery

$ -> code


// vanilla CoffeeScript

document.addEventListener "DOMContentLoaded", ->
  # code

Find all divs

// jQuery

var divs = $("div");


// vanilla JavaScript

var divs = document.querySelectorAll("div");


// vanilla Dart

var divs = document.queryAll("div");


// CoffeeScript+jQuery

divs = $ "div"


// vanilla CoffeeScript

divs = document.querySelectorAll("div")

Create a new div

// jQuery

var newDiv = $("<div/>");


// vanilla JavaScript

var newDiv = document.createElement("div");


// vanilla Dart

var newDiv = new Element.tag("div");


// CoffeeScript+jQuery

divs = $ "<div>"


// vanilla CoffeeScript

newDiv = document.createElement("div")

Add a class

// jQuery

newDiv.addClass("foo");


// vanilla JavaScript

newDiv.classList.add("foo");


// vanilla Dart

newDiv.classes.add("foo");


// CoffeeScript+jQuery

newDiv.addClass "foo"


// vanilla CoffeeScript

newDiv.classList.add "foo"

Toggle a class

// jQuery

newDiv.toggleClass("foo");


// vanilla JavaScript

newDiv.classList.toggle("foo");


// vanilla Dart

// doesn't work yet, see bug http://code.google.com/p/dart/issues/detail?id=1063
// newDiv.classes.toggle("foo");


// CoffeeScript+jQuery

newDiv.toggleClass "foo"


// vanilla CoffeeScript

newDiv.classList.toggle "foo"

Add a click handler for each <a>

// jQuery

$("a").click(function() {
  // code…
})


// vanilla JavaScript

[].forEach.call(document.querySelectorAll("a"), function(el) {
  el.addEventListener("click", function() {
    // code…
  });
});


// vanilla Dart

document.queryAll("a").forEach((el) {
    el.on.click.add((e) => code);
});


// CoffeeScript+jQuery

$("a").click -> code


// vanilla CoffeeScript

[].forEach.call document.querySelectorAll("a"), (el) ->
  el.addEventListener "click", ->
    # code

Append a new <p> to <body>

// jQuery

$("body").append($("<p/>"));


// vanilla JavaScript

document.body.appendChild(document.createElement("p"));


// vanilla Dart

document.body.nodes.add(new Element.tag("p"));


// CoffeeScript+jQuery

$("body").append $("<p>")


// vanilla CoffeeScript

document.body.appendChild document.createElement("p")

Add attribute to an element

// jQuery

$("img").filter(":first").attr("alt", "My image");


// vanilla JavaScript

document.querySelector("img").setAttribute("alt", "My image");


// vanilla Dart

document.query("img").attributes['alt'] = 'My image';


// CoffeeScript+jQuery

$("img:first").attr "alt", "My image"


// vanilla CoffeeScript

document.querySelector("img").setAttribute "alt", "My image"

Get parent node

// jQuery

var parent = $("#about").parent();


// vanilla JavaScript

var parent = document.getElementById("about").parentNode;


// vanilla Dart

var parent = document.query("#about").parent;


// CoffeeScript+jQuery

parent = $("#about").parent()


// vanilla CoffeeScript

parent = document.getElementById("about").parentNode

Clone an element

// jQuery

var clonedElement = $("#about").clone();


// vanilla JavaScript

var clonedElement = document.getElementById("about").cloneNode(true);


// vanilla Dart

var clonedElement = document.query("#about").clone(true);


// CoffeeScript+jQuery

clonedElement = $("#about").clone()


// vanilla CoffeeScript

clonedElement = document.getElementById("about").cloneNode(true)

Clear child nodes

// jQuery

$("#wrap").empty();


// vanilla JavaScript

var wrap = document.getElementById("wrap");
while(wrap.firstChild) wrap.removeChild(wrap.firstChild);


// vanilla Dart

document.query("#wrap").nodes.clear();


// CoffeeScript+jQuery

$("#wrap").empty()


// vanilla CoffeeScript

wrap = document.getElementById("wrap")
wrap.removeChild wrap.firstChild  while wrap.firstChild

Check if element has child nodes

// jQuery

if($("#wrap").is(":empty")) { ... }


// vanilla JavaScript

if(!document.getElementById("wrap").hasChildNodes()) { ... }


// vanilla Dart

if (document.query("#wrap").nodes.isEmpty()) { ... }


// CoffeeScript+jQuery

if $("#wrap").is(":empty")
  code


// vanilla CoffeeScript

code  unless document.getElementById("wrap").hasChildNodes()

Get next sibling element

// jQuery

var nextElement = $("#wrap").next();


// vanilla JavaScript

var nextElement = document.getElementById("wrap").nextSibling;


// vanilla Dart

var nextElement = document.query("#wrap").nextNode;


// CoffeeScript+jQuery

nextElement = $("#wrap").next()


// vanilla CoffeeScript

nextElement = document.getElementById("wrap").nextSibling

Next Steps

Like what you see? Learn more about Dart, its HTML libraries, and join the discussion. File a new issue if you see something missing.

Also, follow @dart_lang and +Dart Bits for more info!

Generics in Dart, or, Why a JavaScript programmer should care about types

2012-01-03T23:22:00.000-08:00

(This is Part 5 in an ongoing series on Dart. Check out Part 4, Maps and hashes in Dart.)

Intro

Dart is, by most accounts, designed to be a familiar programming language. One of Dart's most interesting (and daring features for a mainstream language) is optional typing. Optional static types allow you to choose when to add the static types.

Dart has optional typing because it's a web programming language, and it's designed to scale from interactive scripts (which don't necessarily need lots of declared types) to complex, large web applications (which probably do need lots of declared types, which serve as a documentation annotation for tools and humans.)

An example of untyped Dart code:

smush(a, b) => a + b;

main() {
  var msg = "hello";
  var rcpt = "world";
  print( smush(msg, rcpt) );
}

> helloworld

As you can see in the example above, the var keyword is used to denote a variable. var is synonymous with the Dynamic, or "unknown", type. The above code is is not statically typed, yet it runs just fine.

Note the smush(a, b) method, which smushes two objects together and returns the result. Looking at this method signature, and even its definition, it's not clear exactly what that intent is or what kind of objects it works with. The original programmer's intent isn't clear, which is a problem if the development team is large or if the application itself is complex.

Nothing is stopping a developer from passing in two numbers to smush, as the example below illustrates:

smush(a, b) => a + b;

main() {
  var x = 3;
  var y = 4;
  print( smush(x, y) );
}

> 7 // technically true, but is this what we wanted to allow?

In some sense, this is the beauty of dynamic scripting languages. However, Dart is designed to support large, complex apps as well, and when you add hundreds of classes, thousands of functions, and tens of developers, this kind of ambiguity can be costly.

The typical JavaScript developer would probably first try to solve this problem by just remembering what the intent of smush is, but this doesn't scale. Second, the function would be renamed to something more clear. Third, comments would probably be added, with a note like "this methods takes two strings and concatenates them." I reckon the combination of a renamed function name and descriptive comments would get you pretty far, but they still don't express your intent to the program.

But we can do better than longer function names and more comments, for we want to say less and do more! We want our code to be our comments, and have our systems work for us and understand us!

We must demand a better solution. We must demand that our tools scale to meet our complex app needs. We must demand that our language allow us to express our intent tersely and with minimal friction!

Enter types!

Luckily, Dart gives us a safety net as we scale up our program: optional static types. By adding in simple annotations to our program code, we can express certain expectations and assertions in a way that both a human and the machine can quickly and easily grok. Once our system understands these type assertions, a whole new world of early error detection is now available. Every error caught in development is one less error caught by our users.

Let's declare that the smush method is expecting Strings:

smush(String a, String b) => a + b;

main() {
  var x = 3;
  var y = 4;
  print( smush(x, y) ); // in Checked Mode, this results in a Failed type check
}

When two numbers are passed to smush, and the program is run in Checked Mode (aka "type assertions turned on"), the system will halt execution with a "Failed type check" error.

This is awesome! Our tools caught an error for us, simply because we added some short annotations. Our tools are now working for us.

By simply adding the type declarations to the smush signature, the program understands the developer's intent and expectations and can check them for us. No comment has that power, and even a descriptive and clear function name doesn't have that power.

Think of those type annotations as assertions and documentation, all rolled up in one.

We can go further and give types to our variables x and y. This has the added benefit of generating warnings with or without Checked Mode. For example:

smush(String a, String b) {
  return a + b;
}

main() {
  num x = 3;  // note the type
  num y = 4;
  print( smush(x, y) ); // two warnings are generated here, re: type mismatch!
}

> 7 // yet the program still runs! types don't affect the program semantics

Giving type annotations to x and y, and keeping the type annotations in the smush method, allows our program to detect and warn us about this type mismatch.

This is super awesome! We don't even need to run in Checked Mode for our program to let us know something is afoot. All we had to do was add an annotation that was probably shorter than any comment you would have added to clarify just what x and y were supposed to be.

Optional types give us the powerful, yet terse, expressiveness when we need them for larger, more complex web apps, and we can omit them for our simple one page scripts. Or heck, type everything and catch nearly all type warnings early!

Yo dawg, I heard you like types, so I added types to your collections, so you can put Strings in your Lists of Strings

We've shown the helpfulness and expressiveness of types for variable declarations and function signatures. Let's take it one step farther and add another type annotation which can further tell your program, and your fellow developers, what your intentions are (and catch errors early!)

As covered in previous posts, Dart has support for collections such as Lists (arrays) and Maps (hashes). Lists store ordered collections of objects that can be retrieved via an index, and Maps store key/value pairs.

A simple example of a List:

main() {
  var digits = [0,1,2,3];
}

Adding a new element to a List is also simple:

main() {
  var digits = [0,1,2,3];
  digits.add(4);
}

However, even though I'm clearly expressing a List of numbers, the following code will still execute:

main() {
  var digits = [0,1,2,3];
  digits.add("four"); // executes, but is this what we want?
}

A couple of options spring to mind. We could rename digits to digitsOfNumbers, but that's verbose. Worst of all, not matter what we rename the variable to, we still can't express our intent to the program.

We must demand better! We must be able to tell our program that collections of things only hold certain things. We must demand that our program will warn us if an object of a different type is being added to a collection. We must demand that our programs catch errors early and help us, not hinder us!

Enter generics!

Think of generics as type annotations for your collections. With generics, you can tell your program, and other developers sharing the code, that a List of numbers is, well, actually a List of numbers.

Check it out:

main() {
  var digits = <num>[0,1,2,3];
  digits.add("four"); // BOOM, Failed type check. Program stops.
}

Thanks to the <num> annotation, the program can catch when an object with a mismatched type is added. Best of all, the error is caught early, and not when some other method tries to actually do something (incorrect) with the different object.

Dart's List interface is really a List<E> which you can read as "List of E, where E is some type." That E is a placeholder, and stand-in for a type that is declared external to the List interface definition.

These generics also help when extracting objects from a List, not just adding objects. For example, consider the following code:

add(num a, num b) => a + b;

main() {
  var names = <String>['alice', 'bob'];
  print( add(names[0], names[1]) ); // in Checked Mode, this BOOMs. Failed type check!
}

Wow, Dart is smart! It knows that add takes two numbers, and that names is a List of Strings. It also knows that objects inside of names are Strings, so when we reference names[0] (which the program knows is a String) and attempt to pass it to add(num, num), it errors with a Failed type check.

This is super duper cool! Adding a simple type annotation to our collection gives our program a tremendous amount of information, and the ability to fail quickly at the source of the bug (and not later in the program when it's too late.) Simply being able to catch these sorts of bugs when they occur is enough to make you consider adding type annotations to your collections.

A List of Strings is a List, which sounds obvious when you say it out loud

Warning: the following section is for those who want to dive in deeper to generics, reification, and covariance. If you are new to these terms, the below might blow your mind. It's OK to stop reading here. The below isn't always the best way to write code.

One more cool part about Dart's collections and generics (aka type annotations.) Dart will reify, or remember, the generic types for its collections. Unlike in Java, Dart's generic type annotation is not thrown away.

This means you can perform a check at runtime:

main() {
  var names = <String>['alice', 'bob'];
  print( names is List<String> ); // true!
}

OK, in retrospect, this is a totally obvious example. Trust me when I say, if you're a Java developer, your head is spinning right now.

Remember how we keep repeating that Dart is an optionally typed language? Someone (I don't know who) is going to write a function that does not specify any generic types, but the program should work anyway.

// we really recommend you don't omit the generic types
// for illustration only

awesome(List stuff) {
  // something awesome, if only I knew what was inside of stuff
  // but I was too lazy to add my generic type annotation
}

main() {
  var names = <String>['alice', 'bob'];
  awesome(names); // works! Dart lets a List<String> act as a List

  // which means
  print( new List<String>() is List );  // true!
}

When you say it out loud, it sounds obvious: a List of String is a List.

Here's the best part, and a true reflection of Dart's optional typing. If List<String> is a List, is the inverse true? Can a List be passed to a function expecting a List<String> ?

// hurray! you added generic type annotations. your intention is clear.
awesome(List<String> stuff) {
  // something more awesome, because I know it's a List of Strings
}

main() {
  var names = ['alice', 'bob']; // I got lazy and didn't specify!
  awesome(names); // works!

  // which means
  print( new List() is List<String> );
}

Yes, the above works (though we don't recommend it!) because Dart's generics are covariant. This means List<String> is List, and List is List<String>.

But why oh why would Dart design a system that is so, well, unsound?!?!!

Remember that Dart has optional typing. This means a library author can write classes and functions without specifying any types at all. Heck, there's an army of JavaScript developers that have never seen a static type and many probably never want to see one. Hopefully the first part of this article convinced you that types are terse and useful, but Dart is built for a wide range of developers.

Now imagine that there is an untyped library that is AWESOME, and you want to use it. Your code, because you are a true Dart Viking, is fully typed. Should you be able to mix your fully typed code with an arbitrary library that is untyped? Yes!

// from the SuperLazyLib with zero types

awesome(stuff) {
  // you are brave
}

// from the Dart Viking, who writes clean and typed code

main() {
  var names = <String>['alice', 'bob'];
  awesome(names); // works!
}

Dart allows a mix of typed and untyped code, and as such the generics must be covariant.

If you are authoring a library, please add types. Your machines and humans will both thank you.

Summary

Demand more from your web programming language! Demand terse type annotations which help your program catch errors earlier, and your fellow developers more easily understand your intent.

Dart is a mostly familiar language by design, however it does have novel features like optional types. Types should be thought of as annotations, or documentation, for both the machine and your fellow programmer. Types are terse, often smaller than the comments you'd use to specify what a thing is or what can be passed to a method.

Once added, types can be interpreted by the program, allowing for bugs resulting from type mismatches to be detected early. Types also act to convey your intention and assertions to your fellow developer. This is A Good Thing (tm).

Types can be added to variables and function signatures. Types can also be given to collections such as Lists and Maps. These generics tell the program what objects are expected to be placed inside of, and retrieved from, a collection. Generics also help with tersely expressing programmer intent to both the machine and the fellow developer, and helps to catch bugs early.

Generics in Dart are covariant, which means a List of Strings is a List, and a List is a List of Strings. This is due to the fact that Dart's optional typing allows for a mix of types and untyped code to be used in the same program.

We recommend using types for method signatures, we don't recommend authoring libraries without types.

Next Steps

Learn more about Dart, play with Dart in your browser, browse the API docs, enter feature requests and bugs, and join the discussion. And remember, Dart is in Technology Preview right now, things are changing and we'd like to hear your feedback!

Also, check out Part 6, For loops in Dart, or, Fresh bindings for sane closures.

Maps and hashes in Dart

2012-01-02T21:26:00.000-08:00

(This is Part 4 of our ongoing series about Dart. Check out Part 3: Lists and arrays in Dart.)

Warning: We expect the Dart libraries to undergo potentially sweeping changes before Dart goes to alpha. This document is relevant as of 2012-01-02.

Intro

Dart is not just a language, but a full "batteries included" effort to create a productive, familiar, and fun environment for the modern web app developer. The bundled libraries are one such "battery", including many common classes and utilities such as date manipulation, regular expressions, even asynchronous constructs like Future and Promise.

Probably the most used set of libraries will be the Collections, such as List, Map, and Set. In this post, we'll take a look at Map, which is a mapping of keys to values.

In Dart, a Map is an interface designed to manipulate a collection of keys which point to values. Maps can have null values, and can have parameterized types. Note, Maps do not subclass the Collection interface.

Dart != JavaScript: Unlike JavaScript, Dart objects themselves aren't maps or hashes.

Create, read, count, copy, and remove examples

Dart supports map literals, such as:

main() {
  var stuff = {"hello": "world"};
}

In the above example, hello is the key and world is the value.

Map literals, those declared with the {} syntax, must have Strings as keys.

var map = {};

// is the same as

var map = new Map<String, Dynamic>();

However, if you declare your Map without the literal syntax (eg new Map()), you can use any object that implements the hashCode method as the key. Curious what makes a good hashCode? Josh Bloch covers hashCode in his book Effective Java, and luckily that particular topic is covered in the free Chapter 3.

Of course, the values don't have to be strings:

main() {
  var stuff = {"hello": 4};
}

Dart Maps can contain null values, too:

main() {
  var stuff = {"hello": null};
}

Retrieving a value from a map is familiar:

main() {
  var stuff = {"hello": "world"};
  print( stuff['hello'] ); // world
}

If you look for a key that isn't in a Map, you will get a null in return:

main() {
  var stuff = {"hello": "world"};
  print( stuff['foo'] ); // null
}

Adding a new key/value pair to an existing map is also familiar:

main() {
  var stuff = {"hello": "world"};
  stuff['Dart'] = 'Is Cool';
  print( stuff['Dart'] ); // Is Cool
}

Use the length getter to return the number of key/value pairs in the Map:

main() {
  var stuff = {"hello": "world"};
  stuff['Dart'] = 'Is Cool';
  print( stuff.length ); // 2
}

Removing a value from a map, which also removes its key, is straight forward:

main() {
  var stuff = {"hello": "world"};
  stuff['Dart'] = 'Is Cool';
  print( stuff['Dart'] ); // Is Cool
  stuff.remove('hello');
  print( stuff.length ); // 1
  print( stuff['hello'] ); // null
}

You can copy a Map with a named constructor:

main() {
  var stuff = new Map.from({"hello": "world"});
  print( stuff['hello'] ); // world
}

Iterating

There are a few ways to iterate through the contents of a Map. If you want to access both the key and value at the same time, the forEach method will work nicely.

main() {
  var stuff = {"hello": "world", 'Dart': 'Is Cool'};
  stuff.forEach((k,v) => print(k));
}

Notice how, in the above example, that both the key and the value as passed to the callback function for every iteration of forEach.

No order is implied, do not depend on a certain order of keys and values being returned via forEach.

If you are only interested in just the keys, or just the values, use getKeys() and getValues(), respectively. Both methods return a Collection object.

main() {
  var stuff = {"hello": "world", 'Dart': 'Is Cool'};
  var keys = stuff.getKeys();
  print( keys.length ); // 2
  keys.forEach((k) => print(k)); // hello, Dart
}

putIfAbsent

A fun method on Map is putIfAbsent(K key, V ifAbsent()). It will first if the key exists, and if not, will run the ifAbsent function and will use the return value as the value for the key. For example:

main() {
  var stuff = {"hello": "world", 'Dart': 'Is Cool'};
  stuff.putIfAbsent('foo', () {
    // calculate something awesome
    return 'bar';
  });
  print( stuff['foo'] ); // bar
}

Parameterized types, aka Generics

I haven't written a post on generics yet, so please bear with me if you don't know what generics are. If you do, you'll be pleasantly surprised at how they've been simplified. If you don't know what generics are, think of them as annotations to help you and your tools understand more about the types you'll use with objects such as collections.

Maps can be specified with parameterized types, which allow you to say what kind of types you want to store inside the map. For example, perhaps you want a Map of Strings to integers. Without generics, you'd have to just hope everyone (including you) puts in String/int pairs, and you'd probably have to add a bunch of assertions to ensure that they (or you) did. However, with generics, the tools and runtime can help ensure that the code maps Strings to integers.

(The examples in the post so far have not specified any parameterized types.)

In Dart, you can be more specific about your Map, and actually say "A Map that maps Strings to integers" in this way:

main() {
  var stuff = <String, int>{'four': 4, 'five': 5};
  print( stuff['four'] ); // 4
}

The above is the same as:

main() {
  var stuff = new Map<String, int>();
  stuff['four'] = 4;
  stuff['five'] = 5;
  print( stuff['four'] ); // 4
}

Our tools come to the rescue when someone (definitely not you, because you're a Dart viking) accidentally assigns the wrong type. For example, if you run the below in Checked Mode:

// try it yourself at http://try.dartlang.org/s/InMl
main() {
  var stuff = new Map<String, int>();
  stuff['four'] = "oh uh!"; // Failed type check: type String is not assignable to type int
  print( stuff['four'] ); // won't get this far
}

Now that's what I'm talking about! For the small cost of specifying the expected types at object instantiation time, the system (in checked mode) will warn you the wrong type is being used, and the program will stop running. (again, if you're in checked mode, this is true) Check out the above example and play with the "checked mode" toggle.

You can go further and even specify the parameterized types statically, such as:

main() {
  Map<String, int> stuff = new Map<String, int>();
  stuff['four'] = "oh uh!"; // warning here if NOT in checked mode
  print( stuff['four'] ); // won't get this far
}

Now the system has even more information, so you will get further warnings even if you're not in checked mode! The program will still run if you have checked mode turned off, since the above program still works. However, by specifying the static type for stuff, you've added enough annotations to give you warnings that something isn't quite right. Try the above code yourself, with and without "checked mode" enabled.

As mentioned above, if you are using the non-literal syntax to declare a Map (such as new Map()) then you can use any object that implements hashCode as the key.

Summary

Dart's bundled libraries includes a Map interface, which can map a key (as long as it implements hashCode) to a value for easy lookup. The interface has the standard methods for creating, reading, updating, and deleting key/value pairs, as well as some new methods like putIfAbsent(). Just like in JavaScript, Dart Maps can be created with a literal, terse syntax (however, this restricts you to using only Strings as keys.) Unlike JavaScript, though, Dart objects aren't themselves Maps.

Just as Dart has optional types, parameterized types are optional as well. They are quite useful when you're writing method signatures and interfaces, as they convey even more intention and documentation about the expected containers and objects. The more type annotations you can add, the more rich documentation can be extracted and the more the tools can warn you when things don't go as planned.

Next Steps

Read Part 6 on Generics in Dart, or Why JavaScript developers should care about types.

The core Dart libraries will almost certainly undergo sweeping changes now that Josh Bloch has joined the team. For now, though, there's still a lot you can do with Dart's lists. As you work with the libraries, remember that Dart is in Technology Preview mode, and we really want to hear your feedback.

What do you need from the libraries? Let us know at the mailing list or please file an issue. Thanks!

Read more about the Map interface at the docs, and check out all the libraries at api.dartlang.org.

10 lessons from porting JavaScript to Dart

2011-12-30T22:37:00.000-08:00

I wrote a simple HTML5 game for my Google IO 2011 Introduction to HTML5 Game Development talk. The original game was written in JavaScript, and as an exercise I just ported the game to Dart. This post contains some lessons learned from the process.

Background: The original JavaScript code for the game is open source, as is the new Dart code.

Note: The Dart version doesn't have sound working, as the Web Audio API isn't currently working in Dart.

Straight forward port

The executive summary of the porting process is: it's pretty dang easy. Dart had two primary design constraints: it must be familiar to JavaScript developers, and it must compile to JavaScript. Having just ported over 574 lines of JavaScript to 554 lines of Dart, I can say that those two design constraints are being satisfied quite well.

To be fair, I wrote the first JavaScript version with structured classes in mind (using JavaScript's prototype system) so it was easy to port to Dart's native classes. For example, compare the following JavaScript class:

// old JavaScript code
function Timer() {
    this.gameTime = 0;
    this.maxStep = 0.05;
    this.wallLastTimestamp = 0;
}

Timer.prototype.tick = function() {
    var wallCurrent = Date.now();
    var wallDelta = (wallCurrent - this.wallLastTimestamp) / 1000;
    this.wallLastTimestamp = wallCurrent;
    
    var gameDelta = Math.min(wallDelta, this.maxStep);
    this.gameTime += gameDelta;
    return gameDelta;
}

to the new equivalent Dart class:

// new Dart code
class Timer {

  num gameTime = 0;
  static final num MAX_STEP = 0.05;
  num wallLastTimestamp = 0;
  
  num tick() {
    num wallCurrent = new Date.now().value;
    num wallDelta = (wallCurrent - wallLastTimestamp) / 1000;
    wallLastTimestamp = wallCurrent;
    
    num gameDelta = Math.min(wallDelta, MAX_STEP);
    gameTime += gameDelta;
    return gameDelta;
  }
}

I think the Dart class syntax is easier to read, and it's a welcome relief to be able to omit all of those this qualifiers that are required in JavaScript. Regardless, I think it's safe to say that a developer versed in one language can grok the other.

So what did I learn?

1) Types rule. I know there are a bunch of JavaScript developers that have never seen a static type, and don't want to touch them. To that I say, don't be too quick to judge. Types made the porting process much quicker, because my editor and compiler caught errors much earlier for me. Did I use types for everything? Nope, but I will be using types in Dart for most things.

2) The Dart editor is very handy. With it's ability to warn me of real and potential errors as I code, I'm able to code faster. I think web developers are going to have an epiphany when they realize what they've been missing: real-time analysis of their code as they write it is a real time saver and will result in better code.

3) Frog compiler generates very logical JavaScript. Dart code will run on modern browsers via JavaScript, and Frog is the Dart to JavaScript compiler that is currently recommended due to its terse and human readable output. The Frog compiler turned my Dart code back into what was essentially the same JavaScript code that I originally wrote. For example, check out the following JavaScript code that came from Frog:

// this JavaScript code came from Frog
function Timer() {
  this.gameTime = 0
  this.wallLastTimestamp = 0
  // Initializers done
}
Timer.prototype.tick = function() {
  var wallCurrent = new DateImplementation.now$ctor().value;
  var wallDelta = (wallCurrent - this.wallLastTimestamp) / 1000;
  this.wallLastTimestamp = wallCurrent;
  var gameDelta = Math.min(wallDelta, 0.05/*Timer.MAX_STEP*/);
  this.gameTime += gameDelta;
  return gameDelta;
}

4) Dart doesn't let me get sloppy. Thanks to types, real classes, inheritance, modifiers like static and final, and real lexical scoping, my Dart code feels more robust. I'm not allowed to slack.

5) The api.dartlang.org docs are helpful. Thanks to the new API docs, and the Dart Editor, it was easy to find my way around the core libraries.

6) Math.abs() is now num.abs(). This makes more sense to me, I'm glad they did it. For example, instead of Math.abs(-4) you will write -4.abs().

7) Grab the number of milliseconds since the epoch with new Date.now().value. Slightly more verbose than JavaScript, but this might change as the whole core libraries are going to get some major love in the beginning of 2012.

8) Dart has one falsy value: false. This is such a blessing compared to JavaScript's six falsy values. This means I had to rewrite:

// JavaScript
if (something) {
  // do stuff
}

to:

// Dart
if (something != null) {
  // do stuff
}

9) Real lexical scoping means I can drop this from instance variables. I no longer needed to write this.foo in my objects, I could just reference foo.

10) console.log() is now print(). The new print() is more terse, and works both on the server via the VM and in the browser. I'll allow it!

Summary

If your JavaScript is half way logical, you'll probably find it very straight forward to convert to Dart. There are differences, but most of the work can be handled by some regular expressions and some search and replaces. The resulting code felt more stable, as types and the tools like the Dart Editor didn't allow me to slack.

Check out the resulting Dart code for a simple HTML5 game.

Lists and arrays in Dart

2011-12-22T15:58:00.000-08:00

(This is Part 3 in a series about Dart. Check out Part 2, Function in Dart.)

Warning: We expect the Dart libraries to undergo potentially sweeping changes before Dart goes to alpha. This document is relevant as of 2011-12-22.

Intro

Dart is a "batteries included" effort to help app developers build modern web apps. An important "battery" is the bundled core Dart libraries, providing common and rich functionality. Dart is building a solution for large, complex web apps, and providing well tested, integrated, and common libraries is key to helping a web app developer be more productive out of the box.

The Collection libraries are a crucial set of APIs that Dart developers get for free. Much more than simple arrays and maps, the Collection library includes standard ways to filter, iterate, inspect, compose, and sort your data. This post specifically looks at List<E>, Dart's ordered, indexable collection of objects.

Aside: The Dart project is lucky to welcome Josh Bloch to the team, who will be leading the library design efforts. Expect some great things for the libraries and Dart!

Arrays are Lists

Perhaps the most common collection in nearly every programming language is the array, or ordered set of objects. Dart arrays are Lists, so look for List in the documentation. A Dart List will compile to a JavaScript array.

Fun fact: As of 2011-12-22, the word "array" does not appear in the Dart spec.

List basics

Dart supports List literals like JavaScript. A simple Dart list:

main() {
  var list = [1,2,3];
  print( list is List ); // true
}

Get the list's length, or number of elements inside of the list:

main() {
  var list = [1,2,3];
  print( list.length ); // 3
}

Access the second element in the list: (notice how Dart list indexes are 0 based, i.e. 0 is the first element, 1 is the second element, etc)

main() {
  var list = [1,2,3];
  print( list[1] ); // 2
}

If you try to reference an element that is outside the length of the list, you'll get an IndexOutOfRangeException.

main() {
  var list = [1,2,3];
  print( list[5] );  // Unhandled exception: IndexOutOfRangeException
}

Add an element to a list constructed from a list literal:

main() {
  List list = [1,2,3];
  list.add(4);
  print( list.length ); // 4
}

Now is a good time to point out that the add(object) method is optional. That is, not all implementations of List have to support it. I don't personally like optional methods, but this is where we stand as of 2011-12-22.

An example of a List that you can't add to is the fixed size List, as constructed by:

main() {
  var list = new List(3);
  list.add(4); // this throws an UnsupportedOperationException: Cannot add to a non-extendable array
               // exception thrown for Lists constructed with an initial size
}

Unfortunately, the docs right now don't clue you in that the new List(size) constructor returns a fixed size List, but follow bug 948 for the comment fix.

It's important to know that when you construct a fixed size List, that the List itself is allocated to that size and filled with nulls for the size of the List. For example:

main() {
  var list = new List(5); // [null,null,null,null,null]
  print(list[0]);  // null
}

Also important to know for JavaScript developers: Lists in Dart are not associative arrays. That is, the following code will NOT work in Dart:

main() {
  var list = new List(); // no initial size! aka EMPTY
  list[3] = 'hello'; // IndexOutOfRangeException
}

Remove an element from a list: (I know, I know, we're lacking a simple removeAt(index) function (see bug 947). See comment about Josh Bloch above and just hang tight :)

main() {
  List list = [1,2,3];
  list.removeRange(1, 1); // remove only the second element
  print( list.length ); // 2
}

To print the elements of a List, we need to add a map() function to eventually convert a List to a List<String> because Strings.join only takes a List<String>. The Dart libs are lacking a map function on collections (see bug 945).

List map(List list, converter(x)) {
  final List result = [];
  for (final x in list) {
    result.add(converter(x));
  }
  return result;
}

List<String> listToStrings(List list) {
  return map(list, (x) => x.toString());
}

main() {
  List list = [1,2,3];
  print( Strings.join( listToStrings(list), ',' )); // 1,2,3
}

Sorting

Sorting a List takes advantage of Dart's function support.

main() {
  var list = [4,1,2];
  list.sort(compare(a,b) {
    if (a == b) {
      return 0;
    } else if (a > b) {
      return 1;
    } else {
      return -1;
    }
  });
  // list is now 1,2,4
}

Iterating

Iterating over a List can be done in at least four ways. The standard, most familiar way is the for loop:

main() {
  var list = [4,1,2];
  for (var x = 0; x < list.length; x++) {
    print(x);
  }
}

There's a more terse way of using for if you don't need the current iteration index:

main() {
  var list = [4,1,2];
  for (final x in list) {
    print(x);
  }
}

The verbose way to say the above is to use a formal Iterator from the List:

main() {
  var list = [4,1,2];
  Iterator i = list.iterator();
  while (i.hasNext()) {
    print(i.next());
  }
}

And finally, if you just want to apply a function to each element of the List, use forEach:

main() {
  var list = [4,1,2];
  list.forEach(f(e) => print(e));
}

Filtering

The Collection interface, which List extends, provides a filter method, which returns a new collection with only the elements that satisfy a condition.

An example of filtering:

main() {
  var list = [4,1,2];
  var evens = list.filter(f(e) => e % 2 == 0);
  printList(evens); // 4,2
}

Of course, you don't need to inline the filtering function. Passing in a function also works:

isEven(x) => x % 2 == 0;

main() {
  var list = [4,1,2];
  var evens = list.filter(isEven);
  printList(evens);
}

Next steps

Check out the every(bool f(E element)) and some(bool f(E element)) methods to check if the List matches every condition or at least one condition, respectively.

Of course, please review the full Collection<E> docs and the List<E> docs.

Summary

Dart has Lists which are ordered sequences of objects. There is no class or interface called Array, though Lists act extremely similar to Arrays you might have encountered in other programming languages.

Dart Lists are not associative arrays like JavaScript, but Dart does have list literals for easy declaration.

The core Dart libraries will almost certainly undergo sweeping changes now that Josh Bloch has joined the team. For now, though, there's still a lot you can do with Dart's lists. As you work with the libraries, remember that Dart is in Technology Preview mode, and we really want to hear your feedback.

What do you need from the libraries? Let us know at the mailing list or please file an issue. Thanks!

Next steps

Check out Part 4: Maps and hashes in Dart.

Response to Coffeescript and Dart article on nettuts

2011-12-15T00:34:00.000-08:00

Some slight clarifications, if I may, following a recent article on nettuts.com:

Jeremy said: ” In addition, Dart retreats from the dynamism of JavaScript, and instead exists as a somewhat static language, where types can be checked at compile time, but are erased at runtime. ”

While there are many ways to interpret “dynamism”, it’s true that Dart doesn’t have extremely dynamic features like “eval” or the ability to arbitrarily change object structure.

However, it’s important to point out that Dart is an optionally typed language, allowing a developer to write as much or as little static type information in the code as they wish. This was a pragmatic decision (as there are plenty of web developers that have been writing great untyped code, and who probably don’t want to see a type), however we also think optional typing allows a program to grow over time (as complexity increases, types can help with documentation and tools.)

Types aren’t erased at runtime, values still have their types. A string is a string, a number is a num. In fact, collections have reified types, so you can ask if a List of Strings is really a List of Strings. I think the misconception is that a few presentations out there (mine included) have said, “types don’t affect the runtime semantics of your code.” Admittedly this is something best left for language designers to debate, as real life developers want to know if types help them or just get in the way.

Dart programs can run in something called “checked mode”, which I find quite useful. It can use the types to catch errors earlier in the program, something always helpful.

James said: “Dart doesn’t seem to bring anything to the table other than a more Java-esque syntax, which many developers aren’t too fond of, myself included.”

This is a fair assessment from the early samples and demos we released. However, Dart code can be written to look nothing like Java. Remember, Dart is just a technology preview, and we are still figuring out how to write idiomatic Dart code. The community will probably evolve into something that doesn’t quite look like Java, and something that doesn’t quite look like JavaScript. It will be Dart code, and that’s good. :)

Remember that Dart code doesn’t even have to use classes, and doesn’t have to look anything like Java. For example:

hello(msg, to, wrapper) {
return '${wrapper(msg)} to ${to}';
}

importantify(msg) => '!!! ${msg} !!!';

main() => print(hello('world', 'Seth', importantify));

Granted that’s a contrived example, but we’re doing some non-Java things in there like string interpolation, untyped code, and passing functions as first class objects. Not to mention the syntax sugar for a one line function.

Nathan said: “the end-game for Dart is to get developers writing an entirely different language altogether (preferably interpreted in a browser’s VM, instead of being precompiled to JS).” and Ryan said “Dart aims to replace JavaScript”

The end game of Dart, and CoffeeScript, and modern JavaScript, is to help developers write more complex, full featured, high fidelity, larger modern web apps. These languages are a means to an end: a better modern web. Dart isn’t out to replace anything, any more than CoffeeScript is out to replace JavaScript. Dart is out there to help show developers on other platforms that the web is a compelling and amazing place to build apps.

Finally, Alex said: “Google took rather a walled garden approach to Dart, and I get the impression they didn’t really look outside the confines of their company for inspiration.”

It’s true, Dart was launched into Technology Preview with some ideas written down. Having some code written is better than just abstract ideas, in my opinion, because shipping code wins. But Dart is not done, and it’s open source, and there’s a lot more to do. It’s incredibly open, in fact, with all the code in the open, along with the bug tracker and mailing list. I do not believe Dart is a walled garden. The real test is how the team will accept and integrate outside patches, but I don’t sense this will be an issue.

As for inspiration, there has been plenty of outside and historical influence. Lars Bak, the lead of the project, has been working on virtual machines for many years. His team was responsible for V8, so they must have learned a lot there. Gilad Bracha, leading the spec, worked on the Java language spec and generics, and definitely learned a lot of good and bad lessons there. Many on the team are former Smalltalkers, like Peter Ahe. Bob Nystrom even built his own language. Josh Bloch, of Effective Java fame, knows a thing or two about designing libraries. I’m sure I’m missing people, and I apologize. And we’d be remiss if we didn’t mention CoffeeScript as part of the inspiration, for it is clear evidence that developers are hungry for options and alternatives.

(update: this is a repost of my original comment on the article. if you'd like to respond, we should probably carry on the conversation over at the original article)

Learning Functions for Dart

2011-12-14T23:34:00.000-08:00

(This is Part 2 in a series on Dart. See Part 1: Variables and optional types in Dart)

While it's true that Dart is an object oriented, class based, single inheritance language with interfaces, there's nothing forcing you to use classes. If you haven't seen a class in your life, or you don't want to use classes, you will be pleased to see that Dart can function quite nicely with, well, just functions.

Basics

The most simple function I could come up with:

hello() => 'world';

The => e syntax is shorthand for a function body of the form {return e;}.

The above is the same as:

hello() {
  return 'world';
}

Notice how the return type is omitted. Dart is an optionally typed language, so the programmer is free to omit static type declarations.

The above is the same as:

Dynamic hello() {
  return 'world';
}

The Dynamic type is the "unknown" type. From the spec: "If no static type annotation has been provided the type system assumes the declaration has the type Dynamic." You probably won't see real life code actually statically specify the Dynamic type, because the system will insert it if it needs to.

The above can also be written as:

String hello() {
  return 'world';
}

The above example statically declares String as the return type. Compare this version to the very first one-line example.

Parameters

Adding parameters to functions is familiar:

hello(msg) => msg;

Like all Dart code, types are optional for function parameters. For example, the above is the same as the below:

hello(String msg) => msg;

We think types are useful for interfaces, methods, functions, and any place you need to either communicate with your editing tools or larger team. If you haven't seen a type in your life, Dart isn't going to force types on you. However, they are useful for documentation and catching some errors early.

Multiple parameters are supported as well:

hello(msg, to) => msg + ' for ' + to;

We can do better than the overloaded + sign to concatenate strings together. The above is the same as the below:

hello(msg, to) => '${msg} for ${to}';

Ahhh, much better! Not only does the above string interpolation read better (for me, at least) there's a subtle potential performance improvement. Due to Dart's optional typed nature, using the + concatenation means the running program must first determine if it's adding two numbers or two strings. However, using the string interpolation method (eg, above) means the running program can make assumptions.

Of course the above is the same as the below, with types specified:

hello(String msg, String to) => '${msg} for ${to}';

Optional Parameters

Dart has little gems to help you write programs quickly and easily. One of those gems is optional parameters. For example:

hello(msg, to, [from]) => '${from} sent ${msg} to ${to}';

The brackets around the parameter names indicate that parameter is optional. For example:

hello(msg, to, [from]) => '${from} sent ${msg} to ${to}';

main() => print(hello('world', 'Seth')); // doh! forgot my optional parameter

"null sent world to Seth"

Of course, the null in the above example appears because I never passed in a value for from.

The following example does pass in a value for the last (optional) parameter:

hello(msg, to, [from]) => '${from} sent ${msg} to ${to}';

main() => print(hello('world', 'Seth', 'Bob'));

"Bob sent world to Seth"

Named Parameters

Turns out this gem has a gem of its own. Optional parameters are also named parameters. Check this out:

hello(msg, to, [from]) => '${from} sent ${msg} to ${to}';

main() => print(hello('world', 'Seth', from:'Bob'));

This implies that named parameters can also be reordered when calling the function. For the below example, I added two optional and named parameters:

hello(msg, to, [from, rate]) => '${from} sent ${msg} to ${to} via ${rate}';

main() => print(hello('world', 'Seth', from:'Bob', rate:'First Class'));

Because named parameters can be reordered, the above can be rewritten as:

hello(msg, to, [from, rate]) => '${from} sent ${msg} to ${to} via ${rate}';

main() => print(hello('world', 'Seth', rate:'First Class', from:'Bob'));

This is certainly flexible stuff.

Default Parameters

Yet another bonus of using optional parameters is that they can be given default values. For example:

hello(msg, to, [from, rate='First Class']) => '${from} sent ${msg} to ${to} via ${rate}';

main() => print(hello('world', 'Seth', from:'Bob')); // doh! forgot rate

"Bob sent world to Seth via First Class"

From the spec: "If no default is explicitly specified for an optional parameter, but a default could legally be provided, an implicit default of null is provided."

It should also be noted that default values must be compile time constants. (we'll talk more about what this means in a future blog post) That is, you can't do something like ~~hello(msg, to, [from=new foo(), rate='First Class'])~~.

Inner Functions

Dart understands that there are plenty of developers that don't want to see a class yet still want some composability. One tool that the seasoned web developer will find useful is the "inner function" (what is the proper name here?) Yes, you can nest functions!

An example of a nested (aka inner) function:

hello(msg, to) {
  importantify(msg) => '!!! ${msg} !!!';

  return '${importantify(msg)} to ${to}';
}

main() => print(hello('world', 'Seth'));

"!!! world !!! to Seth"

I've seen developers use these nested functions as a way to document and organize their function bodies. With proper use of nested functions, you probably don't even need comments inside a function.

Functions are First Class

Dart treats functions as first class objects, further reinforcing the notion that you don't need classes if you don't want them. For example, you can pass a function to a function:

hello(msg, to, wrapper) {
  return '${wrapper(msg)} to ${to}';
}

importantify(msg) => '!!! ${msg} !!!';

main() => print(hello('world', 'Seth', importantify));

"!!! world !!! to Seth"

Summary

Even though Dart is a object oriented, class based, single inheritance language with interfaces, developers can be quite productive and happy using only functions. In fact, if a developer never wants to see a class, they will still find Dart useful and interesting.

Dart supports simple functions with optional and named parameters, with optional default values. Dart functions are first class objects, and can be nested inside other functions.

Epilogue

Dart is not done, and has been launched as a Technology Preview in an effort to solicit early feedback from the community. Please check out this new open source structured web programming language, libraries, VM, and editor and let us know what you think. Learn more at dartlang.org and join the conversation.

The easiest way to try Dart is the browser based Dartboard, allowing you to write and run Dart code without downloading anything.

Dart's Sweet Spot is Web Apps

2011-12-04T16:21:00.001-08:00

I've been talking to different people interested in Dart, and a pattern is emerging. It's becoming more clear that Dart is appealing to application developers who are interested in building modern web apps. My theory is that Dart's adoption will accelerate most quickly from developers looking to build apps.

Bringing more apps to the web is a very good thing and is crucial for the long term success of the web. Right now, it's easy to argue that when software developers hear the word "apps" they think of mobile native apps. This is dangerous for the web, because if developer mindshare shifts away from the web as a place to deliver high fidelity and engaging application experiences, the web runs the risk of slowing its evolution and remaining stuck as a document platform.

Of course, the web has done tremendously well as a document platform. It's clearly the most successful and widely distributed information platform we've seen. To be fair, the web isn't a slouch for apps, either. Thanks to features like fast JavaScript engines, XMLHttpRequest, local storage, web workers, Canvas, and a slew of modern HTML5 APIs, the web can deliver relatively high performance applications to modern browsers.

Unfortunately, the typical application developer has a set of requirements and expectations that aren't easily answered by the web platform that we know and love today. For example, the application developer needs IDEs with powerful features like refactoring, integrated debugging, and comprehensive project visibility. The app developer also needs standard and integrated libraries, helping save time and increase commonality across projects. The app developer also needs a structured programming language, with the right mix of familiar features and unique optimizations for the platform.

The Dart effort is a comprehensive approach at addressing all of the above concerns: structured language, common libraries, optimized virtual machine, modularity, and editors. Dart is also a chance to take a fresh look at the web platform and build an integrated ecosystem without some of the baggage that has built up over the past 15 years or so.

While I believe that some of the web's current designers and developers will take to Dart (and certainly ActionScript developers will find much to like), I don't think web pages and web sites are the current sweet spot for Dart. It's becoming more and more clear that Dart's sweet spot is modern web apps.

The Dart team is working hard to make it easy and exciting for the app developer to build modern web apps. It's no wonder that app developers on other platforms are taking an interest in Dart, for they can see the parallels between their current environments and Dart.

Epilogue

Dart is open source and is currently in Technology Preview, so now is the perfect time to check it out and suggest features and direction. The team and mailing list are friendly, so don't be shy. You can try Dart without installing anything, with (what else?) a browser based app.

Variables and Optional Types in Dart

2011-11-29T19:57:00.001-08:00

Update: Reworked some of the optional types section based on comments.

Intro

Dart is a structured web programming language, complete with libraries, a virtual machine, and an editor. Dart is designed to help developers create more complex and feature rich apps for the modern web.

In this post, we look at variables and their types in Dart.

Variables

The most simple example declares a variable without an explicit type:

main() {
  var msg = 'hello';
  print(msg);
}

> hello

The most common way to declare a variable is to use the var keyword. This is truly a variable, as shown here:

main() {
  var msg = 'hello';
  msg = 'world';
  print(msg);
}

> world

final

So far, this is a lot like JavaScript. Let's see what Dart can do differently. Dart allows you to mark variables as final.

main() {
  final msg = 'hello';
  msg = 'world';  // ERROR: cannot assign value to final variable
  print(msg);
}

This all looks simple, but let's reflect on what we've seen. In the above examples, there are no classes. While Dart supports classes, single inheritance, and interfaces, they are not required to write Dart code. Plenty of Dart code is written with minimal or zero classes.

static

Having said that, we're going to introduce a class to illustrate the next concept.

class Bar {
  static x = 4;
}

main() {
  print(Bar.x);
}

> 4

In Dart, variables can also be static to a class. Like in Java, a static variable is associated to the class and not the instance. Notice how, in the above example, we don't need an instance of the Bar class in order to access the x variable.

A common pattern is to make static variables final, usually to declare enumerations or human readable names for codes.

class States {
  static final ON = 1;
  static final OFF = 0;
}

main() {
  print(States.ON);
}

> 1

We will cover classes in depth in a future blog post.

Privacy

Dart has two levels of privacy for its variables: public and private to its library. We will cover how private works when we introduce libraries in another blog post. For now, everything you see is public.

You might see variables with names prefixed with underscore like _foo. The underscore marks the variable as private to the library it was declared in. More on this soon.

Optional Types

All the variables so far have not declared a type. Dart supports optional typing, and treats type declarationss basically like annotations for tools and documentation. Type declarations do not affect the running code.

To start, let's look at a simple untyped example:

multiply(x, factor) {
  return x * factor;
}

main() {
  print( multiply(4, 2) );
}

> 8

This of course works, but imagine importing this code into your project. It would be helpful to know what exactly you can pass to the multiply method, giving tools the option to help you or get warnings earlier. So we can add types:

multiply(num x, num factor) {
  return x * factor;
}

main() {
  print( multiply(4, 2) );
}

// 8

Now the expectations of multiply are more clear, and with more clarity comes easier collaboration with larger teams and more useful tools. We can even catch errors earlier. Consider this code:

multiply(num x, num factor) {
  return x * factor;
}

main() {
  print( multiply(4, "hello") ); // WARNING at this line, string isn't assignable to num
}

> NaN // because you can't multiple a string with a number

With the types specified, we can see a warning at the line with the problem. If we didn't have the types specified in multiply, we would still get an error, but we wouldn't get the early warning.

Remember, though, that while types are great annotations for tools and teams, the type declarations don't affect running code.

For example, consider this wacky code:

main() {
  num msg = 'hello'; // WARNING: String is not assignable to num
  print(msg);
}

> hello  // still runs!

We've replaced the var keyword with the num type declaration. We also did a crazy and assigned a string to what we declared was a number. In more traditional languages, this would have stopped the program in its tracks. However, for Dart, a warning can be reported by the compiler but the program runs just fine.

Does this mean that Dart can run any program no matter how messed up it is? Of course not, if you write code that makes no sense, it will fail to run:

main() {
  num x = "hello";
  x = x / 2; // NoSuchMethodException
  print(x);
}

What's important to remember is that if you write code that can run, it will run, even if the type declarations aren't correct.

To language purists, this sounds awful, for how can you have a programming language with an unsound type system!?!?! Back in the real world, though, we encounter languages with unexpressive type systems everywhere. Every time you perform a cast in your favorite language, you are expressing something your type system can't handle.

Dart is a fan of optional types because they reduce programmer friction. Also important to remember, the web programmer is very much used to a dynamic type system, so forcing static mandatory types in a language bound for the web would hinder adoption.

Types aren't just ephemeral concepts, though. Running Dart programs actually do know what the types of its variables are. For example:

main() {
  print(4 is String);        // false
  print("hello" is String);  // true
  print(4 is Dynamic);       // true
  print(4 is num);           // true

  var x = 1;
  print(x is Dynamic);       // true
  print(x is num);           // true
}

The is check is not affected by the declared types, instead it is checking what the type of the variable actually is.

As you can see in the above code, variables always appear as Dynamic, in order to interoperate with code that did not specify its types. The var keyword is shorthand for the Dynamic type, aka the unknown type.

Built-in types

Dart provides Object as the super type. You'll also find:

Dynamic (used when no static type is provided)
String
bool
num

int
double

Collection

List
Set

Map
others...

Summary

Dart supports variables with optional typing, defaulting to the Dynamic type if no static type annotation is declared. Variables can be marked as final, which means its value cannot be altered. Classes themselves can have variables if they are marked as static.

Dart's optional typing means the program will run with or without declared types, and even if the type declarations are incorrect. Dart variables and objects have types at runtime, however.

Next Steps

Learn about functions in Dart.

Why Dart Excites Me

2011-11-27T21:08:00.001-08:00

Intro

Dart, the new open source structured web programming language currently in technology preview, is making me excited about web programming again. I'm watching it closely, fully understanding it's extremely early in the game to make any predictions. However, at least I can say I'm hopeful that there's a team out there attacking the very real problem of "not enough complex and full featured web apps" by working on an a language/libraries/VM option for modern web apps.

My background

I am a Java developer in a past life, where I grew to love the rich libraries, composable and modular applications, helpful tools, and refactoring techniques. I am a web developer at heart, with a true love for browser based client side web apps. This dichotomy was a bit of an uneasy fit, as part of me wanted a language with more structure (enabling tooling and modularity), and the other part of me wanted the insanely quick iterations of web development and the native-to-the-browser experience.

Dart really strikes a chord with me as it seems like it can be a development environment that answers to both desires: structured development and web development. I can build modular, structured web apps which are assisted by tools while still targeting the browser for modern web apps.

Just the pure fact that I can refactor my web app is enough to get me to pay attention.

How does Dart help?

Dart has a familiar syntax to any Java or JavaScript developer. I know some people wanted Dart to be an esoteric and unique language, but Dart was built for mass adoption. It needed to be accessible by the average app developer.

Dart is a class based, single inheritance, language with interfaces and libraries. You can build a structured web app and compose it in a standard and well defined way. Most of those patterns and practices you learned in other class based languages are available to you. Perhaps best of all, the libraries built by one developer are accessible to another developer in a standard way. It's important to point out that classes are essentially optional, as Dart supports bare functions.

Dart is single threaded, but supports concurrency through isolates. This means Dart avoids the complexity of multi-threaded languages, yet can take advantage of ever prevalent multiple core machines. Isolates are inspired by Erlang actors.

Dart is optionally typed, perhaps the most contentious design decision. Understanding the constraints under which Dart is developed makes it clear why this is the right choice. Dart needs to compile to JavaScript and needs to be accessible to the millions upon millions of JavaScript developers. Forcing a type system, which would almost certainly be unsound anyway, introduces friction for the developer and the JavaScript compiler. However, types are very useful as annotations to tools, e.g. to allow refactoring, and for documenting libraries and interfaces. The types don't affect the running program, which is why they are optional.

Dart can start fast, due to snapshots. A Dart app's heap can be snapshotted and sent over the wire, significantly reducing application startup time. A browser, for instance, doesn't have to re-parse the application's code on page reload or startup.

Dart is batteries included, delivering much more than just a language. The Dart effort is a full attempt at making web developers more productive. The Dart ecosystem is working on a language, libraries, concurrency, a virtual machine, an editor, a documentation tool, a compiler to JavaScript, and even a UI framework. These are coordinated efforts, intended to address developer productivity from many different angles.

Dart is novel, introduces fun concepts like "classes are interfaces", isolate based concurrency, named constructors, factory constructors, and of course optional types.

Dart fixes the DOM with a Dart friendly DOM library that feels natural and refreshing. The Dart team has created a new HTML library for adding events, finding elements, adding elements, that takes advantage of Dart's syntax.

Dart is built by smart people. The team is lead by Lars Bak, who lead the V8 JavaScript VM team and previously worked on the HotSpot VM machine for Sun. The language spec is lead by Gilad Bracha, who previously worked on the Java Language Spec. Other team members have worked on different languages, virtual machines, web browsers, and development environments. This is a focused team with a serious drive to make web developers more productive.

How to get started

Dart is currently (as of 2011-11) in "technology preview", but you can play with it today. I recommend these steps:

Read the Technical Overview
Download the Dart Editor
Read about the new DOM libraries for Dart
Write some sample code
Send feedback to the mailing list
Subscribe to the News and Updates Atom feed and follow @dart_lang
Write more code
Send more feedback
Repeat!

Summary

As a software engineer with exposure to many different languages and environments, Dart seems to hit a sweet spot for me. Dart is what I want to build my modern, structured web applications: a class based, single inheritance language with interfaces, optional typing, just enough sugar, and isolates based concurrency. Dart is a "batteries included" effort, aiming to deliver a language, libraries, editor, and virtual machine. Dart's ultimate goal is to help modern web developers more productive and deliver bigger and better web applications.

I am excited because Dart is an effort to make "programming in the large" easier for both structured and unstructured developers across the entire web. Anything that tries to make the modern web compelling for modern apps is exciting to me.

Resources

If you are interested in building modern web apps for modern browsers, and are looking for a more structured "batteries included" ecosystem, now is the time to look at Dart. It's early in the game, so your feedback has the chance to make an impact. Here's how you get started:

The official Dart website - hosting the library reference, language spec, articles, etc
The Dart editor - start with this tool
Dart articles - good for getting perspective
Dart presentations - slides from talks and presentations
Transcript of a Quick Tour of Dart - talk by Gilad Bracha
Dart Watch - Dart blog
Dart News - G+ stream of all things Dart
Dartboard - try writing Dart code in the browser, no downloads required!
Dart Mailing List - general Dart discussion. Post your feedback here.

Transcription of A Quick Tour of Dart by Gilad Bracha

2011-11-13T22:50:00.001-08:00

On November 2nd, 2011, Gilad Bracha gave a talk at Stanford University titled "A Walk on the Dart Side: A Quick Tour of Dart". I transcribed nearly all of the video so you can more easily skim and study the material. Thanks to Dart News for pushing to YouTube. Learn more about the Dart language.

(disclaimer, I did my best to capture what was said, any errors are my own)

We’re talking about dart. It’s a new language we’re working on at Google. It’s really not my work. I joined the team the 3 months ago, but this project has been running for about a year. I’ve just started to contribute to this in any way I can. Overall, it’s the work of the Dart team, which is a fairly significant team.
At 50,000 ft, the overall summary is that it’s a language for programming the web. What is special about the web? In principle there’s nothing special about the web, but in practice there’s a lot that’s special about the web. And we’ve had an arguably had a regression in terms of tooling and the overall environment that we use to program the web applications in the browser. The fact is that making a significant application that runs in the browser that is competitive with what are considered good applications that are written natively is a very very challenging thing. This happens once in a while but it’s much harder and people jump through a lot of hoops. We want to make it easier.
There are two really tough constraints on this design. One is that there are a lot of people out there programming the web, not necessarily all Stanford grads or Google employees. We want something that is essentially on-site familiar to them, because we’re interested in adoption. I’ve been involved in languages that got adoption, but I’ve also been involved in languages that are more fun but got no adoption. We want this to be unsurprising to the mainstream programmer. We have another constraint in that it must effeciently compile to JavaScript. Which constraint is harder I’ll leave up to you. They are fairly challenging constraints, really. Look at everything that comes in the light of these two constraints.
The actually technical summary of what Dart is: an object oriented, optionally typed, class based, single inheritance language with actor-based concurrency of some form. So you can yawn now and say, “What’s so special about that, that’s done a lot of times before.” Largely that’s true, though some of these things haven’t hit the mainstream yet in very wide usages. We hope to do our part to bring our technologies to a very wide audience. The one thing that’s a bit unusual is this business about optionally typed. It’s also gotten people all fired up because there’s nothing better than a good religious argument about typing to keep people interested. The only thing better is to argue about syntax, which is even more fun!
Optional types are probably the main thing I’ll be talking about. I’ll also be talking about supporting abstract data types without types or dynamically typed languages as it were, which is slightly interesting, and built-in factory support. All of things are what’s modestly new in Dart that hasn’t been as widely circulated as the rest, by and large. The language is designed as I said to be familiar and unsurprising.
Optional types. What do we mean? First of all, a bit of terminology. Optional types as opposed to mandatory types. Mandatory types are the types you know and love or hate as the case may be in most “statically typed” programming languages. The idea is that the type’s are required, and a legal program has to pass the type checker, otherwise it can’t compile and it can’t run. There are many examples of that: . By no means intending to disparage them, they have a philosophy about types. But you can read the color scheme as “leaving the tyranny of type theory behind and into the sun lit plains of the wild west and optional typing.” Depending on your religion, of course. :)
So, we don’t want this (mandatory types). Both for our own experience, I’ve worked with both statically typed and dynamically typed languages and I have a preference but much more important the web is already used to dynamically typed languages. For better or for worse, you can argue about it but that’s where our demographic is.
Brief history of non-mandatory types: there’s been many many years on this idea. Many people want to have the advantage of static typing but don’t want the disadvantages. I’m not doing an academic talk so not spending a lot of time on prior work, but here are some examples: Common Lisp, Scheme, Cecil, Erlang, Strongtalk, BabyJ. As usual, it’s all been done first in Lisp, I’m not even going to contest that. The Scheme people did an approach called soft typing, perhaps the most academic work. Strongtalk was a language I was involved with many years ago, worked with Lars Bak, who is perhaps the father of Dart, as it were. Strongtalk was significant perhaps more for the engineering work done, which eventually became the precursor to HotSpot. It had lots of other innovations at the time, including an optional type system. The one that I’m interested in, of course, is the one I worked on (Strongtalk). Of course, how could it be different. :) I some ways it’s the precursor to the work we’re doing on Dart.
Optional Types: The idea of optional types as we see them is A) of course they are syntactically optional, Everyone gets that. The important thing is that they don’t affect the run-time semantics. This is a surprisingly difficult thing to grasp, because every language that does have mandatory types somehow or another the actual run-time behavior starts to depend on what those types were. Which is very different from say a lambda calculus where the thing works just fine with or without, or works better without, the types. Types don’t change anything. They tell you something might be a problem but they don’t change the reduction rules or anything. So we’re more in that spirit.
What does it look like? (shows Point example on Dartboard) This is Dart running in the browser. It should be fairly obvious what this thing does. It has instance variables X and Y. It has an overloaded plus operator that let’s you add points. There’s a main function which is the entry point. This is a completely dynamically typed program, you’ll notice that there aren’t any types here. There are constructors that are creating Points, and you can notice some sugar here with immediately taking args and assigning them to the corresponding fields. We can run this program and sure enough it runs. What’s unusual is we can start to put in types here (changes var to num). Nothing has really changed, and now we have a partially typed program. It doesn’t matter how many types we put in, it works the same. These things (the types) are annotations. Our purpose with types is largely documentation for the humans who read the programs and for the tools that inspect the program. People love name completion and various features like that in the development environment, and it’s a lot easier to provide those features if we provide the machine with this information. And we’re not hung up if that particular information is right or wrong, which is the strange thing. So if for example I was to say this (some point) was a string, which is nonsense, it can still do it. (runs program, it works!) You don’t know how quite evil this gets. (changes return type of scale to be string. program runs but generates one warning) Changing the types here doesn’t change the semantics, and that’s on purpose. The idea here is that we have a large body of programmers who haven’t seen a type in their life and are in no hurry to meet one. They should be able to ignore typing all together. On the other hand, we should be able to give people some meaningful messages about errors, name completion, so there’s positive value with these declarations. From my experience, most of the value is in having the documentation as opposed to the common approach of saying it’s great for detecting errors. A good programming environment will detect these errors early on. I don’t generally believe the assertion that there’s a difference in robustness in these languages.
Mandatory Types: pros. So far you’ve seen it’s a very vanilla looking language, except for this strange business of the types that give you messages but don’t actually stop the program from running. The order of importance for mandatory types: machine checkable docs, types provide conceptual framework, early error detection, and performance advantages. Never the less, we’re now at a point where we can get good performance from completely untyped code, and for the kinds of applications we’re seeing on the web, it’s not particularly critical. Early error detection is what everyone talks about, but it’s not entirely crucial. What is crucial is machine checkable docs. Types also give you a useful mental framework. These are the things that are actually important to us.
Mandatory Types: Cons. What’s less talked about is the downsides of types. This usually deteriorates to a religious war of one kind or another. There are things that you find difficult to express with a particular type system. If you build a type system that lets you express that, it’s lovely but the system is some complex that only a few logicians are comfortable dealing with it. There are many people that are quite happy to live in a world that a given type system provides them, but we’re not among those. I can give a few examples that would be handy to do engineering wise that are difficult to express. Another issue is that type languages tend to impose a work flow, they tend to make you work in a certain order. For example, “things are missing, things are undeclared, things are inconsistent and please make them consistent before you proceed.” On the other hand, we find it’s much more fun to work with something that is less constrained. Starting with old “read eval print” loop, to environments where you run something, the debugger pops up, and then you fill in the missing method. You build your program from the outside in. You can write a test, there’s nothing there, it immediately crashes, and it doesn’t immediately force you to go back to the beginning. It lets you incrementally interactively build your program. People who have worked with these environments get addicted to them, and people who haven’t don’t seem to get it. We don’t want a language that imposes a work flow. There is an issue with the birttleness of mandatory typing. There is an overwhelming temptation to rely on it for everything, for security, for optimization, and the experience I had on the Java platform where everything relies on that thin layer of typing and that thing collapses and it doesn’t actually work. That’s a different talk, but the point is that there are downsides to traditional typing.
Optional Types: Can we have our Cacke and Eat it Too? Optional types are a kind of “have your cake and eat it too” approach, at least to some degree. We get the documentation, and we admit that the documentation might not actually be correct because we are no longer necessarily in a position to prove it. We still get the conceptual framework, and we often do get the early error detection (and again not fully guaranteed). Sometimes we can even squeeze from performance from these things because sometimes it easier to prove something given these annotations than to infer them and try to optimize. That’s really very much attenuated and not our focus.
Optional Types Precludes... There are a lot of things you can’t do with optional types, there are certain language constructs you can’t have. For example, type based overloading in Java (what you actually call depends on the static types that you wrote). We can’t decide how things should be initialized based on the type information. For example, you can’t just write “int i” and we can’t initialize it to zero for you. We can’t do typed classes, like Haskell, one of the few examples of a construct that I’d want to have if I had types. Most of the others I’m very happy to dispense with. It is a sort of austere discipline.
So what’s actually new? So at this point, somebody might ask, “Ok, this is fine, but what’s actually new? Didn’t you do this 18 years ago?” To a degree we did, but not many people paid attention. There’s always a gap between research/startups and hitting the mainstream and we think we’re ready for the mainstream.
Type Assertion Support. This is really a type assertion system. We support a mode where we can use these modes to drive assertions in what we call “checked mode” so we can find out dynamically if some of these assertions are being violated. This is a very pragmatic thing, something we didn’t have before. This is really the way to think about this. The other thing is, for various reasons, the type system is deliberately unsound. This of course drives some people to high levels of anger, but they just need to view this as something else. This is not a conventional static type system.
Dart Types at Runtime. Checked mode lets you interpret type annotations as adding assertions. T x = o ======> assert(o === null || o is T) This is intended for development, not production because it’s too expensive. Every time you transfer a value, pass a parameter, assign, return from a method, we do this check. This is handy for the developer because we localize the error quickly.
(goes back to the point example, turns on checked mode in Dartboard, generated a “failed type check”) We’re driving this more by ergonomics than mathematical logic. As a practical matter, we’re not building this as a traditional type system. This is a tool in the service of a programmer and what works heuristically in practice most of the time in a dynamically typed language is what we’re concerned with rather than some abstract notion of mathematical correctness. Which btw you never get out of a type system anyway (you get a very partial notion of correctness). One finds that in these common situations that casting goes on. Remember the main audience is not used to casting, and will not fight this beast.
Not your grandfather’s type system. It’s not a type system at all, rather a static analysis tool based on heuristics, coupled to a type assertion mechanism.
What about a real, sound, type system? You can write a tool that will scream bloody murder about these things, but what you can’t do is stop people from running their programs.
Runtime independent of type system. Traditionally, the kinds of types you can check depend on the types you created, but I find that the opposite which is what your program does depends on the type annotations is perverse. Decoupling the two means we can have the type system evolve independently of the language. If someone adds a new way to check types, we don’t have to rejigger everything because the execution engine doesn’t care.
What about type inference? This question comes up a lot. People are very lazy, they hate typing stuff. They would like the system to do this for them and figure out what the types are. I’m happy for tools to do this, I’m not happy for the language to do this. What types you can infer depend on what types you have, but making the type system that you have depend on what you can infer means your type system won’t be good at certain things. We don’t want to restrict things.
Don’t get boxed in. Execution -> Type checking -> Type inference. Where do you want to live? We’re trying to be very very forgiving.
Interfaces. Interfaces are roughly what you would expect from Java. What’s different is that the type system works exclusively with interfaces. There are no types that tell you something is a particular implementation. Every class implicitly induces an interface, we use this to type check. Interfaces are reified at runtime. We use “is” which is like “instanceof”. You can implement the interface of another class without subclassing it. You may not want its code or implementation, but you want to easily write mocks to test it for example. This is what’s good about OO, IMO, in that you only depend on the externally visible interface, and as long as you can fake that behavior you can produce any kind of thing, whether that’s a proxy or a mock for testing.
Generics. I can’t really give a talk about types without my long and tourtured history with generics. I’ve done generics several times, and maybe eventually we’ll get it right, who knows. (shows a simple generic collection, checking List<String>() is List<Object>, etc) This is one of the places that we and the theologians have parted company, because this is an unsound type system. List of string for our purposes is a List of object. Covarient generics, this is well known to be logically wrong. We can afford to have a rule that isn’t correct, because it’s a dynamic and pointer safe language. That means that in some cases we won’t be able to give you absolutely correct assurances about your program, but it also means we won’t have a programmer scratching his head over “what does contravarience mean?” So yes, a List<String> is a List<Object>, a List<Object> is NOT a List<String>, a List<String> is NOT a List<int>, a List<string is a List, and a List is a List<String>. These last two are interesting. What does it mean? It means that List is a list of Dynamic, which basically means “I don’t care about the type”. By covariance, because Dynamic happens to be a supertype of everything, a List<String> is a List of Dynamic. It isn’t necessarily safe, but we only want to present errors when we are very sure of errors, and only with relatively ground and concrete entities. We don’t want people reasoning about higher order things. So a List<String> is a List. Explain this to a guy on the street. If you can’t explain it at that level you have a problem. The last one is perhaps most puzzling, because you can certainly argue that not every List is a List<String> , but practicality has this nasty habit of introducing. We expect to have a lot of libraries with fully typed interfaces, we think that it’s a good thing, it gives people documentation. However what shall the programmer do when they pass a List without a particular type to a function that require a List<String> ? They will probably find out it requires strings and they will produce a List that contains strings. That’s generics in a nutshell. We’re trying something new.
Optional Types and Reified Types. So you might ask, “you’re reifying these types. we actually have these type parameters for generics represented, so they do seem to affect something being executed. We reify the type arguments to constructors, and we also reify the interfaces, but they are optional. Under the covers we pass this magical Dynamic type and it’s accessed at runtime. BTW I have to emphasize that this is very early in the game. This is by no means a product, this a a very early stage of development and we put it out there for people to comments and complain and experiment and so forth.
Summary: Optional Types. There is a static checker that provides warnings, there are no type errors and it is tuned to be unobtrusive. That is, it doesn’t try to catch every possible error. The types don’t affect the semantics. During development you can view this as a special kind of debugging mode where you can turn on these assertions.
But is it Dynamic? (question from the audience, unable to decypher) Programming without types is not bad coding. (from audience: I’m not saying you should have types. But if you have types, using them correctly would seem like a wise move.) That’s a wide spread opinion among a lot of smart people. We disagree. (audience: so it’s OK to write bad code.) I don’t think it’s bad code. I think that getting in people’s way when they are developing is a bad idea, because that encourages bad code. (audience: nobody would disagree with that.) Obviously, that’s why we’re doing this. We’re not imposing a workflow on people, we’re not imposing a static discipline that will inherently always means that some things cannot be effectively expressed. It’s a question of what these annotations are. Every practical language has holes in its type system, whether it’s a cast. We are building a system for people that would otherwise use JavaScript build programs gradually, if they feel types are valuable to them, they can use them, but they don’t have to. We’re not in a position to impose it on anyone, and we wouldn’t even if we could. (question from audience: is it really expense to run everything in debug mode?) Yeah. We call it checked mode, and right now it’s way more expensive. But that might change. But remember that there are programs that will run just fine even if the checked mode craps out. (question from audience: what is the intended purpose of these annotations?) The intended purpose is documentation, they give you an idea of what it’s aboute. They give your tools an idea of what it’s about. And yes it’s not a formally verified guarantee. It’s not at all about trying to guarantee correctness. The type checker will give you warning which you may care to ignore because you know something it doesn’t. We don’t prevent you from running your program. Now in a forum like this I expect to get questions like these. We also get a lot of feedback along the lines of “is it dynamic enough? Can I do all the strange wonderfully warped things that I’d like to do in a dynamically types programming language?” For example, noSuchMethod. It’s this catch all that lets you define a trap, and when a method that is not defined is called you will then, rather than throwing an exception which is the default, you have the option of writing a method that will respond to that. It will get information about what was called, what arguments, what name, and you can do all kinds of whacky things. You can for example write forwarders or proxies. Things that are bloody awkward to express in a type system. So we do support this feature because we think it’s enormously useful. There’s also the ability to do reflection, and we don’t have it yet but it will probably materialize in a couple of months at the most. So we definitely are a “dynamic” language. However we want to do it via layering. We don’t like how JavaScript, Python, etc do it. We prefer a layered approach where there is an API to do reflection, introspection.
Some Modest Innovations. Abstract Data Types without types. Dart has this notion about libraries, it’s a very simple minded notion. A library is a collection of top-level classes, interfaces, and functions. They can import each other, they can refer to each other in a mutually recursive fashion, and they act as units of encapsulation. So essentially, privacy in Dart is something that following the conventions of these communities which they are quite comfortable with, even though you might question them. Privacy is based on names. Naming and privacy are not orthogonal and I can understand the objections to that. Basically if you prefix a name with an underscore, it’s private to the library in which it appears. This has some advantages, it’s context free. Anyone looking at this code can tell it’s private without going to its definition. On the other hand it’s not so pretty that I’m constrained on the naming. But what’s really interesting is how this relates to the interface based types system. (showing a code example on the slide)
Factories. This is kind of nice. Constructors have well known problems. Constructors have failure of abstraction. With a classical constructor you are saying you want a new thing allocated. The problem is you don’t always want a new thing allocated. Maybe you want to look it up in a cache. Maybe you want to allocate it but with a different type. There are design patterns, but then people have to read the books and be more knowledgeable. So the idea is we support factory constructors, which we like to call constructors without tears. It reduces the need for things like dependency injection frameworks, not perhaps entirely. (demos example from Dartboard)
Dart is not Done. Not by any means. Every known programming construct has been proposed on the mailing list, and most of them we had already looked at. We might do them later, we’ll see how things go. Mixins? Reflection. We have a very low level framework for actors. Looking at higher level things on top of that, like erlang style pattern matching, promise pipelining? We’re experimenting. Should classes nest? Should libraries be first class? Non-nullable types? Metadata? Pluggable types? There’s all sorts of things we might do or not do. We’re trying to get feedback from the community. And that’s about everything I had for you.
Questions from audience (though hard to hear). We don’t want to over innovate. If you want adoption you can’t get too far ahead of where the wider programming public is. People who tie their performance to types have had disappointing results generally with dynamically typed languages. Optimizing performance based on types isn’t very high on the list.

Mouse Lock for HTML5 FPS games

2011-09-24T02:38:00.002-07:00

Sponsor: Register today for New Game, the conference for HTML5 game developers. Learn from Mozilla, Opera, Google, Spil, Bocoup, Mandreel, Subsonic, Gamesalad, EA, Zynga, and others at this intimate and technically rich conference. Join us for two days of content from developers building HTML5 games today. Nov 1-2, 2011 in San Francisco. Register now!

Good news, everyone! Work is progressing on the Mouse Lock API, a new JavaScript API which will allow for playable "First Person Shooter" (aka FPS) games, and other use cases, for HTML5 games.

Vince Scheib, Chrome engineer and veteran of the games development industry, has kicked off work back in June 2011 with an email to the public-webapps list. A recent update from Vince, sent in Sept 22, 2011, hints at a work in progress implementation for Chrome.

The draft specification for Mouse Lock API is available for review. It is proposed that the Web Events Working Group adopt the Mouse Lock spec.

Tracking progress for the spec is easy, with bugs available at W3C bug tracker, Chromium issue tracker, WebKit bugzilla, and the Mozilla bugzilla.

From the draft spec:

"""
The Mouse Lock API provides for input methods of applications based on the movement of the mouse, not just the absolute position of a cursor. A popular example is that of first person movement controls in three dimensional graphics applications such as games. Movement of the mouse is interpreted for rotation of the view-port, there is no limit to how far movement can go, and no mouse cursor is displayed.

Mouse Lock is related to Mouse Capture. Capture provides continued event delivery to a target element while a mouse is being dragged, but ceases when the mouse button is released. Mouse Lock differs by being persistent, not limited by screen boundaries, sending events regardless of mouse button state, hiding the cursor, and not releasing until an API call or specific release gesture by the user.
"""

Example code

x = document.getElementById("x");
x.addEventListener("click", mouseClick);
x.addEventListener("mousemove", mouseMove);

function mouseClick(e) {
    // Request that mouse be locked. 
    document.lockMouse(x);

    // If successful the mouseMove handler will continue 
    // to be called no matter how the mouse is moved.
    // The cursor will be hidden. No other elements or
    // system applications will be the target of mouse events.
}

function mouseMove(e) { 
    // .movementX/Y are valid normally as the mouse hovers
    // over an element. But when the mouse is locked the
    // mousemove event continues to fire whenever the mouse
    // moves.
    console.log(e.movementX + ", " + e.movementY); 
}

A call to lockMouse may trigger a user agent to prompt the user for permission.

Both movementX and movementY provide the change, or delta, in position of the mouse. For example, movementX would equal eNow.screenX - ePrevious.screenX.

Summary

Adding Mouse Capture to the open web platform will enable first class FPS games. Along with WebGL and Fullscreen APIs, we'll see the emergence of a new class of web connected games.

I encourage you to follow along with the issues in the bug trackers and voice your support for Mouse Capture API!

Box2D, Collision, Damage, for JavaScript

2011-09-17T23:13:00.002-07:00

Sponsor: Register today for New Game, the conference for HTML5 game developers. Learn from Mozilla, Opera, Google, Spil, Bocoup, Mandreel, Subsonic, Gamesalad, EA, Zynga, and others at this intimate and technically rich conference. Join us for two days of content from developers building HTML5 games today. Nov 1-2, 2011 in San Francisco. Register now!

After exploring Box2D and Impulses, which can make a body jump and move, we will turn our attention to detecting and dealing with body collisions.

Intro

Box2D of course knows when and how each body and fixture is contacting other bodies and fixtures, but so far we haven't reacted to these events nor done anything interesting. Luckily, there is an easy way to be notified when two bodies contact each other, when they stop contacting, and even how much impulse is felt by the bodies. We will explore these concepts in this blog post.

Can you feel it?

The b2ContactListener class from Box2D provides the four callbacks you can use to be notified of contact related events. These events are:

BeginContact - fired when two fixtures start contacting (aka touching) each other
EndContact - fired when two fixtures cease contact
PreSolve - fired before contact is resolved. you have the opportunity to override the contact here.
PostSolve - fired once the contact is resolved. the event also includes the impulse from the contact.

Note that all of the above events are fired during the world Step. This means you need to be very careful not to manipulate the world inside of these events, as the Box2D simulation isn't finished for the step, and you don't want to alter the world at this point.

EndContact can be fired outside of the Step, in the case of a body being removed from the world.

An example listener follows:

    var listener = new Box2D.Dynamics.b2ContactListener;
    listener.BeginContact = function(contact) {
        // console.log(contact.GetFixtureA().GetBody().GetUserData());
    }
    listener.EndContact = function(contact) {
        // console.log(contact.GetFixtureA().GetBody().GetUserData());
    }
    listener.PostSolve = function(contact, impulse) {
        
    }
    listener.PreSolve = function(contact, oldManifold) {

    }
    this.world.SetContactListener(listener);

Each of the events take a contact parameter, which has details of the contact, most of important are GetFixtureA() and GetFixtureB() which return the fixtures involved in the contact. From the fixtures you can reference the bodies. This implies that collisions occur between fixtures, not bodies.

How big was the impact?

You might be wondering, "Great, I see I can tell which two fixtures collided, but what was the force at the collision?" Knowing how hard or soft the collision was is important for lots of game logic.

Looking closely, you'll notice that Box2D doesn't hand you the force or impulse inside BeginContact(). You can of course calculate your own value for the magnitude of the collision, using linearVelocity and mass, both found on the body object. We might even do this in a future article.

Notice, though, that the PostSolve() method includes an impulse object, which includes an array of impulse values for the collision. This value is the easiest way to access the collision's magnitude.

If only things were so easy!

PostSolve() is called seemingly every time a body feels an impulse from another body. If object A hits object B which is connected to object C, then object C will feel the impulse from object A's initial hit (because the impulse "bumps" object B which "bumps" object C). This may or may not be what you want, depending on your game logic.

For example, if you have a ball rolling across the ground, this creates an impulse (albeit tiny) for every frame, and PostSolve() will be fired every frame. If you have other objects touching the ground, those objects will feel an impulse from the ground (which is "rumbled" by the ball rolling.)

If you are intending to calculate damage to an object from an impact, be very aware the PostSolve() event will be fired a LOT. If you are subtracting damage from an object's total "hit points" during every PostSolve() be sure you understand that your object will incur damage from basically every impulse.

You can of course create initial "hit points" high enough to withstand impulses from everywhere, or dismiss impulses below a threshold. Your needs will vary.

The important point to remember is that PostSolve() will be a called a LOT.

Example

For a simple example, I extended a previous example to add support for collisions. The below example will color objects black if they are feeling a contact (i.e. a PostSolve() event is fired) and will apply damage from the impulse.

You can view a stand alone version and see the source code.

I added a simple wrapper for the callback registration to my simple Box2D wrapper class:

bTest.prototype.addContactListener = function(callbacks) {
    var listener = new Box2D.Dynamics.b2ContactListener;
    if (callbacks.BeginContact) listener.BeginContact = function(contact) {
        callbacks.BeginContact(contact.GetFixtureA().GetBody().GetUserData(),
                               contact.GetFixtureB().GetBody().GetUserData());
    }
    if (callbacks.EndContact) listener.EndContact = function(contact) {
        callbacks.EndContact(contact.GetFixtureA().GetBody().GetUserData(),
                             contact.GetFixtureB().GetBody().GetUserData());
    }
    if (callbacks.PostSolve) listener.PostSolve = function(contact, impulse) {
        callbacks.PostSolve(contact.GetFixtureA().GetBody().GetUserData(),
                             contact.GetFixtureB().GetBody().GetUserData(),
                             impulse.normalImpulses[0]);
    }
    this.world.SetContactListener(listener);
}

I register a callback in the main page like this:

      box.addContactListener({
        BeginContact: function(idA, idB) {
        },
        
        PostSolve: function(idA, idB, impulse) {
          if (impulse < 0.1) return; // playing with thresholds
          var entityA = world[idA];
          var entityB = world[idB];
          entityA.hit(impulse, entityB);
          entityB.hit(impulse, entityA);
        }
      });

Note that the above code is not standard Box2D code, it is a simplification I've created for these demos.

I added a new method to Entity for the collision:

    Entity.prototype.hit = function(impulse, source) {
      this.isHit = true;
      if (this.strength) {
        this.strength -= impulse;
        if (this.strength <= 0) {
          this.dead = true
        }
      }
      
      //console.log(this.id + ", " + impulse + ", " + source.id + ", " + this.strength);
    }

For my purposes, entities may or may not have a strength (aka "hit points"). If my entity runs out of strength, it is "dead" and will be removed from the world:

    function update(animStart) {
      box.update();
      bodiesState = box.getState();
      
      var graveyard = [];
      
      for (var id in bodiesState) {
        var entity = world[id];
        
        if (entity && world[id].dead) {
          box.removeBody(id);
          graveyard.push(id);
        } else if (entity) {
          entity.update(bodiesState[id]);
        }
      }
      
      for (var i = 0; i < graveyard.length; i++) {
        delete world[graveyard[i]];
      }
    }

And my simple Box2D wrapper implements removeBody() as such:

bTest.prototype.removeBody = function(id) {
    this.world.DestroyBody(this.bodiesMap[id]);
}

Summary

The Box2D b2ContactListener provides four events for you to be notified when two fixtures contact/collide/touch. The PostSolve() method includes an impulse object which you can use to calculate damage or otherwise measure the intensity of the collision. However, PostSolve() is fired whenever a fixture "feels" another fixture, which means it will be fired quite a lot.

If you're at this point in your development, you'll probably notice that you're now involved with game tuning as much as raw coding. That is, with aspects like damage, the "feel" of the game now becomes quite important. It's not enough to figure out how the APIs work, you need to tune and tweak your game with quite a few "magic" values like damages, thresholds, etc.

Case in point is Angry Birds, which seems easy to copy until you start wanting to capture the essence of the game itself. That essence is wrapped up in many different small values that all add up to the "feel" of the game.

In other words... game balance is hard! :)

Next Steps

More details on Box2D contacts can be found in the Box2D manual. A Box2D collision tutorial from Alan Bishop covers PostSolve() but only deals with an instantaneous collisions and therefore doesn't run into the "PostSolve() gets called more frequently than you might think" issue. The Box2D forums feature a post on finding the maximum impulse from a collision.

Please do leave questions and comments below, and continue to let me know what else you'd like to see!

Box2D, Impulse, and JavaScript

2011-09-15T21:49:00.001-07:00

ApplyImpulse : immediately change momentum. Think being hit by a bat.
ApplyForce : change momentum over time. Think pushing something.

There's a lot of confusion over what the difference is between the two methods. If you need a quick obvious change, use ApplyImpulse. If you need to slowly change over time, use ApplyForce.

Example

The demo above has a stand alone version and the source code is available.

As you can see, we have the beginnings of an Angry Birds clone. An impulse is applied to the circle which propels it through the air, eventually crashing into innocent blocks.

The object configuration is straight forward:

    var initialState = [
      {id: "ground", x: ctx.canvas.width / 2 / SCALE, y: ctx.canvas.height / SCALE, halfHeight: 0.5, halfWidth: ctx.canvas.width / SCALE, color: 'yellow'},
      {id: "ball", x: 2, y: ctx.canvas.height / SCALE - 2, radius: 0.5},
      {id: "b1", x:17, y: ctx.canvas.height / SCALE - 1, halfHeight: 2, halfWidth: 0.10},
      {id: "b2", x:17, y: ctx.canvas.height / SCALE - 5, halfHeight: 0.25, halfWidth: 2}
    ];

Control your impulses

Both force and impulse require a vector, specifically a b2Vec2, for direction and magnitude. The following code is an easy way to create an impulse:

bTest.prototype.applyImpulse = function(bodyId, degrees, power) {
    var body = this.bodiesMap[bodyId];
    body.ApplyImpulse(new b2Vec2(Math.cos(degrees * (Math.PI / 180)) * power,
                                 Math.sin(degrees * (Math.PI / 180)) * power),
                                 body.GetWorldCenter());
}

To compute the vector for the impulse, the direction (in terms of degrees) and power (an arbitrary multiplier provided by me to test different powers) are combined.

The impulse is launched from the center of mass of the circle. The impulse can be launched from any point on the object, which creates a torque on the object.

Summary

Box2D allows you to add force and impulses to bodies. Adding an impulse is like hitting a body with a hard bat. Adding force over time is like pushing on a body.

Next Up

Please continue to follow along and learn about Box2D, Collision detection, and Damage.

Thanks for continuing to follow along. Your comments help, let me know what other topics you're looking for.

Box2D and Joints for JavaScript

2011-09-15T14:24:00.001-07:00

Sponsor: Register today for New Game, the conference for HTML5 game developers. Learn from Mozilla, Opera, Google, Spil, Bocoup, Mandreel, Subsonic, Gamesalad, EA, Zynga, and others at this intimate and technically rich conference. Join us for two days of content from developers building HTML5 games today. Nov 1-2, 2011 in San Francisco. Register now!

Intro

Previously we looked at complex bodies with multiple shapes for Box2D. Using those techniques, we learned how to build concave bodies by associating two or more shapes to a body.

Another way to build more complex objects is to bind bodies together with joints. Joints constrain bodies together, for example by restricting ranges of motion or affecting motion of one body from another. Box2D supports many different types of joints, including pullings, gears, and ropes.

Box2D 2.1a (the version we've been using for all of these tutorials and demos) supports the following joint definitions:

Distance
Friction
Gear
Line
Mouse
Prismatic
Pulley
Revolute
Weld

Box2D 2.2 (the latest at the time of this writing, yet not yet ported to JavaScript) also supports:

all of the above
Wheel
Rope

Example

Let's start with a "revolute joint" which sounds like a fancy way of saying a joint that allows two bodies to revolve around a shared point. The below screenshot shows a sloped ground with a simple two wheel object rolling down.

See the below live example:

Visit the stand alone example of wheel joints with Box2D and check out the source code.

Explanation

Joints bind two bodies. As with many of Box2D's APIs, it all begins with a definition. For example, let's look at the definition of a Revolute joint:

    var joint = new b2RevoluteJointDef();
    joint.Initialize(body1, body2, body1.GetWorldCenter());
    this.world.CreateJoint(joint);

You can see the joint works with Bodies (not shapes or fixtures). The joint is created by the Box2D world.

Really weird stuff starts to happen when the anchor point for the joint is outside the body. And by really weird, I mean doesn't work. I've used the body.GetWorldCenter() to find the center of the body for the joint to bind to.

Notice that I'm only referencing the the center of one body. This is because a revolute joint specifies a single hinge point, and it assumes that the two bodies are already in the right position.

Revolute joints are quite configurable. Some examples of options for a revolute joint are:

enableLimit - whether the joint limits will be active
lowerAngle - angle for the lower limit
upperAngle - angle for the upper limit
enableMotor - whether the joint motor will be active, defaults to false
motorSpeed - the target speed of the joint motor. Positive for counter clockwise, negative for clockwise
maxMotorTorque - the maximum allowable torque the motor can use. A torque too weak won't be able to move the bodies.

Self powered

Using the motorSpeed and the maxMotorTorque we can build a self powered car.

bTest.prototype.addRevoluteJoint = function(body1Id, body2Id, params) {
    var body1 = this.bodiesMap[body1Id];
    var body2 = this.bodiesMap[body2Id];
    var joint = new b2RevoluteJointDef();
    joint.Initialize(body1, body2, body1.GetWorldCenter());
    if (params && params.motorSpeed) {
      joint.motorSpeed = params.motorSpeed;
      joint.maxMotorTorque = params.maxMotorTorque;
      joint.enableMotor = true;
    }
    this.world.CreateJoint(joint);
}

To show off this awesome hotrod, we'll flatten the ground and let her rip!

You can control the direction of the motor with the motorSpeed. A positive motorSpeed will travel counter-clockwise and a negative speed will travel clockwise (as seen above). The maxMotorTorque needs to be high enough to actually move your bodies.

Summary

Box2D joints bind two bodies together. Box2D has numerous joints like revolute, distance, and pulleys. Many joints have attributes like motor speeds, upper and lower angle bounds, and torque.

For more information on Box2D joints, the manual has examples and explanations of all the joint types. For more information on revolute joints specifically, I found this Box2d Revolute Joints tutorial helpful.

Next Up

Add some excitement to your Box2D simulations with Impulse.

Box2D with Complex and Concave Objects, for JavaScript

2011-09-14T17:12:00.002-07:00

Previously in this Box2D for the JavaScript developer series, I covered how to build and simulate arbitrary polygons. Not entirely arbitrary, as I mentioned that you can only build convex objects. Turns out I was both right and wrong. Read on to learn how to build more complex and even concave bodies.

Example

The below screenshot has an example of a complex object. The green square + triangle is also concave.

Below is the live version:

The stand alone example for the above demo is available, as well as the source code for review.

Explanation

I'll start using more exact terminology now that we've covered the basics of getting objects onto the screen and interacting with each other. It's important to understand the specifics now that we're getting more complex.

A Body is the rigid chunk of matter.

A Shape is a geometrical object, such as a polygon, circle, square, etc. A Shape must be convex.

A Fixture binds a shape to a body.

Up to this point, we've had a one-to-one relationship between Body, Shape, and Fixture. Turns out that Box2D Bodies can have multiple shapes! If you extrapolate what that means, you can see that we can build Bodies with complex shapes.

Code

With this more specific understanding and terminology, let's use it to build complex bodies (see, I used the right term there :)

I've extended our JSON shorthand object definitions to support one or more polygons for a body. (This is non-standard Box2D code, just something I put together to make it easier to play around.)

var initialState = {"0": {id: 0, x: 10, y: 5, radius: 2},
                    "1": {id: 1, x: 5, y: 5, polys: [
                      [{x: 0, y: 0}, {x: 1, y: 0}, {x: 0, y:2}] // triangle
                    ]},
                    "2": {id: 2, x: 9, y: 4, halfHeight: 1.5, halfWidth: 0.9},
                    "3": {id: 3, x: 4.5, y: 3, polys: [
                      [{x: 0, y: -2}, {x: 2, y: 0}, {x: 0, y:2}, {x:-0.5, y: 1.5}] // odd shape
                    ]},
                    "4": {id: 4, x: 10, y: 10, polys: [
                        [{x: -1, y: -1}, {x: 1, y: -1}, {x: 1, y: 1}, {x: -1, y: 1}], // box
                        [{x: 1, y: -1.5}, {x: 2, y: 0}, {x: 1, y: 1.5}]  // arrow
                    ], color: "green"}
};

Notice the last definition has two polygon definitions. The first has four points for a box, and the second has three points for a triangle. Just like arbitrary shapes, the points are defined relative to the position of the body as specified by the x,y coordinates.

To construct the Box2D objects from the above definition, I refactored the original code a bit to handle more than one Fixture and Shape per Body.

bTest.prototype.setBodies = function(bodyEntities) {
    this.bodyDef.type = b2Body.b2_dynamicBody;
    
    for(var id in bodyEntities) {
        var entity = bodyEntities[id];
        
        this.bodyDef.position.x = entity.x;
        this.bodyDef.position.y = entity.y;
        this.bodyDef.userData = entity.id;
        var body = this.world.CreateBody(this.bodyDef);
        
        if (entity.radius) {
            this.fixDef.shape = new b2CircleShape(entity.radius);
            body.CreateFixture(this.fixDef);
        } else if (entity.polys) {
            for (var j = 0; j < entity.polys.length; j++) {
                var points = entity.polys[j];
                var vecs = [];
                for (var i = 0; i < points.length; i++) {
                    var vec = new b2Vec2();
                    vec.Set(points[i].x, points[i].y);
                    vecs[i] = vec;
                }
                this.fixDef.shape = new b2PolygonShape;
                this.fixDef.shape.SetAsArray(vecs, vecs.length);
                body.CreateFixture(this.fixDef);
            }
        } else {
            this.fixDef.shape = new b2PolygonShape;
            this.fixDef.shape.SetAsBox(entity.halfWidth, entity.halfHeight);
            body.CreateFixture(this.fixDef);
        }
    }
    this.ready = true;
}

The HTML5 Canvas code didn't change too much. As you can see below, the canvas is translated and rotated once, and then all of the shapes are drawn with a series of moveTo() and lineTo() calls.

PolygonEntity.prototype.draw = function(ctx) {
  ctx.save();
  ctx.translate(this.x * SCALE, this.y * SCALE);
  ctx.rotate(this.angle);
  ctx.translate(-(this.x) * SCALE, -(this.y) * SCALE);
  ctx.fillStyle = this.color;

  for (var i = 0; i < this.polys.length; i++) {
    var points = this.polys[i];
    ctx.beginPath();
    ctx.moveTo((this.x + points[0].x) * SCALE, (this.y + points[0].y) * SCALE);
    for (var j = 1; j < points.length; j++) {
       ctx.lineTo((points[j].x + this.x) * SCALE, (points[j].y + this.y) * SCALE);
    }
    ctx.lineTo((this.x + points[0].x) * SCALE, (this.y + points[0].y) * SCALE);
    ctx.closePath();
    ctx.fill();
    ctx.stroke();
  }

  ctx.restore();
  
  Entity.prototype.draw.call(this, ctx);
}

Summary

Box2D supports bodies with complex and even concave shapes by binding more than one Fixture and Shape to a Body.

Next Up

Did this help clear up shapes and bodies? What would you like to see next? Please leave comments below and let me know.

Box2D and Polygons for JavaScript

2011-09-14T00:53:00.000-07:00

Sponsor: Register today for New Game, the conference for HTML5 game developers. Learn from Mozilla, Opera, Google, Spil, Bocoup, Mandreel, Subsonic, Gamesalad, EA, Zynga, and others at this intimate and technically rich conference. Join us for two days of content from developers building HTML5 games today. Nov 1-2, 2011 in San Francisco. Register now!

Intro

Welcome back to another installment of Box2D for the JavaScript programmer. We will pause our exploration of running Box2D in a Web worker for a while and get back to the fundamentals. Today we look at Polygons, how to specify them, and how to render them.

The shape of things

Box2D supports both circles and squares/rectangles, and we've seen examples of both from our original Box2D Orientation article.

For quick review, specifying a circle requires the radius and the position:

this.fixDef = new b2FixtureDef;
this.fixDef.density = 1.0;
this.fixDef.friction = 0.5;
this.fixDef.restitution = 0.2;

this.bodyDef = new b2BodyDef;
this.bodyDef.type = b2Body.b2_dynamicBody;
this.fixDef.shape = new b2CircleShape(radius);

this.bodyDef.position.x = x;
this.bodyDef.position.y = y;
this.world.CreateBody(this.bodyDef).CreateFixture(this.fixDef);

Remember, the x and y coordinates are using Box2D's meters, and should not be pixels on your canvas.

Specifying a rectangle or square is fairly similar:

this.fixDef = new b2FixtureDef;
this.fixDef.density = 1.0;
this.fixDef.friction = 0.5;
this.fixDef.restitution = 0.2;

this.bodyDef = new b2BodyDef;
this.bodyDef.type = b2Body.b2_dynamicBody;
this.fixDef.shape = new b2PolygonShape;
this.fixDef.shape.SetAsBox(halfWidth, halfHeight);

this.bodyDef.position.x = x;
this.bodyDef.position.y = y;
this.world.CreateBody(this.bodyDef).CreateFixture(this.fixDef);

You can see the reference to bPolygonShape which is a hint that Box2D can simulate other types of polygons.

Constraints and definitions

What does Box2D mean by Polygon? Referring to the manual:

Polygon shapes are solid convex polygons. A polygon is convex when all line segments connecting two points in the interior do not cross any edge of the polygon. Polygons are solid and never hollow. A polygon must have 3 or more vertices.

See the below illustration for the difference between a convex and concave polygons:

You can simulate a concave polygon by binding together more than one convex polygons, and we'll look at an example of that in another article.

Out of the box (pun not intended), Box2D supports polygons with up to eight vertices.

Specification

Specifying a polygon is harder than specifying a square or rectangle, so kudus to Box2D for providing helper methods for those common cases.

The bodyDef still has a position, however with a polygon that position is not considered the center of the object. (This is different than the circle or square, so do be aware of this difference.) The position for a polygon is the point from which the vertices are relative to. For example, a vertex of 0,0 is the same as the x,y position of the polygon. A vertex of 1,1 is one unit to the right and one unit down from the x,y position of the object.

The manual will tell you that the vertices must be specified in CCW, or counter-clockwise, order for "right handed coordinate systems." However, as far as I can tell, this is the opposite of the HTML5 Canvas. When specifying your polygon coordinates for HTML5 canvas, you should specify in clockwise order. (please correct in the comments if this is wrong)

The code for a triangle polygon is as follows:

this.fixDef.density = 1.0;
this.fixDef.friction = 0.5;
this.fixDef.restitution = 0.2;

this.bodyDef = new b2BodyDef;
this.bodyDef.type = b2Body.b2_dynamicBody;
this.fixDef.shape = new b2PolygonShape;

// entity.points == [{x: 0, y: 0}, {x: 1, y: 0}, {x: 0, y:2}]
var points = [];

for (var i = 0; i < entity.points.length; i++) {
    var vec = new b2Vec2();
    vec.Set(entity.points[i].x, entity.points[i].y);
    points[i] = vec;
}

this.fixDef.shape.SetAsArray(points, points.length);

this.bodyDef.position.x = x;
this.bodyDef.position.y = y;
this.world.CreateBody(this.bodyDef).CreateFixture(this.fixDef);

The follow screenshot shows the triangle (amongst other shapes):

Drawing the polygon

Using HTML5 Canvas we can draw any Box2D polygon:

PolygonEntity.prototype.draw = function(ctx) {
  ctx.save();
  ctx.translate(this.x * SCALE, this.y * SCALE);
  ctx.rotate(this.angle);
  ctx.translate(-(this.x) * SCALE, -(this.y) * SCALE);
  ctx.fillStyle = 'red';

  ctx.beginPath();
  ctx.moveTo((this.x + this.points[0].x) * SCALE, (this.y + this.points[0].y) * SCALE);
  for (var i = 1; i < this.points.length; i++) {
     ctx.lineTo((this.points[i].x + this.x) * SCALE, (this.points[i].y + this.y) * SCALE);
  }
  ctx.lineTo((this.x + this points[0].x) * SCALE, (this.y + this.points[0].y) * SCALE);
  ctx.closePath();
  ctx.fill();
  ctx.stroke();

  ctx.restore();

  Entity.prototype.draw.call(this, ctx);
}

Notice how in the above code, we first moveTo() to the position of the object, and then draw lineTo() to the vertices of the object, and then connect the last vertex to the original position.

The only properties of the object that change are the position and the angle, the vertices remain static (as they are essentially offsets from the position).

Center of mass

Finding the center of mass for a circle or rectangle in Box2D is easy, as it's just the position (via GetPosition() on the bodyDef.) The position for a polygon is not the center of mass, more like a simple reference point for the vertices of the polygon.

Finding the "center" of a polygon requires bodyDef.GetWorldCenter(). You can see a yellow dot for the center of mass of each of the objects in the example below.

Example

The embedded example below displays the triangle, with other objects like a circle, rectangle, and a four sides polygon.

&lt;p&gt;&amp;amp;amp;amp;lt;p&amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;lt;p&amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;If you can't see the example, you can't see the iframe&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;amp;amp;amp;amp;gt;&amp;amp;amp;amp;lt;/p&amp;amp;amp;amp;gt;&lt;/p&gt;

You can check out the stand alone example for Box2D polygons. The source code is also available.

Summary

Box2D supports circles and squares and rectangles, as well as more complex polygons. The polygons must be convex, have no more than eight vertices, and the vertices must be specified in a specific order (seemingly clockwise for HTML5 canvas).

Next up is how to build and render complex bodies with Box2D, even convex bodies!

Please let me know what you think in the comments below. Thanks!