Text.CSL

pandoc-citeproc-0.9: Supports using pandoc with citeproc

Copyright | (c) Andrea Rossato
License | BSD-style (see LICENSE)
Maintainer | Andrea Rossato <andrea.rossato@unitn.it>
Stability | unstable
Portability | unportable
Safe Haskell | None
Language | Haskell98

Text.CSL

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]
- data BibFormat
  - = Json
  - | Yaml
  - | Bibtex
  - | BibLatex
  - | Ris
  - | Endnote
  - | EndnotXml
  - | Isi
  - | Medline
  - | Copac
  - | Mods
- readBiblioString :: BibFormat -> String -> IO [Reference]
- data Reference = Reference {
  - refId :: Literal
  - 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 :: Formatted
  - titleShort :: Formatted
  - reviewedTitle :: Formatted
  - containerTitle :: Formatted
  - volumeTitle :: Formatted
  - collectionTitle :: Formatted
  - containerTitleShort :: Formatted
  - collectionNumber :: Formatted
  - originalTitle :: Formatted
  - publisher :: Formatted
  - originalPublisher :: Formatted
  - publisherPlace :: Formatted
  - originalPublisherPlace :: Formatted
  - authority :: Formatted
  - jurisdiction :: Formatted
  - archive :: Formatted
  - archivePlace :: Formatted
  - archiveLocation :: Formatted
  - event :: Formatted
  - eventPlace :: Formatted
  - page :: Formatted
  - pageFirst :: Formatted
  - numberOfPages :: Formatted
  - version :: Formatted
  - volume :: Formatted
  - numberOfVolumes :: Formatted
  - issue :: Formatted
  - chapterNumber :: Formatted
  - medium :: Formatted
  - status :: Formatted
  - edition :: Formatted
  - section :: Formatted
  - source :: Formatted
  - genre :: Formatted
  - note :: Formatted
  - annote :: Formatted
  - abstract :: Formatted
  - keyword :: Formatted
  - number :: Formatted
  - references :: Formatted
  - url :: Literal
  - doi :: Literal
  - isbn :: Literal
  - issn :: Literal
  - pmcid :: Literal
  - pmid :: Literal
  - callNumber :: Literal
  - dimensions :: Literal
  - scale :: Literal
  - categories :: [Literal]
  - language :: Literal
  - citationNumber :: CNum
  - firstReferenceNoteNumber :: Int
  - citationLabel :: Literal
  }
- getReference :: [Reference] -> Cite -> Maybe Reference
- setNearNote :: Style -> [[Cite]] -> [[Cite]]
- readCSLFile :: Maybe String -> FilePath -> IO Style
- parseCSL :: String -> Style
- parseCSL' :: ByteString -> Style
- localizeCSL :: Maybe String -> Style -> IO Style
- data Style = Style {
  - styleVersion :: String
  - styleClass :: String
  - styleInfo :: Maybe CSInfo
  - styleDefaultLocale :: String
  - styleLocale :: [Locale]
  - styleAbbrevs :: Abbreviations
  - 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 :: Formatted
  - citeSuffix :: Formatted
  - citeLabel :: String
  - citeLocator :: String
  - citeNoteNumber :: String
  - citePosition :: String
  - nearNote :: Bool
  - authorInText :: Bool
  - suppressAuthor :: Bool
  - citeHash :: Int
  }
- newtype Abbreviations = Abbreviations {
  - unAbbreviations :: Map String (Map String (Map String String))
  }
- emptyCite :: Cite
- data ProcOpts = ProcOpts {
  - bibOpts :: BibOpts
  - linkCitations :: Bool
  }
- 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 -> [Formatted]
- processBibliography :: ProcOpts -> Style -> [Reference] -> [Formatted]
- data BiblioData = BD {
  - citations :: [Formatted]
  - bibliography :: [Formatted]
  - citationIds :: [String]
  }
- renderPlain :: Formatted -> String
- renderPandoc :: Style -> Formatted -> [Inline]
- renderPandoc' :: Style -> (Formatted, String) -> Block

# Introduction

citeproc-hs provides functions for reading bibliographic databases, for reading and parsing CSL files and for generating citations in an internal format, `Formatted`, 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 Nothing "apa-x.csl"
      let result = citeproc procOpts s m $ [cites]
      putStrLn . unlines . map renderPlain . 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

