• Stars
    star
    1,758
  • Rank 26,474 (Top 0.6 %)
  • Language
    Swift
  • License
    MIT License
  • Created about 6 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A fast, lightweight and flexible Swift syntax highlighter for blogs, tools and fun!

Splash

Swift Package Manager Mac + Linux Twitter: @johnsundell

Welcome to Splash - a fast, lightweight and flexible Swift syntax highlighter. It can be used to generate code sample HTML for a blog post, to turn a string of Swift code into a fully syntax highlighted image, or to build custom developer tools.

It's used to highlight all articles on swiftbysundell.com.

Usage

Splash can be used either as a library in your own Swift Package Manager-powered tool or script, or by using one of the four built-in command line tools that act as frontends for the Splash library.

๐ŸŒ On the web

If you're using Publish, then there's an official plugin that makes it easy to integrate Splash into your website:

๐Ÿ‘‰ SplashPublishPlugin

If you're using Jekyll, there's also a custom {% splash %} tag available for the Liquid templating language.

๐Ÿ‘‰ splashtag

๐Ÿ–ฅ On the command line

The easiest way to get started building things with Splash is to use one of the four built-in command line tools that each enable you to use Splash in different ways.

SplashHTMLGen

SplashHTMLGen uses Splash's HTML output format to generate an HTML string from Swift code. You simply pass it the code you want to highlight as an argument and HTML is returned as standard output.

For example, if you call it like this:

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

You'll get the following output back:

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

To be as flexible as possible, Splash doesn't hardcode any colors or other CSS attributes in the HTML it generates. Instead it simply assigns a CSS class to each token. For an example of a CSS file that can be used to style Splash-generated HTML, see Examples/sundellsColors.css.

When rendering your outputted html, make sure to wrap your output code in the <pre> and <code> tags and properly link to your .css file. Like this:

<!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>

For more information about HTML generation with Splash and how to customize it, see HTMLOutputFormat here.

SplashMarkdown

SplashMarkdown builds on top of SplashHTMLGen to enable easy Splash decoration of any Markdown file. Pass it a path to a Markdown file, and it will iterate through all code blocks within that file and convert them into Splash-highlighted HTML.

Just like the HTML generated by SplashHTMLGen itself, a CSS file should also be added to any page serving the processed Markdown, since Splash only adds CSS classes to tokens โ€” rather than hardcoding styles inline. See the above SplashHTMLGen documentation for more information.

Hereโ€™s an example call to decorate a Markdown file at the path ~/Documents/Article.md:

$ SplashMarkdown ~/Documents/Article.md

The decorated Markdown will be returned as standard output.

