欢迎使用 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，然后将该属性化的字符串绘制到图形上下文中，将其转换为图像，然后写入磁盘。

$ 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 上告诉我您的想法😊

用法

🌍 在 Web 上

🖥 在命令行上

SplashHTMLGen

SplashMarkdown

SplashImageGen

SplashTokenizer

📦 作为包

安装

📦 作为包

🛠 命令行工具

贡献与支持

希望您喜欢使用 Splash！