Rename "--line-length" option to "--page-width". (#1577)

Rename "--line-length" option to "--page-width".

The formatter has always been inconsistent about how to refer to the
limit that it tries to fit code in. The option name (which is older
than when I started working on the formatter) is "--line-length". But
the public API and all of the internal code uses "page width".

This renames that option to "--page-width". The old name is still
supported (but hidden in help) for backwards compatibility.

In practice, this option isn't used often, so this likely won't affect
many users.

Co-authored-by: Nate Bosch <[email protected]>

CHANGELOG.md

@@ -73,6 +73,16 @@
   intended to be extended or implemented. They are now all marked `final` to
   make that intention explicit.
 
+* **Rename the `--line-length` option to `--page-width`.** This is consistent
+  with the public API, internal implementation, and docs, which all use "page
+  width" to refer to the limit that the formatter tries to fit code into.
+
+  The `--line-length` name is still supported for backwards compatibility, but
+  may be removed at some point in the future. You're encouraged to move to
+  `--page-width`. Use of this option (however its named) is rare, and will
+  likely be even rarer now that project-wide configuration is supported, so
+  this shouldn't affect many users.
+
 ## 2.3.7
 
 * Allow passing a language version to `DartFomatter()`. Formatted code will be

lib/src/cli/format_command.dart

@@ -78,11 +78,18 @@ final class FormatCommand extends Command<int> {
 
     if (verbose) argParser.addSeparator('Other options:');
 
+    argParser.addOption('page-width',
+        help: 'Try to keep lines no longer than this.',
+        defaultsTo: '80',
+        hide: !verbose);
+    // This is the old name for "--page-width". We keep it for backwards
+    // compatibility but don't show it in the help output.
     argParser.addOption('line-length',
         abbr: 'l',
         help: 'Wrap lines longer than this.',
         defaultsTo: '80',
         hide: true);
+
     argParser.addOption('indent',
         abbr: 'i',
         help: 'Add this many spaces of leading indentation.',
@@ -189,11 +196,23 @@ final class FormatCommand extends Command<int> {
       }
     }
 
+    // Allow the old option name if the new one wasn't passed.
+    String? pageWidthString;
+    if (argResults.wasParsed('page-width')) {
+      pageWidthString = argResults['page-width'] as String;
+    } else if (argResults.wasParsed('line-length')) {
+      pageWidthString = argResults['line-length'] as String;
+    }
+
     int? pageWidth;
-    if (argResults.wasParsed('line-length')) {
-      pageWidth = int.tryParse(argResults['line-length'] as String) ??
-          usageException('--line-length must be an integer, was '
-              '"${argResults['line-length']}".');
+    if (pageWidthString != null) {
+      pageWidth = int.tryParse(pageWidthString);
+      if (pageWidth == null) {
+        usageException(
+            'Page width must be an integer, was "$pageWidthString".');
+      } else if (pageWidth <= 0) {
+        usageException('Page width must be a positive number, was $pageWidth.');
+      }
     }
 
     var indent = int.tryParse(argResults['indent'] as String) ??

test/cli/page_width_test.dart

@@ -12,6 +12,54 @@ import '../utils.dart';
 void main() {
   compileFormatter();
 
+  group('--page-width', () {
+    test('must be a number', () async {
+      var process = await runFormatter(['--page-width=notint']);
+      await process.shouldExit(64);
+    });
+
+    test('must be an integer', () async {
+      var process = await runFormatter(['--page-width=12.34']);
+      await process.shouldExit(64);
+    });
+
+    test('must be positive', () async {
+      var process = await runFormatter(['--page-width=-123']);
+      await process.shouldExit(64);
+
+      process = await runFormatter(['--page-width=0']);
+      await process.shouldExit(64);
+    });
+
+    test('format at given width', () async {
+      await d.dir('foo', [
+        d.file('main.dart', _unformatted),
+      ]).create();
+
+      var process = await runFormatterOnDir([
+        '--enable-experiment=tall-style',
+        '--page-width=30',
+      ]);
+      await process.shouldExit(0);
+
+      await d.dir('foo', [d.file('main.dart', _formatted30)]).validate();
+    });
+
+    test('support old --line-length option name', () async {
+      await d.dir('foo', [
+        d.file('main.dart', _unformatted),
+      ]).create();
+
+      var process = await runFormatterOnDir([
+        '--enable-experiment=tall-style',
+        '--line-length=30',
+      ]);
+      await process.shouldExit(0);
+
+      await d.dir('foo', [d.file('main.dart', _formatted30)]).validate();
+    });
+  });
+
   test('no options search if experiment is off', () async {
     await d.dir('foo', [
       analysisOptionsFile(pageWidth: 20),
@@ -33,7 +81,7 @@ void main() {
 
     var process = await runFormatterOnDir([
       '--language-version=latest', // Error to not have language version.
-      '--line-length=30',
+      '--page-width=30',
       '--enable-experiment=tall-style'
     ]);
     await process.shouldExit(0);
@@ -173,7 +221,7 @@ void main() {
       var process = await runFormatter([
         '--language-version=latest',
         '--enable-experiment=tall-style',
-        '--line-length=30',
+        '--page-width=30',
         '--stdin-name=foo/main.dart'
       ]);