| 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 |
Text.CSL
Contents
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 :: (Text -> Bool) -> FilePath -> IO [Reference]
- data BibFormat
- readBiblioString :: (Text -> Bool) -> BibFormat -> Text -> IO [Reference]
- data Reference = Reference {
- refId :: Literal
- refOtherIds :: [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 Text -> FilePath -> IO Style
- parseCSL :: Text -> Style
- parseCSL' :: ByteString -> Style
- localizeCSL :: Maybe Text -> Style -> IO Style
- data Style = Style {
- styleVersion :: Text
- styleClass :: Text
- styleInfo :: Maybe CSInfo
- styleDefaultLocale :: Text
- styleLocale :: [Locale]
- styleAbbrevs :: Abbreviations
- csOptions :: [Option]
- csMacros :: [MacroMap]
- citation :: Citation
- biblio :: Maybe Bibliography
- data Citation = Citation {}
- data Bibliography = Bibliography {}
- data Cite = Cite {
- citeId :: Text
- citePrefix :: Formatted
- citeSuffix :: Formatted
- citeLabel :: Text
- citeLocator :: Text
- citeNoteNumber :: Text
- citePosition :: Text
- nearNote :: Bool
- authorInText :: Bool
- suppressAuthor :: Bool
- citeHash :: Int
- 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 :: [Text]
- renderPlain :: Formatted -> Text
- renderPandoc :: Style -> Formatted -> [Inline]
- renderPandoc' :: Style -> (Formatted, Text) -> 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 $ resultThe result would be:
(Caso, 2007, p. 15; Rossato, 2006, p. 10)
Reading Bibliographic Databases
readBiblioFile :: (Text -> 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.
Constructors
Instances
CSL Parser, Representation, and Processing
readCSLFile :: Maybe Text -> 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.
Constructors
| Style | |
Fields
| |
Instances
Instances
| Data Citation Source # | |
Defined in Text.CSL.Style Methods 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.17-C8O1IjUyq0FL1XS6eyOYCQ" 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 #
Constructors
| Bibliography | |
Instances
Constructors
| Cite | |
Fields
| |
Instances
newtype Abbreviations Source #
Constructors
| Abbreviations | |
Instances
High Level Processing
Constructors
| ProcOpts | |
Fields
| |
Constructors
| Select [(Text, Text)] [(Text, Text)] | |
| Include [(Text, Text)] [(Text, Text)] | |
| Exclude [(Text, Text)] [(Text, Text)] |
data BiblioData Source #
Constructors
| BD | |
Fields
| |
Instances
| Data BiblioData Source # | |
Defined in Text.CSL.Style Methods 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 Methods showsPrec :: Int -> BiblioData -> ShowS # show :: BiblioData -> String # showList :: [BiblioData] -> ShowS # | |
| Generic BiblioData Source # | |
Defined in Text.CSL.Style Associated Types type Rep BiblioData :: Type -> Type # | |
| type Rep BiblioData Source # | |
Defined in Text.CSL.Style type Rep BiblioData = D1 (MetaData "BiblioData" "Text.CSL.Style" "pandoc-citeproc-0.17-C8O1IjUyq0FL1XS6eyOYCQ" 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 [Text])))) | |