Brick.Widgets.Skylighting

This module provides an API for building Brick widgets to display syntax-highlighted text using the Skylighting library.

To use this module, you'll need to:

• have some Text you want to syntax-highlight.
• know the language in which the Text is expressed.
• have a Skylighting Style you'd like to use to determine the colors, either from the Skylighting package or one of your own.

To highlight some text in your user interface, use one of the (increasingly finer-grained) highlighting functions simpleHighlight, highlight, highlight', or renderRawSource.

To actually see pretty colors, you'll need to update your application's AttrMap with name-to-color mappings. Those can be built from a Skylighting Style with attrMappingsForStyle and then appended to your attrMap mapping list.

The highlighted code widget produced by this module uses highlightedCodeBlockAttr as its base attribute and then uses a specific attribute for each kind of Skylighting token as per attrNameForTokenType.

See the programs/Demo.hs program in this package for an example of a complete program that uses this module.

Highlighting functions

simpleHighlight

Arguments

:: Text

The Skylighting name of the language in which the input text is written.

-> Text

The text to be syntax-highlighted.

-> Widget n

The simplest way to highlight some text. If the specified language does not have a corresponding Skylighting parser or if a parser is found but fails to parse the input, the text is rendered as-is and tab characters are converted to eight spaces.

highlight

Arguments

:: Syntax

The syntax to use to parse the input text.

-> Text

The text to be syntax-highlighted.

-> Widget n

If you already have a Syntax handy, this provides more control than simpleHighlight.

highlight'

Arguments

:: (Text -> Widget n)

The token widget constructor.

-> Syntax

The syntax to use to parse the input text.

-> Text

The text to be syntax-highlighted.

-> Widget n

If you already have a Syntax handy and want to have control over how each Text token in the Skylighting AST gets converted to a Widget, this provides more control than highlight, which just defaults the text widget constructor to txt. If the specified parser fails to parse the input, the text is displayed as-is and tab characters are converted to eight spaces.

renderRawSource

Arguments

:: (Text -> Widget n)

The token widget constructor.

-> [SourceLine]

The parsed input.

-> Widget n

If you have already parsed your input text into Skylighting tokens, this function is the best one to use.

Attributes

attrMappingsForStyle :: Style -> [(AttrName, Attr)]

Given a Skylighting Style, build an equivalent list of Brick-compatible AttrMap entries. This will usually return 256-color entries.

attrNameForTokenType :: TokenType -> AttrName

The constructor for attribute names for each TokenType in Skylighting.

highlightedCodeBlockAttr :: AttrName

The base attribute name for all syntax-highlighted renderings.