citeproc-hs-0.3.2: A Citation Style Language implementation in HaskellSource codeContentsIndex
Text.CSL
Portabilityunportable
Stabilityunstable
MaintainerAndrea Rossato <andrea.rossato@unitn.it>
Contents
Introduction
Overview: A Simple Example
Reading Bibliographic Databases
Reference Representation
CSL Parser, Representation, and Processing
The Style Types
High Level Processing
The output and the rendering functions
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
readBiblioFile :: FilePath -> IO [Reference]
readModsFile :: FilePath -> IO Reference
readModsCollectionFile :: FilePath -> IO [Reference]
data Reference = Reference {
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
}
getReference :: [Reference] -> Cite -> Reference
parseLocator :: String -> (String, String)
setNearNote :: Style -> [[Cite]] -> [[Cite]]
readCSLFile :: FilePath -> IO Style
data Style = Style {
styleVersion :: String
styleClass :: String
styleInfo :: Maybe CSInfo
styleDefaultLocale :: String
styleLocale :: [Locale]
csOptions :: [Option]
csMacros :: [MacroMap]
citation :: Citation
biblio :: Maybe Bibliography
}
data Citation = Citation {
citOptions :: [Option]
citSort :: [Sort]
citLayout :: Layout
}
data Bibliography = Bibliography {
bibOptions :: [Option]
bibSort :: [Sort]
bibLayout :: Layout
}
data Cite = Cite {
citeId :: String
citePrefix :: Affix
citeSuffix :: Affix
citeLabel :: String
citeLocator :: String
citeNoteNumber :: String
citePosition :: String
nearNote :: Bool
authorInText :: Bool
suppressAuthor :: Bool
citeHash :: Int
}
data Affix
= PlainText String
| PandocText [Inline]
emptyCite :: Cite
data ProcOpts = ProcOpts {
bibOpts :: BibOpts
}
procOpts :: ProcOpts
data BibOpts
= Select [(String, String)] [(String, String)]
| Include [(String, String)] [(String, String)]
| Exclude [(String, String)] [(String, String)]
citeproc :: ProcOpts -> Style -> [Reference] -> Citations -> BiblioData
processCitations :: ProcOpts -> Style -> [Reference] -> Citations -> [[FormattedOutput]]
processBibliography :: ProcOpts -> Style -> [Reference] -> [[FormattedOutput]]
data BiblioData = BD {
citations :: [[FormattedOutput]]
bibliography :: [[FormattedOutput]]
}
data FormattedOutput
= FO Formatting [FormattedOutput]
| FN String Formatting
| FS String Formatting
| FDel String
| FPan [Inline]
| FNull
renderPlain :: [FormattedOutput] -> String
renderPlainStrict :: [FormattedOutput] -> String
renderPandoc :: Style -> [FormattedOutput] -> [Inline]
renderPandoc' :: Style -> [FormattedOutput] -> Block
headInline :: [Inline] -> String
initInline :: [Inline] -> [Inline]
tailFirstInlineStr :: [Inline] -> [Inline]
toCapital :: [Inline] -> [Inline]
startWithPunct :: [Inline] -> Bool
endWithPunct :: [Inline] -> Bool
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]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 ReferenceSource
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
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
show/hide Instances
getReference :: [Reference] -> Cite -> ReferenceSource
parseLocator :: String -> (String, String)Source
setNearNote :: Style -> [[Cite]] -> [[Cite]]Source
CSL Parser, Representation, and Processing
readCSLFile :: FilePath -> IO StyleSource
Read and parse a CSL style file into the internal style representation, the Style.
The Style Types
data Style Source
The representation of a parsed CSL style.
Constructors
Style
styleVersion :: String
styleClass :: String
styleInfo :: Maybe CSInfo
styleDefaultLocale :: String
styleLocale :: [Locale]
csOptions :: [Option]
csMacros :: [MacroMap]
citation :: Citation
biblio :: Maybe Bibliography
show/hide Instances
data Citation Source
Constructors
Citation
citOptions :: [Option]
citSort :: [Sort]
citLayout :: Layout
show/hide Instances
data Bibliography Source
Constructors
Bibliography
bibOptions :: [Option]
bibSort :: [Sort]
bibLayout :: Layout
show/hide Instances
data Cite Source
Constructors
Cite
citeId :: String
citePrefix :: Affix
citeSuffix :: Affix
citeLabel :: String
citeLocator :: String
citeNoteNumber :: String
citePosition :: String
nearNote :: Bool
authorInText :: Bool
suppressAuthor :: Bool
citeHash :: Int
show/hide Instances
data Affix Source
Constructors
PlainText String
PandocText [Inline]
show/hide Instances
emptyCite :: CiteSource
High Level Processing
data ProcOpts Source
Constructors
ProcOpts
bibOpts :: BibOpts
show/hide Instances
procOpts :: ProcOptsSource
data BibOpts Source
Constructors
Select [(String, String)] [(String, String)]
Include [(String, String)] [(String, String)]
Exclude [(String, String)] [(String, String)]
show/hide Instances
citeproc :: ProcOpts -> Style -> [Reference] -> Citations -> BiblioDataSource
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
citations :: [[FormattedOutput]]
bibliography :: [[FormattedOutput]]
show/hide Instances
The output and the rendering functions
data FormattedOutput Source
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
show/hide Instances
renderPlain :: [FormattedOutput] -> StringSource
Render the FormattedOutput into a plain text string.
renderPlainStrict :: [FormattedOutput] -> StringSource
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] -> BlockSource
Same as renderPandoc, but the output is wrapped in a pandoc paragraph block.
headInline :: [Inline] -> StringSource
initInline :: [Inline] -> [Inline]Source
tailFirstInlineStr :: [Inline] -> [Inline]Source
toCapital :: [Inline] -> [Inline]Source
startWithPunct :: [Inline] -> BoolSource
endWithPunct :: [Inline] -> BoolSource
Produced by Haddock version 2.6.1