Dart Cookbook

We assume that you have a working Dart environment installed on your machine. If not, go to https://www.dartlang.org/tools/download.html and choose Option 1 for your platform, which is the complete bundle. Downloading and uncompressing it will produce a folder named dart, which will contain everything you need. Put this in a directory of your choice. This could be anything, but for convenience keep it short, such as d:\dart on Windows or ~/dart on Linux. On OS X, you can just drop the directory in the App folder.

Setting the DART_SDK environment variable, for example, enables plugins such as dart-maven to search for the Dart SDK (dart-maven is a plugin that provides integration for Google Dart into a maven-build process). If the OS of your machine knows the path where the Dart tools reside, you can start any of them (such as the Dart VM or dartanalyzer) anywhere in a terminal or command-line session.

Test the environment variable by typing dart in a terminal and press Enter. You should see the following help text:

Usage: dart [<vm-flags>] <dart-script-file> [<dart-options>]

Executes the Dart script passed as <dart-script-file>

Open your app in Dart Editor and select the startup web page or Dart script, usually web\index.html.

Scripts that are started on the command line (or in a batch file) with the dart command run in the Dart VM and thus in the production mode. If you want to run the Dart VM in the checked mode, you have to explicitly state that with the following command:

dart –c script.dart or: dart --checked script.dart 

You can start Dartium (this is Chromium with the Dart VM) directly by launching the Chrome executable from dart\chromium; by default, it runs Dart Editor in the production mode. If you would like to start Dartium in the checked mode, you can do this as follows:

Verify this setting by going to the following address in the Chrome browser that you just started chromium://version.

When a web app runs in the Dart VM in Chrome, it will run in the production mode, by default.

In the checked mode, types are checked by calling assertions of the form assert (var1 is T) to make sure that var1 is of type T. This happens whenever you perform assignments, pass parameters to a function, or return results from a function.

However, Dart is a dynamic language where types are optional. That's why the VM must, in the production mode, execute your code as if the type annotations (such as int n) do not exist; they are effectively thrown away. So at runtime, the following statement int x = 1 is equivalent to var x = 1.

A binding x is created but the type annotation is not used.

With the checked mode, Dart helps you catch type errors during development. This is in contrast to the other dynamic languages, such as Python, Ruby, and JavaScript, where these are only caught during testing, or much worse, they provoke runtime exceptions. You can easily check whether your Dart app runs in the checked mode or not by calling the function isCheckedMode() from main() (see the script test_checked_mode\bin\ test_checked_mode.dart in the Chapter 1 folder of the code bundle), as shown in the following code:

main() {
  isCheckedMode();
  // your code starts here  
}

void isCheckedMode() {
    try {
        int n = '';
        throw new Exception("Checked Mode is disabled!");
    } on TypeError {
      print("Checked Mode is enabled!");
    }
}

The exception message will be shown in the browser console. Be sure to remove this call or comment it out before deploying it to the production mode; we don't want an exception at runtime!

Some of the JVM settings used by Dart Editor are stored in the DartEditor.ini file in the dart installation directory. This typically contains the following settings (on a Windows system):

-data
@user.home\DartEditor
-vmargs
-d64
-Dosgi.requiredJavaVersion=1.6
-Dfile.encoding=UTF-8
-XX:MaxPermSize=128m
-Xms256m
-Xmx2000m

If you notice strange or unwanted behavior in the editor, deleting the settings folder pointed to by –data and its subfolders can restore things to normal. This folder can be found at different locations depending on the OS; the locations are as follows:

Deleting the settings folder doesn't harm your system because a new settings folder is created as soon as you reopen Dart Editor. You will have to reload your projects though. If you want to save the old settings, you can rename the folder instead of just deleting it; this way, you can revert to the old settings if you ever want to.

The settings for data points to the DartEditor folder are in the users home directory, which contains various settings (the metadata) for the editor. Clearing all the settings removes the metadata the editor uses.

The -d64 or –d32 value specifies the bit width necessary for the JVM. You can check these settings for your installation by issuing the command java –version in a terminal session, whose output will be as follows:

java version "1.7.0_51"

Java(TM) SE Runtime Environment (build 1.7.0_51-b13)

Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)

If this does not correspond with the –d setting, make sure that your downloaded Dart Editor and the installed JVM have the same bit width, by downloading a JVM for your bit width.

If your JVM is not installed in the default location, you can add the following line to the .ini file in the line before -vmargs:

-vm
  /full/path/to/java

If you face a problem, it might be solved by upgrading Dart SDK and the Dart Editor to the latest version. In the Dart Editor menu, select Help and then About Dart Editor. If a new version is available, this will automatically download, and when done, click on Apply the update.

