pkg/shelf: added `url` and `scriptName` named params to Request.change

pkg/shelf/lib/src/request.dart

 // Copyright (c) 2014, 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.
 
 library shelf.request;
 
 import 'dart:async';
 
 import 'package:http_parser/http_parser.dart';
 
@@ skipping 116 matching lines @@
         this.scriptName = _computeScriptName(requestedUri, url, scriptName),
         this._onHijack = onHijack == null ? null : new _OnHijack(onHijack),
         super(body == null ? new Stream.fromIterable([]) : body,
             headers: headers, context: context) {
     if (method.isEmpty) throw new ArgumentError('method cannot be empty.');
 
     if (!requestedUri.isAbsolute) {
       throw new ArgumentError('requstedUri must be an absolute URI.');
     }
 
+    // TODO(kevmoo) if defined, check that scriptName is a fully-encoded, valid
+    // path component
     if (this.scriptName.isNotEmpty && !this.scriptName.startsWith('/')) {
       throw new ArgumentError('scriptName must be empty or start with "/".');
     }
 
     if (this.scriptName == '/') {
       throw new ArgumentError(
           'scriptName can never be "/". It should be empty instead.');
     }
 
     if (this.scriptName.endsWith('/')) {
@@ skipping 14 matching lines @@
   ///
   /// New key-value pairs in [context] and [headers] will be added to the copied
   /// [Request].
   ///
   /// If [context] or [headers] includes a key that already exists, the
   /// key-value pair will replace the corresponding entry in the copied
   /// [Request].
   ///
   /// All other context and header values from the [Request] will be included
   /// in the copied [Request] unchanged.
-  Request change({Map<String, String> headers, Map<String, Object> context}) {
+  ///
+  /// If [scriptName] is provided without [url], the corresponding path
+  /// component of [Request.url] is replaced in the new instance. In this case,
+  /// [scriptName] must match the beginning of the existing `path` component of
+  /// [Request.url] or an [ArgumentError] is thrown.

[nweiz, 2014/05/22 19:50:42]

This paragraph is confusing. I suggest: "If [scriptName] is provided and [url]
is not, [scriptName] must be a prefix of [this.url]. [url] will default to
[this.url] with this prefix removed."

It would also be nice to explain the purpose of this. Maybe "This allows routing
middleware to easily mount handlers under specific URLs."

[kevmoo, 2014/05/22 20:38:36]

Done.

[nweiz, 2014/05/23 21:43:34]

You didn't include any explanation of the purpose. Was that intentional?

+  Request change({Map<String, String> headers, Map<String, Object> context,
+    String scriptName, Uri url}) {
     headers = updateMap(this.headers, headers);
     context = updateMap(this.context, context);
 
+    if (scriptName != null && url == null) {
+      var path = this.url.path;
+      if (path.startsWith(scriptName)) {
+        path = path.substring(scriptName.length);
+        url = new Uri(path: path, query: this.url.query);
+      } else {
+        throw new ArgumentError('If scriptName is provided without url, it must'
+            ' match the beginning of the existing url path.');

[nweiz, 2014/05/22 19:50:42]

"match the beginning" -> "be a prefix"

[kevmoo, 2014/05/22 20:38:36]

Done.

+      }
+    }
+
+    if (url == null) url = this.url;
+

[nweiz, 2014/05/22 19:50:42]

Nit: I'd remove this newline.

[kevmoo, 2014/05/22 20:38:36]

Done.

+    if (scriptName == null) scriptName = this.scriptName;
+
     return new Request(this.method, this.requestedUri,
-        protocolVersion: this.protocolVersion, headers: headers, url: this.url,
-        scriptName: this.scriptName, body: this.read(), context: context);
+        protocolVersion: this.protocolVersion, headers: headers, url: url,
+        scriptName: scriptName, body: this.read(), context: context);
   }
 
   /// Takes control of the underlying request socket.
   ///
   /// Synchronously, this throws a [HijackException] that indicates to the
   /// adapter that it shouldn't emit a response itself. Asynchronously,
   /// [callback] is called with a [Stream<List<int>>] and
   /// [StreamSink<List<int>>], respectively, that provide access to the
   /// underlying request socket.
   ///
@@ skipping 38 matching lines @@
 
 /// Computes `url` from the provided [Request] constructor arguments.
 ///
 /// If [url] and [scriptName] are `null`, infer value from [requestedUrl],
 /// otherwise return [url].
 ///
 /// If [url] is provided, but [scriptName] is omitted, throws an
 /// [ArgumentError].
 Uri _computeUrl(Uri requestedUri, Uri url, String scriptName) {
   if (url == null && scriptName == null) {
-    return new Uri(path: requestedUri.path, query: requestedUri.query,
-        fragment: requestedUri.fragment);
+    return new Uri(path: requestedUri.path, query: requestedUri.query);
   }
 
   if (url != null && scriptName != null) {
     if (url.scheme.isNotEmpty) throw new ArgumentError('url must be relative.');
     return url;
   }
 
   throw new ArgumentError(
       'url and scriptName must both be null or both be set.');
 }
@@ skipping 10 matching lines @@
     return '';
   }
 
   if (url != null && scriptName != null) {
     return scriptName;
   }
 
   throw new ArgumentError(
       'url and scriptName must both be null or both be set.');
 }