编写命令行应用程序

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

要在 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.5.3
8 
9 # Add regular dependencies here.
10 dependencies:
11   args: ^2.5.0
12   # path: ^1.8.0
13 
14 dev_dependencies:
15   lints: ^4.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 属性访问其他值。

API 参考 为 args 库提供了详细的信息，以帮助你使用 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.5.3。页面上次更新于2024年9月16日。 查看源代码 或 报告问题。