关于

Kapow是一个模板处理器，提供以下指令以支持在生成的输出中注入文件内容、命令输出、当前日期/时间、经过时间等。

它可以以不同的方式使用

• 标准：创建一个带有kapow指令的（Markdown）文件，然后运行kapow [选项] 路径/到/文件.ext；可选地通过重定向保存输出：kapow [选项] 路径/到/文件.ext >输出.ext
• Shebang：将#!/usr/bin/env kapow作为（Markdown）文件的第一行，通过chmod +x 文件.ext使其“可执行”，然后通过./file.ext运行（参见块指令下的第3点）。如果向kapow传递选项，请使用env的-S选项，例如：#!/usr/bin/env -S kapow -w 60。请参阅build.md以获取示例。

虽然kapow的设计基于Markdown语法，但它可以与任何可以与其指令一起工作的文本格式一起使用。

块指令

注意

1. 块指令必须放在行的开头。
2. 长命令可以跨反斜杠包裹。
3. 当源文件作为参数传递时，包含的文件路径和命令将按照源文件所在目录进行处理。然而，如果源文件是通过stdin读取或通过shebang运行，包含的文件路径和命令将相对于当前目录进行处理。因此，如果任何包含的文件使用相对路径或依赖于当前目录的命令，则必须手动切换到源文件目录，然后通过./file.ext运行。
4. 块指令将被其内容/输出完全替换，因此您可以在其中嵌入Markdown语法...例如，作为内容列表，在前面添加显示命令的提示等。
5. 如果!run指令失败，kapow会打印错误并停止处理，除非用户指定了-k选项。

跨度指令

• 跨度指令必须放在代码跨度内，并且可以在任何行中出现零次或多次。
• 通过在!前加反斜杠来禁用跨度指令的处理：\!。

其他功能

• 转义包裹：以单个反斜杠\结束行，它将在输出中被展开；这允许作者在源代码中包裹长行，但kapow将展开它们。如果需要保留尾随反斜杠，请添加一个额外的反斜杠，该行将不会展开，并且额外的反斜杠将被删除。
• 相对图像路径：Markdown图像（![alt](path "title")）具有本地路径，相对于包含文件进行处理，除非使用-R选项禁用此功能。
• 消除多个空行。

安装

cargo install kapow bat

注意：安装bat是可选的，但如果安装了，kapow将使用它进行语法高亮和分页（如果在Linux、macOS或UNIX系统上；请参阅-p、-P、-H、-l和-r选项）；它也是一个不错的实用工具。

用法

$ kapow -V
kapow 2.20.0

$ kapow -h
KAPOW!

Usage: kapow [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Source file(s) [default: -]

Options:
  -f <FLAGS>       Flags (comma-separated list of flags to enable)
  -p               Page output
  -P               Do not page output
  -H               Disable syntax highlighting
  -L               Display all syntax highlight languages
  -l <LANG>        Syntax higlight language [default: md]
  -w <WRAP>        Wrap !run directive columns [default: 0]
  -c <STRING>      Wrap !run directive continuation [default: \]
  -k               Ignore !run directive failures
  -R               Disable relative image paths
  -r, --readme     Print readme
  -h, --help       Print help
  -V, --version    Print version

错误

注意：在“正常使用”中，kapow进程可能看起来没有使用这些错误代码退出，因为这些输出被重定向到bat作为分页器（如果安装了，并且输出是TTY），不幸的是，bat掩盖了错误代码。

示例

请参阅Makefile.toml中的readme任务

• 从t/VERSION.t.md生成t/VERSION.md
  • !run:../目标/发布/kapow-V
• 从t/USAGE.t.md生成t/USAGE.md
  • !run:../目标/发布/kapow-h
• 从t/README.md生成README.md
  • !inc:VERSION.md
  • !inc:USAGE.md
  • `!now`（所有变体）
  • 转义包装
  • 相对图像路径

变更日志

请在此CHANGELOG.md仓库中查找。

开发

cargo install b3sum bat cargo-audit cargo-edit cargo-make \
cargo-outdated dtg kapow miniserve