//! A closed subject scheme, and what it says about a heading. //! //! A catalogue that lets anything be a subject ends up with forty thousand of //! them and no way to browse. A scheme is the other approach: a fixed list of //! headings, everything else mapped onto one or dropped. //! //! The scheme itself is supplied rather than compiled in. Which subjects a //! collection uses, and what its parents are, is the most collection-specific //! thing there is — a theology library and a science library agree on nothing //! here — so it arrives as a file and this only knows what to do with one. use std::collections::HashMap; use std::sync::LazyLock; use fancy_regex::Regex; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; /// Titles that say the book is *about* somebody rather than by them, or is a /// study rather than a story. /// /// General reference rather than collection-specific: a Companion is a /// Companion on any shelf. static STUDY_TITLE: LazyLock = LazyLock::new(|| { Regex::new(r"(?i)\b(companion to|guidebook to|very short introduction|letters of|collected letters|memoirs?\b|autobiograph|\bdiary\b|\bessays\b|\blectures\b|\bspeeches\b|a life of|biography of)\b") .expect("a valid pattern") }); /// A subject scheme: what the headings are, and how they relate. #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)] pub struct Scheme { /// Every heading the scheme allows, in the order they should be listed. #[serde(default)] pub subjects: Vec, /// Spellings that mean one of the subjects: alias to subject. #[serde(default)] pub aliases: HashMap, /// Headings too broad or too incidental to keep, whatever they say. #[serde(default)] pub drop: Vec, /// Which subject each subject sits under, child to parent. #[serde(default)] pub parents: HashMap, /// Subjects that mean the work is a study, so it cannot also be fiction. #[serde(default)] pub blocks_fiction: Vec, /// The genres a study blocks. #[serde(default)] pub fiction_genres: Vec, } impl Scheme { /// Whether the scheme says anything at all. pub fn is_empty(&self) -> bool { self.subjects.is_empty() } /// The subject a heading means, or `None` if it is not one. /// /// Exact first, then an alias. A heading on the drop list is not a /// subject however it is spelled, and the brackets a catalogue wraps its /// own annotations in are stripped before the comparison. pub fn canonical(&self, name: &str) -> Option<&str> { let name = name.trim(); if name.is_empty() { return None; } let lower = name.to_lowercase(); let bare = lower.trim_matches(|c: char| "*[]".contains(c)); if self.drop.iter().any(|drop| { let drop = drop.to_lowercase(); let drop = drop.trim_matches(|c: char| "*[]".contains(c)); drop == lower || drop == bare }) { return None; } if let Some(found) = self.subjects.iter().find(|s| s.to_lowercase() == lower) { return Some(found); } self.aliases .iter() .find(|(alias, _)| alias.to_lowercase() == lower) .map(|(_, subject)| subject.as_str()) } /// Every chosen subject, with the parent of each carried alongside it. /// /// Phenomenology becomes Philosophy and Phenomenology, so a shelf browsed /// by the parent still finds the child. Returned in scheme order, which /// is the order a reader expects to see them listed. pub fn with_parents(&self, subjects: &[String]) -> Vec { let mut chosen: Vec<&str> = Vec::new(); for subject in subjects { if !self.subjects.iter().any(|s| s == subject) { continue; } chosen.push(subject); if let Some(parent) = self.parents.get(subject) { chosen.push(parent); } } self.in_order(&chosen) } /// Drop the fiction genres where the work is plainly a study. /// /// A historical novel may be fiction and history at once. A life of /// somebody, a Companion, or a writer's diary may not be a novel. pub fn without_impossible_fiction( &self, subjects: &[String], title: Option<&str>, ) -> Vec { let study = title.is_some_and(|title| STUDY_TITLE.is_match(title).unwrap_or(false)); let blocked = subjects .iter() .any(|s| self.blocks_fiction.iter().any(|block| block == s)); let kept: Vec<&str> = subjects .iter() .map(String::as_str) .filter(|subject| { !(study || blocked) || !self.fiction_genres.iter().any(|genre| genre == subject) }) .collect(); self.in_order(&kept) } /// The subjects a book should carry: the chosen ones, their parents, and /// nothing the title rules out. pub fn compose(&self, subjects: &[String], title: Option<&str>) -> Vec { self.without_impossible_fiction(&self.with_parents(subjects), title) } /// Whether a book has no real subject yet. /// /// Untagged, or tagged only with headings the scheme does not recognise — /// which is what a catalogue built from filenames looks like. pub fn needs_subject(&self, existing: &[String]) -> bool { !existing.iter().any(|tag| self.canonical(tag).is_some()) } /// The given headings, deduplicated and in scheme order. fn in_order(&self, chosen: &[&str]) -> Vec { self.subjects .iter() .filter(|subject| chosen.contains(&subject.as_str())) .cloned() .collect() } } #[cfg(test)] mod tests { use super::*; fn scheme() -> Scheme { Scheme { subjects: [ "Philosophy", "Phenomenology", "History", "Biography", "Fiction", "Science Fiction", ] .iter() .map(|s| s.to_string()) .collect(), aliases: [("Philosophie", "Philosophy"), ("SF", "Science Fiction")] .iter() .map(|(a, b)| (a.to_string(), b.to_string())) .collect(), drop: ["General", "Humanities", "Non-Fiction"] .iter() .map(|s| s.to_string()) .collect(), parents: [("Phenomenology", "Philosophy")] .iter() .map(|(a, b)| (a.to_string(), b.to_string())) .collect(), blocks_fiction: vec!["Biography".into()], fiction_genres: vec!["Fiction".into(), "Science Fiction".into()], } } fn subjects(names: &[&str]) -> Vec { names.iter().map(|s| s.to_string()).collect() } #[test] fn a_heading_in_the_scheme_is_itself() { assert_eq!(scheme().canonical("Philosophy"), Some("Philosophy")); assert_eq!(scheme().canonical("philosophy"), Some("Philosophy")); } #[test] fn an_alias_is_the_subject_it_means() { assert_eq!(scheme().canonical("Philosophie"), Some("Philosophy")); assert_eq!(scheme().canonical("sf"), Some("Science Fiction")); } #[test] fn a_heading_on_the_drop_list_is_not_a_subject() { assert_eq!(scheme().canonical("General"), None); // Including inside the brackets a catalogue wraps its own notes in. assert_eq!(scheme().canonical("[General]"), None); assert_eq!(scheme().canonical("*Humanities*"), None); } #[test] fn a_heading_the_scheme_never_heard_of_is_not_a_subject() { assert_eq!(scheme().canonical("Underwater Basketry"), None); assert_eq!(scheme().canonical(""), None); assert_eq!(scheme().canonical(" "), None); } #[test] fn a_child_carries_its_parent() { assert_eq!( scheme().with_parents(&subjects(&["Phenomenology"])), ["Philosophy", "Phenomenology"] ); } #[test] fn subjects_come_back_in_scheme_order_however_they_went_in() { assert_eq!( scheme().with_parents(&subjects(&["History", "Philosophy"])), ["Philosophy", "History"] ); } #[test] fn a_heading_outside_the_scheme_is_dropped_rather_than_carried() { assert_eq!( scheme().with_parents(&subjects(&["Basketry"])), Vec::::new() ); } #[test] fn a_biography_is_not_also_a_novel() { assert_eq!( scheme().without_impossible_fiction(&subjects(&["Biography", "Fiction"]), None), ["Biography"] ); } #[test] fn a_title_that_says_study_rules_out_fiction_on_its_own() { for title in [ "The Cambridge Companion to Nietzsche", "Logic: A Very Short Introduction", "A Life of Wrangel", "The Diary of a Writer", ] { assert_eq!( scheme() .without_impossible_fiction(&subjects(&["Fiction", "History"]), Some(title)), ["History"], "{title}" ); } } #[test] fn a_historical_novel_may_still_be_both() { assert_eq!( scheme().without_impossible_fiction( &subjects(&["Fiction", "History"]), Some("War and Peace") ), ["History", "Fiction"] ); } #[test] fn composing_does_the_parents_and_the_fiction_rule_at_once() { assert_eq!( scheme().compose( &subjects(&["Phenomenology", "Fiction"]), Some("A Life of Husserl") ), ["Philosophy", "Phenomenology"] ); } #[test] fn a_book_tagged_only_with_rubbish_still_needs_a_subject() { assert!(scheme().needs_subject(&[])); assert!(scheme().needs_subject(&subjects(&["General", "ebook"]))); assert!(!scheme().needs_subject(&subjects(&["General", "Philosophy"]))); } #[test] fn an_empty_scheme_says_nothing_about_anything() { let empty = Scheme::default(); assert!(empty.is_empty()); assert_eq!(empty.canonical("Philosophy"), None); assert!(empty.needs_subject(&subjects(&["Philosophy"]))); } }