Merge pull request #2 from dart-lang/master

Update upstream

Author: butlermatt

AUTHORS

@@ -0,0 +1,9 @@
+# Below is a list of people and organizations that have contributed
+# to the Dart www site. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google Inc.
+
+Matthew Butler <[email protected]>
+Chris Buckett <[email protected]>

LICENSE

@@ -0,0 +1,30 @@
+Except as otherwise noted, the content of this page is licensed under the
+Creative Commons Attribution 3.0 License [1], and code samples are licensed
+under the BSD License:
+
+Copyright 2012, the Dart project authors. All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+[1] http://creativecommons.org/licenses/by/3.0/

src/site/_includes/language-tour/classes/index.markdown

@@ -366,12 +366,14 @@ The distanceTo() method in the following sample is an
 example of an instance method.
 
 {% highlight dart %}
+#import('dart:math');
+
 class Point {
   num x, y;
   Point(this.x, this.y);
 
   num distanceTo(Point other) {
-    return Math.sqrt(((x-other.x)*(x-other.x)) + ((y-other.y)*(y-other.y)));
+    return sqrt(((x-other.x)*(x-other.x)) + ((y-other.y)*(y-other.y)));
   }
 }
 {% endhighlight %}
@@ -569,12 +571,14 @@ Static methods (class methods) do not operate on an instance, and thus
 do not have access to `this`.
 
 {% highlight dart %}
+#import('dart:math');
+
 class Point {
   num x, y;
   Point(this.x, this.y);
 
   static num distanceBetween(Point a, Point b) {
-    return Math.sqrt(((a.x-b.x)*(a.x-b.x)) + ((a.y-b.y)*(a.y-b.y)));
+    return sqrt(((a.x-b.x)*(a.x-b.x)) + ((a.y-b.y)*(a.y-b.y)));
   }
 }
 

src/site/_includes/library-tour/html.markdown

@@ -6,25 +6,25 @@ which describes the hierarchy of an HTML page).
 
 Other common uses of dart:html are manipulating styles (_CSS_),
 getting data using HTTP requests