Follow these steps to host your own private pub mirror:

The server from https://pub.dartlang.org/ is written in Python and is made to run on Google App Engine, but it can be run from an Intranet as well.

You can download Sublime Text free of cost for evaluation, however, for continued use, a license must be purchased from http://www.sublimetext.com/.

Tim Armstrong from Google developed a Dart plugin for Sublime Text, which can be downloaded from GitHub at https://github.com/dart-lang/dart-sublime-bundle, or you can find it in the code download with this book. The easiest way to get started is to install the Package Control plugin first by following the instructions at https://sublime.wbond.net/installation#st2.

In Sublime Text, press Ctrl + Shi ft + P (Windows or Linux) or Cmd + Shift + P (OS X; this goes for all the following commands), click on Install Package to choose that option, and then click and choose Dart to install the plugin. Any Dart file you then open shows the highlighted syntax, matching brackets, and so on.

Also, click on Menu Preferences, Settings, and then on User and add the path to your dart-sdk as the first line in this JSON file:

{
"dartsdk_path": "path\to\dart-sdk",
…
}

If you want to manually install this plugin, copy the contents of the dart-sublime-bundle-master folder to a new directory named Dart in the Sublime packages directory. This directory has different locations on different OS. They are as follows:

The plugin has a number of code snippets to facilitate working with Dart, for example, typing lib expands the library statement. Other snippets include imp for import, class for a class template, method for a method template, and main for a main() function. Typing a snippet in the pop-up window after pressing Ctrl + SHIFT + P lets you see a list of all the snippets. Use Ctrl + / to (un)comment the selected code text.

The plugin has also made a build system for you. Ctrl + B will invoke the dartanalyzer and then compile the Dart code to JavaScript with the dart2js compiler, as shown in the following screenshot. Editing and saving a pubspec.yaml file will automatically invoke the pub get command.

Working in Sublime Text 2

The first option invokes the pub serve command to start a local web server invoking dart2js along its way in the checked mode. However, the compiled .dart.js file is served from the memory by the internal development web server on http://127.0.0.1:4031. This is only good for development testing.

In the second option, the generated files are written to disk in a subfolder build/web of your app. In this way, you can copy this folder to a production web server and deploy your web app to run in all the modern web browsers (you only need to deploy the .js file, not the .precompiled.js file or the .map file). However, Pub Build in Dart Editor enables the checked mode by default; use the pub build command from a console for the production mode.

The dart2js file can also be run from the command line, which is the preferred way to build non-web apps.

You can minify both the JavaScript version and the Dart version of your app.

name: test_pub
description: testing pub

transformers:
- $dart2js:
  minify: false
  checked: true

dependencies:
  js: any

dev_dependencies:
  unittest: any

dart2js --output-type=dart --minify -oapp.complete.dart app.dart

You may be interested in the following recipes in this chapter:

Chrome uses the source map file <file>.js.map generated while compiling the JavaScript code to map the Dart code to the JavaScript code in order to be able to debug it.

In this recipe, we will examine how to debug your app in the Firefox browser.

Debugging your app in JavaScript for Firefox

In Firefox, the source maps feature is not yet implemented. Use Shift + F2 to get the developer toolbar and the command line. In the top menu, you will see Debugger. Place a breakpoint and reload the file. Code execution then stops and you can inspect the value of the variables, as shown in the following screenshot:

Debugging JS in Firefox

This recipe is especially useful when you encounter the following error in your Dart console while trying to open a project in Dart Editor during the pub get phase:

Pub install fails with 'Deletion failed'

First try this; right-click on your project and select Close Folder. Then, restart the editor and open your project again. In many cases, your project will load fine. If this does not work, try the pub gun command:

The Pub\Cache subfolder contains all the packages that have been downloaded in your Dart environment. Your project contains symlinks to the projects in this cache, which sometimes go wrong, mostly on Windows. The pubspeck.lock file keeps the downloaded projects constrained to certain versions; removing this constraint can also be helpful.

Temporarily disabling the virus checker on your system can also help pub get to succeed when it fails with the virus checker on.

The following script by Richard Schmidt that downloads packages from the pub repository and unpacks it into your Dart cache may also prove to be helpful for this error, which can be found at https://github.com/hangstrap/downloadFromPub. Use it as dart downloadFromPub.dart package m.n.l.

Here, package is the package you want to install and m.n.l is the version number such as 0.8.1. You will need to build this like any other dart package, and if during this process the pub get command fails, you will have to download the package and unpack it manually; however, from then on, you should be able to use this script to work around this issue.

When pub get fails in Dart Editor, try the following on the command line to get more information on the possible reasons for the pub --trace 'upgrade' failure.

