Pule tu aplicación de CLI

En este capítulo, darás los toques finales al paquete command_runner. Refinarás el HelpCommand para proporcionar información de uso más detallada y agregarás un argumento onOutput para un manejo de salida más flexible. Esto finaliza el paquete CommandRunner y lo prepara para su uso en escenarios más complejos.

Antes de comenzar este capítulo, asegúrate de:

• Haber completado el Capítulo 7 y tener un entorno de desarrollo de Dart en funcionamiento con el proyecto dartpedia.
• Estar familiarizado con conceptos básicos de programación como variables, funciones y flujo de control.
• Entender los conceptos de paquetes y librerías en Dart.
• Estar familiarizado con los principios de programación orientada a objetos como la herencia y las clases abstractas.

Pulirás el paquete command_runner para hacerlo más robusto y fácil de usar.

Mejora el HelpCommand para proporcionar información de uso más detallada, incluyendo opciones y sus descripciones. Esto facilitará a los usuarios entender cómo usar tu aplicación de CLI.

1. Abre el archivo command_runner/lib/src/help_command.dart.

2. Agrega imports para console.dart y exceptions.dart en la parte superior del archivo. Los necesitas para usar las extensiones de color y para lanzar una ArgumentException.

   dart

   import 'dart:async';
   ​
   import 'package:command_runner/command_runner.dart';
   ​
   import 'console.dart';
   import 'exceptions.dart';
   

   content_copy

3. Reemplaza el método run existente con el siguiente. Esta nueva versión utiliza un StringBuffer para construir eficientemente la cadena de ayuda e incluye la lógica para manejar la salida detallada (verbose).

   dart

   @override
   FutureOr<String> run(ArgResults args) async {
     final buffer = StringBuffer();
     buffer.writeln(runner.usage.titleText);
   ​
     if (args.flag('verbose')) {
       for (var cmd in runner.commands) {
         buffer.write(_renderCommandVerbose(cmd));
       }
   ​
       return buffer.toString();
     }
   ​
     if (args.hasOption('command')) {
       var (:option, :input) = args.getOption('command');
   ​
       var cmd = runner.commands.firstWhere(
         (command) => command.name == input,
         orElse: () {
           throw ArgumentException(
             'Input $input is not a known command.',
             name,
           );
         },
       );
   ​
       return _renderCommandVerbose(cmd);
     }
   ​
     // Verbose is false and no arg was passed in, so print basic usage.
     for (var command in runner.commands) {
       buffer.writeln(command.usage);
     }
   ​
     return buffer.toString();
   }
   

   content_copy

   StringBuffer es una clase de Dart que te permite construir cadenas de texto de manera eficiente. Tiene un mejor rendimiento que usar el operador +, especialmente al realizar muchas concatenaciones dentro de un bucle.

4. Agrega el método de ayuda privado _renderCommandVerbose a la clase HelpCommand. Este método da formato a la salida detallada para un solo comando.

   dart

   String _renderCommandVerbose(Command cmd) {
     final indent = ' ' * 10;
     final buffer = StringBuffer();
     buffer.writeln(cmd.usage.instructionText); //abbr, name: description
     buffer.writeln('$indent ${cmd.help}');
     if (cmd.valueHelp != null) {
       buffer.writeln(
         '$indent [Argument] Required? ${cmd.requiresArgument}, Type: ${cmd.valueHelp}, Default: ${cmd.defaultValue ?? 'none'}',
       );
     }
     buffer.writeln('$indent Options:');
     for (var option in cmd.options) {
       buffer.writeln('$indent ${option.usage}');
     }
     return buffer.toString();
   }
   

   content_copy

A continuación, agrega un argumento onOutput a CommandRunner para permitir un manejo de salida flexible.

1. Abre el archivo command_runner/lib/src/command_runner_base.dart.

2. Agrega el argumento onOutput al constructor de CommandRunner, y agrega el miembro onOutput correspondiente a la clase.

   dart

   class CommandRunner {
     CommandRunner({this.onOutput, this.onError});
   ​
     /// If not null, this method is used to handle output. Useful if you want to
     /// execute code before the output is printed to the console, or if you
     /// want to do something other than print output the console.
     /// If null, the onInput method will [print] the output.
     FutureOr<void> Function(String)? onOutput;
   ​
     FutureOr<void> Function(Object)? onError;
   ​
     // ... rest of the class
   }
   

   content_copy

3. Actualiza el método run para usar el argumento onOutput.

   dart

     Future<void> run(List<String> input) async {
       try {
         final ArgResults results = parse(input);
         if (results.command != null) {
           Object? output = await results.command!.run(results);
           if (onOutput != null) {
             await onOutput!(output.toString());
           } else {
             print(output.toString());
           }
         }
       } on Exception catch (exception) {
         if (onError != null) {
           onError!(exception);
         } else {
           rethrow;
         }
       }
     }
   

   content_copy

   Esto updates el método run para usar la función onOutput si se proporciona; de lo contrario, se imprime en la consola de forma predeterminada.

Finalmente, actualiza tu aplicación principal para usar la nueva característica onOutput.

1. Abre el archivo cli/bin/cli.dart.

2. Actualiza la función main para pasar la función onOutput a CommandRunner. También necesitarás agregar un import para console.dart para hacer disponible la función write.

   dart

   import 'package:command_runner/command_runner.dart';
   ​
   const version = '0.0.1';
   ​
   void main(List<String> arguments) {
     var commandRunner = CommandRunner(
       onOutput: (String output) async {
         await write(output);
       },
       onError: (Object error) {
         if (error is Error) {
           throw error;
         }
         if (error is Exception) {
           print(error);
         }
       },
     )..addCommand(HelpCommand());
     commandRunner.run(arguments);
   }
   

   content_copy

Prueba el HelpCommand mejorado y el callback onOutput.

1. Abre tu terminal y navega al directorio cli.

2. Ejecuta el comando dart run bin/cli.dart help --verbose.

   Deberías ver información de uso detallada para el comando help, impresa usando la función personalizada write.

En la siguiente lección, te prepararás para la parte de Wikipedia de la aplicación.