编写命令行应用

本教程教您如何构建命令行应用，并向您展示一些小型命令行应用。这些程序使用大多数命令行应用需要的资源，包括标准输出、错误和输入流、命令行参数、文件和目录等。

要在 Dart VM 中运行命令行应用，请使用 dart run。dart 命令包含在 Dart SDK 中。

让我们运行一个小程序。

1. 创建一个名为 hello_world.dart 的文件，其中包含以下代码

   dart

   void main() {
     print('Hello, World!');
   }

2. 在包含您刚刚创建的文件的目录中，运行该程序

   $ dart run hello_world.dart
   Hello, World!

Dart 工具支持许多命令和选项。使用 dart --help 查看常用命令和选项。使用 dart --verbose 查看所有选项。

本教程涵盖了一个名为 dcat 的小型示例应用的详细信息，该应用显示命令行上列出的任何文件的内容。此应用使用命令行应用可用的各种类、函数和属性。继续本教程以了解应用的每个部分以及使用的各种 API。

import 'dart:convert';
import 'dart:io';

import 'package:args/args.dart';

const lineNumber = 'line-number';

void main(List<String> arguments) {
  exitCode = 0; // Presume success
  final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n');

  ArgResults argResults = parser.parse(arguments);
  final paths = argResults.rest;

  dcat(paths, showLineNumbers: argResults[lineNumber] as bool);
}

Future<void> dcat(List<String> paths, {bool showLineNumbers = false}) async {
  if (paths.isEmpty) {
    // No files provided as arguments. Read from stdin and print each line.
    await stdin.pipe(stdout);
  } else {
    for (final path in paths) {
      var lineNumber = 1;
      final lines = utf8.decoder
          .bind(File(path).openRead())
          .transform(const LineSplitter());
      try {
        await for (final line in lines) {
          if (showLineNumbers) {
            stdout.write('${lineNumber++} ');
          }
          stdout.writeln(line);
        }
      } catch (_) {
        await _handleError(path);
      }
    }
  }
}

Future<void> _handleError(String path) async {
  if (await FileSystemEntity.isDirectory(path)) {
    stderr.writeln('error: $path is a directory');
  } else {
    exitCode = 2;
  }
}

您可能会注意到 dcat 依赖于一个名为 args 的包。要获取 args 包，请使用pub 包管理器。

一个真正的应用程序有测试、许可证文件、依赖项文件、示例等等。但是，对于第一个应用，我们可以使用dart create命令轻松地仅创建必要的内容。

1. 在一个目录中，使用 dart 工具创建 dcat 应用。

   $ dart create dcat

2. 更改到创建的目录。

   $ cd dcat

3. 在 dcat 目录中，使用dart pub add添加 args 包作为依赖项。这会将 args 添加到 pubspec.yaml 文件中找到的依赖项列表中。

   $ dart pub add args

4. 打开 bin/dcat.dart 文件，并将前面的代码复制到其中。

有了应用的依赖项后，您可以从命令行在任何文本文件上运行该应用，例如 pubspec.yaml

$ dart run bin/dcat.dart -n pubspec.yaml
1 name: dcat
2 description: A sample command-line application.
3 version: 1.0.0
4 # repository: https://github.com/my_org/my_repo
5 
6 environment:
7   sdk: ^3.6.0
8 
9 # Add regular dependencies here.
10 dependencies:
11   args: ^2.5.0
12   # path: ^1.8.0
13 
14 dev_dependencies:
15   lints: ^5.0.0
16   test: ^1.24.0

此命令显示指定文件的每一行。因为您指定了 -n 选项，所以每行之前都会显示一个行号。

args 包为将命令行参数转换为一组选项、标志和其他值提供了解析器支持。按如下方式导入包的args 库

import 'package:args/args.dart';

args 库包含以下类（包括其他类）

dcat 应用中的以下代码使用这些类来解析和存储指定的命令行参数

void main(List<String> arguments) {
  exitCode = 0; // Presume success
  final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n');

  ArgResults argResults = parser.parse(arguments);
  final paths = argResults.rest;

  dcat(paths, showLineNumbers: argResults[lineNumber] as bool);
}