-(_XMLHttpRequest_, or _XHR_),
+(_HttpRequest_ (previously known as XMLHttpRequest)),
 and exchanging data using [WebSockets](#html-websockets).
 
 <aside class="note" markdown="1">
 **Note:**
-HTML5 (and dart:html) have many additional APIs that this section doesn't cover.
+HTML5, and dart:html, have many additional APIs that this
+section doesn't cover.
 These APIs include background worker tasks,
 audio,
 2D and 3D graphics,
 database,
 geolocation,
 speech input,
 and more.
-XMLHttpRequest will soon be covered in this section.
+HttpRequest will soon be covered in this section.
 </aside>
 
 Only web apps can use dart:html&mdash;not command-line apps.
 
-
 ### Importing the HTML library
 
 To use the HTML library in your web app,

src/site/articles/idiomatic-dart/index.html

@@ -66,23 +66,29 @@ <h3>Named constructors</h3>
 <p>Like most dynamically-typed languages, Dart doesn't support overloading. With methods, this isn't much of a limitation because you can always use a different name, but constructors aren't so lucky. To alleviate that, Dart lets you define <em>named constructors</em>:</p>
 
 {% highlight dart %}
+#import('dart:math');
+
 class Point {
   num x, y;
   Point(this.x, this.y);
   Point.zero() : x = 0, y = 0;
   Point.polar(num theta, num radius) {
-    x = Math.cos(theta) * radius;
-    y = Math.sin(theta) * radius;
+    x = cos(theta) * radius;
+    y = sin(theta) * radius;
   }
 }
 {% endhighlight dart 0 %}
 
 <p>Here our Point class has three constructors, a normal one and two named ones. You can use them like so:</p>
 
 {% highlight dart %}
-var a = new Point(1, 2);
-var b = new Point.zero();
-var c = new Point.polar(Math.PI, 4.0);
+#import('dart:math');
+
+main() {
+  var a = new Point(1, 2);
+  var b = new Point.zero();
+  var c = new Point.polar(PI, 4.0);
+}
 {% endhighlight dart 0 %}
 
 <p>Note that we're still using <code>new</code> here when we invoke the named constructor. It isn't just a static method.</p>
@@ -255,9 +261,11 @@ <h2 id="top-level-definitions">Top-level definitions</h2>
 <p>Dart is a "pure" object-oriented language in that everything you can place in a variable is a real object (no mutant "primitives") and every object is an instance of some class. It's not a <em>dogmatic</em> OOP language though. You aren't required to place everything you define inside some class. Instead, you are free to define functions, variables, and even getters and setters at the top level if you want.</p>
 
 {% highlight dart %}
+#import('dart:math');
+
 num abs(num value) => value < 0 ? -value : value;
 
-final TWO_PI = Math.PI * 2.0;
+final TWO_PI = PI * 2.0;
 
 int get today() {
   final date = new Date.now();
@@ -267,7 +275,7 @@ <h2 id="top-level-definitions">Top-level definitions</h2>
 
 <p>Even in languages that don't require you to place everything inside a class or object, like JavaScript, it's still common to do so as a form of namespacing: top-level definitions with the same name could inadvertently collide. To address that, Dart has a library system that allows you to import definitions from other libraries with a prefix applied to disambiguate it. That means you shouldn't <em>need</em> to defensively squirrel your definitions inside classes.</p>
 
-<p>We're still exploring what this actually means for how we define libraries. Most of our code does place definitions inside classes, like Math. It's hard to tell if this is just an ingrained habit we have from other languages or a practice that's also good for Dart. This is an area we want feedback on.</p>
+<p>We're still exploring what this actually means for how we define libraries. For example, the project used to have a Math class, but we moved all functionality from that class to top-level methods inside the dart:math library.</p>
 
 <p>We do have some examples where we use top-level definitions. The first you'll run into is <code>main()</code> which is expected to be defined at the top level. If you work with the DOM, the familiar <code>document</code> and <code>window</code> "variables" are actually top-level getters in Dart.</p>
 
@@ -304,8 +312,11 @@ <h2 id="strings-and-interpolation">Strings and interpolation</h2>
   placing them inside curly braces:</p>
 
 {% highlight dart %}
-var r = 2;
-print('The area of a circle with radius $r is ${Math.PI * r * r}');
+#import('dart:math');
+main() {
+  var r = 2;
+  print('The area of a circle with radius $r is ${PI * r * r}');
+}
 {% endhighlight dart 0 %}
 
 <h2 id="operators">Operators</h2>

src/site/articles/json-web-service/index.markdown

@@ -12,7 +12,7 @@ has-permalinks: true
 _Written by Chris Buckett<br>
 April 2012_
 
-Most client-side Dart apps need a way to communicate with a server, and sending JSON via [XMLHttpRequest](https://developer.mozilla.org/en/XMLHttpRequest) is the preferred way to do this. This article discusses communicating with a server using the [XMLHttpRequest API](http://api.dartlang.org/html/XMLHttpRequest.html) from the [dart:html](http://api.dartlang.org/html.html) library and parsing JSON data using the [dart:json](http://api.dartlang.org/json.html) library. It then goes on to show how to provide strong type information about that JSON data through the use of JsonObject and Dart's interface feature.
+Most client-side Dart apps need a way to communicate with a server, and sending JSON via [XMLHttpRequest](https://developer.mozilla.org/en/XMLHttpRequest) is the preferred way to do this. This article discusses communicating with a server using the [HttpRequest API](http://api.dartlang.org/html/HttpRequest.html) from the [dart:html](http://api.dartlang.org/html.html) library and parsing JSON data using the [dart:json](http://api.dartlang.org/json.html) library. It then goes on to show how to provide strong type information about that JSON data through the use of JsonObject and Dart's interface feature.
 
 #### Contents
 
@@ -27,7 +27,7 @@ Most client-side Dart apps need a way to communicate with a server, and sending
   <li><a href="#parsing-json">Parsing JSON</a>
     <ol>
       <li><a href="#jsonobject">Introducing JsonObject</a></li>
-      <li><a href="#note-on-jsonp">A note on JSONP and XMLHttpRequest</a></li>
+      <li><a href="#note-on-jsonp">A note on JSONP and HttpRequest</a></li>
     </ol>
   </li>
   <li><a href="#summary">Summary</a></li>
@@ -54,43 +54,45 @@ The same web service accepts data on the same URL with an HTTP POST.  The web se
 
 <h2 id="connecting-to-server">Connecting to the server</h2>
 
-When communicating with a web service, use the XMLHttpRequest API from the dart:html library. XMLHttpRequest is a standard way to programmatically send and receive data to and from web servers.
+When communicating with a web service, use the HttpRequest API from the dart:html library.
+HttpRequest is a standard way to programmatically send and receive data to and from web servers.
 
 <h3 id="getting-data">Getting data from the server</h3>
 
-Get objects from the server using HTTP GET.  XMLHttpRequest provides a named constructor called getTEMPNAME that takes a URL and a callback function that's invoked when the server responds.
+Get objects from the server using HTTP GET.  HttpRequest provides a named constructor called
+<code>get</code> that takes a URL and a callback function that's invoked when the server responds.
 
 {% highlight dart %}
-getLanguageData(String languageName, onSuccess(XMLHttpRequest req)) {
+getLanguageData(String languageName, onSuccess(HttpRequest req)) {
   var url = "http://my-site.com/programming-languages/$languageName"; 
 
   // call the web server asynchronously 
-  var request = new XMLHttpRequest.getTEMPNAME(url, onSuccess);
+  var request = new HttpRequest.get(url, onSuccess);
 }
 
 // print the raw json response text from the server
-onSuccess(XMLHttpRequest req) {
+onSuccess(HttpRequest req) {
    print(req.responseText); // print the received raw JSON text
 }
 
 getLanguageData("dart", onSuccess);
 {% endhighlight %}
 
-Note: getTEMPNAME is a convenience constructor, and its name will change. The full XMLHttpRequest API is still an option for HTTP GET, if you need more control over the API.  
+Note: getTEMPNAME is a convenience constructor, and its name will change. The full HttpRequest API is still an option for HTTP GET, if you need more control over the API.  
 
 <h3 id="saving-object">Saving objects on the server</h3>
 
-To create a new object on the server, use the raw XMLHttpRequest API with the HTTP POST method.  Use the readyStateChange listener to be notified when the request is complete.  The example below calls an onSuccess function when the request is complete:
+To create a new object on the server, use the raw HttpRequest API with the HTTP POST method.  Use the readyStateChange listener to be notified when the request is complete.  The example below calls an onSuccess function when the request is complete:
 
 {% highlight dart %}
-saveLanguageData(String data, onSuccess(XMLHttpRequest req)) {
-  XMLHttpRequest req = new XMLHttpRequest(); // create a new XHR
+saveLanguageData(String data, onSuccess(HttpRequest req)) {
+  HttpRequest req = new HttpRequest(); // create a new XHR
 
   var url = "http://example.com/programming-languages/";
   req.open("POST", url); // POST to send data
 
   req.on.readyStateChange.add((Event e) {
-    if (req.readyState == XMLHttpRequest.DONE &&
+    if (req.readyState == HttpRequest.DONE &&
         (req.status == 200 || req.status == 0)) {
       onSuccess(req); // called when the POST successfully completes
     }
@@ -100,7 +102,7 @@ saveLanguageData(String data, onSuccess(XMLHttpRequest req)) {
 }
 
 // print the raw json response text from the server
-onSuccess(XMLHttpRequest req) {
+onSuccess(HttpRequest req) {
    print(req.responseText); // print the received raw JSON text
 }
 
@@ -111,7 +113,7 @@ saveLanguageData(stringData, onSuccess); // send the data to
 
 <h2 id="parsing-json">Parsing JSON</h2>
 
-Now that you have seen how XMLHttpRequest GETs data from the server back to the client, and POSTs data from the client to the server, the next step is to make use of the JSON data in the client application.
+Now that you have seen how HttpRequest GETs data from the server back to the client, and POSTs data from the client to the server, the next step is to make use of the JSON data in the client application.
 
 The dart:json library provides two static functions, JSON.parse() and JSON.stringify(). 
 
@@ -130,10 +132,10 @@ print(parsedMap["language"]); // dart
 
 JSON also works for more complex data structures, such as nested maps inside of lists.
 
-Use JSON.parse() to convert the XMLHttpRequest's response from raw text to an actual Dart object:
+Use JSON.parse() to convert the HttpRequest's response from raw text to an actual Dart object:
 
 {% highlight dart %}
-onSuccess(XMLHttpRequest req) {
+onSuccess(HttpRequest req) {
   Map data = JSON.parse(req.responseText); // parse response text
   print(data["language"]); // dart
   print(data["targets"][0]); // dartium
@@ -169,7 +171,7 @@ JsonObject uses Dart's noSuchMethod method support, which enables objects to int
 Here is an example of using JsonObject instead of a raw Map:
 
 {% highlight dart %}
-onSuccess(XMLHttpRequest req) {
+onSuccess(HttpRequest req) {
   // decode the JSON response text using JsonObject
   var data = new JsonObject.fromJsonString(req.responseText);
 
@@ -253,14 +255,14 @@ Language data = new JsonObject.fromJsonString(req.responseText);
 String json = JSON.stringify(data);  
 
 // and POST it back to the server
-XMLHttpRequest req = new XMLHttpRequest(); 
+HttpRequest req = new HttpRequest(); 
 req.open("POST", url); 
 req.send(json); 
 {% endhighlight %}
 
-<h3 id="note-on-jsonp">A note on JSONP and XMLHttpRequest</h3>
+<h3 id="note-on-jsonp">A note on JSONP and HttpRequest</h3>
 
-One caveat: Make sure your app is served from the same origin (domain name, port, and application layer protocol) as the web service you are trying to access with XMLHttpRequest. Otherwise your app will hit the Access-Control-Allow-Origin restriction.  This is a security restriction to prevent loading data from a different server than the one serving the client app.
+One caveat: Make sure your app is served from the same origin (domain name, port, and application layer protocol) as the web service you are trying to access with HttpRequest. Otherwise your app will hit the Access-Control-Allow-Origin restriction.  This is a security restriction to prevent loading data from a different server than the one serving the client app.
 
 You can get around this restriction in a couple of ways.  The first is to use an emerging technology known as [Cross-Origin Resource Sharing](https://developer.mozilla.org/en/http_access_control) (CORS), which is starting to become implemented by web servers. The second, older way is to use a workaround called JSONP, which makes use of JavaScript callbacks.  To use [JSONP with Dart](http://blog.sethladd.com/2012/03/jsonp-with-dart.html), you need to use window.postMessage to allow the JavaScript callbacks to communicate with your Dart code.
 
@@ -271,7 +273,7 @@ This article showed how a client-side Dart application communicates with a JSON-
 <h2 id="resources">Resources</h2>
 
 * [dart:json](http://api.dartlang.org/json/JSON.html)
-* [XmlHttpRequest](http://api.dartlang.org/html/XMLHttpRequest.html)
+* [HttpRequest](http://api.dartlang.org/html/HttpRequest.html)
 * [JsonObject](https://github.com/chrisbu/dartwatch-JsonObject)
 * [Using JSONP with Dart](http://blog.sethladd.com/2012/03/jsonp-with-dart.html)
 * [About access-control restrictions](https://developer.mozilla.org/en/http_access_control)

src/site/articles/mocking-with-dart/index.markdown

@@ -393,7 +393,7 @@ themselves can be `expect()`-style `Matcher`s, for example:
 {% highlight dart %}
 m.when(callsTo('sqrt', isNegative)).
   alwaysThrow('No imaginary number support');
-m.when(callsTo('sqrt', isNonNegative)).alwaysCall((x) => Math.sqrt(x));
+m.when(callsTo('sqrt', isNonNegative)).alwaysCall((x) => sqrt(x));
 {% endhighlight %}
 
 You don't need to provide argument matchers in `callsTo()` for all arguments of a method, but you do need 

src/site/articles/puzzlers/chapter-2.markdown

@@ -677,9 +677,12 @@ So the mysterious behavior is explained.
 What happens when we do a naive translation to Dart?
 
 {% highlight dart %}
+#import('dart:math');
+
 main() {
   StringBuffer word = null;
-  switch ((Math.random() * 2).toInt()) {
+  var random = new Random();
+  switch ((random.nextDouble() * 2).toInt()) {
     case 1:  word = new StringBuffer('P');
     case 2:  word = new StringBuffer('G');
     default: word = new StringBuffer('M');

src/site/articles/style-guide/index.markdown

@@ -612,8 +612,10 @@ together.
 
 <div class="good">
 {% highlight dart good %}
+#import('dart:math');
+// ...
 /* Rolls both [Dice] and returns the highest rolled value. */
-num greatestRoll(Dice a, Dice b) => Math.max(a.roll(), b.roll());
+num greatestRoll(Dice a, Dice b) => max(a.roll(), b.roll());
 {% endhighlight %}
 </div>
 

src/site/css/style.css

@@ -337,7 +337,7 @@ <h3>Using autocomplete</h3>
     <p>
     Type a class, interface, or variable name, and then type a period.
     <br />
-    For example, type <code>document.</code> or <code>Math.</code>
+    For example, type <code>document.</code>
     and pause a moment.
     Once the suggestions appear,
     continue typing to pare down the list.
@@ -348,9 +348,9 @@ <h3>Using autocomplete</h3>
     <p>
     Type <b>Ctl+Space</b>.
     <br />
-    For example, type <code>Mat</code>, then Ctl+Space
+    For example, type <code>Str</code>, then Ctl+Space
     to see a list of classes and interfaces
-    that start with "Mat".
+    that start with "Str".
     </p>
   </li>
 </ul>
@@ -410,9 +410,9 @@ <h4>Finding where an API is declared</h4>
 
     <p>
       The editor displays the file that declares the item.
-      For example, if you Command-click Math,
+      For example, if you Command-click String,
       the file that declares the
-      <a href="http://api.dartlang.org/dart_core/Math.html"><code>Math</code></a> type appears.
+      <code>String</code> type appears.
     </p>
   </li>
 </ol>