formatUsage method

String formatUsage({ bool includeDescription = true, })

Formats help output for this command.

Implementation

String formatUsage({bool includeDescription = true}) {
  final buffer = StringBuffer();
  final Renderer renderer = runner is CommandRunner<T>
      ? (runner as CommandRunner<T>).renderer
      : StringRenderer(colorProfile: ColorProfile.ascii);

  String heading(String text) =>
      (Style()
            ..colorProfile = renderer.colorProfile
            ..hasDarkBackground = renderer.hasDarkBackground)
          .bold()
          .foreground(Colors.yellow)
          .render(text);
  String command(String text) =>
      (Style()
            ..colorProfile = renderer.colorProfile
            ..hasDarkBackground = renderer.hasDarkBackground)
          .foreground(Colors.green)
          .render(text);
  String formatOptionsUsage(String usage) {
    if (renderer.colorProfile == ColorProfile.ascii) return usage;
    final lines = usage.split('\n');
    final styled = <String>[];
    for (final line in lines) {
      if (line.trim().isEmpty) {
        styled.add(line);
        continue;
      }
      final match = RegExp(r'^(\s*)(.*)$').firstMatch(line);
      if (match == null) {
        styled.add(line);
        continue;
      }
      final indent = match.group(1) ?? '';
      final rest = match.group(2) ?? '';
      final split = RegExp(r'\s{2,}').firstMatch(rest);
      if (split == null) {
        styled.add(line);
        continue;
      }
      final option = rest.substring(0, split.start);
      final desc = rest.substring(split.end);
      final styledOption =
          (Style()
                ..colorProfile = renderer.colorProfile
                ..hasDarkBackground = renderer.hasDarkBackground)
              .foreground(Colors.green)
              .render(option);
      styled.add(
        '$indent$styledOption${' ' * (split.end - split.start)}$desc',
      );
    }
    return styled.join('\n');
  }

  final desc = description.trim();
  if (includeDescription && desc.isNotEmpty) {
    buffer.writeln(heading('Description:'));
    buffer.writeln('  $desc');
    buffer.writeln();
  }

  buffer.writeln(heading('Usage:'));
  buffer.writeln('  ${invocation.trim()}');
  buffer.writeln();

  buffer.writeln(heading('Options:'));
  final options = argParser.usage.trimRight();
  if (options.isEmpty) {
    buffer.writeln('  (none)');
  } else {
    buffer.writeln(indentBlock(formatOptionsUsage(options), 2));
  }

  final uniqueSubs = <args.Command<T>>{};
  final entries = <CommandListingEntry>[];
  for (final sub in subcommands.values) {
    if (!uniqueSubs.add(sub)) continue;
    if (sub.hidden) continue;
    entries.add(
      CommandListingEntry(name: sub.name, description: sub.summary),
    );
  }
  if (entries.isNotEmpty) {
    buffer.writeln();
    buffer.writeln(heading('Available commands:'));
    buffer.writeln(
      formatCommandListing(
        entries,
        namespaceSeparator: namespaceSeparator,
        styleNamespace: heading,
        styleCommand: command,
      ),
    );
  }

  return buffer.toString().trimRight();
}