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

Portabilityunportable
Stabilityunstable
MaintainerAndrea Rossato <andrea.rossato@unitn.it>

Text.CSL

Contents

Description

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.

Synopsis

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.

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.

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
 
shortTitle :: String
 
containerTitle :: String
 
collectionTitle :: 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 

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

High Level Processing

data ProcOpts

Constructors

ProcOpts 

Fields

bibOpts :: BibOpts
 

Instances

Eq ProcOpts 
Read ProcOpts 
Show 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 

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] 
FN String Formatting 
FS String Formatting 
FDel String 
FPan [Inline] 
FNull 

Instances

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]

startWithPunct :: [Inline] -> Bool

endWithPunct :: [Inline] -> Bool