de.undercouch.citeproc

Class CSL

java.lang.Object

de.undercouch.citeproc.CSL

public class CSL
extends Object

The citation processor.

In order to use the processor in your application you first have to create an ItemDataProvider that provides citation item data. For example, the following dummy provider returns always the same data:

 public class MyItemProvider implements ItemDataProvider {
     @Override
     public CSLItemData retrieveItem(String id) {
         return new CSLItemDataBuilder()
             .id(id)
             .type(CSLType.ARTICLE_JOURNAL)
             .title("A dummy journal article")
             .author("John", "Smith")
             .issued(2013, 9, 6)
             .containerTitle("Dummy journal")
             .build();
     }
     
     @Override
     public String[] getIds() {
         String ids[] = {"ID-0", "ID-1", "ID-2"};
         return ids;
     }
 }

Now you can instantiate the CSL processor.

 CSL citeproc = new CSL(new MyItemProvider(), "ieee");
 citeproc.setOutputFormat("html");

Ad-hoc usage

You may also use makeAdhocBibliography(String, CSLItemData...) or makeAdhocBibliography(String, String, CSLItemData...) to create ad-hoc bibliographies from CSL items.

 CSLItemData item = new CSLItemDataBuilder()
     .type(CSLType.WEBPAGE)
     .title("citeproc-java: A Citation Style Language (CSL) processor for Java")
     .author("Michel", "Kraemer")
     .issued(2014, 7, 13)
     .URL("http://michel-kraemer.github.io/citeproc-java/")
     .accessed(2014, 7, 13)
     .build();
     
 String bibl = CSL.makeAdhocBibliography("ieee", item).makeString();

Thread-safety

Please note that this class is not thread-safe. However, shared resources are held in memory, so constructing new instances is generally rather cheap. If your settings do not change you may cache instances of this class in a ThreadLocal.

 ThreadLocal<CSL> csl = new ThreadLocal<CSL>() {
     @Override
     protected CSL initialValue() {
         return new CSL(itemDataProvider, style, lang);
     }
 };

Please remember to reset the ThreadLocal if you don't need the CSL instance anymore to avoid memory leaks.

Author:

Michel Kraemer

Constructor Summary

Constructors

Constructor and Description
CSL(ItemDataProvider itemDataProvider, AbbreviationProvider abbreviationProvider, String style) Constructs a new citation processor
CSL(ItemDataProvider itemDataProvider, AbbreviationProvider abbreviationProvider, String style, String lang) Constructs a new citation processor
CSL(ItemDataProvider itemDataProvider, LocaleProvider localeProvider, AbbreviationProvider abbreviationProvider, String style, String lang, boolean forceLang) Constructs a new citation processor
CSL(ItemDataProvider itemDataProvider, LocaleProvider localeProvider, AbbreviationProvider abbreviationProvider, VariableWrapper variableWrapper, String style, String lang, boolean forceLang) Constructs a new citation processor
CSL(ItemDataProvider itemDataProvider, LocaleProvider localeProvider, String style, String lang, boolean forceLang) Constructs a new citation processor
CSL(ItemDataProvider itemDataProvider, String style) Constructs a new citation processor
CSL(ItemDataProvider itemDataProvider, String style, String lang) Constructs a new citation processor

Method Summary

Modifier and Type	Method and Description
protected Object	getEngine()
protected ScriptRunner	getScriptRunner()
static Set<String>	getSupportedLocales() Calculates a list of available citation locales
static List<String>	getSupportedOutputFormats() Calculates a list of supported output formats
static Set<String>	getSupportedStyles() Calculates a list of available citation styles
static Bibliography	makeAdhocBibliography(String style, CSLItemData... items) Creates an ad hoc bibliography from the given citation items using the "html" output format.
static Bibliography	makeAdhocBibliography(String style, String outputFormat, CSLItemData... items) Creates an ad hoc bibliography from the given citation items.
Bibliography	makeBibliography() Generates a bibliography for the registered citations
Bibliography	makeBibliography(SelectionMode mode, CSLItemData... selection) Generates a bibliography for the registered citations.
Bibliography	makeBibliography(SelectionMode mode, CSLItemData[] selection, CSLItemData[] quash) Generates a bibliography for the registered citations.
List<Citation>	makeCitation(CSLCitation citation) Generates citation strings that can be inserted into the text.
List<Citation>	makeCitation(CSLCitation citation, List<CitationIDIndexPair> citationsPre, List<CitationIDIndexPair> citationsPost) Generates citation strings that can be inserted into the text.
List<Citation>	makeCitation(String... ids) Generates citation strings that can be inserted into the text.
void	registerCitationItems(String... ids) Introduces the given citation IDs to the processor.
void	registerCitationItems(String[] ids, boolean unsorted) Introduces the given citation IDs to the processor.
void	reset() Resets the processor's state
void	setAbbreviations(String name) Enables the abbreviation list with the given name.
void	setConvertLinks(boolean convert) Specifies if the processor should convert URLs and DOIs in the output to links.
void	setOutputFormat(String format) Sets the processor's output format
static boolean	supportsStyle(String style) Checks if a given citation style is supported

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CSL

