1use crate::error::Result;
2use crate::query::facet::FacetCount;
3use crate::query::types::Type;
4use crate::query::*;
5use chrono::NaiveDate;
6use std::borrow::Cow;
7
8define_keyed_enum! {
9WorkElement {
16 DOI => "DOI",
17 ISBN => "ISBN",
18 ISSN => "ISSN",
19 URL => "URL",
20 Abstract_ => "abstract",
21 Accepted => "accepted",
22 AlternativeId => "alternative-id",
23 Approved => "approved",
24 Archive => "archive",
25 ArticleNumber => "article-number",
26 Assertion => "assertion",
27 Author => "author",
28 Chair => "chair",
29 ClinicalTrialNumber => "clinical-trial-number",
30 ContainerTitle => "container-title",
31 ContentCreated => "content-created",
32 ContentDomain => "content-domain",
33 Contributor => "contributor",
34 Created => "created",
35 Degree => "degree",
36 Deposited => "deposited",
37 Editor => "editor",
38 Event => "event",
39 Funder => "funder",
40 GroupTitle => "group-title",
41 Indexed => "indexed",
42 IsReferencedByCount => "is-referenced-by-count",
43 IssnType => "issn-type",
44 Issue => "issue",
45 Issued => "issued",
46 License => "license",
47 Link => "link",
48 Member => "member",
49 OriginalTitle => "original-title",
50 Page => "page",
51 Posted => "posted",
52 Prefix => "prefix",
53 Published => "published",
54 PublishedOnline => "published-online",
55 PublishedPrint => "published-print",
56 Publisher => "publisher",
57 PublisherLocation => "publisher-location",
58 Reference => "reference",
59 ReferencesCount => "references-count",
60 Relation => "relation",
61 Resource => "resource",
62 Score => "score",
63 ShortContainerTitle => "short-container-title",
64 ShortTitle => "short-title",
65 StandardsBody => "standards-body",
66 Subject => "subject",
67 Subtitle => "subtitle",
68 Title => "title",
69 Translator => "translator",
70 Type => "type",
71 UpdatePolicy => "update-policy",
72 UpdateTo => "update-to",
73 UpdatedBy => "updated-by",
74 Volume => "volume",
75}
76}
77
78define_filter! {
79WorksFilter;
93markers {
94 HasFunder => "has-funder",
96 HasFunderDoi => "has-funder-doi",
98 HasFunderRorId => "has-funder-ror-id",
100 HasAffiliation => "has-affiliation",
102 HasAffiliationRorId => "has-affiliation-ror-id",
104 HasRorId => "has-ror-id",
106 HasLicense => "has-license",
108 HasFullText => "has-full-text",
110 HasReferences => "has-references",
112 HasArchive => "has-archive",
114 HasOrcid => "has-orcid",
116 HasAuthenticatedOrcid => "has-authenticated-orcid",
118 HasAbstract => "has-abstract",
120 HasClinicalTrialNumber => "has-clinical-trial-number",
122 HasContentDomain => "has-content-domain",
124 HasDomainRestriction => "has-domain-restriction",
126 HasRelation => "has-relation",
128 HasUpdate => "has-update",
130 HasUpdatePolicy => "has-update-policy",
132 HasAssertion => "has-assertion",
134 HasAward => "has-award",
136 HasAlias => "has-alias",
138 HasPrimeDoi => "has-prime-doi",
140 HasEvent => "has-event",
142 IsUpdate => "is-update",
144}
145values {
146 Funder(String) => "funder",
148 Prefix(String) => "prefix",
150 Member(String) => "member",
152 Doi(String) => "doi",
154 Issn(String) => "issn",
156 Isbn(String) => "isbn",
158 Orcid(String) => "orcid",
160 Archive(String) => "archive",
162 Directory(String) => "directory",
165 Updates(String) => "updates",
167 ContainerTitle(String) => "container-title",
169 CategoryName(String) => "category-name",
172 TypeName(String) => "type-name",
174 Type(Type) => "type",
177 GroupTitle(String) => "group-title",
179 ContentDomain(String) => "content-domain",
181 ClinicalTrialNumber(String) => "clinical-trial-number",
183 AlternativeId(String) => "alternative-id",
186 ArticleNumber(String) => "article-number",
188 RorId(String) => "ror-id",
191 UpdateType(String) => "update-type",
193 FunderDoiAssertedBy(String) => "funder-doi-asserted-by",
196 Assertion(String) => "assertion",
198 AssertionGroup(String) => "assertion-group",
200 AwardNumber(String) => "award.number",
203 AwardFunder(String) => "award.funder",
206 GteAwardAmount(u64) => "gte-award-amount",
208 LteAwardAmount(u64) => "lte-award-amount",
210 LicenseUrl(String) => "license.url",
212 LicenseVersion(String) => "license.version",
214 LicenseDelay(i32) => "license.delay",
216 FullTextVersion(String) => "full-text.version",
218 FullTextType(String) => "full-text.type",
220 FullTextApplication(String) => "full-text.application",
222 RelationType(String) => "relation.type",
225 RelationObject(String) => "relation.object",
227 RelationObjectType(String) => "relation.object-type",
229 FromIndexDate(NaiveDate) => "from-index-date",
231 UntilIndexDate(NaiveDate) => "until-index-date",
233 FromDepositDate(NaiveDate) => "from-deposit-date",
235 UntilDepositDate(NaiveDate) => "until-deposit-date",
237 FromUpdateDate(NaiveDate) => "from-update-date",
240 UntilUpdateDate(NaiveDate) => "until-update-date",
243 FromCreatedDate(NaiveDate) => "from-created-date",
245 UntilCreatedDate(NaiveDate) => "until-created-date",
247 FromPubDate(NaiveDate) => "from-pub-date",
249 UntilPubDate(NaiveDate) => "until-pub-date",
251 FromOnlinePubDate(NaiveDate) => "from-online-pub-date",
253 UntilOnlinePubDate(NaiveDate) => "until-online-pub-date",
255 FromPrintPubDate(NaiveDate) => "from-print-pub-date",
257 UntilPrintPubDate(NaiveDate) => "until-print-pub-date",
259 FromPostedDate(NaiveDate) => "from-posted-date",
261 UntilPostedDate(NaiveDate) => "until-posted-date",
263 FromAcceptedDate(NaiveDate) => "from-accepted-date",
265 UntilAcceptedDate(NaiveDate) => "until-accepted-date",
267 FromApprovedDate(NaiveDate) => "from-approved-date",
269 UntilApprovedDate(NaiveDate) => "until-approved-date",
271 FromAwardedDate(NaiveDate) => "from-awarded-date",
273 UntilAwardedDate(NaiveDate) => "until-awarded-date",
275 FromIssuedDate(NaiveDate) => "from-issued-date",
277 UntilIssuedDate(NaiveDate) => "until-issued-date",
279 FromEventStartDate(NaiveDate) => "from-event-start-date",
281 UntilEventStartDate(NaiveDate) => "until-event-start-date",
283 FromEventEndDate(NaiveDate) => "from-event-end-date",
285 UntilEventEndDate(NaiveDate) => "until-event-end-date",
287}
288}
289
290define_field_queries! {
291 Title => "title" / title,
293 ContainerTitle => "container-title" / container_title,
295 Author => "author" / author,
297 Editor => "editor" / editor,
299 Chair => "chair" / chair,
301 Translator => "translator" / translator,
303 Contributor => "contributor" / contributor,
305 Bibliographic => "bibliographic" / bibliographic,
308 Affiliation => "affiliation" / affiliation,
310 Degree => "degree" / degree,
312 Description => "description" / description,
314 EventAcronym => "event-acronym" / event_acronym,
316 EventLocation => "event-location" / event_location,
318 EventName => "event-name" / event_name,
320 EventSponsor => "event-sponsor" / event_sponsor,
322 EventTheme => "event-theme" / event_theme,
324 FunderName => "funder-name" / funder_name,
326 PublisherLocation => "publisher-location" / publisher_location,
328 PublisherName => "publisher-name" / publisher_name,
330 StandardsBodyAcronym => "standards-body-acronym" / standards_body_acronym,
332 StandardsBodyName => "standards-body-name" / standards_body_name,
334}
335
336impl CrossrefQueryParam for FieldQuery {
337 fn params(&self) -> Vec<(Cow<'_, str>, Cow<'_, str>)> {
338 vec![(
339 Cow::Borrowed(self.name()),
340 Cow::Owned(format_query(self.value())),
341 )]
342 }
343}
344
345#[derive(Debug, Clone)]
347pub enum WorkResultControl {
348 Standard(ResultControl),
350 Cursor {
352 token: Option<String>,
354 rows: Option<usize>,
356 },
357}
358
359impl WorkResultControl {
360 pub fn new_cursor() -> Self {
362 WorkResultControl::Cursor {
363 token: None,
364 rows: None,
365 }
366 }
367
368 pub fn cursor(token: &str) -> Self {
370 WorkResultControl::Cursor {
371 token: Some(token.to_string()),
372 rows: None,
373 }
374 }
375}
376
377impl Default for WorkResultControl {
378 fn default() -> Self {
379 WorkResultControl::new_cursor()
380 }
381}
382
383impl CrossrefQueryParam for WorkResultControl {
384 fn params(&self) -> Vec<(Cow<'_, str>, Cow<'_, str>)> {
385 match self {
386 WorkResultControl::Standard(standard) => standard.params(),
387 WorkResultControl::Cursor { token, rows } => {
388 let mut params = vec![(
389 Cow::Borrowed("cursor"),
390 Cow::Borrowed(token.as_deref().unwrap_or("*")),
391 )];
392 if let Some(rows) = rows {
393 params.push((Cow::Borrowed("rows"), Cow::Owned(rows.to_string())));
394 }
395 params
396 }
397 }
398 }
399}
400#[derive(Debug, Clone)]
421pub enum Works {
422 Identifier(String),
424 Query(WorksQuery),
426 Agency(String),
428}
429
430impl Works {
431 pub fn doi(doi: &str) -> Self {
433 Works::Identifier(doi.to_string())
434 }
435 pub fn agency_for_doi(doi: &str) -> Self {
437 Works::Agency(doi.to_string())
438 }
439}
440
441impl CrossrefRoute for Works {
442 fn route(&self) -> Result<String> {
443 match self {
444 Works::Identifier(s) => Ok(format!("{}/{}", Component::Works.route()?, s)),
445 Works::Agency(s) => Ok(format!("{}/{}/agency", Component::Works.route()?, s)),
446 Works::Query(query) => query.route(),
447 }
448 }
449}
450
451impl CrossrefQuery for Works {
452 fn resource_component(self) -> ResourceComponent {
453 ResourceComponent::Works(self)
454 }
455}
456
457#[derive(Debug, Clone)]
459pub enum WorkListQuery {
460 Works(WorksQuery),
462 Combined {
464 primary_component: WorksComponent,
466 ident: WorksIdentQuery,
468 },
469}
470
471impl WorkListQuery {
472 pub fn query(&self) -> &WorksQuery {
474 match self {
475 WorkListQuery::Works(query) => query,
476 WorkListQuery::Combined { ident, .. } => &ident.query,
477 }
478 }
479
480 pub fn query_mut(&mut self) -> &mut WorksQuery {
482 match self {
483 WorkListQuery::Works(query) => query,
484 WorkListQuery::Combined { ident, .. } => &mut ident.query,
485 }
486 }
487}
488
489impl From<WorksQuery> for WorkListQuery {
490 fn from(val: WorksQuery) -> Self {
491 WorkListQuery::Works(val)
492 }
493}
494
495impl<T: ToString> From<T> for WorkListQuery {
496 fn from(term: T) -> Self {
497 WorkListQuery::Works(WorksQuery::new(term))
498 }
499}
500
501impl CrossrefRoute for WorkListQuery {
502 fn route(&self) -> Result<String> {
503 match self {
504 WorkListQuery::Works(query) => query.route(),
505 WorkListQuery::Combined {
506 primary_component,
507 ident,
508 } => Ok(format!(
509 "{}/{}{}",
510 primary_component.route()?,
511 ident.id,
512 ident.query.route()?
513 )),
514 }
515 }
516}
517
518impl CrossrefQuery for WorkListQuery {
519 fn resource_component(self) -> ResourceComponent {
520 match self {
521 WorkListQuery::Works(query) => ResourceComponent::Works(Works::Query(query)),
522 WorkListQuery::Combined {
523 primary_component,
524 ident,
525 } => match primary_component {
526 WorksComponent::Funders => ResourceComponent::Funders(Funders::Works(ident)),
527 WorksComponent::Journals => ResourceComponent::Journals(Journals::Works(ident)),
528 WorksComponent::Members => ResourceComponent::Members(Members::Works(ident)),
529 WorksComponent::Prefixes => ResourceComponent::Prefixes(Prefixes::Works(ident)),
530 WorksComponent::Types => ResourceComponent::Types(Types::Works(ident)),
531 },
532 }
533 }
534}
535
536#[derive(Debug, Clone)]
556pub struct WorksIdentQuery {
557 pub id: String,
559 pub query: WorksQuery,
561}
562
563impl WorksIdentQuery {
564 pub fn new<T: Into<String>>(id: T, query: WorksQuery) -> Self {
566 WorksIdentQuery {
567 id: id.into(),
568 query,
569 }
570 }
571}
572
573pub trait WorksCombiner {
575 fn primary_component() -> WorksComponent;
577
578 fn ident_query(ident: WorksIdentQuery) -> Self;
580
581 fn combined_route(ident: &WorksIdentQuery) -> Result<String> {
583 Ok(format!(
584 "{}/{}{}",
585 Self::primary_component().route()?,
586 ident.id,
587 ident.query.route()?
588 ))
589 }
590
591 fn work_list_query(ident: WorksIdentQuery) -> WorkListQuery {
593 WorkListQuery::Combined {
594 primary_component: Self::primary_component(),
595 ident,
596 }
597 }
598}
599
600macro_rules! impl_combiner {
601 ($($name:ident,)*) => {
602 $(
603 impl WorksCombiner for $name {
604 fn primary_component() -> WorksComponent {
605 WorksComponent::$name
606 }
607
608 fn ident_query(ident: WorksIdentQuery) -> Self {
609 $name::Works(ident)
610 }
611 }
612 )+
613 };
614}
615
616impl_combiner!(Journals, Funders, Members, Prefixes, Types,);
617
618impl WorksQuery {
619 pub fn empty() -> Self {
621 WorksQuery::default()
622 }
623
624 pub fn random(len: usize) -> Self {
627 WorksQuery::default().sample(len)
628 }
629
630 pub fn new<T: ToString>(query: T) -> Self {
632 WorksQuery::empty().query(query)
633 }
634
635 pub fn sample(mut self, len: impl Into<Option<usize>>) -> Self {
638 self.sample = len.into();
639 self
640 }
641
642 pub fn query<T: ToString>(mut self, query: T) -> Self {
644 self.free_form_queries.push(query.to_string());
645 self
646 }
647
648 pub fn queries<T: ToString>(mut self, queries: &[T]) -> Self {
659 self.free_form_queries
660 .extend(queries.iter().map(T::to_string));
661 self
662 }
663
664 pub fn field_query(mut self, query: FieldQuery) -> Self {
666 self.field_queries.push(query);
667 self
668 }
669
670 pub fn elements(mut self, element: Vec<WorkElement>) -> Self {
679 self.elements.extend(element);
680 self
681 }
682
683 pub fn field_queries(mut self, queries: Vec<FieldQuery>) -> Self {
690 self.field_queries.extend(queries);
691 self
692 }
693
694 pub fn filter(mut self, filter: WorksFilter) -> Self {
696 self.filter.push(filter);
697 self
698 }
699
700 pub fn sort(mut self, sort: impl Into<Option<Sort>>) -> Self {
702 self.sort = sort.into();
703 self
704 }
705
706 pub fn order(mut self, order: impl Into<Option<Order>>) -> Self {
708 self.order = order.into();
709 self
710 }
711
712 pub fn facet(mut self, facet: FacetCount) -> Self {
714 self.facets.push(facet);
715 self
716 }
717
718 pub fn next_cursor(mut self, cursor: &str) -> Self {
720 let rows = match self.result_control {
721 Some(WorkResultControl::Standard(ResultControl::Rows(rows))) => Some(rows),
722 _ => None,
723 };
724 self.result_control = Some(WorkResultControl::Cursor {
725 token: Some(cursor.to_string()),
726 rows,
727 });
728 self
729 }
730
731 pub fn new_cursor(mut self) -> Self {
733 self.result_control = Some(WorkResultControl::new_cursor());
734 self
735 }
736 pub fn result_control(mut self, result_control: impl Into<Option<WorkResultControl>>) -> Self {
738 self.result_control = result_control.into();
739 self
740 }
741
742 pub fn into_combined<W: WorksCombiner>(self, id: &str) -> W {
752 W::ident_query(self.into_ident(id))
753 }
754
755 pub fn into_ident(self, id: &str) -> WorksIdentQuery {
757 WorksIdentQuery::new(id, self)
758 }
759
760 pub fn into_combined_query<W: WorksCombiner>(self, id: &str) -> WorkListQuery {
774 W::work_list_query(self.into_ident(id))
775 }
776}
777
778#[derive(Debug, Clone, Default)]
791pub struct WorksQuery {
792 pub free_form_queries: Vec<String>,
794 pub field_queries: Vec<FieldQuery>,
796 pub filter: Vec<WorksFilter>,
798 pub sort: Option<Sort>,
800 pub order: Option<Order>,
802 pub elements: Vec<WorkElement>,
804 pub facets: Vec<FacetCount>,
806 pub result_control: Option<WorkResultControl>,
808 pub sample: Option<usize>,
811}
812
813fn select_value(elements: &[WorkElement]) -> String {
824 let selected = elements.iter().map(WorkElement::name);
825
826 if elements.contains(&WorkElement::DOI) {
827 selected.collect::<Vec<_>>().join(",")
828 } else {
829 std::iter::once(WorkElement::DOI.name())
830 .chain(selected)
831 .collect::<Vec<_>>()
832 .join(",")
833 }
834}
835
836impl CrossrefRoute for WorksQuery {
837 fn route(&self) -> Result<String> {
838 let mut params: Vec<(Cow<'_, str>, Cow<'_, str>)> = Vec::new();
839
840 if let Some(sample) = self.sample {
841 params.push((Cow::Borrowed("sample"), Cow::Owned(sample.to_string())));
842 return Ok(format!(
843 "{}{}",
844 Component::Works.route()?,
845 encode::query_string(¶ms)
846 ));
847 }
848
849 if !self.free_form_queries.is_empty() {
850 params.push((
851 Cow::Borrowed("query"),
852 Cow::Owned(format_queries(&self.free_form_queries)),
853 ));
854 }
855 params.extend(
856 self.field_queries
857 .iter()
858 .flat_map(CrossrefQueryParam::params),
859 );
860 if !self.filter.is_empty() {
861 reject_unsendable_filters(&self.filter)?;
862 params.extend(self.filter.params());
863 }
864 if !self.elements.is_empty() {
865 params.push((
866 Cow::Borrowed("select"),
867 Cow::Owned(select_value(&self.elements)),
868 ));
869 }
870 if !self.facets.is_empty() {
871 params.extend(self.facets.params());
872 }
873 if let Some(sort) = &self.sort {
874 params.extend(sort.params());
875 }
876 if let Some(order) = &self.order {
877 params.extend(order.params());
878 }
879 if let Some(rc) = &self.result_control {
880 params.extend(rc.params());
881 }
882
883 Ok(format!(
884 "{}{}",
885 Component::Works.route()?,
886 encode::query_string(¶ms)
887 ))
888 }
889}
890
891#[cfg(test)]
892mod tests {
893 use super::*;
894
895 #[test]
896 fn serialize_works_ident() {
897 let works = Works::doi("10.1037/0003-066X.59.1.29");
898
899 assert_eq!("/works/10.1037/0003-066X.59.1.29", &works.route().unwrap())
900 }
901
902 #[test]
903 fn sample_query_keeps_the_works_route() {
904 let route = WorksQuery::random(10).route().unwrap();
907
908 assert_eq!("/works?sample=10", &route);
909
910 let query: WorkListQuery = WorksQuery::random(10).into();
911 assert_eq!(
912 "https://api.crossref.org/works?sample=10",
913 &query.to_url("https://api.crossref.org").unwrap()
914 );
915 }
916
917 #[test]
918 fn filter_names_have_no_stray_whitespace() {
919 let route = WorksQuery::empty()
920 .filter(WorksFilter::HasClinicalTrialNumber)
921 .route()
922 .unwrap();
923
924 assert_eq!("/works?filter=has-clinical-trial-number:true", &route);
925 }
926
927 #[test]
928 fn cursor_with_rows_renders_two_parameters() {
929 let query = WorksQuery::empty().result_control(WorkResultControl::Cursor {
930 token: Some("abc".to_string()),
931 rows: Some(20),
932 });
933
934 assert_eq!("/works?cursor=abc&rows=20", &query.route().unwrap());
935 }
936
937 #[test]
938 fn new_cursor_renders_the_wildcard_token() {
939 let query = WorksQuery::empty().new_cursor();
940
941 assert_eq!("/works?cursor=*", &query.route().unwrap());
942 }
943
944 #[test]
945 fn a_query_term_can_no_longer_inject_a_parameter() {
946 assert_eq!(
948 "/works?query=R%26D",
949 &WorksQuery::new("R&D").route().unwrap()
950 );
951 }
952
953 #[test]
954 fn filter_and_field_query_values_are_encoded_too() {
955 let route = WorksQuery::empty()
956 .field_query(FieldQuery::container_title("Ecology & Evolution"))
957 .filter(WorksFilter::ContainerTitle("Q&A".to_string()))
958 .route()
959 .unwrap();
960
961 assert_eq!(
962 "/works?query.container-title=Ecology%20%26%20Evolution&filter=container-title:Q%26A",
963 &route
964 );
965 }
966
967 #[test]
968 fn an_empty_query_targets_the_bare_works_route() {
969 assert_eq!("/works", &WorksQuery::empty().route().unwrap());
970 }
971
972 #[test]
973 fn selected_elements_render_as_one_comma_separated_parameter() {
974 let route = WorksQuery::empty()
975 .elements(vec![WorkElement::DOI, WorkElement::Title])
976 .route()
977 .unwrap();
978
979 assert_eq!("/works?select=DOI,title", &route);
980 }
981
982 #[test]
983 fn a_select_that_omits_the_doi_still_asks_for_it() {
984 let route = WorksQuery::empty()
987 .elements(vec![WorkElement::Title])
988 .route()
989 .unwrap();
990
991 assert_eq!("/works?select=DOI,title", &route);
992 }
993
994 #[test]
995 fn a_filter_value_with_a_comma_in_it_is_refused() {
996 let error = WorksQuery::empty()
999 .filter(WorksFilter::ContainerTitle("A, B".to_string()))
1000 .route()
1001 .expect_err("crossref cannot read this back");
1002
1003 let crate::Error::UnsendableFilterValue { filter, value } = error else {
1004 panic!("expected an unsendable filter value, got {error:?}");
1005 };
1006 assert_eq!("container-title", filter);
1007 assert_eq!("A, B", value);
1008 }
1009
1010 #[test]
1011 fn rows_offset_renders_two_parameters() {
1012 let query = WorksQuery::empty().result_control(WorkResultControl::Standard(
1013 ResultControl::RowsOffset {
1014 rows: 10,
1015 offset: 20,
1016 },
1017 ));
1018
1019 assert_eq!("/works?rows=10&offset=20", &query.route().unwrap());
1020 }
1021
1022 #[test]
1023 fn referenced_by_count_uses_the_crossref_spelling() {
1024 assert_eq!("is-referenced-by-count", Sort::IsReferencedByCount.as_str());
1026 }
1027}