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

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

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

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

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

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`.

## 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] csOptions :: [Option] csMacros :: [MacroMap] citation :: Citation biblio :: Maybe Bibliography

Instances

Data Style |
Show Style |
Typeable Style |

data Citation

Constructors

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

Instances

Data Citation |
Show Citation |
Typeable Citation |

data Bibliography

Constructors

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

Instances

Data 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] |
FN String Formatting |
FS String Formatting |
FDel String |
FPan [Inline] |
FNull |

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