public CSL(ItemDataProvider itemDataProvider,
           String style)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

CSL

public CSL(ItemDataProvider itemDataProvider,
           AbbreviationProvider abbreviationProvider,
           String style)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

abbreviationProvider - an object that provides abbreviations

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

CSL

public CSL(ItemDataProvider itemDataProvider,
           String style,
           String lang)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

lang - an RFC 4646 identifier for the citation locale (e.g. en-US)

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

CSL

public CSL(ItemDataProvider itemDataProvider,
           AbbreviationProvider abbreviationProvider,
           String style,
           String lang)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

abbreviationProvider - an object that provides abbreviations

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

lang - an RFC 4646 identifier for the citation locale (e.g. en-US)

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

CSL

public CSL(ItemDataProvider itemDataProvider,
           LocaleProvider localeProvider,
           String style,
           String lang,
           boolean forceLang)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

localeProvider - an object that provides CSL locales

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

lang - an RFC 4646 identifier for the citation locale (e.g. en-US)

forceLang - true if the given locale should overwrite any default locale

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

CSL

public CSL(ItemDataProvider itemDataProvider,
           LocaleProvider localeProvider,
           AbbreviationProvider abbreviationProvider,
           String style,
           String lang,
           boolean forceLang)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

localeProvider - an object that provides CSL locales

abbreviationProvider - an object that provides abbreviations

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

lang - an RFC 4646 identifier for the citation locale (e.g. en-US)

forceLang - true if the given locale should overwrite any default locale

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

CSL

public CSL(ItemDataProvider itemDataProvider,
           LocaleProvider localeProvider,
           AbbreviationProvider abbreviationProvider,
           VariableWrapper variableWrapper,
           String style,
           String lang,
           boolean forceLang)
    throws IOException

Constructs a new citation processor

Parameters:

itemDataProvider - an object that provides citation item data

localeProvider - an object that provides CSL locales

abbreviationProvider - an object that provides abbreviations

variableWrapper - an object that decorates rendered items

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

lang - an RFC 4646 identifier for the citation locale (e.g. en-US)

forceLang - true if the given locale should overwrite any default locale

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

Method Detail

getSupportedOutputFormats

public static List<String> getSupportedOutputFormats()
                                              throws IOException

Calculates a list of supported output formats

Returns:

the formats

Throws:

IOException - if the underlying JavaScript files could not be loaded

getSupportedStyles

public static Set<String> getSupportedStyles()
                                      throws IOException

Calculates a list of available citation styles

Returns:

the list

Throws:

IOException - if the citation styles could not be loaded

supportsStyle

public static boolean supportsStyle(String style)

Checks if a given citation style is supported

Parameters:

style - the citation style's name

Returns:

true if the style is supported, false otherwise

getSupportedLocales

public static Set<String> getSupportedLocales()
                                       throws IOException

Calculates a list of available citation locales

Returns:

the list

Throws:

IOException - if the citation locales could not be loaded

getScriptRunner

protected ScriptRunner getScriptRunner()

Returns:

the JavaScript runner used to execute citeproc-js

getEngine

protected Object getEngine()

Returns:

the underlying citeproc-js engine

setOutputFormat

public void setOutputFormat(String format)

Sets the processor's output format

Parameters:

format - the format (one of "html", "text", "asciidoc", "fo", or "rtf")

setConvertLinks

public void setConvertLinks(boolean convert)

Specifies if the processor should convert URLs and DOIs in the output to links. How links are created depends on the output format that has been set with setOutputFormat(String)

Parameters:

convert - true if URLs and DOIs should be converted to links

setAbbreviations

public void setAbbreviations(String name)

Enables the abbreviation list with the given name. The processor will call AbbreviationProvider.getAbbreviations(String) with the given String to get the abbreviations that should be used from here on.

Parameters:

name - the name of the abbreviation list to enable

registerCitationItems

public void registerCitationItems(String... ids)

Introduces the given citation IDs to the processor. The processor will call ItemDataProvider.retrieveItem(String) for each ID to get the respective citation item. The retrieved items will be added to the bibliography, so you don't have to call makeCitation(String...) for each of them anymore.

