Allow a comment in code to explicitly configure the page width.

If the code being formatted contains a comment anywhere in it like:

```
// dart format width=123
```

Then the code is formatted at that width instead of the default width.

The intent is that tools that generate code and then format it will put
this comment in the generated code. That way, the tool doesn't have to
handle the complex logic to find a surrounding analysis_options.yaml
file and get the user's project-wide page width configuration.

End users may also want to use this comment in rare cases. For example,
maybe they have a library that contains a large value of data that looks
better as a big wide table but they don't want their entire project to
have a wider page width.

Author: munificent

lib/src/front_end/comment_writer.dart

@@ -42,12 +42,29 @@ import '../comment_type.dart';
 /// written. When that [TextPiece] is output later, it will include the comments
 /// as well.
 class CommentWriter {
+  /// Regular expression that matches a format width comment like:
+  ///
+  ///     // dart format width=123
+  static final RegExp _widthCommentPattern =
+      RegExp(r'^// dart format width=(\d+)$');
+
   final LineInfo _lineInfo;
 
   /// The tokens whose preceding comments have already been taken by calls to
   /// [takeCommentsBefore()].
   final Set<Token> _takenTokens = {};
 
+  /// If we have encountered a comment that sets an explicit page width, that
+  /// width, otherwise `null`.
+  ///
+  /// The comment looks like:
+  ///
+  ///     // dart format width=123
+  ///
+  /// If there are multiple of these comments, the first one wins.
+  int? get pageWidthFromComment => _pageWidthFromComment;
+  int? _pageWidthFromComment;
+
   CommentWriter(this._lineInfo);
 
   /// Returns the comments that appear before [token].
@@ -106,6 +123,14 @@ class CommentWriter {
         if (comment == token.precedingComments) linesBefore = 2;
       }
 
+      // If this comment configures the page width, remember it.
+      if (_widthCommentPattern.firstMatch(text) case var match?
+          when _pageWidthFromComment == null) {
+        // If integer parsing fails for some reason, the returned `null`
+        // means we correctly ignore the comment.
+        _pageWidthFromComment = int.tryParse(match[1]!);
+      }
+
       CommentType type;
       if (text.startsWith('///') && !text.startsWith('////') ||
           text.startsWith('/**') && text != '/**/') {

lib/src/front_end/piece_writer.dart

@@ -399,7 +399,8 @@ class PieceWriter {
 
     var cache = SolutionCache();
     var solver = Solver(cache,
-        pageWidth: _formatter.pageWidth, leadingIndent: _formatter.indent);
+        pageWidth: _comments.pageWidthFromComment ?? _formatter.pageWidth,
+        leadingIndent: _formatter.indent);
     var solution = solver.format(rootPiece);
     var output = solution.code.build(source, _formatter.lineEnding);
 

test/tall/other/format_off.unit

@@ -193,4 +193,134 @@ main() {
   unformatted  +  code  +  // dart format on
       after +
       region;
+}
+>>> "dart format off" whitespace must match exactly.
+main() {
+  //dart format off
+  unformatted  +  code;
+  // dart format on
+
+  //   dart format off
+  unformatted  +  code;
+  // dart format on
+
+  // dart   format off
+  unformatted  +  code;
+  // dart format on
+
+  // dart format   off
+  unformatted  +  code;
+  // dart format on
+}
+<<<
+main() {
+  //dart format off
+  unformatted + code;
+  // dart format on
+
+  //   dart format off
+  unformatted + code;
+  // dart format on
+
+  // dart   format off
+  unformatted + code;
+  // dart format on
+
+  // dart format   off
+  unformatted + code;
+  // dart format on
+}
+>>> "dart format on" whitespace must match exactly.
+main() {
+  // dart format off
+  // Doesn't actually turn back on:
+  //dart format on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted  +  code;
+
+  // dart format off
+  // Doesn't actually turn back on:
+  //   dart format on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted  +  code;
+
+  // dart format off
+  // Doesn't actually turn back on:
+  // dart   format on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted  +  code;
+
+  // dart format off
+  // Doesn't actually turn back on:
+  // dart format   on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted  +  code;
+}
+<<<
+main() {
+  // dart format off
+  // Doesn't actually turn back on:
+  //dart format on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted + code;
+
+  // dart format off
+  // Doesn't actually turn back on:
+  //   dart format on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted + code;
+
+  // dart format off
+  // Doesn't actually turn back on:
+  // dart   format on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted + code;
+
+  // dart format off
+  // Doesn't actually turn back on:
+  // dart format   on
+  unformatted  +  code;
+
+  // Does now:
+  // dart format on
+  unformatted + code;
+}
+>>> Can't be doc comment.
+main() {
+  here   +   gets   +   formatted    ;
+  /// dart format off
+  here   +   does    +    too   ;
+  /// dart format on
+  and   +   here   +    does   ;
+}
+<<<
+main() {
+  here + gets + formatted;
+
+  /// dart format off
+  here + does + too;
+
+  /// dart format on
+  and + here + does;
 }

test/tall/other/format_width.unit

@@ -0,0 +1,118 @@
+40 columns                              |
+### Tests for the comment to set formatting width.
+>>> Comment sets page width.
+main() {
+  // dart format width=30
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  // dart format width=30
+  fitsUnsplitAt40 +
+      butNotAt30;
+}
+>>> Comment anywhere affects all code.
+main() {
+  fitsUnsplitAt40   +   butNotAt30;
+}
+// dart format width=30
+<<<
+main() {
+  fitsUnsplitAt40 +
+      butNotAt30;
+}
+
+// dart format width=30
+>>> If multiple comments, first one wins.
+main() {
+  // dart format width=30
+  // dart format width=60
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  // dart format width=30
+  // dart format width=60
+  fitsUnsplitAt40 +
+      butNotAt30;
+}
+>>> Does nothing if width is not an integer.
+main() {
+  // dart format width=wat
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  // dart format width=wat
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Can't have trailing text.
+main() {
+  // dart format width=30 some more text
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  // dart format width=30 some more text
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Whitespace must match exactly.
+main() {
+  //dart format width=30
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  //dart format width=30
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Whitespace must match exactly.
+main() {
+  // dart   format width=30
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  // dart   format width=30
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Whitespace must match exactly.
+main() {
+  // dart format width = 30
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  // dart format width = 30
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Can't be doc comment.
+main() {
+  /// dart format width=30
+  fitsUnsplitAt40 + butNotAt30;
+}
+<<<
+main() {
+  /// dart format width=30
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Can't be nested inside other comment.
+main() {
+  /* // dart format width=30 */
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  /* // dart format width=30 */
+  fitsUnsplitAt40 + butNotAt30;
+}
+>>> Can't be inside string literal.
+main() {
+  var c = '// dart format width=30';
+  fitsUnsplitAt40   +   butNotAt30;
+}
+<<<
+main() {
+  var c = '// dart format width=30';
+  fitsUnsplitAt40 + butNotAt30;
+}