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

Portability | unportable
Stability | unstable
Maintainer | Andrea Rossato <andrea.rossato@unitn.it>
Safe Haskell | None

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
  - = Mods
  - | Json
  - | Native
  - | Bibtex
  - | BibLatex
  - | Ris
  - | Endnote
  - | EndnotXml
  - | Isi
  - | Medline
  - | Copac
- readBiblioString :: BibFormat -> String -> IO [Reference]
- readModsFile :: FilePath -> IO Reference
- readModsCollectionFile :: FilePath -> IO [Reference]
- readJsonInput :: FilePath -> IO [Reference]
- readJsonInputString :: String -> [Reference]
- readJsonAbbrevFile :: FilePath -> IO [Abbrev]
- data Reference = Reference {
  - 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
  - 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]
  - citationNumber :: CNum
  - firstReferenceNoteNumber :: Int
  - citationLabel :: String
  }
- getReference :: [Reference] -> Cite -> Reference
- parseLocator :: String -> (String, String)
- setNearNote :: Style -> [[Cite]] -> [[Cite]]
- readCSLFile :: FilePath -> IO Style
- parseCSL :: String -> IO Style
- data Style = Style {
  - styleVersion :: String
  - styleClass :: String
  - styleInfo :: Maybe CSInfo
  - styleDefaultLocale :: String
  - styleLocale :: [Locale]
  - styleAbbrevs :: [Abbrev]
  - 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
  - | FUrl Target Formatting
  - | 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://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]

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

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

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

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.

readJsonInput :: FilePath -> IO [Reference]

readJsonInputString :: String -> [Reference]

readJsonAbbrevFile :: FilePath -> IO [Abbrev]

## 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]
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
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]
citationNumber :: CNum
firstReferenceNoteNumber :: Int
citationLabel :: String

Instances

Eq Reference |
Data Reference |
Read Reference |
Show Reference |
Typeable Reference |

getReference :: [Reference] -> Cite -> 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`.

parseCSL :: String -> IO Style

Parse a `String` into a fully localized `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 :: [Abbrev]
csOptions :: [Option]
csMacros :: [MacroMap]
citation :: Citation
biblio :: Maybe Bibliography

Instances

Data Style |
Read Style |
Show Style |
Typeable Style |

data Citation

Constructors

Citation |

Fields

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

Instances

Data Citation |
Read Citation |
Show Citation |
Typeable Citation |

data Bibliography

Constructors

Bibliography |

Fields

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

Instances

Data Bibliography |
Read 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.

emptyCite :: Cite

## High Level Processing

data ProcOpts

Constructors

ProcOpts |

Fields

bibOpts :: BibOpts

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 |

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

With a `Style`, a list of `Reference`s 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 `Reference`s 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 `Reference`s produce the `FormattedOutput` for the bibliography.

data BiblioData

Constructors

BD |

Fields

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

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

Instances

Eq FormattedOutput |
Show FormattedOutput |

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