hscolour


hscolour is a small Haskell script to colourise Haskell code. It currently has six output formats: ANSI terminal codes, HTML 3.2 with <font> tags, HTML 4.01 with CSS, XHTML 1.0 with inline CSS styling, LaTeX, and mIRC chat client codes.

Example

Here's a little example of the HTML output:

    module Main (main) where
    import Prelude 
    
    -- The notorious nfib "benchmark", but using Doubles.
    main = print (nfib 30)
    
    nfib :: Double -> Double
    nfib n = if n <= 1
             then 1
             else nfib (n`subtract`1) + nfib (n`subtract`2) + 1

Download

  • Find it on Hackage.
  • Or use the darcs repository at
    darcs get http://code.haskell.org/hscolour

Build

Just use one of the standard ways of building a Haskell program:

  • cabal install hscolour
  • hmake HsColour
  • ghc --make HsColour
  • runhugs HsColour
  • runhaskell Setup.hs configure/build/install

Use

  • HsColour [ -help | -version | -print-css ]
             [ -oOUTPUT ]
             [ -tty | -html | -css | -icss | -latex | -mirc ]
             [ -lit | -lit-tex | -nolit ]
             [ -anchor | -noanchor | -partial | -nopartial ]
             [ --annot=FILE ]
             [file.hs]*

You can colourise a Haskell source file for either ANSI terminal codes (option -tty), or HTML 3.2 with font tags (option -html), or HTML 4.01 output with CSS (option -css), or for XHTML 1.0 with inline CSS styling (option -icss), or for LaTeX (option -latex), or for IRC (option -mirc). The default is for terminal output.

If no file argument is given, it reads standard input. Output is written to file OUTPUT (option -o), defaulting to stdout. Multiple input files will be concatenated to the same output.

HsColour can add named anchors in HTML (option -anchor) to top-level definitions in the source file (functions, datatypes, classes). This enables you to make links to a specific location in the generated file with the standard file.html#anchor notation (e.g. from haddock-generated library documentation). See below for details.

If you have externally-generated type information for identifiers (e.g. by Haddock), it can be displayed as mouseover tooltips in the output of HsColour. See below for details.

If an input file is literate, that is, it has a suffix ".lhs" or ".ly" or ".lx", then only the code fragments will be colourised, leaving the commentary untouched. You can explicitly override this filename-guessing of literate status: use the -lit option to force literate colouring, or -nolit to force all text to be colourised. (-lit-tex is an obsolete synonym for -lit)

For more advanced usage, if you are building documents in parts, and you want to embed several individual colourised fragments into a larger document, use the -partial option with each fragment, to omit the HTML DOCTYPE header, CSS stylesheet link, or LaTeX prologue.

Configuration of colours

If you use any output-format choice except -css, you can configure the colours for different lexical entities by editing a configuration file called .hscolour in the current directory. (An example is included in the distribution.) For (non-inline) CSS output, it is sufficient to edit the hscolour.css file, also in the distribution. (An alternative choice is supplied as emacs.css.) The -print-css option prints out the default CSS definitions, in case you lose the .css file.

The .hscolour file format is a simple Haskell value of type ColourPrefs, constructed using named fields, as follows:

  data ColourPrefs = ColourPrefs
    { keyword, keyglyph, layout, comment
    , conid, varid, conop, varop
    , string, char, number , cpp
    , selection, variantselection
    , definition :: [Highlight]
    }

  data Colour = Black | Red | Green | Yellow | Blue | Magenta | Cyan | White

  data Highlight =
      Normal
    | Bold
    | Dim
    | Underscore
    | Blink
    | ReverseVideo
    | Concealed
    | Foreground Colour
    | Background Colour
    | Italic

Use it as a library

If you want to incorporate hscolour-like functionality into your own Haskell program, it is now (from 1.4) also available as a library, thanks to Björn Bringert. The library is Cabal-ised, so just do the usual thing to install it as a package:
  • runhaskell Setup.hs configure
  • runhaskell Setup.hs build
  • runhaskell Setup.hs install
There is haddock documentation of the API.

Using HsColour with Haddock

Let's say you want to generate some pretty-coloured HTML versions of your source files, at the same time as you are generating library documentation using Haddock. Haddock (0.8 onwards) has options to link the API docs to the source code itself. Here is a quick summary of the shell commands to use:
for file in $(SRCS)
do HsColour -html -anchor $file >docs/`dirname $file`/`basename $file .hs`.html
done
haddock --html --title="My Library" --odir=docs   $(SRCS) \
    --source-module="src/%{MODULE/.//}.html" \
    --source-entity="src/%{MODULE/.//}.html#%{NAME}"

Mouseover type information

Since version 1.18, HsColour has the ability to add mouseover tooltips that display the type of each variable identifier at its usage points. The type annotations are generated separately by Haddock using --annot=FILE, and the resulting file is given to HsColour with the similar argument --annot=FILE.

Copyright and licence

hscolour is © Malcolm Wallace 2003-2012. It is distributed under the Gnu GPL, which can be found in the file LICENCE-GPL.

Shortcomings

HsColour is not yet able to add anchors to class methods, nor to foreign decls.

Alternatives

The Programatica project has a more sophisticated HTML syntax-highlighter. It hyperlinks every usage of an identifier to its definition, which is highly useful for browsing large amounts of code. However, it is a more heavyweight solution as well - requiring the entire front-end of a compiler not only to parse the Haskell code, but to chase all its module dependencies as well. As a consequence, you need source access to every definition used in your program, including the Prelude and all library packages...

History

1.20
add anchors to instance decls
1.19
make it build with ghc-7.0.x
1.18
add --annot argument for mouseover type information
1.17
declare UTF-8 encoding in HTML/CSS output
1.16
deal with UTF-8 sources in ghc-6.12.x
1.15
makes -nopartial the default for literate files
1.14
merges the -lit and -lit-tex options, adds -lit guessing, and permits multiple input files
1.13
added the new -icss output format, and italic highlights
1.12
changed the CSS class names to avoid clashes with other web tools
1.11
new literate input option -lit-tex
1.10.1
reports the correct version with the --version flag
1.10
the title of HTML output is now the filename
1.9
added the -mirc and -lit options, and -print-css
1.8
added highlights for cpp lines
tuple constructors now treated as ConIds
checked for absence of pattern-match failure by Catch
1.7
renamed -anchorHTML -anchorCSS options to -anchor, added -partial option
1.6
added -latex output mode
1.5
move generated HTML anchors to before comments/typesigs
1.4
made available as a Cabal-ised library
1.3
added HTML and CSS anchors
1.2
added CSS output mode (from Neil Mitchell)
1.1
fixed compatibility with ghc-6.4
1.0
first release

This page last modified: 29th May 2012
Malcolm Wallace