Public Interface

Highlights.jl is a Julia package for source code highlighting. It provides a regular expression based mechanism for creating lexers in a similar way to Pygments.

The following names are exported from the root module, Highlights, and are available for external use. Note that unexported names are considered unstable and subject to change.

• Format
• Lexers
• Themes
• Tokens
• highlight
• lexer
• stylesheet

Highlight source code using a specific lexer, mimetype and theme.

highlight(io, mime, src, lexer)
highlight(io, mime, src, lexer, theme)

src is tokenised using the provided lexer, then colourised using theme, and finally output to io in the given format mime. theme defaults to Themes.DefaultTheme theme.

mime can be either MIME("text/html") or MIME("text/latex").

Examples

julia> using Highlights

julia> highlight(stdout, MIME("text/html"), "2x", Lexers.JuliaLexer)
<pre class='hljl'>
<span class='hljl-ni'>2</span><span class='hljl-n'>x</span>
</pre>

julia> highlight(stdout, MIME("text/latex"), "'x'", Lexers.JuliaLexer, Themes.VimTheme)
\begin{lstlisting}
(*@\HLJLsc{{\textquotesingle}x{\textquotesingle}}@*)
\end{lstlisting}

lexer(name)

Return the AbstractLexer associated with the lexer named name. name must be a string. Internally this checks the :aliases field in each lexer definition to see whether it is a match.

When no lexer matches the given name an ArgumentError is thrown.

Generate a "stylesheet" for the given theme.

stylesheet(io, mime)
stylesheet(io, mime, theme)

Prints out the style information needed to colourise source code in the given theme. Note that theme defaults to Themes.DefaultTheme. Output is printed to io in the format mime. mine can be one of

• MIME("text/html")
• MIME("text/css")
• MIME("text/latex")

Examples

julia> using Highlights

julia> buf = IOBuffer();

julia> stylesheet(buf, MIME("text/css"), Themes.EmacsTheme)

A submodule that provides a selection of themes that can be used to colourise source code.

• AbstractTheme
• DefaultTheme
• EmacsTheme
• GitHubTheme
• MonokaiMiniTheme
• MonokaiTheme
• PygmentsTheme
• @S_str
• TangoTheme
• TracTheme
• VimTheme
• VisualStudioTheme
• XcodeTheme
• @theme

The default colour scheme with colours based on the Julia logo.

A theme based on the Emacs colour scheme.

A GitHub inspired colour scheme.

A colour scheme similar to the Monokai theme that works on both light and dark backgrounds.

A colour scheme similar to the Monokai theme.

Based on the default colour scheme used by the Pygments highlighter.

A Tango-inspired colour scheme.

Based on the default trac highlighter.

A Vim 7.0 based colour scheme.

A theme based on the default Visual Studio colours.

A theme based on the default Xcode colour scheme.

Construct a Style object.

Declare the theme definition for theme T based on dict. dict must be a Dict and T must be a subtype of AbstractTheme.

Examples

julia> using Highlights.Themes

julia> abstract type CustomTheme <: AbstractTheme end

julia> @theme CustomTheme Dict(
           :name => "Custom",
           :tokens => Dict(
               # ...
           )
       );

An exported submodule that provides a selection of lexer definitions for tokenising source code. The following names are exported from the module:

• AbstractLexer
• FortranLexer
• JuliaConsoleLexer
• JuliaLexer
• MatlabLexer
• RLexer
• TOMLLexer
• @lexer

A FORTRAN 90 source code lexer.

A lexer for Julia REPL sessions.

A lexer for Julia source code.

A lexer for MATLAB source code.

A lexer for the R language.

TOML (Tom's Obvious, Minimal Language) lexer.

Declare the lexer definition for a custom lexer T using a Dict object dict. dict must either be a Dict literal or an expression that returns a Dict – such as a let block.

Examples

julia> using Highlights.Lexers

julia> abstract type CustomLexer <: AbstractLexer end

julia> @lexer CustomLexer Dict(
           :name => "Custom",
           :tokens => Dict(
               # ...
           )
       );

This submodule provides a collection of token names for use in lexer and theme definitions. The table shown below lists all the exported tokens as well as the abbreviations used when printing stylesheets and highlighted source code.

The Format module provides a public interface that can be used to define custom formatters aside from the predefined HTML and LaTeX outputs supported by Highlights.

The Formatting section of the manual provides a example of how to go about extending Highlights to support additional output formats.

The following functions and types are exported from the module for public use:

• TokenIterator
• render

struct TokenIterator

An iterator type used in user-defined render methods to provide custom output formats. This type supports the basic Julia iterator protocol: namely iterate which enables for-loop interation over tokenised text.

The iterator returns a 3-tuple of str, id, and style where

• str is the SubString covered by the token;
• id is the shorthand name of the token type as a Symbol;
• style is the Style applied to the token.

The render function is used to define custom output formats for tokenised source code. Methods with signatures of the form

function Format.render(io::IO, mime::MIME, tokens::Format.TokenIterator)
    # ...
    for (str, id, style) in tokens
        # ...
    end
    # ...
end

can be defined for any mime type to allow the highlight function to support new output formats.