Parameters:

ids - the IDs to register

Throws:

IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

registerCitationItems

public void registerCitationItems(String[] ids,
                                  boolean unsorted)

Introduces the given citation IDs to the processor. The processor will call ItemDataProvider.retrieveItem(String) for each ID to get the respective citation item. The retrieved items will be added to the bibliography, so you don't have to call makeCitation(String...) for each of them anymore.

Parameters:

ids - the IDs to register

unsorted - true if items should not be sorted in the bibliography

Throws:

IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

makeCitation

public List<Citation> makeCitation(String... ids)

Generates citation strings that can be inserted into the text. The method calls ItemDataProvider.retrieveItem(String) for each of the given IDs to request the corresponding citation item. Additionally, it saves the IDs, so makeBibliography() will generate a bibliography that only consists of the retrieved citation items.

Parameters:

ids - IDs of citation items for which strings should be generated

Returns:

citations strings that can be inserted into the text

Throws:

IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

makeCitation

public List<Citation> makeCitation(CSLCitation citation)

Generates citation strings that can be inserted into the text. The method calls ItemDataProvider.retrieveItem(String) for each item in the given set to request the corresponding citation item data. Additionally, it saves the requested citation IDs, so makeBibliography() will generate a bibliography that only consists of the retrieved items.

Parameters:

citation - a set of citation items for which strings should be generated

Returns:

citations strings that can be inserted into the text

Throws:

IllegalArgumentException - if the given set of citation items refers to citation item data that does not exist

makeCitation

public List<Citation> makeCitation(CSLCitation citation,
                                   List<CitationIDIndexPair> citationsPre,
                                   List<CitationIDIndexPair> citationsPost)

Generates citation strings that can be inserted into the text. The method calls ItemDataProvider.retrieveItem(String) for each item in the given set to request the corresponding citation item data. Additionally, it saves the requested citation IDs, so makeBibliography() will generate a bibliography that only consists of the retrieved items.

Parameters:

citation - a set of citation items for which strings should be generated

citationsPre - citations that precede citation

citationsPost - citations that come after citation

Returns:

citations strings that can be inserted into the text

Throws:

IllegalArgumentException - if the given set of citation items refers to citation item data that does not exist

makeBibliography

public Bibliography makeBibliography()

Generates a bibliography for the registered citations

Returns:

the bibliography

makeBibliography

public Bibliography makeBibliography(SelectionMode mode,
                                     CSLItemData... selection)

Generates a bibliography for the registered citations. Depending on the selection mode selects, includes, or excludes bibliography items whose fields and field values match the fields and field values from the given example item data objects.

Parameters:

mode - the selection mode

selection - the example item data objects that contain the fields and field values to match

Returns:

the bibliography

makeBibliography

public Bibliography makeBibliography(SelectionMode mode,
                                     CSLItemData[] selection,
                                     CSLItemData[] quash)

Generates a bibliography for the registered citations. Depending on the selection mode selects, includes, or excludes bibliography items whose fields and field values match the fields and field values from the given example item data objects.

Parameters:

mode - the selection mode

selection - the example item data objects that contain the fields and field values to match

quash - regardless of the item data in selection skip items if all fields/values from this list match

Returns:

the bibliography

reset

public void reset()

Resets the processor's state

makeAdhocBibliography

public static Bibliography makeAdhocBibliography(String style,
                                                 CSLItemData... items)
                                          throws IOException

Creates an ad hoc bibliography from the given citation items using the "html" output format. Calling this method is rather expensive as it initializes the CSL processor. If you need to create bibliographies multiple times in your application you should create the processor yourself and cache it if necessary.

Parameters:

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

items - the citation items to add to the bibliography

Returns:

the bibliography

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded

See Also:

makeAdhocBibliography(String, String, CSLItemData...)

makeAdhocBibliography

public static Bibliography makeAdhocBibliography(String style,
                                                 String outputFormat,
                                                 CSLItemData... items)
                                          throws IOException

Creates an ad hoc bibliography from the given citation items. Calling this method is rather expensive as it initializes the CSL processor. If you need to create bibliographies multiple times in your application you should create the processor yourself and cache it if necessary.

Parameters:

style - the citation style to use. May either be a serialized XML representation of the style or a style's name such as ieee. In the latter case, the processor loads the style from the classpath (e.g. /ieee.csl)

outputFormat - the processor's output format (one of "html", "text", "asciidoc", "fo", or "rtf")

items - the citation items to add to the bibliography

Returns:

the bibliography

Throws:

IOException - if the underlying JavaScript files or the CSL style could not be loaded