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, 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: http://code.haskell.org/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 "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]

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

Mods

Json

Native

Bibtex

BibLatex

Ris

Endnote

EndnotXml

Isi

Medline

Copac

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

readModsFile :: FilePath -> IO Reference

Read a file with a single MODS record.

readModsCollectionFile :: FilePath -> IO [Reference]

Read a file with a collection of MODS records.

readJsonInput :: FilePath -> IO [Reference]

readJsonInputString :: String -> [Reference]

readJsonAbbrevFile :: FilePath -> IO [Abbrev]

Reference Representation

data Reference

The Reference record.

Constructors

Reference

Fields

refId :: String

refType :: RefType

author :: [Agent]

editor :: [Agent]

translator :: [Agent]

recipient :: [Agent]

interviewer :: [Agent]

composer :: [Agent]

originalAuthor :: [Agent]

containerAuthor :: [Agent]

collectionEditor :: [Agent]

editorialDirector :: [Agent]

issued :: [RefDate]

eventDate :: [RefDate]

accessed :: [RefDate]

container :: [RefDate]

originalDate :: [RefDate]

title :: String

titleShort :: String

containerTitle :: String

collectionTitle :: String

containerTitleShort :: String

collectionNumber :: String

originalTitle :: String

publisher :: String

originalPublisher :: String

publisherPlace :: String

authority :: 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

genre :: String

note :: String

annote :: String

abstract :: String

keyword :: String

number :: String

references :: String

url :: String

doi :: String

isbn :: String

categories :: [String]

citationNumber :: CNum

firstReferenceNoteNumber :: Int

citationLabel :: String

Instances

Eq Reference

Data Reference

Read Reference

Show Reference

Typeable Reference

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

parseLocator :: String -> (String, String)

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

CSL Parser, Representation, and Processing

readCSLFile :: FilePath -> IO Style

Read and parse a CSL style file into the internal style representation, the 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 :: [Abbrev]

csOptions :: [Option]

csMacros :: [MacroMap]

citation :: Citation

biblio :: Maybe Bibliography

Instances

Data Style

Show Style

Typeable Style

data Citation

Constructors

Citation

Fields

citOptions :: [Option]

citSort :: [Sort]

citLayout :: Layout

Instances

Data Citation

Show Citation

Typeable Citation

data Bibliography

Constructors

Bibliography

Fields

bibOptions :: [Option]

bibSort :: [Sort]

bibLayout :: Layout

Instances

Data Bibliography

Show Bibliography

Typeable Bibliography

data Cite

Constructors

Cite

Fields

citeId :: String

citePrefix :: Affix

citeSuffix :: Affix

citeLabel :: String

citeLocator :: String

citeNoteNumber :: String

citePosition :: String

nearNote :: Bool

authorInText :: Bool

suppressAuthor :: Bool

citeHash :: Int

Instances

Eq Cite

Data Cite

Show Cite

Typeable Cite

data Affix

Constructors

PlainText String

PandocText [Inline]

Instances

Eq Affix

Data Affix

Ord Affix

Read Affix

Show Affix

Typeable Affix

JSON Affix

Needed for the test-suite.

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

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

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]]

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]]

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

data BiblioData

Constructors

BD

Fields

citations :: [[FormattedOutput]]

bibliography :: [[FormattedOutput]]

Instances

Show BiblioData

The output and the rendering functions

data FormattedOutput

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

Constructors

FO Formatting [FormattedOutput]

List of FormatOutput items

FN String Formatting

Formatted number

FS String Formatting

Formatted string

FUrl String Formatting

Formatted uniform resource locator (URL)

FDel String

Delimeter string

FPan [Inline]

Pandoc inline elements

FNull

Null formatting item

Instances

Eq FormattedOutput

Show FormattedOutput

renderPlain :: [FormattedOutput] -> String

Render the FormattedOutput into a plain text string.

renderPlainStrict :: [FormattedOutput] -> String

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

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

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

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

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

headInline :: [Inline] -> String

initInline :: [Inline] -> [Inline]

tailFirstInlineStr :: [Inline] -> [Inline]

toCapital :: [Inline] -> [Inline]

endWithPunct, startWithPunct :: [Inline] -> Bool