add support to ignore ansi sequences when formatting usage display. Fixes #879

pkgs/args/CHANGELOG.md

@@ -1,4 +1,4 @@
-## 2.8.0
+## 2.8.0-wip
 
 * Allow designating a top-level command or a subcommand as a default one by
   passing `isDefault: true` to `addCommand` or `addSubcommand`.
@@ -8,15 +8,14 @@
   (Fixes #103).
 * Remove sorting of the subcommands in usage output. Ordering will depend on the
   order that `addSubCommand` is called.
-
-## 2.7.0
-
 * Remove sorting of the `allowedHelp` argument in usage output. Ordering will
   depend on key order for the passed `Map`.
 * Fix the repository URL in `pubspec.yaml`.
 * Added option `hideNegatedUsage` to `ArgParser.flag()` allowing a flag to be
   `negatable` without showing it in the usage text.
 * Fixed #101, adding check for mandatory when using `.option()`.
+* Fix usage column formatting to calculate correct string lengths when there are
+  ANSI coloring/styling escape sequences present
 
 ## 2.6.0
 

pkgs/args/example/arg_parser/ansi_example.dart

@@ -0,0 +1,190 @@
+// 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.
+
+/// This is an example of converting the args in test.dart to use this API.
+/// It shows what it looks like to build an [ArgParser] and then, when the code
+/// is run, demonstrates what the generated usage text looks like.
+library;
+
+import 'dart:io';
+
+import 'package:args/args.dart';
+import 'package:io/ansi.dart';
+
+void main() {
+  var parser = ArgParser();
+
+  parser.addSeparator('===== Platform');
+
+  final javaScriptStyled = styleItalic.wrap(lightGreen.wrap('JavaScript'));
+
+  parser.addOption('compiler',
+      abbr: 'c',
+      defaultsTo: 'none',
+      help: blue.wrap('Specify any compilation step (if needed).'),
+      allowed: [
+        'none',
+        'dart2js',
+        'dartc'
+      ],
+      allowedHelp: {
+        'none':
+            red.wrap('Do not compile the Dart code (run native Dart code on the'
+                ' VM).\n(only valid with the following runtimes: vm, drt)')!,
+        'dart2js': green
+            .wrap('Compile dart code to $javaScriptStyled by running dart2js.\n'
+                '(only valid with the following runtimes: d8, drt, chrome\n'
+                'safari, ie, firefox, opera, none (compile only))')!,
+        'dartc': lightBlue
+            .wrap('Perform static analysis on Dart code by running dartc.\n'
+                '(only valid with the following runtimes: none)')!,
+      });
+
+  parser.addOption('runtime',
+      abbr: 'r',
+      defaultsTo: 'vm',
+      help: magenta.wrap('Where the tests should be run.'),
+      allowed: [
+        'vm',
+        'd8',
+        'drt',
+        'dartium',
+        'ff',
+        'firefox',
+        'chrome',
+        'safari',
+        'ie',
+        'opera',
+        'none'
+      ],
+      allowedHelp: {
+        'vm': cyan.wrap('Run Dart code on the standalone dart vm.')!,
+        'd8': yellow
+            .wrap('Run $javaScriptStyled from the command line using v8.')!,
+        'drt': lightGreen.wrap(
+            'Run Dart or $javaScriptStyled in the headless version of Chrome,\n'
+            'content shell.')!,
+        'dartium': lightBlue.wrap('Run Dart or $javaScriptStyled in Dartium.')!,
+        'ff': lightRed.wrap('Run $javaScriptStyled in Firefox')!,
+        'chrome': yellow.wrap('Run $javaScriptStyled in Chrome')!,
+        'safari': magenta.wrap('Run $javaScriptStyled in Safari')!,
+        'ie': cyan.wrap('Run $javaScriptStyled in Internet Explorer')!,
+        'opera': lightYellow.wrap('Run $javaScriptStyled in Opera')!,
+        'none': darkGray.wrap(
+            'No runtime, compile only (for example, used for dartc static\n'
+            'analysis tests).')!,
+      });
+
+  parser.addOption('arch',
+      abbr: 'a',
+      defaultsTo: 'ia32',
+      help: cyan.wrap('The architecture to run tests for'),
+      allowed: ['all', 'ia32', 'x64', 'simarm']);
+
+  parser.addOption('system',
+      abbr: 's',
+      defaultsTo: Platform.operatingSystem,
+      help: yellow.wrap('The operating system to run tests on'),
+      allowed: ['linux', 'macos', 'windows']);
+
+  parser.addSeparator('===== Runtime');
+
+  parser.addOption('mode',
+      abbr: 'm',
+      defaultsTo: 'debug',
+      help: lightMagenta.wrap('Mode in which to run the tests'),
+      allowed: ['all', 'debug', 'release']);
+
+  parser.addFlag('checked',
+      defaultsTo: false, help: lightGreen.wrap('Run tests in checked mode'));
+
+  parser.addFlag('host-checked',
+      defaultsTo: false, help: red.wrap('Run compiler in checked mode'));
+
+  parser.addOption('timeout',
+      abbr: 't', help: white.wrap('Timeout in seconds'));
+
+  parser.addOption('tasks',
+      abbr: 'j',
+      defaultsTo: Platform.numberOfProcessors.toString(),
+      help: backgroundWhite
+          .wrap(blue.wrap('The number of parallel tasks to run')));
+
+  parser.addOption('shards',
+      defaultsTo: '1',
+      help: green
+          .wrap('The number of instances that the tests will be sharded over'));
+
+  parser.addOption('shard',
+      defaultsTo: '1',
+      help: lightYellow
+          .wrap('The index of this instance when running in sharded mode'));
+
+  parser.addFlag('valgrind',
+      defaultsTo: false, help: lightRed.wrap('Run tests through valgrind'));
+
+  parser.addSeparator('===== Output');
+
+  parser.addOption('progress',
+      abbr: 'p',
+      defaultsTo: 'compact',
+      help: lightBlue.wrap('Progress indication mode'),
+      allowed: [
+        'compact',
+        'color',
+        'line',
+        'verbose',
+        'silent',
+        'status',
+        'buildbot'
+      ]);
+
+  parser.addFlag('report',
+      defaultsTo: false,
+      help: lightMagenta.wrap(
+          'Print a summary report of the number of tests, by expectation'));
+
+  parser.addFlag('verbose',
+      abbr: 'v', defaultsTo: false, help: red.wrap('Verbose output'));
+
+  parser.addFlag('list',
+      defaultsTo: false, help: blue.wrap('List tests only, do not run them'));
+
+  parser.addFlag('time',
+      help: green.wrap('Print timings information after running tests'),
+      defaultsTo: false);
+
+  parser.addFlag('batch',
+      abbr: 'b',
+      help: blue.wrap('Run browser tests in batch mode'),
+      defaultsTo: true);
+
+  parser.addSeparator('===== Miscellaneous');
+
+  parser.addFlag('keep-generated-tests',
+      defaultsTo: false,
+      help: lightBlue
+          .wrap('Keep the generated files in the temporary directory'));
+
+  parser.addOption('special-command', help: lightMagenta.wrap("""
+Special command support. Wraps the command line in
+a special command. The special command should contain
+an '@' character which will be replaced by the normal
+command.
+
+For example if the normal command that will be executed
+is 'dart file.dart' and you specify special command
+'python -u valgrind.py @ suffix' the final command will be
+'python -u valgrind.py dart file.dart suffix'"""));
+
+  parser.addOption('dart', help: yellow.wrap('Path to dart executable'));
+  parser.addOption('drt',
+      help: lightMagenta.wrap('Path to content shell executable'));
+  parser.addOption('dartium',
+      help: lightCyan.wrap('Path to Dartium Chrome executable'));
+  parser.addOption('mandatory',
+      help: magenta.wrap('A mandatory option'), mandatory: true);
+
+  print(parser.usage);
+}

pkgs/args/example/arg_parser/pubspec.yaml

@@ -4,7 +4,7 @@
 
 name: arg_parser_example
 version: 1.0.0
-description: An example of using ArgParser
+description: An example of using ArgParser (and companion example using ANSI colors)
 publish_to: 'none'
 
 environment:
@@ -13,3 +13,4 @@ environment:
 dependencies:
   args:
     path: ../..
+  io: ^1.0.0

pkgs/args/lib/command_runner.dart

@@ -549,7 +549,8 @@ String _getCommandUsage(Map<String, Command> commands,
       var lines = wrapTextAsLines(defaultMarker + command.summary,
           start: columnStart, length: lineLength);
       buffer.writeln();
-      buffer.write('  ${padRight(command.name, length)}   ${lines.first}');
+      buffer.write(
+          '  ${command.name.padRightIgnoreAnsi(length)}   ${lines.first}');
 
       for (var line in lines.skip(1)) {
         buffer.writeln();

pkgs/args/lib/src/usage.dart

@@ -149,16 +149,19 @@ class _Usage {
       if (option.hide) continue;
 
       // Make room in the first column if there are abbreviations.
-      abbr = math.max(abbr, _abbreviation(option).length);
+      abbr = math.max(abbr, _abbreviation(option).lengthWithoutAnsi);
 
       // Make room for the option.
       title = math.max(
-          title, _longOption(option).length + _mandatoryOption(option).length);
+          title,
+          _longOption(option).lengthWithoutAnsi +
+              _mandatoryOption(option).lengthWithoutAnsi);
 
       // Make room for the allowed help.
       if (option.allowedHelp != null) {
         for (var allowed in option.allowedHelp!.keys) {
-          title = math.max(title, _allowedTitle(option, allowed).length);
+          title =
+              math.max(title, _allowedTitle(option, allowed).lengthWithoutAnsi);
         }
       }
     }
@@ -218,7 +221,7 @@ class _Usage {
 
     if (column < _columnWidths.length) {
       // Fixed-size column, so pad it.
-      _buffer.write(text.padRight(_columnWidths[column]));
+      _buffer.write(text.padRightIgnoreAnsi(_columnWidths[column]));
     } else {
       // The last column, so just write it.
       _buffer.write(text);

pkgs/args/lib/src/utils.dart

@@ -3,9 +3,39 @@
 // BSD-style license that can be found in the LICENSE file.
 import 'dart:math' as math;
 
-/// Pads [source] to [length] by adding spaces at the end.
-String padRight(String source, int length) =>
-    source + ' ' * (length - source.length);
+/// ANSI code stripping and length calculation without ANSI codes.
+extension AnsiStringExtension on String {
+  /// Matches the Control Sequence Introducer (CSI) ANSI escape sequences.
+  ///
+  /// Structure based on ECMA-48:
+  /// * `\x1b`: The literal ESC character (ASCII 27, U+001B).
+  /// * `\[`: The literal `[` character (together with the ESC, this starts the CSI).
+  /// * `[\x30-\x3f]*`: Parameter bytes (`0-9:;<=>?`).
+  /// * `[\x20-\x2f]*`: Intermediate bytes (`!"#$%&'()*+,-./`).
+  /// * `[\x40-\x7e]`: Final byte (`@A-Z[\]^_`a-z{|}~`).
+  static final RegExp _ansiRegExp =
+      RegExp(r'\x1b\[[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]');
+
+  /// Combined length of all ANSI escape sequences in the string.
+  int get ansiLength {
+    return _ansiRegExp
+        .allMatches(this)
+        .fold(0, (sum, match) => sum + match[0]!.length);
+  }
+
+  /// Length of the string without ANSI escape sequences.
+  int get lengthWithoutAnsi => length - ansiLength;
+
+  /// String with all ANSI escape sequences removed.
+  String get withoutAnsi => replaceAll(_ansiRegExp, '');
+
+  /// Whether this string contains any ANSI escape sequences.
+  bool get containsAnsi => _ansiRegExp.hasMatch(this);
+
+  /// Pads this string to [length] by adding spaces at the end, ignoring
+  /// ANSI escape sequences when calculating the current length.
+  String padRightIgnoreAnsi(int length) => padRight(length + ansiLength);
+}
 
 /// Wraps a block of text into lines no longer than [length].
 ///

pkgs/args/pubspec.yaml

@@ -1,5 +1,5 @@
 name: args
-version: 2.8.0
+version: 2.8.0-wip
 description: >-
   Library for defining parsers for parsing raw command-line arguments into a set
   of options and values using GNU and POSIX style options.