scholdoc-citeproc-0.6: Scholdoc fork of pandoc-citeproc

Copyright(c) Andrea Rossato
LicenseBSD-style (see LICENSE)
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, Formatted, 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 Nothing "apa-x.csl"
  let result = citeproc procOpts s m $ [cites]
  putStrLn . unlines . map renderPlain . 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.

Reference Representation

data Reference Source

The Reference record.




refId :: Literal
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 :: Formatted
titleShort :: Formatted
reviewedTitle :: Formatted
containerTitle :: Formatted
volumeTitle :: Formatted
collectionTitle :: Formatted
containerTitleShort :: Formatted
collectionNumber :: Formatted
originalTitle :: Formatted
publisher :: Formatted
originalPublisher :: Formatted
publisherPlace :: Formatted
originalPublisherPlace :: Formatted
authority :: Formatted
jurisdiction :: Formatted
archive :: Formatted
archivePlace :: Formatted
archiveLocation :: Formatted
event :: Formatted
eventPlace :: Formatted
page :: Formatted
pageFirst :: Formatted
numberOfPages :: Formatted
version :: Formatted
volume :: Formatted
numberOfVolumes :: Formatted
issue :: Formatted
chapterNumber :: Formatted
medium :: Formatted
status :: Formatted
edition :: Formatted
section :: Formatted
source :: Formatted
genre :: Formatted
note :: Formatted
annote :: Formatted
abstract :: Formatted
keyword :: Formatted
number :: Formatted
references :: Formatted
url :: Literal
doi :: Literal
isbn :: Literal
issn :: Literal
pmcid :: Literal
pmid :: Literal
callNumber :: Literal
dimensions :: Literal
scale :: Literal
categories :: [Literal]
language :: Literal
citationNumber :: CNum
firstReferenceNoteNumber :: Int
citationLabel :: Literal

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

CSL Parser, Representation, and Processing

readCSLFile :: Maybe String -> FilePath -> IO Style Source

Read and parse a CSL style file into a localized sytle.

parseCSL :: String -> Style Source

Parse a String into a Style (with default locale).

localizeCSL :: Maybe String -> Style -> IO Style Source

Merge locale into a CSL style.

The Style Types

High Level Processing

data ProcOpts Source




bibOpts :: BibOpts

citeproc :: ProcOpts -> Style -> [Reference] -> Citations -> BiblioData Source

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

processCitations :: ProcOpts -> Style -> [Reference] -> Citations -> [Formatted] Source

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

processBibliography :: ProcOpts -> Style -> [Reference] -> [Formatted] Source

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

The output and the rendering functions

renderPlain :: Formatted -> String Source

Render the Formatted into a plain text string.