tera-cli

简介

tera 是一个使用 Rust 编写并受 Jinja2 启发的模板引擎。它允许将一些称为 上下文数据 的数据合并到一个模板中，并生成新的输出。本项目 tera-cli 是 tera 模板引擎 的命令行界面。

该项目被称为 tera-cli，但安装在您系统上的命令是简单的 tera。

tera-ci 提供与您的环境变量相关的强大功能，允许您从传递的上下文数据以及您系统上设置的环境变量来控制输出。

示例

这里有一个基本示例。例如，您将传递一些数据，如

.data.json:
{
    "title": "Demo",
    "users": [
        {
            "username": "Alice",
            "url": "http://example.org/alice",
            "fav_colors": ["red", "green", "yellow"]
        },
        {
            "username": "Bob",
            "url": "http://example.org/bob",
            "fav_colors": ["orange"]
        }
    ]
}

以及一个模板，如

.template.tmpl
<title>{% block title %} {{title}} {% endblock title %}</title>

<ul>
{% for user in users -%}
    <li><a href="{{ user.url }}">{{ user.username }}
    {{ user.username }} likes {% for color in user.fav_colors -%}{{ color }} {% endfor %}
    </a></li>
{% endfor %}
</ul>

以及一个调用，如 tera --template template.tera data.json 将产生

.result
<title> Demo </title>

<ul>
<li><a href="http://example.org/alice">Alice
    Alice likes red green yellow
    </a></li>
<li><a href="http://example.org/bob">Bob
    Bob likes orange
    </a></li>

</ul>

tera 引擎允许比上面显示的简单替换更多。您可以查看 文档 了解更多信息。仅举几个例子，tera 提供以下功能

• 变量与表达式（您可以进行数学运算…）

• 注释

• 控制结构与循环（if、for 等）

• 过滤器

• 格式化函数（显示文件大小，格式化日期等…）

• 继承、包含等…

• 内置函数：首字母大写字符串、替换、修剪等…

安装

cargo install --git https://github.com/chevdor/tera-cli

热重载

您可能会发现监视包含模板的文件夹并使用 tera 来运行在模板更改时很有用。为此，建议将您的模板命名为 foobar.md.tera，如果您的模板扩展为 markdown 文件，例如。然后，您可以使用 fswatch 并使用以下命令监视 templates 文件夹

fswatch templates -e ".*\.md$" | \
    xargs -n1 -I{} \
    tera --include-path templates \
        --template templates/template.md.tera context.json

作为 Docker 容器执行

您可以在 chevdor/tera 找到 tera 的 Docker 镜像。这个镜像非常小，应该小于 8MB。

您可以通过以下方式测试它：

docker run --rm -it chevdor/tera --version

上面提到的 Docker 镜像尚未由 CI 构建，因此您可能无法时时刻刻找到最新版本。

构建容器镜像

docker build --tag tera-cli .

在 Docker 容器中执行 tera

查看 tera 帮助

docker run -it --rm tera-cli --help

解析模板

docker run -it --rm \
    --volume="$(pwd)/templates:/templates" \
    --read-only \
    --env=FOO=BAR \
    tera-cli --template /templates/env-debug.txt --env-only --env-key env

那我能用它做什么呢？

嗯……如果您的数据需要格式化，这个工具可能是个很好的伴侣。

• 您可以生成漂亮的变更日志，例如 markdown、asciidoc、reStructuredText 等。

• 您可以生成更多关于您数据的直观视图。

• 您可以用它来写博客……

• 您还可以生成 k8s 配置文件……

功能

支持格式

您可以将 context 数据作为文件传递或直接输入到 stdin。

当前 stdin 只支持 json。

环境变量支持

有一些与环境变量相关的选项。

启用环境变量注入

默认情况下，环境变量不会合并。您可以使用 --env 启用此功能。

冲突

您已经启用了环境变量的合并，重要的是要了解在某些情况下，您的环境变量可能与您的上下文数据冲突。如果您想使环境变量覆盖上下文数据，这可能是方便的。

环境变量注入优先级

如果您希望上下文数据覆盖环境变量，您可以使用 --env-first。结果，环境变量将首先应用于上下文，然后加载上下文数据。

冲突处理

您可以将冲突视为失败。这是 --fail-on-collision 的用途。如果检测到冲突，程序将退出并返回状态码 1 和适当的消息。

USER="[YOURNAME]" tera --template data/include/hello.txt --include --env-only

USER="[YOURNAME]" tera --template data/inheritance/child.txt --inherit --env-only

Command line utility for the tera templating engine. You need to provide a template using the tera syntax as well as some data (various format are supported)

Usage: tera [OPTIONS] --template <TEMPLATE> [CONTEXT]

Arguments:
  [CONTEXT]  Location of the context data. This file can be of the following type: json | toml | yaml. If you prefer to pass the data as stdin, use `--stdin`

Options:
  -t, --template <TEMPLATE>          Location of the template
  -i, --include                      This flag tells the command to parse all templates found in the same path where the given template is located [aliases: inherit]
      --include-path <INCLUDE_PATH>  Option to define a different path from which search and parse templates [aliases: inherit-path]
  -s, --stdin                        The context data can be passed using stdin
  -e, --env                          If true, the current ENV will be appended to the data under the --env-key key
      --env-key <ENV_KEY>            By default, if --env is set, the environment variables will be attached at the root of the context. This is convenient but may end up conflicting with your data. To prevent collisions, you can provide a custom key with this option
      --env-first                    By default, the context is made of the data you pass and the ENV is applied afterwards. Setting this option will apply the ENV first. This is interesting if you prefer your data to override the ENV
      --fail-on-collision            if you prefer your data to override the ENV
      --env-only                     If you want to solely use the ENV as context, you may pass this option. This will prevent an error about no context being passed to be raised
  -o, --out <OUT>                    Optional output file. If not passed, using stdout
  -a, --escape                       Auto-escape rendered content. This is useful for HTML output
  -h, --help                         Print help
  -V, --version                      Print version