feat: add Leaf

README.md

@@ -44,7 +44,7 @@ Quick Reference
 非常感谢一直以来支持我开源项目的朋友们！如果您认可我的工作，欢迎通过 [赞助](https://wangchujiang.com/#/sponsor)<!--rehype:target=_blank--> 我或下载并使用我开发的 [macOS 应用](https://wangchujiang.com/#/app)<!--rehype:target=_blank--> 来支持我。以下是我个人独立开发的 macOS 应用列表：
 
 <p style="display: inline-block">
-  <a target="_blank" href="https://apps.apple.com/app/Keyzer/6500434773" title="Keyzer for macOS"><img alt="Keyzer" height="52" width="52" src="https://wangchujiang.com/appicon/keyzer.png"></a>
+  <a target="_blank" href="https://apps.apple.com/app/Keyzer/6500434773" title="Keyzer for macOS"><img alt="Keyzer" height="52" width="52" src="./appicon/keyzer.png"></a>
   <a target="_blank" href="https://github.com/jaywcjlove/vidwall-hub" title="Vidwall Hub for macOS"><img alt="Vidwall Hub" height="52" width="52" src="./appicon/vidwall-hub.png"></a>
   <a target="_blank" href="https://apps.apple.com/app/VidCrop/6752624705" title="VidCrop for macOS"><img alt="VidCrop" height="52" width="52" src="./appicon/vidcrop.png"></a>
   <a target="_blank" href="https://apps.apple.com/app/Vidwall/6747587746" title="Vidwall for macOS"><img alt="Vidwall" height="52" width="52" src="./appicon/vidwall.png"></a>
@@ -147,6 +147,7 @@ Quick Reference
 [Kubernetes](./docs/kubernetes.md)<!--rehype:style=background:rgb(51 113 227);&class=contributing&data-info=👆看看还缺点儿什么？-->
 [LaTeX](./docs/latex.md)<!--rehype:style=background:rgb(0 128 128);&class=contributing-->
 [Laravel 8](./docs/laravel.md)<!--rehype:style=background:rgb(249 50 44);&class=contributing tag&data-lang=PHP-->
+[Leaf](./docs/leaf.md)<!--rehype:style=background:rgb(106 105 254);&class=contributing tag&data-lang=Swift-->
 [Lua](./docs/lua.md)<!--rehype:style=background:rgb(3 3 128);-->
 [Markdown](./docs/markdown.md)<!--rehype:style=background:rgb(103 61 156);-->
 [MATLAB](./docs/matlab.md)<!--rehype:style=background:rgb(0 118 168);&class=contributing-->

assets/leaf.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 44 50"><g fill="none" fill-rule="evenodd"><polygon fill="#FFF" points="0 18.234 21.191 0 43.403 18.234 43.403 18.365 21.702 35.818 0 18.365"/><path fill="#40C4FF" d="M21.8169,35.8142 L21.9452,35.8142 C21.9452,35.8142 21.9868,39.0876 21.9452,40.6557 C21.9036,42.2237 21.8169,40.6557 21.8169,40.6557 L0,23.1217 L0,18.2803 L21.8169,35.8142 Z"/><polygon fill="#3DC4FF" points="21.817 40.525 21.945 40.525 21.945 45.235 21.817 45.366 0 27.832 0 22.991"/><polygon fill="#FFF" fill-opacity=".25" points="21.817 40.525 21.945 40.525 21.945 45.235 21.817 45.366 0 27.832 0 22.991"/><polygon fill="#3DC4FF" points="21.817 45.236 21.945 45.105 21.945 49.684 21.817 49.815 0 32.281 0 27.702"/><polygon fill="#FFF" fill-opacity=".5" points="21.817 45.236 21.945 45.105 21.945 49.684 21.817 49.815 0 32.281 0 27.702"/><polygon fill="#E040FB" points="21.656 35.814 21.656 40.656 43.403 23.122 43.403 18.28"/><polygon fill="#E040FB" points="21.656 40.525 21.656 45.366 43.403 27.832 43.403 22.991"/><polygon fill="#FFF" fill-opacity=".25" points="21.656 40.525 21.656 45.366 43.403 27.832 43.403 22.991"/><polygon fill="#E040FB" points="21.656 45.236 21.656 49.815 43.403 32.412 43.403 27.702"/><polygon fill="#FFF" fill-opacity=".5" points="21.656 45.236 21.656 49.815 43.403 32.412 43.403 27.702"/><path fill="#1C1C1F" fill-rule="nonzero" d="M14.559,11.6222 C14.559,11.6222 24.812,11.948 27.5377,14.2818 C30.2635,16.6157 30.6498,20.725 28.4006,23.4601 C26.1514,26.1953 22.1185,26.5206 19.3927,24.1868 C16.667,21.8529 14.559,11.6222 14.559,11.6222 Z"/></g></svg>

docs/leaf.md

@@ -0,0 +1,474 @@
+Leaf 备忘清单
+====
+
+[Leaf](https://github.com/vapor/leaf) 是 [Vapor](https://github.com/vapor/vapor) 的轻量级模板引擎，用于在服务端生成动态 HTML 页面。
+
+入门
+----
+
+### Leaf
+
+`Leaf` 是一种强大的模板语言，其语法受 `Swift` 启发。
+
+- [Leaf 模板语言官方文档](https://docs.vapor.codes/zh/leaf/getting-started/) _(vapor.codes)_
+- [**LeafKit**：Swift 模板引擎库](https://github.com/vapor/leaf-kit) _(github.com)_
+- [**Leaf**：LeafKit 的 Vapor 集成模板系统](https://github.com/vapor/leaf) _(github.com)_
+
+### Package
+<!--rehype:wrap-class=col-span-2-->
+
+```swift
+// swift-tools-version:5.2
+import PackageDescription
+
+let package = Package(
+    name: "MyApp",
+    platforms: [ .macOS(.v10_15) ],
+    dependencies: [ /// 添加其它依赖
+        .package(url: "https://github.com/vapor/leaf.git", from: "4.0.0"),
+    ],
+    targets: [
+        .target(name: "App", dependencies: [ .product(name: "Leaf", package: "leaf") ]),
+    ]
+)
+```
+
+### 配置
+
+```swift
+import Vapor
+import Leaf
+```
+
+设置工作目录
+
+```swift
+app.directory.workingDirectory = "...."
+```
+
+设置模板目录
+
+```swift
+app.directory.viewsDirectory = "...."
+```
+
+设置模板引擎
+
+```swift
+app.views.use(.leaf)
+```
+
+### 目录结构
+
+```
+VaporApp
+├── Package.swift
+├── Resources
+│   ├── Views
+│   │   └── hello.leaf
+├── Public
+│   ├── images (images 资源)
+│   ├── styles (css 资源)
+└── Sources
+    └── ...
+```
+
+- Views 文件夹来存储 `.leaf` 文件
+- 配置 [`FileMiddleware`](https://api.vapor.codes/vapor/documentation/vapor/filemiddleware/) 提供静态文件
+
+```swift
+app.middleware.use(FileMiddleware(
+    publicDirectory: 
+        app.directory.publicDirectory
+))
+```
+
+### 渲染视图
+
+```swift
+app.get("hello") { 
+    req -> EventLoopFuture<View> in
+    return req.view.render("hello", [
+        "name": "Leaf"
+    ])
+}
+// 或
+app.get("hello") { 
+    req async throws -> View in
+    return try await req.view.render(
+        "hello", ["name": "Leaf"]
+    )
+}
+```
+
+在 `hello.leaf` 模板中使用 `name`
+
+```
+Hello, #(name)!
+```
+
+打开浏览器访问 `/hello` 显示 `Hello, Leaf!`。
+
+## Leaf 概述
+
+### 模板语法
+
+一个基本的 `Leaf` 标签使用示例
+
+```swift
+There are #count(users) users.
+```
+
+可以使用冒号和结束标签为某些标签提供可选的正文。
+
+- 标记 `#`：这表示 leaf 解析器开始寻找的标记。
+- 名称 `count`：标签的标识符。
+- 参数列表 (`users`)：可以接受零个或多个参数。
+
+### 内置标签示例
+
+```html
+#(variable)
+#extend("template"): 添加到模板中！#endextend
+#export("title"): 欢迎使用 Vapor #endexport
+#import("body")
+#count(friends)
+#for(friend in friends): 
+    <li>#(friend.name)</li> 
+#endfor
+```
+
+### 表达式
+
+- `+`
+- `%`
+- `>`
+- `==`
+- `||`
+<!--rehype:className=cols-3 style-none-->
+
+```leaf
+#if(1 + 1 == 2):
+    Hello!
+#endif
+
+#if(index % 2 == 0):
+    This is even index.
+#else:
+    This is odd index.
+#endif
+```
+
+### 上下文
+<!--rehype:wrap-class=row-span-2-->
+
+Leaf 推荐用 `Encodable` 结构体传数据，数组需包装，`[String: Any]` 不支持。
+
+```swift
+struct WelcomeContext: Encodable {
+    var title: String
+    var numbers: [Int]
+}
+return req.view.render("home", 
+    WelcomeContext(
+        title: "Hello!", 
+        numbers: [42, 9001]
+    )
+)
+```
+
+`title` 和 `numbers` 将暴露给 `Leaf` 模板，就可以在标签中使用这些变量。
+
+```html
+<h1>#(title)</h1>
+#for(number in numbers):
+    <p>#(number)</p>
+#endfor
+```
+
+### 条件
+<!--rehype:wrap-class=row-span-2-->
+
+变量是否存在
+
+```html
+#if(title):
+    The title is #(title)
+#endif
+```
+
+比较
+
+```html
+#if(title == "Welcome"):
+    This is a friendly web page.
+#endif
+```
+
+使用另一个标签作为判断条件的一部分，内部标签应该省略 `#`
+
+```html
+#if(count(users) > 0):
+    You have users!
+#else:
+    There are no users yet :(
+#endif
+```
+
+### #elseif
+
+```html
+#if(title == "Welcome"):
+    Hello new user!
+#elseif(title == "Welcome back!"):
+    Hello old user
+#else:
+    Unexpected page!
+#endif
+```
+
+### 循环
+
+```swift
+struct SolarSystem: Codable {
+  let planets = ["Venus", "Earth", "Mars"]
+}
+return req.view.render(
+  "solarSystem", SolarSystem()
+)
+```
+
+在 `Leaf` 中循环它们：
+
+```html
+<ul>
+#for(planet in planets):
+    <li>#(planet)</li>
+#endfor
+</ul>
+```
+
+### 模板示例
+<!--rehype:wrap-class=row-span-4-->
+
+入口页面，通过 `#extend("main")` 将 `mainleaf` 模板的内容复制到当前模板中使用
+
+```html
+#extend("main"):
+  #export("body"):
+    <p>Welcome to Vapor!</p>
+  #endexport
+#endextend
+```
+
+在公共模板 `main.leaf` 中
+
+```html
+<html>
+  <head>
+    <title>#(name)</title>
+  </head>
+  <body>#import("body")</body>
+</html>
+```
+
+呈现如下内容：
+
+```html
+<html>
+  <head>
+    <title>Leaf</title>
+  </head>
+  <body>
+    <p>Welcome to Vapor!</p>
+  </body>
+</html>
+```
+
+### 扩展模板
+<!--rehype:wrap-class=row-span-3-->
+
+在模板中使用 `#export` 存储名为 `body` 的一些 HTML
+
+```html
+#export("body"):
+    <p>Welcome to Vapor!</p>
+#endexport
+```
+
+使用 `#import` 获取传递给 `#extend` 标签的内容
+
+```html
+<body>
+  #import("body")
+</body>
+```
+
+### #count
+
+```html
+Your search matched #count(matches) pages.
+```
+
+`#count` 标签返回数组中的项目数量
+
+### #lowercased
+
+```html
+#lowercased(name)
+```
+
+`#lowercased` 标签将字符串转成小写字母。
+
+### #capitalized
+
+```html
+#capitalized(name)
+```
+
+`#capitalized` 标签将字符串中每个单词的首字母大写，其他字母小写。
+
+### #contains
+
+```html
+#if(contains(planets, "Earth")):
+    Earth is here!
+#else:
+    Earth is not in this array.
+#endif
+```
+
+`#contains` 标签接受一个数组和一个值作为其两个参数，如果参数一中的数组包含参数二中的值，则返回 true。
+
+### #date
+<!--rehype:wrap-class=row-span-2-->
+
+`#date` 标签将日期格式化为可读的字符串。默认情况下，它使用 ISO8601 格式。
+
+```swift
+render(..., ["now": Date()])
+```
+
+模板中使用
+
+```
+The time is #date(now)
+```
+
+你可以传自定义日期格式作为第二参数，详见 [Swift DateFormatter](https://developer.apple.com/documentation/foundation/dateformatter)。
+
+```
+The date is #date(now, "yyyy-MM-dd")
+```
+
+### #unsafeHTML
+
+标签就像一个变量标签 - 例如 `#(variable)`。
+
+```
+The time is #unsafeHTML(styledTitle)
+```
+
+它不会转义任何 `variable` 可能包含的 HTML 标签
+
+### #dumpContext
+
+`#dumpContext` 标签将整个上下文渲染为可读的字符串。使用此标记来调试作为上下文提供给当前渲染的内容。
+
+```
+Hello, world!
+#dumpContext
+```
+
+自定义标签
+---
+
+### LeafTag
+<!--rehype:wrap-class=col-span-2 row-span-2-->
+
+创建一个名为 `NowTag` 的类并遵循 `LeafTag` 协议
+
+```swift
+struct NowTag: LeafTag {
+    func render(_ ctx: LeafContext) throws -> LeafData {
+        ...
+    }
+}
+```
+
+实现 `render(_:)` 方法。传递给该方法的 `LeafContext` 参数包含了我们需要的所有内容。
+
+```swift
+enum NowTagError: Error {
+    case invalidFormatParameter
+    case tooManyParameters
+}
+
+struct NowTag: LeafTag {
+    func render(_ ctx: LeafContext) throws -> LeafData {
+        let formatter = DateFormatter()
+        switch ctx.parameters.count {
+        case 0: formatter.dateFormat = "yyyy-MM-dd HH:mm:ss"
+        case 1:
+            guard let string = ctx.parameters[0].string else {
+                throw NowTagError.invalidFormatParameter
+            }
+
+            formatter.dateFormat = string
+        default:
+            throw NowTagError.tooManyParameters
+        }
+
+        let dateAsString = formatter.string(from: Date())
+        return LeafData.string(dateAsString)
+    }
+}
+```
+
+### 配置标签
+
+实现了 `NowTag`，告诉 `Leaf` 并设置标签名称为 `#now`
+
+```swift
+app.leaf.tags["now"] = NowTag()
+```
+
+现在可以在 Leaf 中使用我们的自定义标签 `#now` 了
+
+```html
+The time is #now()
+```
+
+### 上下文属性
+
+#### `parameters`： 包含标签参数的数组
+
+```swift
+struct NowTag: LeafTag {
+  func render(
+    _ ctx: LeafContext
+  ) throws -> LeafData {
+      /// ctx.parameters
+  }
+}
+```
+
+#### 使用 Data，`render(_:_:)` 方法作为上下文视图的数据
+
+```swift
+return try await req.view.render(
+  "home", ["name": "John"]
+)
+```
+
+```swift
+struct NowTag: LeafTag {
+  func render(
+    _ ctx: LeafContext
+  ) throws -> LeafData {
+      let name = ctx.data["name"]?.string
+  }
+}
+```
+
+`LeafContext` 包含两个重要的属性