Flutter插件popmark的使用方法介绍

欢迎来到popmark，这是一个简单的库，可以将嵌入在Markdown文件中的Dart代码段输出填充到文件中。这可以帮助你检查Markdown文件中的代码段是否正确运行。

安装popmark

dart pub global activate popmark

popmark基本用法

要将Markdown文件中的嵌入代码段的输出填充到文件中，我们可以运行：

popmark [目标Markdown文件]

这会让popmark搜索文件中的dart标记的代码段，执行这些代码段，并将相应的代码段输出填充到text块中。

例如，以下Dart代码段的输出是通过运行以下命令添加的：

popmark README.md

final message = 'spamtapaalesrest', cycle = 4;
for (var i = 0; i < cycle; i++) {
    final buffer = StringBuffer('  ' * i);
    for (var j = i; j < message.length; j += cycle) {
        buffer.write(' ' * cycle + message[j]);
    }
    print(buffer);
}

    s    t    a    r
      p    a    l    e
        a    p    e    s
          m    a    s    t

摘要和选项

基本用法：

popmark [文件] [选项] [标志]

--help

获取帮助。

--execute

使用--execute来标识要执行（或不执行）的代码段。例如，只执行第1个和第3个代码段，使用：

popmark target.md --execute '1,3'

要执行除第1个和第3个代码段外的所有代码段，可以使用星号：

popmark target.md --execute '*1,3'

--output

默认情况下，popmark直接写入目标文件。要指定另一个文件来写入，设置输出文件：

popmark target.md --output out.md

--imports

指定文档代码依赖的任何库或包，以分号分隔。例如：

popmark target.md --imports 'dart:io;dart:math'

--template

指定一个模板Dart文件的路径。例如，template.txt可能包含带有文本{BODY}的Dart代码，以指示应插入文档代码段的位置；然后使用template.txt作为模板，运行：

popmark target.md --template template.txt

--cleanup

默认情况下，popmark会清理自己，删除生成输出时创建的后台脚本。如果你不想这样做，可以使用--no-cleanup，在这种情况下，这些生成的文件可以在.popmark中找到：

popmark target.md --no-cleanup

--cache

默认情况下，popmark将代码段的输出保存到缓存中（在.popmark中），以便将来不需要重新生成输出。要执行所有代码段，无论结果是否已缓存，可以使用--no-cache。

--refresh

使用--refresh来执行所有代码段并插入其结果，无论结果是否存储在缓存中。

--strip

使用--strip从Markdown文件中移除Dart代码段输出。

--time

在输出中包括每个代码段的执行时间。

其他注意事项

• 确保在运行popmark之前保存目标文件。
• 你可能希望将.popmark（popmark存储其缓存和任何生成的临时Dart文件的地方）添加到你的.gitignore文件中。
• popmark会覆盖任何标记为text的块（它保留用于Dart代码段的输出）。考虑使用更具体的标签或未标记的块来保存你不希望修改的文本。
• 如果嵌入代码的实现在这几次运行之间发生变化，请清除缓存（或标记代码段为dart!）以强制执行这些代码段。

谢谢

感谢你对这个项目的兴趣。请在此处提交问题。

示例

简单的代码段

以下是popmark的一些简单示例。该文件最初只有以下Dart代码段，popmark通过运行以下命令添加了包含代码输出的文本段：

popmark example/example.md

段落1

这里是嵌入的Dart代码…

for (var i = 1; i <= 3; i++) {
  print('$i. Hello, world!');
}

1. Hello, world!
2. Hello, world!
3. Hello, world!

段落2

…这里还有一些…

print('What the heck, world?!');

What the heck, world?!

段落3

…这里还有更多…

print('Goodbye, world!');

Goodbye, world!

段落4

谁不喜欢文字循环？

final message = 'spamtapaalesrest', cycle = 4;
for (var i = 0; i < cycle; i++) {
    final buffer = StringBuffer('  ' * i);
    for (var j = i; j < message.length; j += cycle) {
        buffer.write(' ' * cycle + message[j]);
    }
    print(buffer);
}

    s    t    a    r
      p    a    l    e
        a    p    e    s
          m    a    s    t

导入库

以下是一个需要dart:math和dart:convert库的代码段。为了使此代码正确运行，我们需要在调用popmark时设置--imports选项：

popmark example/example.md \
  --imports 'dart:math as math;dart:convert show json'

(否则错误消息将在文本段中输出。)

print(math.pi);
var map = {'a': 1, 'b': 2};
print(json.encode(map));

3.141592653589793
{"a":1,"b":2}