There is now also a way to condense these four steps into one command in a terminal as follows:

pub cache repair

When you're ready to deploy, minify the size of the generated JavaScript with –m or -- minify, as shown in the following command:

dart2js –m -o prorabbits.js prorabbits.dart

Using pub build on the command line minifies JavaScript by default because this command is meant for deployment.

The dart2js file utilizes a tree-shaking feature; only code that is necessary during execution is retained, that is, functions, classes, and libraries that are not called are excluded from the produced .js file. The minification process further reduces the size by replacing the names of variables, functions, and so on with shorter names and moving code around to use a few lines.

Be careful when you use reflection.

library mylib;

@MirrorsUsed(targets: 'mylib')
import 'dart:mirrors';

Use the run method to begin an external program as shown in the following code snippet, where we start Notepad on a Windows system, which shows the question to open a new file tst.txt (refer to make_system_call\bin\ make_system_call.dart):

import 'dart:io';

main() {
  // running an external program process without interaction:
  Process.run('notepad', ['tst.txt']).then((ProcessResult rs){
    print(rs.exitCode);
    print(rs.stdout);
    print(rs.stderr);
  });
}

If the process is an OS command, use the runInShell argument, as shown in the following code:

Process.run('dir',[], runInShell:true).then((ProcessResult 
rs)
{ … }

The Run command returns a Future of type ProcessResult, which you can interrogate for its exit code or any messages. The exit code is OS-specific, but usually a negative value indicates an execution problem.

Use the start method if your Dart code has to interact with the process by writing to its stdin stream or listening to its stdout stream.

To generate a script snapshot file called prorabbits from the Dart script prorabbits.dart, issue the following command:

dart --snapshot=prorabbits prorabbits.dart

Then, start the app with dart prorabbits args, where args stands for optional arguments needed by the script.

A script snapshot is the byte representation of the app's objects in the memory (more precisely in the heap of the started isolate) after it is loaded, but before it starts executing. This enables a much faster startup because the work of tokenizing and parsing the app's code was already done in the snapshot.

This recipe is intended for server apps or command-line apps. A browser with a built-in Dart VM can snapshot your web app automatically and store that in the browser cache; the next time the app is requested, it starts up way faster from its snapshot. Because a snapshot is in fact a serialized form of an object(s), this is also the way the Dart VM uses to pass objects between isolates. The folder dart/dart-sdk/bin/snapshots contains snapshots of the main Dart tools.

The Platform class provides you with information about the OS and the computer the app is executing on. It lives in dart:io, so we need to import this library.

The following script shows the use of some interesting options (refer to the code files tools\code\platform\bin\platform.dart of this chapter):

import 'dart:io';

Map env = Platform.environment;

void main() {
  print('We run from this VM: ${Platform.executable}');
// getting the OS and Dart version:
  print('Our OS is: ${Platform.operatingSystem}');
  print('We are running Dart version: ${Platform.version}');
  if (!Platform.isLinux) {
    print('We are not running on Linux here!');
  }
  // getting the number of processors:
  int noProcs = Platform.numberOfProcessors;
  print('no of processors: $noProcs');
  // getting the value of environment variables from the Map env:
  print('OS = ${env["OS"]}');
  print('HOMEDRIVE = ${env["HOMEDRIVE"]}');
  print('USERNAME = ${env["USERNAME"]}');
  print('PATH = ${env["PATH"]}');
  // getting the path to the executing Dart script:
  var path = Platform.script.path;
  print('We execute at $path');
  // on this OS we use this path separator:
  print('path separator: ${Platform.pathSeparator}');
}

When run, the above code gives the following output:

Our OS is: windows
We are running Dart version: 1.3.3 (Wed Apr 16 12:40:55 2014) on "windows_ia32"
We are not running on Linux here!
no of processors: 8
OS = Windows_NT
HOMEDRIVE = C:
USERNAME = CVO
PATH = C:\mongodb\bin;C:\MinGW\bin;...
We execute at /F:/Dartiverse/platform/bin/platform.dart
path separator: \

Most of the options are straightforward. You can get the running VM from Platform.executable. You can get the OS from Platform.operatingSystem; this can also be tested on a Boolean property such as Platform.isLinux. The Dart version can be tested with the Platform.version property. The Platform.environment option returns a nice map structure for the environment variables of your system, so you can access their values by name, for example, for a variable envVar, use var envVar = Platform.environment["envVar"].

To get the path of the executing Dart script, you can use the path property of Platform.script because the latter returns the absolute URI of the script. When building file paths in your app, you need to know how the components in a path are separated; Platform.pathSeparator gives you this information.

Don't confuse this class with Platform from dart:html, which returns information about the browser platform.