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

MaintainerAndrea Rossato <>
Safe HaskellNone




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 and JSON formatted bibliographic databases. The JSON format is only partially documented. It is used by citeproc-js, by the CSL processor test-suite and is derived by the CSL scheme. More information can be read here:

A (git) repository of styles can be found here:

Overview: A Simple Example

The following example assumes you have installed citeproc-hs with hs-bibutils support (which is the default).

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

 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 styles that come with the test-suite for CSL processors. Suppose this one:

saved locally as apa-x.csl.

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

 import Text.CSL

 cites :: [Cite]
 cites = [emptyCite { citeId = "Caso2007"
                    , citeLabel = "page"
                    , citeLocator = "15"}
         ,emptyCite { citeId = "Rossato2006"
                    , citeLabel = "page"
                    , citeLocator = "10"}

 main :: IO ()
 main = do
   m <- readBiblioFile "mybibdb.bib"
   s <- readCSLFile "apa-x.csl"
   let result = citeproc procOpts s m $ [cites]
   putStrLn . unlines . map (renderPlainStrict) . citations $ result

The result would be:

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

Reading Bibliographic Databases

readBiblioFile :: FilePath -> IO [Reference]Source

Read a file with a bibliographic database. The database format is recognized by the file extension.

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

readModsFile :: FilePath -> IO ReferenceSource

Read a file with a single MODS record.

readModsCollectionFile :: FilePath -> IO [Reference]Source

Read a file with a collection of MODS records.

Reference Representation

data Reference Source

The Reference record.




refId :: String
refType :: RefType
author :: [Agent]
editor :: [Agent]
translator :: [Agent]
recipient :: [Agent]
interviewer :: [Agent]
composer :: [Agent]
director :: [Agent]
illustrator :: [Agent]
originalAuthor :: [Agent]
containerAuthor :: [Agent]
collectionEditor :: [Agent]
editorialDirector :: [Agent]
reviewedAuthor :: [Agent]
issued :: [RefDate]
eventDate :: [RefDate]
accessed :: [RefDate]
container :: [RefDate]
originalDate :: [RefDate]
submitted :: [RefDate]
title :: String
titleShort :: String
reviewedTitle :: String
containerTitle :: String
volumeTitle :: String
collectionTitle :: String
containerTitleShort :: String
collectionNumber :: String
originalTitle :: String
publisher :: String
originalPublisher :: String
publisherPlace :: String
originalPublisherPlace :: String
authority :: String
jurisdiction :: String
archive :: String
archivePlace :: String
archiveLocation :: String
event :: String
eventPlace :: String
page :: String
pageFirst :: String
numberOfPages :: String
version :: String
volume :: String
numberOfVolumes :: String
issue :: String
chapterNumber :: String
medium :: String
status :: String
edition :: String
section :: String
source :: String
genre :: String
note :: String
annote :: String
abstract :: String
keyword :: String
number :: String
references :: String
url :: String
doi :: String
isbn :: String
issn :: String
pmcid :: String
pmid :: String
callNumber :: String
dimensions :: String
scale :: String
categories :: [String]
language :: String
citationNumber :: CNum
firstReferenceNoteNumber :: Int
citationLabel :: String

setNearNote :: Style -> [[Cite]] -> [[Cite]]Source

CSL Parser, Representation, and Processing

readCSLFile :: FilePath -> IO StyleSource

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

parseCSL :: String -> IO StyleSource

Parse a String into a fully localized Style

The Style Types

data Affix Source


Eq Affix 
Data Affix 
Ord Affix 
Read Affix 
Show Affix 
Typeable Affix 
JSON Affix

Needed for the test-suite.

High Level Processing

data ProcOpts Source




bibOpts :: BibOpts

citeproc :: ProcOpts -> Style -> [Reference] -> Citations -> BiblioDataSource

With a Style, a list of References and the list of Citations, produce the FormattedOutput for each citation group and the bibliography.

processCitations :: ProcOpts -> Style -> [Reference] -> Citations -> [[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 :: ProcOpts -> 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.


FO Formatting [FormattedOutput]

List of FormatOutput items

FN String Formatting

Formatted number

FS String Formatting

Formatted string

FDel String

Delimeter string

FUrl Target Formatting

Formatted URL

FPan [Inline]

Pandoc inline elements


Null formatting item

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] -> [Inline]Source

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

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

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