Rename Match.str to input.

sdk/lib/core/regexp.dart

 // Copyright (c) 2012, 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.
 
 part of dart.core;
 
 /**
- * [Match] contains methods to manipulate a regular expression match.
+ * [Match] contains methods to manipulate a pattern match.
  *
- * Iterables of [Match] objects are returned from [RegExp] matching methods.
+ * A [Match] or and iterable of [Match] objects are returned from [Pattern]
+ * matching methods.
  *
  * The following example finds all matches of a [RegExp] in a [String]
  * and iterates through the returned iterable of [Match] objects.
  *
  *     RegExp exp = new RegExp(r"(\w+)");
  *     String str = "Parse my string";
  *     Iterable<Match> matches = exp.allMatches(str);
  *     for (Match m in matches) {
  *       String match = m.group(0);
  *       print(match);
  *     }
  *
  * The output of the example is:
  *
  *     Parse
  *     my
  *     string
+ *
+ * Some patterns, regular expressions in particular, may record subtrings
+ * that were part of the matching. These are called "groups" in the `Match`
+ * object. Some patterns may never have any groups, and their matches always
+ * have zero [groupCount].
  */
 abstract class Match {
   /**
    * Returns the index in the string where the match starts.
    */
   int get start;
 
   /**
    * Returns the index in the string after the last character of the
    * match.
    */
   int get end;
 
   /**
-   * Returns the string matched by the given [group]. If [group] is 0,
-   * returns the match of the regular expression.
+   * Returns the string matched by the given [group].
+   *
+   * If [group] is 0, returns the match of the pattern.
+   *
+   * The result may be `null` if the pattern didn't assign a value to it
+   * as part of this match.
    */
   String group(int group);
+
+  /**
+   * Returns the string matched by the given [group].
+   *
+   * If [group] is 0, returns the match of the pattern.
+   *
+   * Short alias for [Match.group].
+   */
   String operator [](int group);
 
   /**
-   * Returns the strings matched by [groups]. The order in the
-   * returned string follows the order in [groups].
+   * Returns a list of the full match and all the captured groups.
+   *
+   * The list contains the strings returned by [group] for arguments from
+   * `0` to [groupCount] (inclusive), in that order.

[floitsch, 2013/08/28 09:34:50]

That sounds wrong.
This returns the groups requested by the argument. We should maybe rename
[groups] (the argument) to `requestedGroups`.

[Lasse Reichstein Nielsen, 2013/08/28 10:43:24]

Ack, I missed that there was an argument.
Why is there one to begin with? This seems like a highly speculative method.

    */
   List<String> groups(List<int> groups);
 
   /**
-   * Returns the number of groups in the regular expression.
+   * Returns the number of captured groups in the match.
+   *
+   * Some patterns may capture parts of the input that was used to
+   * compute the full match. This is the number of captured groups,
+   * which is also the maximal allowed argument to the [group] method.
    */
   int get groupCount;
 
   /**
-   * The string on which this matcher was computed.
+   * The string on which this match was computed.
    */
-  String get str;
+  String get input;
 
   /**
-   * The pattern used to search in [str].
+   * Deprecated alias for [input].
+   *
+   * Will be removed soon.

[floitsch, 2013/08/28 09:34:50]

If possible mark this an @deprecated so that users get editor feedback.

Agree on a date and put that date into the comment.

[Lasse Reichstein Nielsen, 2013/08/28 10:43:24]

Do we STILL have that silly declaration in _collection_dev?
Shouldn't I just write "@0" instead, it is the same thing!!!
(No, I'll never let it go :)

+   */
+  String get src;
+
+  /**
+   * The pattern used to search in [input].
    */
   Pattern get pattern;
 }
 
 
 /**
- * A class for working with regular expressions.
+ * A regular expression pattern.
+ *
+ * Regular expressions are [Pattern]s, and can as such be used to match strings
+ * or parts of strings.
  *
  * Dart regular expressions have the same syntax and semantics as
  * JavaScript regular expressions. See
  * <http://ecma-international.org/ecma-262/5.1/#sec-15.10>
  * for the specification of JavaScript regular expressions.
  *
  * [firstMatch] is the main implementation method that applies a regular
  * expression to a string and returns the first [Match]. All
  * other methods in [RegExp] can build on it.
  *
  * Use [allMatches] to look for all matches of a regular expression in
  * a string.
  *
  * The following example finds all matches of a regular expression in
  * a string.
  *
  *     RegExp exp = new RegExp(r"(\w+)");
  *     String str = "Parse my string";
  *     Iterable<Match> matches = exp.allMatches(str);
  */
 abstract class RegExp implements Pattern {
   /**
-   * Constructs a regular expression. The default implementation of a
-   * [RegExp] sets [multiLine] to false and [caseSensitive] to true.
-   * Throws a [FormatException] if [pattern] is not a valid regular
-   * exression pattern.
+   * Constructs a regular expression.
+   *
+   * Throws a [FormatException] if [source] is not valid regular
+   * expression syntax.
    */
-  external factory RegExp(String pattern, {bool multiLine: false,
-                                           bool caseSensitive: true});
+  external factory RegExp(String source, {bool multiLine: false,
+                                          bool caseSensitive: true});
 
   /**
    * Searches for the first match of the regular expression
-   * in the string [str]. Returns `null` if there is no match.
+   * in the string [input]. Returns `null` if there is no match.
    */
-  Match firstMatch(String str);
+  Match firstMatch(String input);
 
   /**
-   * Returns an iterable on the  matches of the regular
-   * expression in [str].
+   * Returns an iterable of the matches of the regular expression on [input].
    */
-  Iterable<Match> allMatches(String str);
+  Iterable<Match> allMatches(String input);
 
   /**
-   * Returns whether the regular expression has a match in the string [str].
+   * Returns whether the regular expression has a match in the string [input].
    */
-  bool hasMatch(String str);
+  bool hasMatch(String input);
 
   /**
-   * Searches for the first match of the regular expression
-   * in the string [str] and returns the matched string.
+   * Returns the first substring match of this regular expression in [input].
    */
-  String stringMatch(String str);
+  String stringMatch(String input);
 
   /**
    * The pattern of this regular expression.
    */
   String get pattern;
 
   /**
    * Whether this regular expression matches multiple lines.
+   *
+   * If the regexp does match multiple lines, the "^" and "$" characters
+   * match the beginning and end of lines. If not, the character match the
+   * beginning and end of the input.
    */
   bool get isMultiLine;
 
   /**
-   * Whether this regular expression is case insensitive.
+   * Whether this regular expression is case sensitive.
+   *
+   * If the regular expression is not case sensitive, it will match an input
+   * letter with a pattern letter even if the two letters are different case
+   * versions of the same letter.
    */
   bool get isCaseSensitive;
 }