Dart 运行时将命令行参数作为字符串列表传递给应用的 main 函数。ArgParser 配置为解析 -n 选项。然后，解析命令行参数的结果存储在 argResults 中。

下图显示了上面使用的 dcat 命令行是如何解析为 ArgResults 对象的。

您可以通过名称访问标志和选项，将 ArgResults 视为 Map。您可以使用 rest 属性访问其他值。

args 库的API 参考提供了详细信息，以帮助您使用 ArgParser 和 ArgResults 类。

与其他语言一样，Dart 具有标准输出、标准错误和标准输入流。标准 I/O 流在 dart:io 库的顶层定义

按如下方式导入 dart:io 库

import 'dart:io';

dcat 应用中的以下代码将行号写入 stdout（如果指定了 -n 选项），然后写入文件中行的内容。

if (showLineNumbers) {
  stdout.write('${lineNumber++} ');
}
stdout.writeln(line);

write() 和 writeln() 方法采用任何类型的对象，将其转换为字符串并打印出来。writeln() 方法还会打印一个换行符。dcat 应用使用 write() 方法打印行号，以便行号和文本出现在同一行上。

您还可以使用 writeAll() 方法打印对象列表，或使用 addStream() 异步打印流中的所有元素。

stdout 提供的功能比 print() 函数更多。例如，您可以使用 stdout 显示流的内容。但是，对于在 Web 上运行的应用，您必须使用 print() 而不是 stdout。

使用 stderr 将错误消息写入控制台。标准错误流与 stdout 具有相同的方法，并且您以相同的方式使用它。尽管 stdout 和 stderr 都打印到控制台，但它们的输出是分开的，可以在命令行或以编程方式重定向或管道传输到不同的目标。

如果用户尝试输出目录而不是文件的行，dcat 应用中的以下代码会打印一条错误消息。

if (await FileSystemEntity.isDirectory(path)) {
  stderr.writeln('error: $path is a directory');
} else {
  exitCode = 2;
}

标准输入流通常从键盘同步读取数据，尽管它可以异步读取并从另一个程序的标准输出管道输入。

这是一个小程序，可以从 stdin 读取单行数据。

import 'dart:io';

void main() {
  stdout.writeln('Type something');
  final input = stdin.readLineSync();
  stdout.writeln('You typed: $input');
}

readLineSync() 方法从标准输入流读取文本，会阻塞程序，直到用户输入文本并按下回车键。这个小程序会打印出输入的文本。

在 dcat 应用中，如果用户在命令行没有提供文件名，程序会使用 pipe() 方法从 stdin 读取数据。因为 pipe() 是异步的（返回一个 Future，即使这段代码没有使用返回值），调用它的代码使用了 await。

await stdin.pipe(stdout);

在这种情况下，用户输入文本行，应用会将它们复制到 stdout。用户通过按下 Control+D（在 Windows 上是 Control+Z）来表示输入结束。

$ dart run bin/dcat.dart
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.

dart:io 库中的 FileSystemEntity 类提供了属性和静态方法，帮助你检查和操作文件系统。

例如，如果你有一个路径，你可以使用 FileSystemEntity 类的 type() 方法来确定该路径是文件、目录、链接还是未找到。由于 type() 方法访问文件系统，因此它会异步执行检查。

以下来自 dcat 应用的代码使用 FileSystemEntity 来确定命令行提供的路径是否为目录。返回的 Future 会完成，并带有一个布尔值，指示该路径是否为目录。由于检查是异步的，代码使用 await 调用 isDirectory()。

if (await FileSystemEntity.isDirectory(path)) {
  stderr.writeln('error: $path is a directory');
} else {
  exitCode = 2;
}

FileSystemEntity 类中其他有趣的方法包括 isFile()、exists()、stat()、delete() 和 rename()，它们也都使用 Future 返回值。

FileSystemEntity 是 File、Directory 和 Link 类的超类。

dcat 应用使用 openRead() 方法打开命令行中列出的每个文件，该方法返回一个 Stream。 await for 代码块等待文件被异步读取和解码。当数据在流上可用时，应用程序将其打印到 stdout。

for (final path in paths) {
  var lineNumber = 1;
  final lines = utf8.decoder
      .bind(File(path).openRead())
      .transform(const LineSplitter());
  try {
    await for (final line in lines) {
      if (showLineNumbers) {
        stdout.write('${lineNumber++} ');
      }
      stdout.writeln(line);
    }
  } catch (_) {
    await _handleError(path);
  }
}

