handleSpecialCommands function

SpecialCommandResult handleSpecialCommands(List<String> args, ToolDefinition tool, { void printer(String)?, String toolHelpGenerator(ToolDefinition)?, String commandHelpGenerator(ToolDefinition, CommandDefinition)?, String versionGenerator(ToolDefinition)?, })

Check for and handle special commands (help, version).

Returns SpecialCommandResult.handled if a special command was processed and the caller should exit, or SpecialCommandResult.none to continue normal argument processing.

Supports:

• tool help - Show tool help
• tool help :command - Show command help
• tool help command - Show command help (without colon)
• tool --help or tool -h - Show tool help
• tool version - Show version
• tool --version or tool -V - Show version

Parameters:

• args - Command line arguments
• tool - Tool definition for generating help
• printer - Optional custom print function (defaults to print)
• toolHelpGenerator - Optional custom function to generate tool help text
• commandHelpGenerator - Optional custom function to generate command help text
• versionGenerator - Optional custom function to generate version text

Example:

Future<void> main(List<String> args) async {
  if (handleSpecialCommands(args, myTool) == SpecialCommandResult.handled) {
    return;
  }
  // Continue normal processing...
}

Implementation

SpecialCommandResult handleSpecialCommands(
  List<String> args,
  ToolDefinition tool, {
  void Function(String)? printer,
  String Function(ToolDefinition)? toolHelpGenerator,
  String Function(ToolDefinition, CommandDefinition)? commandHelpGenerator,
  String Function(ToolDefinition)? versionGenerator,
}) {
  printer ??= print;
  toolHelpGenerator ??= generatePlainToolHelp;
  commandHelpGenerator ??= (t, c) => generatePlainCommandHelp(t, c);
  versionGenerator ??= (t) => '${t.name} v${t.version}';

  if (args.isEmpty) {
    printer(toolHelpGenerator(tool));
    return SpecialCommandResult.handled;
  }

  final first = args.first.toLowerCase();

  // Version command
  if (first == 'version' ||
      first == '--version' ||
      first == '-version' ||
      first == '-v') {
    printer(versionGenerator(tool));
    return SpecialCommandResult.handled;
  }

  // Help command
  if (first == 'help' ||
      first == '--help' ||
      first == '-help' ||
      first == '-h') {
    if (args.length > 1 && first == 'help') {
      // Command-specific help: help :command or help command or help topic
      final target = args[1];
      final cmdName = target.startsWith(':') ? target.substring(1) : target;
      // Check help topics first (they don't need : prefix)
      final topic = tool.helpTopics.cast<HelpTopic?>().firstWhere(
        (t) => t!.name == cmdName,
        orElse: () => null,
      );
      if (topic != null) {
        printer(HelpGenerator.generateTopicHelp(topic, tool: tool));
      } else {
        _printCommandHelp(tool, cmdName, printer, commandHelpGenerator);
      }
    } else {
      printer(toolHelpGenerator(tool));
    }
    return SpecialCommandResult.handled;
  }

  return SpecialCommandResult.none;
}