| citeproc-hs-0.2: A Citation Style Language implementation in Haskell | Source code | Contents | Index

Text.CSL

Portability | unportable
Stability | unstable
Maintainer | Andrea 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://xbiblio.sourceforge.net/. This module documents and exports the library API.
Synopsis

readBiblioFile :: FilePath -> String -> IO [Reference]
readModsFile :: FilePath -> IO Reference
readModsColletionFile :: FilePath -> IO [Reference]

data Reference = Reference {

citeKey :: String
refType :: RefType
author :: [Agent]
editor :: [Agent]
translator :: [Agent]
recipient :: [Agent]
interviewer :: [Agent]
publisher :: [Agent]
composer :: [Agent]
originalPublisher :: [Agent]
originalAuthor :: [Agent]
containerAuthor :: [Agent]
collectionEditor :: [Agent]
issued :: [RefDate]
eventDate :: [RefDate]
accessed :: [RefDate]
container :: [RefDate]
originalDate :: [RefDate]
title :: String
containerTitle :: String
collectionTitle :: String
collectionNumber :: Int
originalTitle :: String
publisherPlace :: String
archive :: String
archivePlace :: String
archiveLocation :: String
event :: String
eventPlace :: String
page :: String
locator :: Locator
version :: String
volume :: String
numberOfVolumes :: Int
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
citationNumber :: CNum
yearSuffix :: String
citationLabel :: String

}

getReference :: [Reference] -> (String, String) -> Reference
readCSLFile :: FilePath -> IO Style

data Style = Style {

styleClass :: String
styleInfo :: Maybe CSInfo
styleLang :: String
styleLocale :: String
csTerms :: [TermMap]
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

}

citeproc :: Style -> [Reference] -> [[(String, String)]] -> BiblioData
processCitations :: Style -> [Reference] -> [[(String, String)]] -> [[FormattedOutput]]
processBibliography :: Style -> [Reference] -> [[FormattedOutput]]

data BiblioData = BD {

citations :: [[FormattedOutput]]
bibliography :: [[FormattedOutput]]

}

data FormattedOutput

= FO String Formatting [FormattedOutput]
| Delimiter String

renderPlain :: [FormattedOutput] -> String
renderPlainStrict :: [FormattedOutput] -> String
renderPandoc :: Style -> [FormattedOutput] -> String
renderPandoc' :: Style -> [FormattedOutput] -> String
renderPandocStrict :: [FormattedOutput] -> String

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 formatted bibliographic databases.

Overview: A Simple Example

The following example assumes you have properly installed hs-bibutils. If not you can use bibutils to convert the following bibtex bibliographic database into a MODS collection.

Suppose you have a small bibliographic database, like this one:

     @Book{Rossato2005,
     author="Andrea Rossato",
     title="My First Book",
     year="2005"
     }

     @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 style developed by the Zotero community. Suppose this one:

http://www.zotero.org/styles/apa

saved locally as `apa.csl`.

This would be a simple program that formats a list of citations according to that style:

     import Text.CSL

     main :: IO ()
     main = do
       m <- readBiblioFile "mybibdb.bib" "bibtex"
       s <- readCSLFile "apa.csl"
       let result = citeproc s m $ [[("Caso2007","p. 10"),("Rossato2005","p. 10"),("Rossato2006","p. 15")]]
       putStrLn . unlines . map (renderPlainStrict) . citations $ result

The result would be:

     (Caso, 2007, p. 10; Rossato, 2005, p. 10, 2006, p. 15)

Reading Bibliographic Databases

readBiblioFile :: FilePath -> String -> IO [Reference] | Source

Read a file with a bibliographic database of the format specified by the `String`. If the `String` is empty the file extension will be used to identify the format. Supported formats are: `"mods"`, `"bibtex"`, `"biblatex"`, `"ris"`, `"endnote"`, `"endnotexml"`, `"isi"`, `"medline"`, and `"copac"`.

readModsFile :: FilePath -> IO Reference | Source

Read a file with a single MODS record.

readModsColletionFile :: FilePath -> IO [Reference] | Source

Read a file with a collection of MODS records.
Reference Representation

data Reference | Source

The `Reference` record.
Constructors

Reference |

citeKey :: String |
refType :: RefType |
author :: [Agent] |
editor :: [Agent] |
translator :: [Agent] |
recipient :: [Agent] |
interviewer :: [Agent] |
publisher :: [Agent] |
composer :: [Agent] |
originalPublisher :: [Agent] |
originalAuthor :: [Agent] |
containerAuthor :: [Agent] |
collectionEditor :: [Agent] |
issued :: [RefDate] |
eventDate :: [RefDate] |
accessed :: [RefDate] |
container :: [RefDate] |
originalDate :: [RefDate] |
title :: String |
containerTitle :: String |
collectionTitle :: String |
collectionNumber :: Int |
originalTitle :: String |
publisherPlace :: String |
archive :: String |
archivePlace :: String |
archiveLocation :: String |
event :: String |
eventPlace :: String |
page :: String |
locator :: Locator |
version :: String |
volume :: String |
numberOfVolumes :: Int |
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 |
citationNumber :: CNum |
yearSuffix :: String |
citationLabel :: String |

Instances

Eq Reference
Data Reference
Read Reference
Show Reference
Typeable Reference

getReference :: [Reference] -> (String, String) -> Reference | Source

With the list of `Reference`s and the tuple (citation key, locator), return the needed reference with the correct locator set.
CSL Parser, Representation, and Processing

readCSLFile :: FilePath -> IO Style | Source

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 |

styleClass :: String |
styleInfo :: Maybe CSInfo |
styleLang :: String |
styleLocale :: String |
csTerms :: [TermMap] |
csMacros :: [MacroMap] |
citation :: Citation |
biblio :: Maybe Bibliography |

Instances

Data Style
Show Style
Typeable Style

data Citation | Source

Constructors

Citation |

citOptions :: [Option] |
citSort :: [Sort] |
citLayout :: Layout |

Instances

Data Citation
Show Citation
Typeable Citation

data Bibliography | Source

Constructors

Bibliography |

bibOptions :: [Option] |
bibSort :: [Sort] |
bibLayout :: Layout |

Instances

Data Bibliography
Show Bibliography
Typeable Bibliography

High Level Processing

citeproc :: Style -> [Reference] -> [[(String, String)]] -> BiblioData | Source

With a `Style`, a list of `Reference`s and the list of citation groups (the list of citations with their locator), produce the `FormattedOutput` for each citation group and the bibliography.

processCitations :: Style -> [Reference] -> [[(String, String)]] -> [[FormattedOutput]] | Source

With a `Style`, a list of `Reference`s and the list of citation groups (the list of citations with their locator), produce the `FormattedOutput` for each citation group.

processBibliography :: Style -> [Reference] -> [[FormattedOutput]] | Source

With a `Style` and the list of `Reference`s produce the `FormattedOutput` for the bibliography.

data BiblioData | Source

Constructors

BD |

citations :: [[FormattedOutput]] |
bibliography :: [[FormattedOutput]] |

Instances

Show BiblioData

The output and the rendering functions

data FormattedOutput | Source

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

FO String Formatting [FormattedOutput] |
Delimiter String |

Instances

Eq FormattedOutput
Show FormattedOutput

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

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

renderPandocStrict :: [FormattedOutput] -> String | Source

Same as `renderPandoc`, but will not clean up the produced output.
Produced by Haddock version 2.4.2