Skip to main content

crossref_client/
cn.rs

1//! Content negotiation: a work's metadata in a format other than crossref json.
2//!
3//! Crossref re-serializes a registered work on request, so a DOI can be pulled
4//! straight out as BibTeX, RIS, RDF or a formatted citation without going
5//! through [`Work`](crate::Work) at all. Pass a [`CnFormat`] to
6//! [`Crossref::transform`](crate::Crossref::transform); the format becomes the
7//! `Accept` header and the body comes back verbatim.
8
9use serde::{Deserialize, Serialize};
10use std::borrow::Cow;
11
12/// A format crossref will re-serialize a work into.
13///
14/// Every variant here was checked against the live api. `application/vnd.datacite.datacite+xml`
15/// is deliberately absent: crossref answers it with a `406`, since it only
16/// serves formats for the DOIs it registers itself.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18pub enum CnFormat {
19    /// RDF/XML
20    RdfXml,
21    /// RDF in the Turtle syntax
22    Turtle,
23    /// [CSL](https://citationstyles.org) JSON, the standard citeproc shape
24    CiteProcJson,
25    /// crossref's older, non-standard citeproc flavour
26    CiteProcJsonIsh,
27    /// [RIS](https://en.wikipedia.org/wiki/RIS_(file_format)), for reference managers
28    Ris,
29    /// BibTeX
30    BibTex,
31    /// crossref's own deposit schema
32    CrossrefXml,
33    /// crossref's [text and data mining](https://www.crossref.org/documentation/retrieve-metadata/rest-api/text-and-data-mining/)
34    /// schema, which carries the full-text links
35    CrossrefTdm,
36    /// a citation formatted for reading, rendered by crossref itself
37    Bibliography {
38        /// the [CSL style](https://api.crossref.org/styles) to render in, e.g.
39        /// `apa` or `ieee`; crossref answers an unknown one with a `406`.
40        ///
41        /// List what it accepts with [`Crossref::styles`](crate::Crossref::styles).
42        style: String,
43        /// the locale to render in, e.g. `de-DE`. [`None`] leaves it to
44        /// crossref, which uses `en-US`.
45        locale: Option<String>,
46    },
47}
48
49impl CnFormat {
50    /// A citation in the named [CSL style](https://api.crossref.org/styles),
51    /// rendered in crossref's default locale.
52    pub fn bibliography(style: impl Into<String>) -> Self {
53        CnFormat::Bibliography {
54            style: style.into(),
55            locale: None,
56        }
57    }
58
59    /// The `Accept` header that asks crossref for this format.
60    pub fn accept(&self) -> Cow<'_, str> {
61        let simple = match self {
62            CnFormat::RdfXml => "application/rdf+xml",
63            CnFormat::Turtle => "text/turtle",
64            CnFormat::CiteProcJson => "application/vnd.citationstyles.csl+json",
65            CnFormat::CiteProcJsonIsh => "application/citeproc+json",
66            CnFormat::Ris => "application/x-research-info-systems",
67            CnFormat::BibTex => "application/x-bibtex",
68            CnFormat::CrossrefXml => "application/vnd.crossref.unixref+xml",
69            CnFormat::CrossrefTdm => "application/vnd.crossref.unixsd+xml",
70            CnFormat::Bibliography { style, locale } => {
71                let mut accept = format!("text/x-bibliography; style={style}");
72                if let Some(locale) = locale {
73                    accept.push_str("; locale=");
74                    accept.push_str(locale);
75                }
76                return Cow::Owned(accept);
77            }
78        };
79        Cow::Borrowed(simple)
80    }
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    /// One of every variant, for the tests below.
88    fn one_of_each() -> Vec<CnFormat> {
89        vec![
90            CnFormat::RdfXml,
91            CnFormat::Turtle,
92            CnFormat::CiteProcJson,
93            CnFormat::CiteProcJsonIsh,
94            CnFormat::Ris,
95            CnFormat::BibTex,
96            CnFormat::CrossrefXml,
97            CnFormat::CrossrefTdm,
98            CnFormat::bibliography("apa"),
99        ]
100    }
101
102    #[test]
103    fn no_two_formats_ask_for_the_same_thing() {
104        let mut accepts: Vec<_> = one_of_each()
105            .iter()
106            .map(|f| f.accept().to_string())
107            .collect();
108        let total = accepts.len();
109        accepts.sort();
110        accepts.dedup();
111
112        assert_eq!(
113            total,
114            accepts.len(),
115            "duplicate `Accept` values: {accepts:?}"
116        );
117    }
118
119    #[test]
120    fn a_style_and_locale_become_accept_parameters() {
121        assert_eq!(
122            "text/x-bibliography; style=apa",
123            CnFormat::bibliography("apa").accept()
124        );
125
126        assert_eq!(
127            "text/x-bibliography; style=apa; locale=de-DE",
128            CnFormat::Bibliography {
129                style: "apa".to_string(),
130                locale: Some("de-DE".to_string()),
131            }
132            .accept()
133        );
134    }
135}