Highlighting can be skipped for any code block by adding no-highlight next to the blockโ€™s opening row of backticks โ€” like this: โ€œ```no-highlightโ€.

SplashImageGen

SplashImageGen uses Splash to generate an NSAttributedString from Swift code, then draws that attributed string into a graphics context to turn it into an image, which is then written to disk.

For example, if you call it like this:

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

The following image will be generated (and written to disk as MyImage.png):

Code sample

SplashImageGen is currently only available on macOS.

SplashTokenizer

The final built-in command line tool, SplashTokenizer, is mostly useful as a debugging tool when working on Splash - but can also be interesting to use in order to see how Splash breaks down code into tokens. Given a string of Swift code, it simply outputs all of its components (excluding whitespaces).

So if you call it like this:

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

You'll get the following standard output back:

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

๐Ÿ“ฆ As a package

To include Splash in your own script or Swift package, add it as a dependency and use the SyntaxHighlighter class combined with your output format of choice to highlight a string of code:

import Splash

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

Splash ships with two built-in output formats - HTML and NSAttributedString, but you can also easily add your own by implementing the OutputFormat protocol.

Installation

Splash is distributed as a Swift package, making it easy to install for use in scripts, developer tools, server-side applications, or to use its built-in command line tools.

Splash supports both macOS and Linux.

Before you begin, make sure that you have a Swift 5.2-compatible toolchain installed (for example Xcode 11.5 or later if you're on a Mac).

๐Ÿ“ฆ As a package

To install Splash for use in a Swift Package Manager-powered tool or server-side application, add Splash as a dependency to your Package.swift file. For more information, please see the Swift Package Manager documentation.

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

๐Ÿ›  Command line tools

If you want to use Splash through one of its built-in command line tools, start by cloning the repo to your local machine:

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

To run a tool without installing it, you can use the Swift Package Manager's run command, like this:

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

To install all four command line tools globally on your system, use Make:

$ make install

That will install the following four tools in your /usr/local/bin folder:

SplashHTMLGen
SplashMarkdown
SplashImageGen
SplashTokenizer

If you only wish to install one of these, compile it and then move it to /usr/local/bin, like this:

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

Contributions and support

Splash is developed completely in the open, and your contributions are more than welcome. It's still a very new project, so I'm sure there are bugs to be found and improvements to be made - and hopefully we can work on those together as a community.

This project does not come with GitHub Issues-based support, and users are instead encouraged to become active participants in its continued development โ€” by fixing any bugs that they encounter, or by improving the documentation wherever it's found to be lacking.

To read more about suggested workflows when contributing to Splash, how to report bugs and feature requests, as well as technical details and an architectural overview - check out the Contributing Guide.

Hope you enjoy using Splash!

I had a lot of fun building Splash, and I'm looking forward to continue working on it in the open together with you! I hope you'll like it and that you'll find it useful. Let me know what you think on Twitter ๐Ÿ˜Š

More Repositories

1

Publish

A static site generator for Swift developers
Swift
4,840
star
2

SwiftTips

A collection of Swift tips & tricks that I've shared on Twitter
3,971
star
3

Files

A nicer way to handle files & folders in Swift
Swift
2,456
star
4

Ink

A fast and flexible Markdown parser written in Swift.
Swift
2,377
star
5

Plot

A DSL for writing type-safe HTML, XML and RSS in Swift.
Swift
1,979
star
6

Unbox

[Deprecated] The easy to use Swift JSON decoder
Swift
1,956
star
7

Marathon

[DEPRECATED] Marathon makes it easy to write, run and manage your Swift scripts ๐Ÿƒ
Swift
1,863
star
8

ImagineEngine

A project to create a blazingly fast Swift game engine that is a joy to use ๐Ÿš€
Swift
1,825
star
9

SwiftPlate

Easily generate cross platform Swift framework projects from the command line
Swift
1,766
star
10

TestDrive

Quickly try out any Swift pod or framework in a playground
Swift
1,597
star
11

Codextended

Extensions giving Swift's Codable API type inference super powers ๐Ÿฆธโ€โ™‚๏ธ๐Ÿฆนโ€โ™€๏ธ
Swift
1,495
star
12

ShellOut

Easily run shell commands from a Swift script or command line tool
Swift
836
star
13

Wrap

[DEPRECATED] The easy to use Swift JSON encoder
Swift
732
star
14

CollectionConcurrencyKit

Async and concurrent versions of Swiftโ€™s forEach, map, flatMap, and compactMap APIs.
Swift
730
star
15

Sweep

Fast and powerful Swift string scanning made simple
Swift
531
star
16

Playground

Instantly create Swift playgrounds from the command line
Swift
439
star
17

Require

Require optional values to be non-nil, or crash gracefully
Swift
414
star
18

XcodeTheme

My Xcode theme - Sundell's Colors
Swift
408
star
19

AsyncCompatibilityKit

iOS 13-compatible backports of commonly used async/await-based system APIs that are only available from iOS 15 by default.
Swift
378
star
20

Shapeshift

Quickly convert a folder containing Swift files into an iPad-compatible Playground
Swift
338
star
21

Identity

๐Ÿ†” Type-safe identifiers in Swift
Swift
298
star
22

SwiftBySundell

Code samples from the Swift by Sundell website & podcast
Swift
289
star
23

SwiftScripting

A list of Swift scripting tools, frameworks & examples
235
star
24

SuperSpriteKit

Extensions to Apple's SpriteKit game engine
Objective-C
224
star
25

Flow

Operation Oriented Programming in Swift
Swift
217
star
26

Xgen

A Swift package for generating Xcode workspaces & playgrounds
Swift
189
star
27

IndieSupportWeeks

A two-week effort to help support indie developers shipping apps on Apple's platforms who have been financially impacted by the COVID-19 pandemic.
182
star
28

CGOperators

Easily manipulate CGPoints, CGSizes and CGVectors using math operators
Swift
148
star
29

Animate

Declarative UIView animations without nested closures
Swift
129
star
30

SplashPublishPlugin

A Splash plugin for the Publish static site generator
Swift
92
star
31

Assert

A collection of convenient assertions for Swift testing
Swift
69
star
32

UITestingExample

Example code from my blog post about UI testing
Swift
67
star
33

Marathon-Examples

A collection of example Swift scripts that can easily be run using Marathon
Swift
55
star
34

Releases

A Swift package for resolving released versions from a Git repository
Swift
51
star
35

BlockSnippets

Xcode snippets that are very handy when working with blocks in various contexts
51
star
36

PlotPlayground

A Swift playground that comes pre-loaded with Plot, that can be used to explore the new component API.
Swift
49
star
37

SwiftKit

A collection of Swift utilities that I share across my Swift-based projects
Swift
38
star
38

UnitTestingWorkshop

Project used during my workshop "Getting started with unit testing in Swift"
Swift
36
star
39

JSUpdateLookup

A lightweight, easy to use Objective-C class to check if your iOS app has an update available
Objective-C
28
star
40

SwiftAveiro

Skeleton project for my Swift Aveiro workshop "Everyone is an API designer"
Swift
15
star
41

CloudKitChat

A demo chat application powered by CloudKit
Objective-C
14
star
42

swiftbysundell-beta-feedback

Submit your feedback on the Swift by Sundell 2.0 beta
9
star
43

JSGeometry

A set of utility functions that enables easy one-line manipulation of CoreGraphics geometry structs like CGPoint, CGSize & CGRect.
Objective-C
6
star
44

JSAutoCopy

An Objective-C category that enables automatic copying of any object
Objective-C
4
star
45

UnboxDemoPlayground

A Swift Playground that comes setup with Unbox & Wrap, used in my CocoaHeads Stockholm presentation
Swift
3
star
46

JSAutoEncodedObject

Automatically encode or decode any Objective-C object
Objective-C
3
star
47

JSLocalization

An Objective-C class that enables dynamic localization of an iOS app.
Objective-C
3
star
48

MarathonTestScriptWithDependencies

A test script with dependencies - used for Marathon's tests
Swift
2
star
49

JSObservableObject

Easily add protocol-based observation to any Objective-C class
Objective-C
2
star
50

MarathonTestScript

A Swift script that's used in Marathon's tests
Swift
1
star
51

MarathonTestPackage

A Swift package that's used in Marathon's tests
Swift
1
star