Text.CSL

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: http://citationstyles.org/.

This module documents and exports the library API.

Introduction

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: http://hackage.haskell.org/package/hs-bibutils.

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: http://citationstyles.org/.

A (git) repository of styles can be found here: https://github.com/citation-style-language/styles.

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:

@Book{Rossato2006,
author="Andrea Rossato",
title="My Second Book",
year="2006"
}

@Book{Caso2007,
author="Roberto Caso",
title="Roberto's Book",
year="2007"
}

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:

https://bitbucket.org/bdarcus/citeproc-test/raw/18141149d1d3/styles/apa-x.csl

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]

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.

data BibFormat

Constructors

Json

Yaml

Bibtex

BibLatex

Ris

Endnote

EndnotXml

Isi

Medline

Copac

Mods

readBiblioString :: BibFormat -> String -> IO [Reference]

Reference Representation

data Reference

The Reference record.

Constructors

Reference

Fields

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

Instances

Eq Reference

Data Reference

Read Reference

Show Reference

Generic Reference

ToJSON Reference

FromJSON Reference

Typeable * Reference

type Rep Reference

getReference :: [Reference] -> Cite -> Maybe Reference

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

CSL Parser, Representation, and Processing

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

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

parseCSL :: String -> Style

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

parseCSL' :: ByteString -> Style

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

Merge locale into a CSL style.

The Style Types

data Style

The representation of a parsed CSL style.

Constructors

Style

Fields

styleVersion :: String

styleClass :: String

styleInfo :: Maybe CSInfo

styleDefaultLocale :: String

styleLocale :: [Locale]

styleAbbrevs :: Abbreviations

csOptions :: [Option]

csMacros :: [MacroMap]

citation :: Citation

biblio :: Maybe Bibliography

Instances

Data Style

Read Style

Show Style

Generic Style

Typeable * Style

type Rep Style

data Citation

Constructors

Citation

Fields

citOptions :: [Option]

citSort :: [Sort]

citLayout :: Layout

Instances

Data Citation

Read Citation

Show Citation

Generic Citation

Typeable * Citation

type Rep Citation

data Bibliography

Constructors

Bibliography

Fields

bibOptions :: [Option]

bibSort :: [Sort]

bibLayout :: Layout

Instances

Data Bibliography

Read Bibliography

Show Bibliography

Generic Bibliography

Typeable * Bibliography

type Rep Bibliography

data Cite

Constructors

Cite

Fields

citeId :: String

citePrefix :: Formatted

citeSuffix :: Formatted

citeLabel :: String

citeLocator :: String

citeNoteNumber :: String

citePosition :: String

nearNote :: Bool

authorInText :: Bool

suppressAuthor :: Bool

citeHash :: Int

Instances

Eq Cite

Data Cite

Show Cite

Generic Cite

FromJSON Cite

Typeable * Cite

FromJSON [[Cite]]

type Rep Cite

newtype Abbreviations

Constructors

Abbreviations

Fields

unAbbreviations :: Map String (Map String (Map String String))

Instances

Data Abbreviations

Read Abbreviations

Show Abbreviations

Generic Abbreviations

FromJSON Abbreviations

Typeable * Abbreviations

type Rep Abbreviations

emptyCite :: Cite

High Level Processing

data ProcOpts

Constructors

ProcOpts

Fields

bibOpts :: BibOpts

Instances

Eq ProcOpts

Read ProcOpts

Show ProcOpts

procOpts :: ProcOpts

data BibOpts

Constructors

Select [(String, String)] [(String, String)]

Include [(String, String)] [(String, String)]

Exclude [(String, String)] [(String, String)]

Instances

Eq BibOpts

Read BibOpts

Show BibOpts

FromJSON BibOpts

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

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]

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]

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

data BiblioData

Constructors

BD

Fields

citations :: [Formatted]

bibliography :: [Formatted]

Instances

Data BiblioData

Show BiblioData

Generic BiblioData

Typeable * BiblioData

type Rep BiblioData

The output and the rendering functions

renderPlain :: Formatted -> String

Render the Formatted into a plain text string.

renderPandoc :: Style -> Formatted -> [Inline]

renderPandoc' :: Style -> Formatted -> Block