Copyright | (c) Andrea Rossato |
---|---|
License | BSD-style (see LICENSE) |
Maintainer | Andrea Rossato <andrea.rossato@unitn.it> |
Stability | unstable |
Portability | unportable |
Safe Haskell | None |
Language | Haskell2010 |
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 :: (String -> Bool) -> FilePath -> IO [Reference]
- data BibFormat
- readBiblioString :: (String -> Bool) -> 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 :: CLabel
- 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 {}
- data Bibliography = Bibliography {}
- data Cite = Cite {}
- newtype Abbreviations = Abbreviations {}
- emptyCite :: Cite
- data ProcOpts = ProcOpts {
- bibOpts :: BibOpts
- linkCitations :: Bool
- procOpts :: ProcOpts
- data BibOpts
- 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 :: (String -> Bool) -> FilePath -> IO [Reference] Source #
Read a file with a bibliographic database. The database format is recognized by the file extension. The first argument is a predicate to filter citation identifiers.
Supported formats are: json
, mods
, bibtex
, biblatex
, ris
,
endnote
, endnotexml
, isi
, medline
, copac
, and nbib
.
Reference Representation
The Reference
record.
Instances
CSL Parser, Representation, and Processing
readCSLFile :: Maybe String -> FilePath -> IO Style Source #
Read and parse a CSL style file into a localized sytle.
parseCSL' :: ByteString -> Style Source #
The Style Types
The representation of a parsed CSL style.
Style | |
|
Instances
Instances
Data Citation Source # | |
Defined in Text.CSL.Style gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Citation -> c Citation # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Citation # toConstr :: Citation -> Constr # dataTypeOf :: Citation -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Citation) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Citation) # gmapT :: (forall b. Data b => b -> b) -> Citation -> Citation # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Citation -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Citation -> r # gmapQ :: (forall d. Data d => d -> u) -> Citation -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Citation -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Citation -> m Citation # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Citation -> m Citation # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Citation -> m Citation # | |
Read Citation Source # | |
Show Citation Source # | |
Generic Citation Source # | |
type Rep Citation Source # | |
Defined in Text.CSL.Style type Rep Citation = D1 (MetaData "Citation" "Text.CSL.Style" "pandoc-citeproc-0.14.4-GpO8Frq2QSw6TtNRuoOjZN" False) (C1 (MetaCons "Citation" PrefixI True) (S1 (MetaSel (Just "citOptions") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Option]) :*: (S1 (MetaSel (Just "citSort") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Sort]) :*: S1 (MetaSel (Just "citLayout") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Layout)))) |
data Bibliography Source #
Instances
Cite | |
|
Instances
newtype Abbreviations Source #
Instances
High Level Processing
ProcOpts | |
|
Select [(String, String)] [(String, String)] | |
Include [(String, String)] [(String, String)] | |
Exclude [(String, String)] [(String, String)] |
data BiblioData Source #
BD | |
|
Instances
Data BiblioData Source # | |
Defined in Text.CSL.Style gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> BiblioData -> c BiblioData # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c BiblioData # toConstr :: BiblioData -> Constr # dataTypeOf :: BiblioData -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c BiblioData) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c BiblioData) # gmapT :: (forall b. Data b => b -> b) -> BiblioData -> BiblioData # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> BiblioData -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> BiblioData -> r # gmapQ :: (forall d. Data d => d -> u) -> BiblioData -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> BiblioData -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> BiblioData -> m BiblioData # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> BiblioData -> m BiblioData # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> BiblioData -> m BiblioData # | |
Show BiblioData Source # | |
Defined in Text.CSL.Style showsPrec :: Int -> BiblioData -> ShowS # show :: BiblioData -> String # showList :: [BiblioData] -> ShowS # | |
Generic BiblioData Source # | |
Defined in Text.CSL.Style type Rep BiblioData :: * -> * # from :: BiblioData -> Rep BiblioData x # to :: Rep BiblioData x -> BiblioData # | |
type Rep BiblioData Source # | |
Defined in Text.CSL.Style type Rep BiblioData = D1 (MetaData "BiblioData" "Text.CSL.Style" "pandoc-citeproc-0.14.4-GpO8Frq2QSw6TtNRuoOjZN" False) (C1 (MetaCons "BD" PrefixI True) (S1 (MetaSel (Just "citations") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Formatted]) :*: (S1 (MetaSel (Just "bibliography") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Formatted]) :*: S1 (MetaSel (Just "citationIds") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [String])))) |