#color-palette #template #catppuccin #whiskers #flavor #front-matter #port

bin+lib catppuccin-whiskers

😾 为热情的人设计的舒缓端口创建工具!

15 个稳定版本

2.4.0 2024年6月14日
2.3.0 2024年5月27日
2.1.0 2024年4月27日
2.0.0 2024年3月31日
1.1.1 2023年10月28日

模板引擎 中排名第24

MIT 许可证

92KB
2K SLoC

Logo
Catppuccin Whiskers

 

Whiskers 是一个专门为 Catppuccin 定制的端口创建辅助工具,允许开发者定义可以注入调色板的模板文件。

[!重要] 此仓库已从 catppuccin/toolbox 迁移。要查看 v2.3.0 之前的版本,请参阅 catppuccin/toolbox 的版本

安装

您可以使用以下方法之一安装 Whiskers

安装方法 说明
crates.io cargo安装 catppuccin-whiskers
cargo安装 --githttps://github.com/catppuccin/whiskers catppuccin-whiskers
Homebrew brew安装 catppuccin/tap/whiskers
Nix nix profile install github:catppuccin/whiskers
nix run github:catppuccin/whiskers-- <参数>
二进制文件
(Windows, MacOS & Linux)
可在 最新 GitHub 版本 中获取。

用法

$ whiskers --help
Soothing port creation tool for the high-spirited!

Usage: whiskers [OPTIONS] [TEMPLATE]

Arguments:
  [TEMPLATE]
          Path to the template file, or - for stdin

Options:
  -f, --flavor <FLAVOR>
          Render a single flavor instead of all four

          [possible values: latte, frappe, macchiato, mocha]

      --color-overrides <COLOR_OVERRIDES>
          Set color overrides

      --overrides <OVERRIDES>
          Set frontmatter overrides

      --check [<EXAMPLE_PATH>]
          Instead of creating an output, check it against an example

          In single-output mode, a path to the example file must be provided. In multi-output mode, no path is required and, if one is provided, it will be ignored.

      --dry-run
          Dry run, don't write anything to disk

      --list-functions
          List all Tera filters and functions

      --list-flavors
          List the Catppuccin flavors

      --list-accents
          List the Catppuccin accent colors

  -o, --output-format <OUTPUT_FORMAT>
          Output format of --list-functions

          [default: json]
          [possible values: json, yaml, markdown, markdown-table, plain]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

模板

请熟悉 Whiskers 使用的模板引擎 Tera

命名约定

Whiskers 对模板名称没有限制。然而,我们建议您使用以下选项之一

  • <端口号>.tera 存放在仓库根目录,用于只需要一个模板的端口。
  • templates/<文件名>.tera 尤其适用于有多个模板的端口。
    • 例如,一个生成名为 ui.cfgpalette.cfg 文件的端口可以分别使用 templates/ui.teratemplates/palette.tera

这些约定旨在使贡献者更容易找到模板,并为代码编辑器提供有关正确文件类型的提示。

上下文变量

以下变量可用于您的模板中

单口味模式

