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

Copyright(c) Andrea Rossato
LicenseBSD-style (see LICENSE)
MaintainerAndrea Rossato <andrea.rossato@unitn.it>
Stabilityunstable
Portabilityunportable
Safe HaskellNone
LanguageHaskell98

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://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 "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 Reference Source

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.

Constructors

Reference 

Fields

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 Style Source

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

parseCSL :: String -> IO Style Source

Parse a String into a fully localized Style

The Style Types

data Style Source

The representation of a parsed CSL style.

data Affix Source

Instances

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

Needed for the test-suite.

Typeable * Affix 

High Level Processing

data ProcOpts Source

Constructors

ProcOpts 

Fields

bibOpts :: BibOpts
 

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

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

Constructors

BD 

Instances

The output and the rendering functions

data FormattedOutput Source

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

FDel String

Delimeter string

FUrl Target Formatting

Formatted URL

FPan [Inline]

Pandoc inline elements

FNull

Null formatting item

renderPlain :: [FormattedOutput] -> String Source

Render the FormattedOutput into a plain text string.

renderPlainStrict :: [FormattedOutput] -> String Source

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

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