欢迎使用 Splash - 一个快速、轻量级且灵活的 Swift 语法高亮器。它可以用于为博客文章生成代码示例 HTML，将一段 Swift 代码转换为完全语法高亮显示的图像，或者构建自定义的开发者工具。

Splash 既可以作为库在您自己的 Swift Package Manager 支持的工具或脚本中使用，也可以使用作为 Splash 库前端的四个内置命令行工具之一。

如果您正在使用 Publish，那么有一个官方插件可以轻松地将 Splash 集成到您的网站中

如果您正在使用 Jekyll，那么 Liquid 模板语言还有一个自定义的 {% splash %} 标签。

开始使用 Splash 构建内容的最简单方法是使用四个内置命令行工具之一，每个工具都使您能够以不同的方式使用 Splash。

SplashHTMLGen 使用 Splash 的 HTML 输出格式从 Swift 代码生成 HTML 字符串。您只需将要高亮显示的代码作为参数传递给它，HTML 将作为标准输出返回。

$ SplashHTMLGen "func hello(world: String) -> Int"

<span class="keyword">func</span> hello(world: <span class="type">String</span>) -> <span class="type">Int</span>

为了尽可能灵活，Splash 不会在其生成的 HTML 中硬编码任何颜色或其他 CSS 属性。相反，它只是为每个 token 分配一个 CSS 类。有关可用于设置 Splash 生成的 HTML 样式的 CSS 文件的示例，请参见 Examples/sundellsColors.css。

在渲染输出的 html 时，请确保将输出代码包装在 <pre> 和 <code> 标签中，并正确链接到您的 .css 文件。像这样

<!DOCTYPE html>
<head>
    <title>Hello World</title>
    <link rel="stylesheet" href="sundellsColors.css">
</head>

<pre>
    <code>
        <span class="keyword">func</span> hello(world: <span class="type">String</span>) -> <span class="type">Int</span>
    </code>
</pre>

有关使用 Splash 生成 HTML 以及如何自定义它的更多信息，请参见这里的 HTMLOutputFormat。

SplashMarkdown 构建于 SplashHTMLGen 之上，可以轻松地对任何 Markdown 文件进行 Splash 装饰。将 Markdown 文件的路径传递给它，它将遍历该文件中的所有代码块，并将它们转换为 Splash 高亮显示的 HTML。

就像 SplashHTMLGen 本身生成的 HTML 一样，CSS 文件也应添加到提供处理后的 Markdown 的任何页面中，因为 Splash 仅将 CSS 类添加到 token 中，而不是内联硬编码样式。有关更多信息，请参见上面的 SplashHTMLGen 文档。

这是一个示例调用，用于装饰路径 ~/Documents/Article.md 中的 Markdown 文件

$ SplashMarkdown ~/Documents/Article.md

可以通过在代码块的开头行的反引号旁边添加 no-highlight 来跳过任何代码块的高亮显示 - 像这样：“```no-highlight”。

SplashImageGen 使用 Splash 从 Swift 代码生成一个 NSAttributedString，然后将该 attributed string 绘制到图形上下文中以将其转换为图像，然后将其写入磁盘。

$ SplashImageGen "func hello(world: String) -> Int" "MyImage.png"

最后一个内置命令行工具 SplashTokenizer 主要用作在 Splash 上工作时的调试工具 - 但也可以用来了解 Splash 如何将代码分解为 token。给定一个 Swift 代码字符串，它只是输出其所有组件（不包括空格）。

$ SplashTokenizer "func hello(world: String) -> Int"

Keyword token: func
Plain text: hello(world:
Type token: String
Plain text: )
Plain text: ->
Type token: Int

要将 Splash 包含在您自己的脚本或 Swift 包中，将其添加为依赖项，并使用 SyntaxHighlighter 类与您选择的输出格式相结合来高亮显示代码字符串

import Splash

let highlighter = SyntaxHighlighter(format: HTMLOutputFormat())
let html = highlighter.highlight("func hello() -> String")

Splash 附带两种内置输出格式 - HTML 和 NSAttributedString，但您也可以通过实现 OutputFormat 协议轻松添加自己的格式。

Splash 作为 Swift 软件包分发，可以轻松安装以用于脚本、开发者工具、服务器端应用程序或使用其内置命令行工具。

在开始之前，请确保您已安装与 Swift 5.2 兼容的工具链（例如，如果您使用的是 Mac，则为 Xcode 11.5 或更高版本）。

要安装 Splash 以用于 Swift Package Manager 支持的工具或服务器端应用程序，请将 Splash 作为依赖项添加到您的 Package.swift 文件。有关更多信息，请参见 Swift Package Manager 文档。

.package(url: "https://github.com/JohnSundell/Splash", from: "0.1.0")

如果您想通过其内置命令行工具之一使用 Splash，请首先将 repo 克隆到您的本地计算机

$ git clone https://github.com/johnsundell/splash.git
$ cd splash

要在不安装工具的情况下运行工具，可以使用 Swift Package Manager 的 run 命令，如下所示

$ swift run SplashHTMLGen "func hello(world: String) -> Int"

$ make install

SplashHTMLGen
SplashMarkdown
SplashImageGen
SplashTokenizer

如果您只想安装其中一个，请编译它，然后将其移动到 /usr/local/bin，如下所示

$ swift build -c release -Xswiftc -static-stdlib
$ install .build/release/SplashHTMLGen /usr/local/bin/SplashHTMLGen

Splash 完全开放地开发，并且非常欢迎您的贡献。它仍然是一个非常新的项目，所以我相信肯定有待发现的错误和有待改进的地方 - 希望我们可以作为一个社区共同努力。

此项目不提供基于 GitHub Issues 的支持，而是鼓励用户积极参与其持续开发 - 通过修复他们遇到的任何错误，或通过改进发现不足的文档。

要了解更多有关贡献 Splash 时的建议工作流程、如何报告错误和功能请求，以及技术细节和架构概述 - 请查看贡献指南。

我构建 Splash 的过程非常愉快，并且我期待着继续与您一起开放地进行开发！我希望您会喜欢它，并且发现它有用。请在 Twitter 上告诉我您的想法 😊

用法

🌍 在网页上

🖥 在命令行中

SplashHTMLGen

SplashMarkdown

SplashImageGen

SplashTokenizer

📦 作为软件包

安装

📦 作为软件包

🛠 命令行工具

贡献和支持

希望您喜欢使用 Splash！