变量 描述
flavor (Flavor) 正在模板化的口味。
rosewaterflamingopink,等。(Color 正在模板化的口味的所有颜色。
任何前置内容 前置内容部分所述的所有前置内容变量。

多口味模式

变量 描述
flavors (Map<String, Flavor>) 包含所有命名口味的数组,包括所有其他上下文变量。
任何前置内容 前置内容部分所述的所有前置内容变量。

类型

这些类型设计得与 palette.json 非常接近。

口味
字段 类型 描述 示例
name String 口味的名称。 "Latte""Frappé""Macchiato""Mocha"
identifier String 口味的标识符。 "latte""frappe""macchiato""mocha"
emoji char 与口味相关的表情符号。 '🌻''🪴''🌺''🌿'
order u32 口味在调色板规范中的顺序。 03
dark bool 口味是否为深色。 false 对 Latte,true 对其他
light bool 是否是浅色。 true 对 Latte,false 对其他
colors Map<String,颜色> 颜色标识符与其相应值的映射。
颜色
字段 类型 描述 示例
name String 颜色的名称。 "Rosewater""Surface 0""Base"
identifier String 颜色的标识符。 "rosewater""surface0""base"
order u32 颜色在调色板规范中的顺序。 025
accent bool 颜色是否为强调色。
hex String 颜色以十六进制格式表示。 "1e1e2e"
rgb RGB 颜色以 RGB 格式表示。
hsl HSL 颜色以 HSL 格式表示。
opacity u8 颜色的不透明度。 0255
RGB
字段 类型 描述
r u8 颜色的红色通道。
g u8 颜色的绿色通道。
b u8 颜色的蓝色通道。
HSL
字段 类型 描述
h u16 颜色的色调。
s u8 颜色的饱和度。
l u8 颜色的亮度。

函数

描述 示例
if 如果条件为真,则返回一个值,如果为假则返回另一个值 if(cond=true, t=1, f=0)1
object 从输入创建一个对象 object(a=1, b=2){a: 1, b: 2}
css_rgb 将颜色转换为 RGB CSS 字符串 css_rgb(color=red)rgb(210, 15, 57)
css_rgba 将颜色转换为 RGBA CSS 字符串 css_rgba(color=red)rgba(210, 15, 57, 1.00)
css_hsl 将颜色转换为 HSL CSS 字符串 css_hsl(color=red)hsl(347, 87%, 44%)
css_hsla 将颜色转换为 HSLA CSS 字符串 css_hsla(color=red)hsla(347, 87%, 44%, 1.00)
read_file 读取并包含文件的正文,路径相对于模板文件 read_file(path="abc.txt")abc

过滤器

描述 示例
add 向颜色添加值 red | add(hue=30)#ff6666
sub 从颜色中减去值 red | sub(hue=30)#d30f9b
mod 修改颜色 red | mod(lightness=80)#f8a0b3
mix 混合两种颜色 red | mix(color=base, amount=0.5)#e08097
urlencode_lzma 使用 LZMA 压缩将对象序列化为 URL 安全字符串 red | urlencode_lzma#ff6666
trunc 将数字截断到指定的小数位数 1.123456 | trunc(places=3)1.123
css_rgb 将颜色转换为 RGB CSS 字符串 red | css_rgbrgb(210, 15, 57)
css_rgba 将颜色转换为 RGBA CSS 字符串 red | css_rgbargba(210, 15, 57, 1.00)
css_hsl 将颜色转换为 HSL CSS 字符串 red | css_hslhsl(347, 87%, 44%)
css_hsla 将颜色转换为 HSLA CSS 字符串 red | css_hslahsla(347, 87%, 44%, 1.00)

[!注意] 您还可以访问所有Tera的内置过滤器和函数。有关更多信息,请参阅Tera文档

前端信息

Whiskers模板可以在文件顶部包含一个前端信息部分。

前端信息是一个包含模板元数据的YAML块。如果存在,前端信息部分必须是文件中的第一个内容,并且必须以三横线之间的有效YAML形式出现。

模板版本

最重要的前端信息键是Whiskers版本。此键允许Whiskers确保它正在渲染一个它可以理解的模板。

示例

---
whiskers:
  version: "2.0.0"
---
... standard template content goes here ...

如果版本键不存在,Whiskers将显示警告并尝试渲染模板。然而,建议始终包含版本键以确保与Whiskers未来版本的兼容性。

十六进制格式

用于渲染十六进制颜色的格式可以使用hex_format前端变量进行自定义。

此字符串作为以下上下文变量下的Tera模板进行渲染

  • rgba:颜色的红色、绿色、蓝色和alpha通道,作为小写两位十六进制字符串。
  • RGBA:如上所述,但为大写。
  • z:如果颜色不是完全不透明,则与a相同,否则为空字符串。
  • Z:如上所述,但为大写。

hex_format的默认值为{{r}}{{g}}{{b}}{{z}}

示例

---
whiskers:
  version: "2.0.0"
  hex_format: "0x{{B}}{{G}}{{R}}{{A}}"
---
{{red.hex}}

运行 whiskers example.tera -f mocha 会产生以下输出: 0xA88BF3FF

页眉变量

您还可以通过将它们添加到模板的页眉中,在模板过程中包含额外的上下文变量。

例如,给定以下模板 (example.tera)

---
app: "Pepperjack"
author: "winston"
---
# Catppuccin for {{app}}
# by {{author}}
bg = '{{base.hex}}'
fg = '{{text.hex}}'

运行 whiskers example.tera -f mocha 产生以下输出

# Catppuccin for Pepperjack
# by winston
bg = '1e1e2e'
fg = 'cdd6f4'

页眉的一个常见用途是设置主题的强调色

---
accent: "mauve"
---
{% set darkGreen = green | sub(lightness=30) %}
bg = "#{{base.hex}}"
fg = "#{{text.hex}}"
border = "#{{flavor.colors[accent].hex}}"
diffAddFg = "#{{green.hex}}"
diffAddBg = "#{{darkGreen.hex}}"

渲染上述模板产生以下输出

bg = "#1e1e2e"
fg = "#cdd6f4"
border = "#cba6f7"
diffaddfg = "#a6e3a1"
diffaddbg = "#40b436"

覆盖

页眉覆盖也可以通过命令行工具使用 --overrides 标志来指定,接受类似于页眉的 JSON 字符串。这对于构建脚本来说特别有用,可以自动为每个强调色生成文件

示例.tera

---
accent: "mauve"
---
theme:
  accent: "{{flavor.colors[accent].hex}}"

当运行 whiskers example.tera -f latte --overrides '{"accent": "pink"}' 时,accent 将被覆盖为粉色。

颜色覆盖

可以通过命令行工具使用 --color-overrides 标志来指定颜色覆盖。此标志接受如下 JSON 字符串

{
  "all": {
    "text": "ff0000"
  },
  "mocha": {
    "base": "000000",
    "mantle": "010101",
    "crust": "020202"
  }
}

传递这些覆盖将设置所有口味的文本颜色为亮红色,并将 Mocha 的 basemantlecrust 颜色设置为黑色/接近黑色。

单口味模式

使用 --flavor/-f 标志运行 Whiskers 将使其进入单口味模式。这意味着所选口味被放置到模板上下文中作为 flavor,并且为了方便起见,它的所有颜色也被放置到上下文中作为相应的标识符(redsurface0 等。)

多口味模式

不使用 --flavor/-f 标志运行 Whiskers 将使其进入多口味模式。在这种模式下,所有口味都被放置到模板上下文中,作为口味标识符到相应 Flavor 对象的映射。

此映射可以像这样迭代

{% for id, flavor in flavors %}
{{id}} is one of "latte", "frappe", "macchiato", or "mocha".
{{flavor}} is an object containing the flavor's properties and colors.
{% endfor %}

请参阅 examples/single-file 目录,了解如何使用它的更多具体示例。

模板矩阵

Whiskers 可以使用在页眉中设置的矩阵从单个模板渲染多个输出。例如,这可以用于为每种口味和强调色生成一个输出。

在此模式下,Whiskers 将直接渲染到页眉中指定的 filename 键所指定的文件集中。这可以通过 --dry-run 标志禁用,在这种情况下,Whiskers 将渲染模板但不会将它们写入任何地方。

矩阵定义为一个可迭代对象的列表。Whiskers 将为矩阵中可迭代对象的每个组合生成一个文件。

矩阵中的一些可迭代对象可以是没有任何值提供的字符串。在这种情况下,Whiskers 将将其视为“魔法可迭代对象”,这是一个在渲染模板之前 Whiskers 可以自动生成值的可迭代对象。

以下支持以下魔法可迭代对象

  • flavor:latte、frappe、macchiato、mocha
  • accent:玫瑰水、火烈鸟、粉色、淡紫色、红色、栗色、桃色、黄色、绿色、蓝绿色、天空色、蓝宝石色、蓝色、薰衣草色

示例

---
whiskers:
  version: 2.0.0
  matrix:
    - variant: ["normal", "no-italics"]
    - flavor
    - accent
  filename: "catppuccin-{{flavor.identifier}}-{{accent}}-{{variant}}.ini"
---
# Catppuccin {{flavor.name}}{% if variant == "no-italics" %} (no italics){% endif %}
[theme]
{{accent}}: #{{flavor.colors[accent].hex}}

运行 whiskers template.tera 将生成以下文件

catppuccin-latte-rosewater-normal.ini
catppuccin-latte-rosewater-no-italics.ini
catppuccin-latte-flamingo-normal.ini
catppuccin-latte-flamingo-no-italics.ini
...
catppuccin-frappe-rosewater-normal.ini
catppuccin-frappe-rosewater-no-italics.ini

... 以及 flavor、accent 和 variant 的每一种组合。请注意,文件名是通过渲染矩阵可迭代元素的每种组合中的 frontmatter 中的 filename 键来生成的。

检查模式

您可以使用 Whiskers 作为带有 检查模式 的 linter。要做到这一点,请设置 --check 选项。Whiskers 将像平常一样渲染模板,但然后它不会打印结果,而是将其与预期输出进行比较,如果它们不同,则会以退出代码 1 失败。

这在 CI 管道中特别有用,以确保生成的文件在没有对模板进行相应更改的情况下不会更改。

在单 flavor 模式下,您必须将预期输出文件的路径作为 --check 选项的参数提供。在多 flavor 模式下,路径是不必要的,将被忽略。

Whiskers 将使用在 DIFFTOOL 环境变量中设置的程序将输出与检查文件进行比较,如果没有设置,将回退到 diff。命令将以以下方式调用:$DIFFTOOL <实际> <预期>

$ whiskers theme.tera latte --check themes/latte.cfg
(no output, exit code 0)

$ whiskers theme.tera latte --check themes/latte.cfg
Templating would result in changes.
4c4
< accent is #ea76cb
---
> accent is #40a02b

(exit code 1)

编辑器支持

Tera 的语法不是大多数编辑器原生支持的。一些编辑器有可用的扩展,可以提供 Tera 模板的语法高亮和其他功能。如果您的编辑器没有可用的扩展,您可以尝试使用 Jinja 扩展。虽然不是完全匹配,但 Tera 的语法与 Jinja 的语法足够相似,在大多数情况下可以很好地使用。

对于 Visual Studio Code 用户,我们推荐 Better Jinja 扩展。

进一步阅读

  • 请参阅 示例 目录,其中进一步展示了 Whiskers 的实用性和功能。
  • 请参阅 RFC,CAT-0003-Whiskers,了解创建 Whiskers 的动机。

 

版权 © 2023-present Catppuccin Org

依赖关系

~15–27MB
~478K SLoC