dsabanin/pygmentskit

A library to wrap pygments formatting in a Cocoa library with support for NSAttributedStrings.

PygmentsKit

PygmentsKit is a small Cocoa framework that wraps pygmentize to obtain pygments tokens, and provides a method for turning these tokens into NSAttributedString attributes. PygmentsKit's AttributedParser uses tmTheme theme files, making PygmentsKit compatible with TextMate and Sublime Text theme files.

Requirements

• Xcode 8 or newer
• Mercurial (hg) on your PATH. You can install mercurial using homebrew by running brew install hg.

Installation

Carthage

Add the following line to your project's Cartfile:

github "notronik/PygmentsKit" "master"

Then run carthage update and add the PygmentsKit.framework files to your project.

Right now you have to use "master" in your Cartfile, as there are no tagged release versions.

Manually

I recommend that you use Carthage, but if you really don't want to or can't, you can also build PygmentsKit manually.

To do this, just open the xcodeproj file and build the framework like normal. If you need a release version, modify the build scheme as required.

There is no need to run the get_pygments.sh script. This script is used by the Xcode project to download and patch pygments from the project's repository. If you really want to run it manually, make sure that the working directory is the project root directory.

Using PygmentsKit

Just Tokens

import PygmentsKit
// ...
Parser.parse("my code string", with: "pygments lexer identifier") { (range, token) in
	// range is the range within the String.

	// token is an instance of `Token` that contains the token kind and substring
	// within the range.
}
// ...

Tokens and Theme Attributes

To use the AttributedParser you must provide a Theme. Theme loads and stores the scopes and colour attributes of a tmTheme file.

import PygmentsKit
// ...
// Create a Theme
guard let tmTheme = NSDictionary(contentsOfFile: "my_theme.tmTheme") as? [NSObject: AnyObject] else {
	// handle the error
}

let theme = Theme(data: tmTheme) // this also returns nil if creation fails
// ...

You can then parse the code string with the theme:

// ...
AttributedParser.parse("my code string", with: "pygments lexer identifier", theme: theme) { (range, token, attributes) in
	// attributes is an array of attributes that you can just set or add to your attributed string
}
// ...

Other Stuff

When you create a Theme, its constructor also loads the theme's global settings into memory. Global settings include things like the editor background colour, the text colour, the gutter colour, etc. To access these settings, use the Theme.Global enum to locate the associated colour in the global dictionary property of Theme. If the theme does not specify a colour, it will not be in this dictionary.

License

MIT -- see LICENSE.