12 个版本 (2 个稳定版)

1.1.0	2023 年 10 月 6 日
1.0.0	2023 年 10 月 5 日
0.5.4	2023 年 10 月 4 日
0.4.1	2023 年 10 月 4 日
0.1.0	2023 年 4 月 19 日

#286 在命令行工具

自定义许可协议

40KB
1K SLoC

评估 Markdown

这是一个用于评估或从 Markdown 文件中导出代码的工具。

为什么？因为我喜欢用代码片段编写 Markdown 文件（在 Obsidian 上也很有用）。

通过在 Markdown 文件中使用较小的代码片段和文档，文件将很容易被读者阅读，同时还可以执行而无需复制粘贴。如果文件包含多个具有给定语言的代码块，eval-md 将将它们组合并作为单个脚本进行评估。

安装

cargo install eval-md

支持的语言

JavaScript (node, deno)
Lua
PHP
Python3
Ruby
Shell (bash, zsh)

导出

使用 --export 标志，目标语言可以是任何东西，它不会评估最终代码。它将输出内容到 stdout。非常适合从 Markdown 文件生成内容，例如配置文件。在我们的示例中，我们有一个服务的 JSON 配置文件，我们可以添加关于配置文件部分的额外注释。

在输出中，将添加一个标题，例如 Python 脚本在 --export 上得到 #!/usr/bin/env python3。

自定义标签

可以使用 : 定义自定义标签和执行器。第一部分将是提取代码块的字符串标签，第二部分将是评估提取的代码的语言。

py:python => 将解析 py 并作为 python 运行
js => 将解析 js 并作为 js 运行 (js 是 javascript 的别名)
js:deno => 将解析 js 并使用 deno 运行

示例

以下示例将使用 example/test.md

❯ eval-md zsh example/test.md -- --random-flag
nice in zsh
Arguments: --random-flag

❯ eval-md bash example/test.md
nice in bash
Arguments:

❯ eval-md python example/test.md -- --hype-level=awesomeness
awesome
Arguments: ['-', '--hype-level=awesomeness']

❯ eval-md ruby example/test.md -- --debug
it works :)
Arguments: ["--debug"]

❯ eval-md --debug python example/test.md -- --hype-level=awesomeness
 -- Target Language: python
 -- Source file: example/test.md
 -- Arguments: ["--hype-level=awesomeness"]
awesome
Arguments: ['-', '--hype-level=awesomeness']

❯ eval-md json example/test.md --export
{
  "enable_registration": true,
  "debug": false,
  "hostname": "efertone.me",
  "port": 9999
}

❯ eval-md lua example/test.md
Value:  15

❯ eval-md something:javascript example/test.md
Fancy

安装和启动 Flux

显然，整个文档可以作为一个壳脚本中的注释存在。如果你想要添加图像和链接到其他页面，你仍然可以“执行”有关如何安装 Flux 的文档。当然，这个示例仅安装和启动一种特定的方式。

❯ eval-md bash example/install-flux.md
 !! git repository is not defined.
 --help            This help message
 --repo <repo>     Git repository. (example: [email protected]/org/repo)
 --branch <branch> Git branch. [default: main]
 --path <path>     Path to the cluster. [default: ./clusters/management]

❯ eval-md bash example/install-flux.md -- --repo [email protected]/yitsushi/cluster-conf --branch production
...

使用Flux部署Helm发行版

example/flux-helm-repo.md 示例展示了如何在一个集群上部署Helm图表的简单场景。通常这涉及到大量的复制粘贴，但我们可以通过eval-md来变得聪明。

这个简单的命令将评估Markdown文件中的所有bash代码。唯一的bash代码片段是导出yaml块并将其传递给kubectl的代码片段。最后，我们将得到一份很好的文档（不是这篇，它大部分都是填充文本，没有花太多时间在这上面）。

❯ eval-md bash example/flux-helm-repo.md
helmrepository.source.toolkit.fluxcd.io/podinfo created
helmrelease.helm.toolkit.fluxcd.io/podinfo created

分组过滤器

使用特殊标记，可以在代码块上定义键值对

```bash #group=a something=else
echo "This is group A"
```

```bash #group=b
echo "This is group B"
```

```bash
echo "This one does not belon anywhere"
```

没有任何额外参数，所有bash块都将被评估

❯ eval-md bash a.md
This is group A
This is group B
This one does not belon anywhere

如果我们只想评估特定的分组，我们可以使用--group标志来设置过滤器

❯ eval-md bash a.md --group=a
This is group A

❯ eval-md bash a.md --group=b
This is group B

如果指定了--group标志，但值为空，则表示评估所有没有分组的部分。

❯ ./target/release/eval-md bash a.md --group=
This one does not belon anywhere

选择模式

使用--pick标志，我们会询问每个分组是否将其添加到脚本或丢弃。如果我们有多个代码块，但不想评估所有这些块，这是一个很好的选择。

分组选择和选择模式一起工作，因此可以在评估之前过滤分组并丢弃其部分。

选择模式问题将打印到stderr，程序输出可以重定向到文件或管道，与--export一起使用很有用。

❯ eval-md bash a.md --group=a --pick --export > myscript.sh

---
echo "This is group A"
---
 --> Do you want to add this block? (yes/no) yes

---
echo "This is group A again"
---
 --> Do you want to add this block? (yes/no) no

❯ cat myscript.sh
#!/usr/bin/env bash

echo "This is group A"

作为一个脚本评估所有内容

这是一个奇怪的情况，但有人说他们想使用它，那会很有趣。如果名称设置为all，并且指定了解释器，如all:python，则无论文档中代码块的标记语言如何，都会使用文档中的所有代码块，并使用指定的解释器（在这种情况下为python）进行评估。

请参见example/use-all.md示例

❯ eval-md all:python example/use-all.md
Do something with:


<html>
  <head><title>Nice</title></head>
  <body>
    <div id="app">awesome</div>
  </body>
</html>

依赖关系

~1.2–1.7MB
~33K SLoC