citeproc-hs-0.2: A Citation Style Language implementation in Haskell

MaintainerAndrea Rossato <>




citeproc-hs is a library for automatically formatting bibliographic reference citations into a variety of styles using a macro language called Citation Style Language (CSL). More details on CSL can be found here:

This module documents and exports the library API.



citeproc-hs provides functions for reading bibliographic databases, for reading and parsing CSL files and for generating citations in an internal format, FormattedOutput, that can be easily rendered into different final formats. At the present time only Pandoc and plain text rendering functions are provided by the library.

The library also provides a wrapper around hs-bibutils, the Haskell bindings to Chris Putnam's bibutils, a library that interconverts between various bibliography formats using a common MODS-format XML intermediate.

For more information about hs-bibutils see here:

citeproc-hs can natively read MODS formatted bibliographic databases.

Overview: A Simple Example

The following example assumes you have properly installed hs-bibutils. If not you can use bibutils to convert the following bibtex bibliographic database into a MODS collection.

Suppose you have a small bibliographic database, like this one:

 author="Andrea Rossato",
 title="My First Book",

 author="Andrea Rossato",
 title="My Second Book",

 author="Roberto Caso",
 title="Roberto's Book",

Save it as mybibdb.bib.

Then you can grab one of the CSL style developed by the Zotero community. Suppose this one:

saved locally as apa.csl.

This would be a simple program that formats a list of citations according to that style:

 import Text.CSL

 main :: IO ()
 main = do
   m <- readBiblioFile "mybibdb.bib" "bibtex"
   s <- readCSLFile "apa.csl"
   let result = citeproc s m $ [[("Caso2007","p. 10"),("Rossato2005","p. 10"),("Rossato2006","p. 15")]]
   putStrLn . unlines . map (renderPlainStrict) . citations $ result

The result would be:

 (Caso, 2007, p. 10; Rossato, 2005, p. 10, 2006, p. 15)

Reading Bibliographic Databases

readBiblioFile :: FilePath -> String -> IO [Reference]Source

Read a file with a bibliographic database of the format specified by the String. If the String is empty the file extension will be used to identify the format.

Supported formats are: "mods", "bibtex", "biblatex", "ris", "endnote", "endnotexml", "isi", "medline", and "copac".

readModsFile :: FilePath -> IO ReferenceSource

Read a file with a single MODS record.

readModsColletionFile :: FilePath -> IO [Reference]Source

Read a file with a collection of MODS records.

Reference Representation

getReference :: [Reference] -> (String, String) -> ReferenceSource

With the list of References and the tuple (citation key, locator), return the needed reference with the correct locator set.

CSL Parser, Representation, and Processing

readCSLFile :: FilePath -> IO StyleSource

Read and parse a CSL style file into the internal style representation, the Style.

The Style Types

data Style Source

The representation of a parsed CSL style.

High Level Processing

citeproc :: Style -> [Reference] -> [[(String, String)]] -> BiblioDataSource

With a Style, a list of References and the list of citation groups (the list of citations with their locator), produce the FormattedOutput for each citation group and the bibliography.

processCitations :: Style -> [Reference] -> [[(String, String)]] -> [[FormattedOutput]]Source

With a Style, a list of References and the list of citation groups (the list of citations with their locator), produce the FormattedOutput for each citation group.

processBibliography :: Style -> [Reference] -> [[FormattedOutput]]Source

With a Style and the list of References produce the FormattedOutput for the bibliography.

data BiblioData Source




The output and the rendering functions

data FormattedOutput Source

The formatted output, produced after post-processing the evaluated citations.

renderPlain :: [FormattedOutput] -> StringSource

Render the FormattedOutput into a plain text string.

renderPlainStrict :: [FormattedOutput] -> StringSource

Same as renderPlain , but will not clean up the produced output.

renderPandoc :: Style -> [FormattedOutput] -> StringSource

With a Style and the formatted output generate a String in the native Pandoc formats (i.e. immediately readable by pandoc).

renderPandoc' :: Style -> [FormattedOutput] -> StringSource

Same as renderPandoc, but the output is wrapped in a pandoc paragraph block.

renderPandocStrict :: [FormattedOutput] -> StringSource

Same as renderPandoc, but will not clean up the produced output.