Add utility methods for sending non-form data in pkg/http.

pkg/http/lib/http.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// A composable, [Future]-based library for making HTTP requests.
 ///
 /// ## Installing ##
 ///
 /// Use [pub][] to install this package. Add the following to your
 /// `pubspec.yaml` file.
 ///
 ///     dependencies:
 ///       http: any
 ///
 /// Then run `pub install`.
 ///
 /// For more information, see the
 /// [http package on pub.dartlang.org](http://pub.dartlang.org/packages/http).
 ///
 /// The easiest way to use this library is via the top-level functions. They
 /// allow you to make individual HTTP requests with minimal hassle:
 ///
 ///     import 'package:http/http.dart' as http;
 ///
 ///     var url = "http://example.com/whatsit/create";
-///     http.post(url, fields: {"name": "doodle", "color": "blue"})
+///     http.post(url, body: {"name": "doodle", "color": "blue"})
 ///         .then((response) {
 ///       print("Response status: ${response.statusCode}");
 ///       print("Response body: ${response.body}");
 ///     });
 ///
 ///     http.read("http://example.com/foobar.txt").then(print);
 ///
 /// If you're making multiple requests to the same server, you can keep open a
 /// persistent connection by using a [Client] rather than making one-off
 /// requests. If you do this, make sure to close the client when you're done:
 ///
 ///     var client = new http.Client();
 ///     client.post(
 ///         "http://example.com/whatsit/create",
-///         fields: {"name": "doodle", "color": "blue"})
+///         body: {"name": "doodle", "color": "blue"})
 ///       .then((response) => client.get(response.bodyFields['uri']))
 ///       .then((response) => print(response.body))
 ///       .whenComplete(client.close);
 ///
 /// You can also exert more fine-grained control over your requests and
 /// responses by creating [Request] or [StreamedRequest] objects yourself and
 /// passing them to [Client.send].
 ///
 /// This package is designed to be composable. This makes it easy for external
 /// libraries to work with one another to add behavior to it. Libraries wishing
 /// to add behavior should create a subclass of [BaseClient] that wraps another
 /// [Client] and adds the desired behavior:
 ///
 ///     class UserAgentClient extends http.BaseClient {
 ///       final String userAgent;
 ///       final http.Client _inner;
 ///
 ///       UserAgentClient(this.userAgent, this._inner);
 ///
 ///       Future<StreamedResponse> send(BaseRequest request) {
 ///         request.headers[HttpHeaders.USER_AGENT] = userAgent;
 ///         return _inner.send(request);
 ///       }
 ///     }
 ///
 /// [pub]: http://pub.dartlang.org
 library http;
 
 import 'dart:async';
+import 'dart:convert';
 import 'dart:typed_data';
 
 import 'src/client.dart';
 import 'src/response.dart';
 
 export 'src/base_client.dart';
 export 'src/base_request.dart';
 export 'src/base_response.dart';
 export 'src/byte_stream.dart';
 export 'src/client.dart';
@@ skipping 19 matching lines @@
 /// be a [Uri] or a [String].
 ///
 /// This automatically initializes a new [Client] and closes that client once
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
 ///
 /// For more fine-grained control over the request, use [Request] instead.
 Future<Response> get(url, {Map<String, String> headers}) =>
   _withClient((client) => client.get(url, headers: headers));
 
-/// Sends an HTTP POST request with the given headers and fields to the given
-/// URL, which an be a [Uri] or a [String]. If any fields are specified, the
-/// content-type is automatically set to `"application/x-www-form-urlencoded"`.
+/// Sends an HTTP POST request with the given headers and body to the given URL,
+/// which can be a [Uri] or a [String].
 ///
-/// This automatically initializes a new [Client] and closes that client once
-/// the request is complete. If you're planning on making multiple requests to
-/// the same server, you should use a single [Client] for all of those requests.
+/// [body] sets the body of the request. It can be a [String], a [List<int>] or
+/// a [Map<String, String>]. If it's a String, it's encoded using [encoding] and
+/// used as the body of the request. The content-type of the request will
+/// default to "text/plain".
+///
+/// If [body] is a List, it's used as-is as the body of the request.

[Bob Nystrom, 2013/11/12 00:07:33]

Instead of "used as-is" how about clarifying that it's treated as a list of
bytes?

[nweiz, 2013/11/12 01:59:13]

Done.

+///
+/// If [body] is a Map, it's encoded as form fields using [encoding]. The
+/// content-type of the request will be set to
+/// `"application/x-www-form-urlencoded"`; this cannot be overridden.
+///
+/// [encoding] defaults to [UTF8].
 ///
 /// For more fine-grained control over the request, use [Request] or
 /// [StreamedRequest] instead.
-Future<Response> post(url,
-    {Map<String, String> headers,
-     Map<String, String> fields}) =>
-  _withClient((client) => client.post(url, headers: headers, fields: fields));
+Future<Response> post(url, {Map<String, String> headers, body,
+    Encoding encoding}) =>
+  _withClient((client) => client.post(url,
+      headers: headers, body: body, encoding: encoding));
 
-/// Sends an HTTP POST request with the given headers and fields to the given
-/// URL, which can be a [Uri] or a [String]. If any fields are specified, the
-/// content-type is automatically set to `"application/x-www-form-urlencoded"`.
+/// Sends an HTTP PUT request with the given headers and body to the given URL,
+/// which can be a [Uri] or a [String].
 ///
-/// This automatically initializes a new [Client] and closes that client once
-/// the request is complete. If you're planning on making multiple requests to
-/// the same server, you should use a single [Client] for all of those requests.
+/// [body] sets the body of the request. It can be a [String], a [List<int>] or
+/// a [Map<String, String>]. If it's a String, it's encoded using [encoding] and
+/// used as the body of the request. The content-type of the request will
+/// default to "text/plain".
+///
+/// If [body] is a List, it's used as-is as the body of the request.
+///
+/// If [body] is a Map, it's encoded as form fields using [encoding]. The
+/// content-type of the request will be set to
+/// `"application/x-www-form-urlencoded"`; this cannot be overridden.
+///
+/// [encoding] defaults to [UTF8].
 ///
 /// For more fine-grained control over the request, use [Request] or
 /// [StreamedRequest] instead.
-Future<Response> put(url,
-    {Map<String, String> headers,
-     Map<String, String> fields}) =>
-  _withClient((client) => client.put(url, headers: headers, fields: fields));
+Future<Response> put(url, {Map<String, String> headers, body,
+    Encoding encoding}) =>
+  _withClient((client) => client.put(url,
+      headers: headers, body: body, encoding: encoding));
 
 /// Sends an HTTP DELETE request with the given headers to the given URL, which
 /// can be a [Uri] or a [String].
 ///
 /// This automatically initializes a new [Client] and closes that client once
 /// the request is complete. If you're planning on making multiple requests to
 /// the same server, you should use a single [Client] for all of those requests.
 ///
 /// For more fine-grained control over the request, use [Request] instead.
 Future<Response> delete(url, {Map<String, String> headers}) =>
@@ skipping 29 matching lines @@
 /// For more fine-grained control over the request and response, use [Request]
 /// instead.
 Future<Uint8List> readBytes(url, {Map<String, String> headers}) =>
   _withClient((client) => client.readBytes(url, headers: headers));
 
 Future _withClient(Future fn(Client)) {
   var client = new Client();
   var future = fn(client);
   return future.whenComplete(client.close);
 }