Package de.undercouch.citeproc

Class CSL

  • public class CSL
extends java.lang.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();
    Author:
    Michel Kraemer

    • Constructor Summary

      Constructors 
      Constructor Description
      CSL​(ItemDataProvider itemDataProvider, LocaleProvider localeProvider, AbbreviationProvider abbreviationProvider, java.lang.String style, java.lang.String lang)
      Constructs a new citation processor
      CSL​(ItemDataProvider itemDataProvider, java.lang.String style)
      Constructs a new citation processor
      CSL​(ItemDataProvider itemDataProvider, java.lang.String style, java.lang.String lang)
      Constructs a new citation processor

    • Constructor Detail

      • CSL

        public CSL​(ItemDataProvider itemDataProvider,
           java.lang.String style)
    throws java.io.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:
        java.io.IOException - if the CSL style could not be loaded

      • CSL

        public CSL​(ItemDataProvider itemDataProvider,
           java.lang.String style,
           java.lang.String lang)
    throws java.io.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:
        java.io.IOException - if the CSL style could not be loaded

      • CSL

        public CSL​(ItemDataProvider itemDataProvider,
           LocaleProvider localeProvider,
           AbbreviationProvider abbreviationProvider,
           java.lang.String style,
           java.lang.String lang)
    throws java.io.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 (may be null)
        style - the citation style to use. May either be a serialized XML representation of the style or a style 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). If this argument is null, the default locale of the citation style will be used. If the citation style does not define a default locale, the method falls back to en-US.
        Throws:
        java.io.IOException - if the CSL style could not be loaded

    • Method Detail

      • getSupportedOutputFormats

        public static java.util.List<java.lang.String> getSupportedOutputFormats()
        Get a list of supported output formats
        Returns:
        the formats

      • getSupportedStyles

        public static java.util.Set<java.lang.String> getSupportedStyles()
                                                          throws java.io.IOException
        Calculates a list of available citation styles
        Returns:
        the list
        Throws:
        java.io.IOException - if the citation styles could not be loaded

      • supportsStyle

        public static boolean supportsStyle​(java.lang.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 java.util.Set<java.lang.String> getSupportedLocales()
                                                           throws java.io.IOException
        Calculates a list of available citation locales
        Returns:
        the list
        Throws:
        java.io.IOException - if the citation locales could not be loaded

      • canFormatBibliographies

        public static boolean canFormatBibliographies​(java.lang.String style)
                                       throws java.io.IOException
        Determines whether the given citation style contains instructions to format bibliographies
        Parameters:
        style - the citation style. May either be a serialized XML representation of the style or a style name such as ieee. In the latter case, the style is loaded from the classpath (e.g. /ieee.csl)
        Returns:
        true if the style can be used to format bibliographies
        Throws:
        java.io.IOException - if the style could not be loaded or parsed

      • getIndependentParentLink

        public static java.lang.String getIndependentParentLink​(java.lang.String style)
                                                 throws javax.xml.parsers.ParserConfigurationException,
                                                        java.io.IOException,
                                                        org.xml.sax.SAXException
        Parse a string representing a dependent parent style and get link to its independent parent style
        Parameters:
        style - the dependent style
        Returns:
        the link to the parent style or null if the link could not be found
        Throws:
        javax.xml.parsers.ParserConfigurationException - if the XML parser could not be created
        java.io.IOException - if the string could not be read
        org.xml.sax.SAXException - if the string could not be parsed

      • setOutputFormat

        public void setOutputFormat​(java.lang.String format)
        Sets the processor's output format
        Parameters:
        format - the format (one of "asciidoc", "fo", "html", and "text".

      • setOutputFormat

        public void setOutputFormat​(de.undercouch.citeproc.csl.internal.format.Format outputFormat)
        Sets the processor's output format
        Parameters:
        outputFormat - the format

      • 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

      • registerCitationItems

        public void registerCitationItems​(java.lang.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:
        java.lang.IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

      • registerCitationItems

        public void registerCitationItems​(java.lang.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:
        java.lang.IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

      • registerCitationItems

        public void registerCitationItems​(java.util.Collection<java.lang.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:
        java.lang.IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

      • registerCitationItems

        public void registerCitationItems​(java.util.Collection<java.lang.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:
        java.lang.IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

      • getRegisteredItems

        public java.util.Collection<CSLItemData> getRegisteredItems()
        Get an unmodifiable collection of all citation items that have been registered with the processor so far
        Returns:
        the registered citation items

      • makeCitation

        public java.util.List<Citation> makeCitation​(java.lang.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:
        java.lang.IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

      • makeCitation

        public java.util.List<Citation> makeCitation​(java.util.Collection<java.lang.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:
        java.lang.IllegalArgumentException - if one of the given IDs refers to citation item data that does not exist

      • makeCitation

        public java.util.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:
        java.lang.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.

        Note: This method will be deprecated in the next release.

        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

      • makeBibliography

        public Bibliography makeBibliography​(java.util.function.Predicate<CSLItemData> filter)
        Generates a bibliography for registered citations
        Parameters:
        filter - a function to apply to each registered citation item to determine if it should be included in the bibliography or not (may be null if all items should be included)
        Returns:
        the bibliography

      • reset

        public void reset()
        Resets the processor's state

      • makeAdhocBibliography

        public static Bibliography makeAdhocBibliography​(java.lang.String style,
                                                 CSLItemData... items)
                                          throws java.io.IOException
        Creates an ad hoc bibliography from the given citation items using the "html" output format.
        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:
        java.io.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​(java.lang.String style,
                                                 java.lang.String outputFormat,
                                                 CSLItemData... items)
                                          throws java.io.IOException
        Creates an ad hoc bibliography from the given citation items.
        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:
        java.io.IOException - if the CSL style could not be loaded

      • makeAdhocCitation

        public static java.util.List<Citation> makeAdhocCitation​(java.lang.String style,
                                                         CSLItemData... items)
                                                  throws java.io.IOException
        Creates an ad hoc citation from the given citation items using the "html" output format.
        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
        Returns:
        a list of generated citations strings that can be inserted into the text
        Throws:
        java.io.IOException - if the CSL style could not be loaded
        See Also:
        makeCitation(String...)

      • makeAdhocCitation

        public static java.util.List<Citation> makeAdhocCitation​(java.lang.String style,
                                                         java.lang.String outputFormat,
                                                         CSLItemData... items)
                                                  throws java.io.IOException
        Creates an ad hoc citation from the given citation items.
        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
        Returns:
        a list of generated citations strings that can be inserted into the text
        Throws:
        java.io.IOException - if the CSL style could not be loaded
        See Also:
        makeCitation(String...)