以下代码突出了其余部分，它使用了两个解码器，在数据在 await for 代码块中可用之前对其进行转换。 UTF8 解码器将数据转换为 Dart 字符串。 LineSplitter 在换行符处分割数据。

for (final path in paths) {
  var lineNumber = 1;
  final lines = utf8.decoder
      .bind(File(path).openRead())
      .transform(const LineSplitter());
  try {
    await for (final line in lines) {
      if (showLineNumbers) {
        stdout.write('${lineNumber++} ');
      }
      stdout.writeln(line);
    }
  } catch (_) {
    await _handleError(path);
  }
}

dart:convert 库提供了这些以及其他数据转换器，包括一个用于 JSON 的转换器。要使用这些转换器，你需要导入 dart:convert 库

import 'dart:convert';

将文本写入文件的最简单方法是创建一个 File 对象并使用 writeAsString() 方法

final quotes = File('quotes.txt');
const stronger = 'That which does not kill us makes us stronger. -Nietzsche';

await quotes.writeAsString(stronger, mode: FileMode.append);

writeAsString() 方法异步写入数据。它在写入之前打开文件，并在完成后关闭文件。要将数据追加到现有文件，可以使用可选的命名参数 mode 并将其值设置为 FileMode.append。否则，模式默认为 FileMode.write，并且文件的先前内容（如果有）将被覆盖。

如果你想写入更多数据，可以打开文件进行写入。 openWrite() 方法返回一个 IOSink，它的类型与 stdin 和 stderr 相同。当使用从 openWrite() 返回的 IOSink 时，你可以继续写入文件直到完成，此时，你必须手动关闭文件。 close() 方法是异步的，并返回一个 Future。

final quotes = File('quotes.txt').openWrite(mode: FileMode.append);

quotes.write("Don't cry because it's over, ");
quotes.writeln('smile because it happened. -Dr. Seuss');
await quotes.close();

使用 Platform 类获取有关运行你的应用程序的机器和操作系统的信息。

静态的 Platform.environment 属性在不可变的映射中提供环境变量的副本。如果你需要可变的映射（可修改的副本），可以使用 Map.of(Platform.environment)。

final envVarMap = Platform.environment;

print('PWD = ${envVarMap['PWD']}');
print('LOGNAME = ${envVarMap['LOGNAME']}');
print('PATH = ${envVarMap['PATH']}');

Platform 提供了其他有用的属性，可以提供有关机器、操作系统和当前运行的应用程序的信息。 例如

• Platform.isMacOS()
• Platform.numberOfProcessors
• Platform.script

dart:io 库定义了一个顶层属性 exitCode，你可以更改它来设置当前 Dart VM 调用的退出代码。退出代码是一个从 Dart 应用传递到父进程的数字，用于指示应用的执行的成功、失败或其他状态。

dcat 应用在 _handleError() 函数中设置退出代码，以指示执行期间发生错误。

Future<void> _handleError(String path) async {
  if (await FileSystemEntity.isDirectory(path)) {
    stderr.writeln('error: $path is a directory');
  } else {
    exitCode = 2;
  }
}

退出代码 2 表示应用程序遇到错误。

使用 exitCode 的替代方法是使用顶层 exit() 函数，它设置退出代码并立即退出应用程序。例如， _handleError() 函数可以调用 exit(2) 而不是将 exitCode 设置为 2，但是 exit() 会退出程序，并且它可能不会处理运行命令指定的所有文件。

尽管你可以使用任何数字作为退出代码，但按照惯例，下表中的代码具有以下含义

本教程介绍了一些在 dart:io 库的以下类中找到的基本 API

此外，本教程还介绍了 package:args 中的两个类，它们有助于解析和使用命令行参数： ArgParser 和 ArgResults。

有关更多类、函数和属性，请查阅 dart:io、 dart:convert 和 package:args 的 API 文档。

有关命令行应用程序的另一个示例，请查看 command_line 示例。

如果你对服务器端编程感兴趣，请查看下一个教程。

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2024-12-11。 查看源代码 或者报告问题。