Json |
Yaml |
Bibtex |
BibLatex |
Ris |
Endnote |
EndnotXml |
Isi |
Medline |
Copac |
Mods |

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

## Reference Representation

data Reference

The `Reference` record.

Constructors

Reference |
Fields refId :: Literal 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 :: Formatted titleShort :: Formatted reviewedTitle :: Formatted containerTitle :: Formatted volumeTitle :: Formatted collectionTitle :: Formatted containerTitleShort :: Formatted collectionNumber :: Formatted originalTitle :: Formatted publisher :: Formatted originalPublisher :: Formatted publisherPlace :: Formatted originalPublisherPlace :: Formatted authority :: Formatted jurisdiction :: Formatted archive :: Formatted archivePlace :: Formatted archiveLocation :: Formatted event :: Formatted eventPlace :: Formatted page :: Formatted pageFirst :: Formatted numberOfPages :: Formatted version :: Formatted volume :: Formatted numberOfVolumes :: Formatted issue :: Formatted chapterNumber :: Formatted medium :: Formatted status :: Formatted edition :: Formatted section :: Formatted source :: Formatted genre :: Formatted note :: Formatted annote :: Formatted abstract :: Formatted keyword :: Formatted number :: Formatted references :: Formatted url :: Literal doi :: Literal isbn :: Literal issn :: Literal pmcid :: Literal pmid :: Literal callNumber :: Literal dimensions :: Literal scale :: Literal categories :: [Literal] language :: Literal citationNumber :: CNum firstReferenceNoteNumber :: Int citationLabel :: Literal

Instances

Eq Reference |
Data Reference |
Read Reference |
Show Reference |
Generic Reference |
ToJSON Reference |
FromJSON Reference |
ToYaml Reference |
type Rep Reference |

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

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

# CSL Parser, Representation, and Processing

readCSLFile :: Maybe String -> FilePath -> IO Style

Read and parse a CSL style file into a localized sytle.

parseCSL :: String -> Style

Parse a `String` into a `Style` (with default locale).

parseCSL' :: ByteString -> Style

localizeCSL :: Maybe String -> Style -> IO Style

Merge locale into a CSL 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 :: Abbreviations csOptions :: [Option] csMacros :: [MacroMap] citation :: Citation biblio :: Maybe Bibliography

Instances

Data Style |
Read Style |
Show Style |
Generic Style |
type Rep Style |

data Citation

Constructors

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

Instances

Data Citation |
Read Citation |
Show Citation |
Generic Citation |
type Rep Citation |

data Bibliography

Constructors

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

Instances

Data Bibliography |
Read Bibliography |
Show Bibliography |
Generic Bibliography |
type Rep Bibliography |

data Cite

Constructors

Cite |
Fields citeId :: String citePrefix :: Formatted citeSuffix :: Formatted citeLabel :: String citeLocator :: String citeNoteNumber :: String citePosition :: String nearNote :: Bool authorInText :: Bool suppressAuthor :: Bool citeHash :: Int

Instances

Eq Cite |
Data Cite |
Show Cite |
Generic Cite |
FromJSON Cite |
FromJSON [[Cite]] |
type Rep Cite |

newtype Abbreviations

Constructors

Abbreviations |
Fields unAbbreviations :: Map String (Map String (Map String String))

Instances

Data Abbreviations |
Read Abbreviations |
Show Abbreviations |
Generic Abbreviations |
FromJSON Abbreviations |
type Rep Abbreviations |

emptyCite :: Cite

## High Level Processing

data ProcOpts

Constructors

ProcOpts |
Fields bibOpts :: BibOpts linkCitations :: Bool

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 |
FromJSON BibOpts |

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

With a `Style`, a list of `Reference`s and the list of `Citations`, produce the `Formatted` for each citation group and the bibliography.

processCitations :: ProcOpts -> Style -> [Reference] -> Citations -> [Formatted]

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

processBibliography :: ProcOpts -> Style -> [Reference] -> [Formatted]

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

data BiblioData

Constructors

BD |
Fields citations :: [Formatted] bibliography :: [Formatted] citationIds :: [String]

Instances

Data BiblioData |
Show BiblioData |
Generic BiblioData |
type Rep BiblioData |

# The output and the rendering functions

renderPlain :: Formatted -> String

Render the `Formatted` into a plain text string.

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

renderPandoc' :: Style -> (Formatted, String) -> Block