harper_core/

word_metadata.rs

use harper_brill::UPOS;
use is_macro::Is;
use itertools::Itertools;
use paste::paste;
use serde::{Deserialize, Serialize};
use strum::{EnumCount, VariantArray};
use strum_macros::{Display, EnumCount, EnumString, VariantArray};

use std::convert::TryFrom;

use crate::{Document, TokenKind, TokenStringExt, WordId};

#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize, PartialOrd, Hash)]
pub struct WordMetadata {
    pub noun: Option<NounData>,
    pub pronoun: Option<PronounData>,
    pub verb: Option<VerbData>,
    pub adjective: Option<AdjectiveData>,
    pub adverb: Option<AdverbData>,
    pub conjunction: Option<ConjunctionData>,
    pub swear: Option<bool>,
    /// The dialects this word belongs to.
    /// If no dialects are defined, it can be assumed that the word is
    /// valid in all dialects of English.
    #[serde(default = "default_default")]
    pub dialects: DialectFlags,
    /// Whether the word is a [determiner](https://en.wikipedia.org/wiki/English_determiners).
    pub determiner: Option<DeterminerData>,
    /// Whether the word is a [preposition](https://www.merriam-webster.com/dictionary/preposition).
    #[serde(default = "default_false")]
    pub preposition: bool,
    /// Whether the word is considered especially common.
    #[serde(default = "default_false")]
    pub common: bool,
    #[serde(default = "default_none")]
    pub derived_from: Option<WordId>,
    /// Generated by a chunker
    pub np_member: Option<bool>,
    /// Generated by a POS tagger
    pub pos_tag: Option<UPOS>,
}

/// Needed for `serde`
fn default_false() -> bool {
    false
}

/// Needed for `serde`
fn default_none<T>() -> Option<T> {
    None
}

/// Needed for `serde`
fn default_default<T: Default>() -> T {
    T::default()
}

macro_rules! generate_metadata_queries {
    ($($category:ident has $($sub:ident),*).*) => {
        paste! {
            pub fn is_likely_homograph(&self) -> bool {
                [self.is_determiner(), self.preposition, $(
                    self.[< is_ $category >](),
                )*].iter().map(|b| *b as u8).sum::<u8>() > 1
            }

            $(
                #[doc = concat!("Checks if the word is definitely a ", stringify!($category), ".")]
                pub fn [< is_ $category >](&self) -> bool {
                    self.$category.is_some()
                }

                $(
                    #[doc = concat!("Checks if the word is definitely a ", stringify!($category), " and more specifically is labeled as (a) ", stringify!($sub), ".")]
                    pub fn [< is_ $sub _ $category >](&self) -> bool {
                        matches!(
                            self.$category,
                            Some([< $category:camel Data >]{
                                [< is_ $sub >]: Some(true),
                                ..
                            })
                        ) }

                    #[doc = concat!("Checks if the word is definitely a ", stringify!($category), " and more specifically is labeled as __not__ (a) ", stringify!($sub), ".")]
                    pub fn [< is_non_ $sub _ $category >](&self) -> bool {
                        matches!(
                            self.$category,
                            Some([< $category:camel Data >]{
                                [< is_ $sub >]: None | Some(false),
                                ..
                            })
                        )
                    }
                )*
            )*
        }
    };
}

impl WordMetadata {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, other: &Self) -> Self {
        macro_rules! merge {
            ($a:expr, $b:expr) => {
                match ($a, $b) {
                    (Some(a), Some(b)) => Some(a.or(&b)),
                    (Some(a), None) => Some(a),
                    (None, Some(b)) => Some(b),
                    (None, None) => None,
                }
            };
        }

        Self {
            noun: merge!(self.noun, other.noun),
            pronoun: merge!(self.pronoun, other.pronoun),
            verb: merge!(self.verb, other.verb),
            adjective: merge!(self.adjective, other.adjective),
            adverb: merge!(self.adverb, other.adverb),
            conjunction: merge!(self.conjunction, other.conjunction),
            dialects: self.dialects | other.dialects,
            swear: self.swear.or(other.swear),
            determiner: merge!(self.determiner, other.determiner),
            preposition: self.preposition || other.preposition,
            common: self.common || other.common,
            derived_from: self.derived_from.or(other.derived_from),
            pos_tag: self.pos_tag.or(other.pos_tag),
            np_member: self.np_member.or(other.np_member),
        }
    }

    /// Given a UPOS tag, discard any metadata that would disagree with the given POS tag.
    /// For example, if the metadata suggests a word could either be a noun or an adjective, and we
    /// provide a [`UPOS::NOUN`], this function will remove the adjective data.
    ///
    /// Additionally, if the metadata does not currently declare the potential of the word to be
    /// the specific POS, it becomes so. That means if we provide a [`UPOS::ADJ`] to the function
    /// for a metadata whose `Self::adjective = None`, it will become `Some`.
    pub fn enforce_pos_exclusivity(&mut self, pos: &UPOS) {
        use UPOS::*;
        match pos {
            NOUN => {
                if let Some(noun) = self.noun {
                    self.noun = Some(NounData {
                        is_proper: Some(false),
                        ..noun
                    })
                } else {
                    self.noun = Some(NounData {
                        is_proper: Some(false),
                        is_singular: None,
                        is_plural: None,
                        is_possessive: None,
                    })
                }

                self.pronoun = None;
                self.verb = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            PROPN => {
                if let Some(noun) = self.noun {
                    self.noun = Some(NounData {
                        is_proper: Some(true),
                        ..noun
                    })
                } else {
                    self.noun = Some(NounData {
                        is_proper: Some(true),
                        is_singular: None,
                        is_plural: None,
                        is_possessive: None,
                    })
                }

                self.pronoun = None;
                self.verb = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            PRON => {
                if self.pronoun.is_none() {
                    self.pronoun = Some(PronounData::default())
                }

                self.noun = None;
                self.verb = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            VERB => {
                if let Some(verb) = self.verb {
                    self.verb = Some(VerbData {
                        is_auxiliary: Some(false),
                        ..verb
                    })
                } else {
                    self.verb = Some(VerbData {
                        is_auxiliary: Some(false),
                        ..Default::default()
                    })
                }

                self.noun = None;
                self.pronoun = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            AUX => {
                if let Some(verb) = self.verb {
                    self.verb = Some(VerbData {
                        is_auxiliary: Some(true),
                        ..verb
                    })
                } else {
                    self.verb = Some(VerbData {
                        is_auxiliary: Some(true),
                        ..Default::default()
                    })
                }

                self.noun = None;
                self.pronoun = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            ADJ => {
                if self.adjective.is_none() {
                    self.adjective = Some(AdjectiveData::default())
                }

                self.noun = None;
                self.pronoun = None;
                self.verb = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            ADV => {
                if self.adverb.is_none() {
                    self.adverb = Some(AdverbData::default())
                }

                self.noun = None;
                self.pronoun = None;
                self.verb = None;
                self.adjective = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = false;
            }
            ADP => {
                self.noun = None;
                self.pronoun = None;
                self.verb = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.determiner = None;
                self.preposition = true;
            }
            DET => {
                self.noun = None;
                self.pronoun = None;
                self.verb = None;
                self.adjective = None;
                self.adverb = None;
                self.conjunction = None;
                self.preposition = false;
                self.determiner = Some(DeterminerData::default());
            }
            CCONJ | SCONJ => {
                if self.conjunction.is_none() {
                    self.conjunction = Some(ConjunctionData::default())
                }

                self.noun = None;
                self.pronoun = None;
                self.verb = None;
                self.adjective = None;
                self.adverb = None;
                self.determiner = None;
                self.preposition = false;
            }
            _ => {}
        }
    }

    generate_metadata_queries!(
        noun has proper, plural, possessive.
        pronoun has personal, singular, plural, possessive, reflexive, object.
        determiner has demonstrative, possessive.
        verb has linking, auxiliary.
        conjunction has.
        adjective has.
        adverb has
    );

    pub fn is_first_person_plural_pronoun(&self) -> bool {
        matches!(
            self.pronoun,
            Some(PronounData {
                person: Some(Person::First),
                is_plural: Some(true),
                ..
            })
        )
    }

    pub fn is_first_person_singular_pronoun(&self) -> bool {
        matches!(
            self.pronoun,
            Some(PronounData {
                person: Some(Person::First),
                is_singular: Some(true),
                ..
            })
        )
    }

    pub fn is_third_person_plural_pronoun(&self) -> bool {
        matches!(
            self.pronoun,
            Some(PronounData {
                person: Some(Person::Third),
                is_plural: Some(true),
                ..
            })
        )
    }

    pub fn is_third_person_singular_pronoun(&self) -> bool {
        matches!(
            self.pronoun,
            Some(PronounData {
                person: Some(Person::Third),
                is_singular: Some(true),
                ..
            })
        )
    }

    pub fn is_third_person_pronoun(&self) -> bool {
        matches!(
            self.pronoun,
            Some(PronounData {
                person: Some(Person::Third),
                ..
            })
        )
    }

    pub fn is_second_person_pronoun(&self) -> bool {
        matches!(
            self.pronoun,
            Some(PronounData {
                person: Some(Person::Second),
                ..
            })
        )
    }

    pub fn is_verb_lemma(&self) -> bool {
        matches!(
            self.verb,
            Some(VerbData {
                verb_form: Some(VerbForm::LemmaForm),
                ..
            })
        )
    }

    pub fn is_verb_past_form(&self) -> bool {
        matches!(
            self.verb,
            Some(VerbData {
                verb_form: Some(VerbForm::PastForm),
                ..
            })
        )
    }

    pub fn is_verb_progressive_form(&self) -> bool {
        matches!(
            self.verb,
            Some(VerbData {
                verb_form: Some(VerbForm::ProgressiveForm),
                ..
            })
        )
    }

    pub fn is_verb_third_person_singular_present_form(&self) -> bool {
        matches!(
            self.verb,
            Some(VerbData {
                verb_form: Some(VerbForm::ThirdPersonSingularPresentForm),
                ..
            })
        )
    }

    /// Checks if the word is definitely nominal.
    pub fn is_nominal(&self) -> bool {
        self.noun.is_some() || self.pronoun.is_some()
    }

    /// Checks if the word is definitely a nominal and more specifically is labeled as (a) singular.
    pub fn is_singular_nominal(&self) -> bool {
        matches!(
            self.noun,
            Some(NounData {
                is_singular: None | Some(true),
                ..
            })
        ) || matches!(
            self.pronoun,
            Some(PronounData {
                is_singular: None | Some(true),
                ..
            })
        )
    }

    /// Checks if the word is definitely a nominal and more specifically is labeled as (a) plural.
    pub fn is_plural_nominal(&self) -> bool {
        matches!(
            self.noun,
            Some(NounData {
                is_plural: Some(true),
                ..
            })
        ) || matches!(
            self.pronoun,
            Some(PronounData {
                is_plural: Some(true),
                ..
            })
        )
    }

    /// Checks if the word is definitely a nominal and more specifically is labeled as (a) possessive.
    pub fn is_possessive_nominal(&self) -> bool {
        matches!(
            self.noun,
            Some(NounData {
                is_possessive: Some(true),
                ..
            })
        ) || matches!(
            self.pronoun,
            Some(PronounData {
                is_possessive: Some(true),
                ..
            })
        )
    }

    /// Checks if the word is definitely a nominal and more specifically is labeled as __not__ (a) singular.
    pub fn is_non_singular_nominal(&self) -> bool {
        matches!(
            self.noun,
            Some(NounData {
                is_singular: Some(false),
                ..
            })
        ) || matches!(
            self.pronoun,
            Some(PronounData {
                is_singular: Some(false),
                ..
            })
        )
    }

    /// Checks if the word is definitely a nominal and more specifically is labeled as __not__ (a) plural.
    pub fn is_non_plural_nominal(&self) -> bool {
        matches!(
            self.noun,
            Some(NounData {
                is_plural: None | Some(false),
                ..
            })
        ) || matches!(
            self.pronoun,
            Some(PronounData {
                is_plural: None | Some(false),
                ..
            })
        )
    }

    /// Checks if the word is definitely a nominal and more specifically is labeled as __not__ (a) possessive.
    pub fn is_non_possessive_nominal(&self) -> bool {
        matches!(
            self.noun,
            Some(NounData {
                is_possessive: Some(false),
                ..
            })
        ) && matches!(
            self.pronoun,
            Some(PronounData {
                is_possessive: Some(false),
                ..
            })
        )
    }

    /// Checks whether a word is _definitely_ a swear.
    pub fn is_swear(&self) -> bool {
        matches!(self.swear, Some(true))
    }

    /// Same thing as [`Self::or`], except in-place rather than a clone.
    pub fn append(&mut self, other: &Self) -> &mut Self {
        *self = self.or(other);
        self
    }
}

// These verb forms are morphological variations, distinct from TAM (Tense-Aspect-Mood)
// Each form can be used in various TAM combinations:
// - Lemma form (infinitive, citation form, dictionary form)
//   Used in infinitives (e.g., "to sleep"), imperatives (e.g., "sleep!"), and with modals (e.g., "will sleep")
// - Past form (past participle and simple past)
//   Used as verbs (e.g., "slept") or adjectives (e.g., "closed door")
// - Progressive form (present participle and gerund)
//   Used as verbs (e.g., "sleeping"), nouns (e.g., "sleeping is important"), or adjectives (e.g., "sleeping dog")
// - Third person singular present (-s/-es)
//   Used for third person singular subjects (e.g., "he sleeps", "she reads")
//
// Important notes:
// 1. English expresses time through auxiliary verbs, not verb form alone
// 2. Irregular verbs can have different forms for past participle and simple past
// 3. Future is always expressed through auxiliary verbs (e.g., "will sleep", "going to sleep")
#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, PartialOrd, Is, Hash)]
pub enum VerbForm {
    LemmaForm,
    PastForm,
    ProgressiveForm,
    ThirdPersonSingularPresentForm,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct VerbData {
    pub is_linking: Option<bool>,
    pub is_auxiliary: Option<bool>,
    pub verb_form: Option<VerbForm>,
}

impl VerbData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, other: &Self) -> Self {
        Self {
            is_linking: self.is_linking.or(other.is_linking),
            is_auxiliary: self.is_auxiliary.or(other.is_auxiliary),
            verb_form: self.verb_form.or(other.verb_form),
        }
    }
}

// nouns can be both singular and plural: "aircraft", "biceps", "fish", "sheep"
// TODO other noun properties may be worth adding:
// TODO count vs mass; abstract
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct NounData {
    pub is_proper: Option<bool>,
    pub is_singular: Option<bool>,
    pub is_plural: Option<bool>,
    pub is_possessive: Option<bool>,
}

impl NounData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, other: &Self) -> Self {
        Self {
            is_proper: self.is_proper.or(other.is_proper),
            is_singular: self.is_singular.or(other.is_singular),
            is_plural: self.is_plural.or(other.is_plural),
            is_possessive: self.is_possessive.or(other.is_possessive),
        }
    }
}

// Person is a property of pronouns; the verb 'be', plus all verbs reflect 3rd person singular with -s
#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, PartialOrd, Is, Hash)]
pub enum Person {
    First,
    Second,
    Third,
}

// TODO for now focused on personal pronouns?
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct PronounData {
    pub is_personal: Option<bool>,
    pub is_singular: Option<bool>,
    pub is_plural: Option<bool>,
    pub is_possessive: Option<bool>,
    pub is_reflexive: Option<bool>,
    pub person: Option<Person>,
    pub is_subject: Option<bool>,
    pub is_object: Option<bool>,
}

impl PronounData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, other: &Self) -> Self {
        Self {
            is_personal: self.is_personal.or(other.is_personal),
            is_singular: self.is_singular.or(other.is_singular),
            is_plural: self.is_plural.or(other.is_plural),
            is_possessive: self.is_possessive.or(other.is_possessive),
            is_reflexive: self.is_reflexive.or(other.is_reflexive),
            person: self.person.or(other.person),
            is_subject: self.is_subject.or(other.is_subject),
            is_object: self.is_object.or(other.is_object),
        }
    }
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct DeterminerData {
    pub is_demonstrative: Option<bool>,
    pub is_possessive: Option<bool>,
}

impl DeterminerData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, other: &Self) -> Self {
        Self {
            is_demonstrative: self.is_demonstrative.or(other.is_demonstrative),
            is_possessive: self.is_possessive.or(other.is_possessive),
        }
    }
}

// Degree is a property of adjectives: positive is not inflected
// Comparative is inflected with -er or comes after the word "more"
// Superlative is inflected with -est or comes after the word "most"
#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, PartialOrd, Is, Hash)]
pub enum Degree {
    Positive,
    Comparative,
    Superlative,
}

// Some adjectives are not comparable so don't have -er or -est forms and can't be used with "more" or "most".
// Some adjectives can only be used "attributively" (before a noun); some only predicatively (after "is" etc.).
// In old grammars words like the articles and determiners are classified as adjectives but behave differently.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct AdjectiveData {
    pub degree: Option<Degree>,
}

impl AdjectiveData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, other: &Self) -> Self {
        Self {
            degree: self.degree.or(other.degree),
        }
    }
}

// Adverb can be a "junk drawer" category for words which don't fit the other major categories.
// The typical adverbs are "adverbs of manner", those derived from adjectives in -ly
// other adverbs (time, place, etc) should probably not be considered adverbs for Harper's purposes
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct AdverbData {}

impl AdverbData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, _other: &Self) -> Self {
        Self {}
    }
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash, Default)]
pub struct ConjunctionData {}

impl ConjunctionData {
    /// Produce a copy of `self` with the known properties of `other` set.
    pub fn or(&self, _other: &Self) -> Self {
        Self {}
    }
}

/// A regional dialect.
#[derive(
    Debug,
    Clone,
    Copy,
    Serialize,
    Deserialize,
    PartialEq,
    PartialOrd,
    Eq,
    Hash,
    EnumCount,
    EnumString,
    Display,
    VariantArray,
)]
pub enum Dialect {
    // Note: these have bit-shifted values so that they can ergonomically integrate with
    // `DialectFlags`. Each value here must have a unique bit index inside
    // `DialectsUnderlyingType`.
    American = 1 << 0,
    Canadian = 1 << 1,
    Australian = 1 << 2,
    British = 1 << 3,
}
impl Dialect {
    /// Tries to guess the dialect used in the document by finding which dialect is used the most.
    /// Returns `None` if it fails to find a single dialect that is used the most.
    #[must_use]
    pub fn try_guess_from_document(document: &Document) -> Option<Self> {
        Self::try_from(DialectFlags::get_most_used_dialects_from_document(document)).ok()
    }

    /// Tries to get a dialect from its abbreviation. Returns `None` if the abbreviation is not
    /// recognized.
    ///
    /// # Examples
    ///
    /// ```
    /// use harper_core::Dialect;
    ///
    /// let abbrs = ["US", "CA", "AU", "GB"];
    /// let mut dialects = abbrs.iter().map(|abbr| Dialect::try_from_abbr(abbr));
    ///
    /// assert_eq!(Some(Dialect::American), dialects.next().unwrap()); // US
    /// assert_eq!(Some(Dialect::Canadian), dialects.next().unwrap()); // CA
    /// assert_eq!(Some(Dialect::Australian), dialects.next().unwrap()); // AU
    /// assert_eq!(Some(Dialect::British), dialects.next().unwrap()); // GB
    /// ```
    #[must_use]
    pub fn try_from_abbr(abbr: &str) -> Option<Self> {
        match abbr {
            "US" => Some(Self::American),
            "CA" => Some(Self::Canadian),
            "AU" => Some(Self::Australian),
            "GB" => Some(Self::British),
            _ => None,
        }
    }
}
impl TryFrom<DialectFlags> for Dialect {
    type Error = ();

    /// Attempts to convert `DialectFlags` to a single `Dialect`.
    ///
    /// # Errors
    ///
    /// Will return `Err` if more than one dialect is enabled or if an undefined dialect is
    /// enabled.
    fn try_from(dialect_flags: DialectFlags) -> Result<Self, Self::Error> {
        // Ensure only one dialect is enabled before converting.
        if dialect_flags.bits().count_ones() == 1 {
            match dialect_flags {
                df if df.is_dialect_enabled_strict(Dialect::American) => Ok(Dialect::American),
                df if df.is_dialect_enabled_strict(Dialect::Canadian) => Ok(Dialect::Canadian),
                df if df.is_dialect_enabled_strict(Dialect::Australian) => Ok(Dialect::Australian),
                df if df.is_dialect_enabled_strict(Dialect::British) => Ok(Dialect::British),
                _ => Err(()),
            }
        } else {
            // More than one dialect enabled; can't soundly convert.
            Err(())
        }
    }
}

// The underlying type used for DialectFlags.
// At the time of writing, this is currently a `u8`. If we want to define more than 8 dialects in
// the future, we will need to switch this to a larger type.
type DialectFlagsUnderlyingType = u8;

bitflags::bitflags! {
    /// A collection of bit flags used to represent enabled dialects.
    ///
    /// This is generally used to allow a word (or similar) to be tagged with multiple dialects.
    #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, PartialOrd, Eq, Hash)]
    #[serde(transparent)]
    pub struct DialectFlags: DialectFlagsUnderlyingType {
        const AMERICAN = Dialect::American as DialectFlagsUnderlyingType;
        const CANADIAN = Dialect::Canadian as DialectFlagsUnderlyingType;
        const AUSTRALIAN = Dialect::Australian as DialectFlagsUnderlyingType;
        const BRITISH = Dialect::British as DialectFlagsUnderlyingType;
    }
}
impl DialectFlags {
    /// Checks if the provided dialect is enabled.
    /// If no dialect is explicitly enabled, it is assumed that all dialects are enabled.
    #[must_use]
    pub fn is_dialect_enabled(self, dialect: Dialect) -> bool {
        self.is_empty() || self.intersects(Self::from_dialect(dialect))
    }

    /// Checks if the provided dialect is ***explicitly*** enabled.
    ///
    /// Unlike `is_dialect_enabled`, this will return false when no dialects are explicitly
    /// enabled.
    #[must_use]
    pub fn is_dialect_enabled_strict(self, dialect: Dialect) -> bool {
        self.intersects(Self::from_dialect(dialect))
    }

    /// Constructs a `DialectFlags` from the provided `Dialect`, with only that dialect being
    /// enabled.
    ///
    /// # Panics
    ///
    /// This will panic if `dialect` represents a dialect that is not defined in
    /// `DialectFlags`.
    #[must_use]
    pub fn from_dialect(dialect: Dialect) -> Self {
        let Some(out) = Self::from_bits(dialect as DialectFlagsUnderlyingType) else {
            panic!("The '{dialect}' dialect isn't defined in DialectFlags!");
        };
        out
    }

    /// Gets the most commonly used dialect(s) in the document.
    ///
    /// If multiple dialects are used equally often, they will all be enabled in the returned
    /// `DialectFlags`. On the other hand, if there is a single dialect that is used the most, it
    /// will be the only one enabled.
    #[must_use]
    pub fn get_most_used_dialects_from_document(document: &Document) -> Self {
        // Initialize counters.
        let mut dialect_counters: [(Dialect, usize); Dialect::COUNT] = Dialect::VARIANTS
            .iter()
            .map(|d| (*d, 0))
            .collect_array()
            .unwrap();

        // Count word dialects.
        document.iter_words().for_each(|w| {
            if let TokenKind::Word(Some(word_metadata)) = &w.kind {
                // If the token is a word, iterate though the dialects in `dialect_counters` and
                // increment those counters where the word has the respective dialect enabled.
                dialect_counters.iter_mut().for_each(|(dialect, count)| {
                    if word_metadata.dialects.is_dialect_enabled(*dialect) {
                        *count += 1;
                    }
                });
            }
        });

        // Find max counter.
        let max_counter = dialect_counters
            .iter()
            .map(|(_, count)| count)
            .max()
            .unwrap();
        // Get and convert the collection of most used dialects into a `DialectFlags`.
        dialect_counters
            .into_iter()
            .filter(|(_, count)| count == max_counter)
            .fold(DialectFlags::empty(), |acc, dialect| {
                // Fold most used dialects into `DialectFlags` via bitwise or.
                acc | Self::from_dialect(dialect.0)
            })
    }
}
impl Default for DialectFlags {
    /// A default value with no dialects explicitly enabled.
    /// Implicitly, this state corresponds to all dialects being enabled.
    fn default() -> Self {
        Self::empty()
    }
}

#[cfg(test)]
mod tests {
    use crate::{Dictionary, FstDictionary, WordMetadata};

    // Helper function to get word metadata from the curated dictionary
    fn md(word: &str) -> WordMetadata {
        FstDictionary::curated()
            .get_word_metadata_str(word)
            .unwrap_or_else(|| panic!("Word '{word}' not found in dictionary"))
            .clone()
    }

    mod dialect {
        use super::super::{Dialect, DialectFlags};
        use crate::Document;

        #[test]
        fn guess_british_dialect() {
            let document = Document::new_plain_english_curated("Aluminium was used.");
            let df = DialectFlags::get_most_used_dialects_from_document(&document);
            assert!(
                df.is_dialect_enabled_strict(Dialect::British)
                    && !df.is_dialect_enabled_strict(Dialect::American)
            );
        }

        #[test]
        fn guess_american_dialect() {
            let document = Document::new_plain_english_curated("Aluminum was used.");
            let df = DialectFlags::get_most_used_dialects_from_document(&document);
            assert!(
                df.is_dialect_enabled_strict(Dialect::American)
                    && !df.is_dialect_enabled_strict(Dialect::British)
            );
        }
    }

    mod noun {
        use crate::word_metadata::tests::md;

        #[test]
        fn puppy_is_noun() {
            assert!(md("puppy").noun.is_some());
        }

        #[test]
        fn prepare_is_not_noun() {
            assert!(md("prepare").noun.is_none());
        }

        #[test]
        fn paris_is_proper_noun() {
            assert!(md("Paris").noun.unwrap().is_proper.unwrap());
        }

        #[test]
        fn permit_is_not_proper_noun() {
            assert!(matches!(
                md("lapdog").noun.and_then(|n| n.is_proper),
                None | Some(false)
            ));
        }

        #[test]
        #[ignore = "noun singular property not implemented yet"]
        fn hound_is_singular_noun() {
            assert!(md("hound").noun.unwrap().is_singular.unwrap());
        }

        #[test]
        fn pooches_is_not_singular_noun() {
            assert!(matches!(
                md("pooches").noun.and_then(|n| n.is_singular),
                None | Some(false)
            ));
        }

        #[test]
        fn hounds_is_plural_noun() {
            assert!(md("hounds").noun.unwrap().is_plural.unwrap());
        }

        #[test]
        fn pooch_is_not_plural_noun() {
            assert!(matches!(
                md("pooch").noun.and_then(|n| n.is_plural),
                None | Some(false)
            ));
        }

        #[test]
        #[ignore = "noun singular property not implemented yet"]
        fn fish_is_singular_noun() {
            assert!(md("fish").noun.unwrap().is_singular.unwrap());
        }

        #[test]
        fn fish_is_plural_noun() {
            assert!(md("fish").noun.unwrap().is_plural.unwrap());
        }

        #[test]
        fn fishes_is_plural_noun() {
            assert!(md("fishes").noun.unwrap().is_plural.unwrap());
        }

        #[test]
        #[ignore = "noun singular property not implemented yet"]
        fn sheep_is_singular_noun() {
            assert!(md("sheep").noun.unwrap().is_singular.unwrap());
        }

        #[test]
        fn sheep_is_plural_noun() {
            assert!(md("sheep").noun.unwrap().is_plural.unwrap());
        }

        #[test]
        #[should_panic]
        fn sheeps_is_not_word() {
            md("sheeps");
        }

        #[test]
        #[ignore = "noun singular property not implemented yet"]
        fn bicep_is_singular_noun() {
            assert!(md("bicep").noun.unwrap().is_singular.unwrap());
        }

        #[test]
        #[ignore = "noun singular property not implemented yet"]
        fn biceps_is_singular_noun() {
            assert!(md("biceps").noun.unwrap().is_singular.unwrap());
        }

        #[test]
        fn biceps_is_plural_noun() {
            assert!(md("biceps").noun.unwrap().is_plural.unwrap());
        }

        #[test]
        #[ignore = "noun singular property not implemented yet"]
        fn aircraft_is_singular_noun() {
            assert!(md("aircraft").noun.unwrap().is_singular.unwrap());
        }

        #[test]
        #[ignore = "noun plural property not implemented yet"]
        fn aircraft_is_plural_noun() {
            assert!(md("aircraft").noun.unwrap().is_plural.unwrap());
        }

        #[test]
        #[should_panic]
        fn aircrafts_is_not_word() {
            md("aircrafts");
        }

        #[test]
        fn dog_apostrophe_s_is_possessive_noun() {
            assert!(md("dog's").noun.unwrap().is_possessive.unwrap());
        }

        #[test]
        fn dogs_is_not_possessive_noun() {
            assert!(md("dogs").noun.unwrap().is_possessive.is_none());
        }
    }

    mod pronoun {
        use crate::word_metadata::tests::md;

        mod i_me_myself {
            use crate::word_metadata::tests::md;

            #[test]
            fn i_is_pronoun() {
                assert!(md("I").pronoun.is_some());
            }
            #[test]
            fn i_is_personal_pronoun() {
                assert!(md("I").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn i_is_singular_pronoun() {
                assert!(md("I").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn i_is_subject_pronoun() {
                assert!(md("I").pronoun.unwrap().is_subject.unwrap());
            }

            #[test]
            fn me_is_pronoun() {
                assert!(md("me").pronoun.is_some());
            }
            #[test]
            fn me_is_personal_pronoun() {
                assert!(md("me").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn me_is_singular_pronoun() {
                assert!(md("me").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn me_is_object_pronoun() {
                assert!(md("me").pronoun.unwrap().is_object.unwrap());
            }

            #[test]
            fn myself_is_pronoun() {
                assert!(md("myself").pronoun.is_some());
            }
            #[test]
            fn myself_is_personal_pronoun() {
                assert!(md("myself").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn myself_is_singular_pronoun() {
                assert!(md("myself").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn myself_is_reflexive_pronoun() {
                assert!(md("myself").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        mod we_us_ourselves {
            use crate::word_metadata::tests::md;

            #[test]
            fn we_is_pronoun() {
                assert!(md("we").pronoun.is_some());
            }
            #[test]
            fn we_is_personal_pronoun() {
                assert!(md("we").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn we_is_plural_pronoun() {
                assert!(md("we").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn we_is_subject_pronoun() {
                assert!(md("we").pronoun.unwrap().is_subject.unwrap());
            }

            #[test]
            fn us_is_pronoun() {
                assert!(md("us").pronoun.is_some());
            }
            #[test]
            fn us_is_personal_pronoun() {
                assert!(md("us").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn us_is_plural_pronoun() {
                assert!(md("us").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn us_is_object_pronoun() {
                assert!(md("us").pronoun.unwrap().is_object.unwrap());
            }

            #[test]
            fn ourselves_is_pronoun() {
                assert!(md("ourselves").pronoun.is_some());
            }
            #[test]
            fn ourselves_is_personal_pronoun() {
                assert!(md("ourselves").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn ourselves_is_plural_pronoun() {
                assert!(md("ourselves").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn ourselves_is_reflexive_pronoun() {
                assert!(md("ourselves").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        mod you_yourself {
            use crate::word_metadata::tests::md;

            #[test]
            fn you_is_pronoun() {
                assert!(md("you").pronoun.is_some());
            }
            #[test]
            fn you_is_personal_pronoun() {
                assert!(md("you").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn you_is_singular_pronoun() {
                assert!(md("you").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn you_is_plural_pronoun() {
                assert!(md("you").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn you_is_subject_pronoun() {
                assert!(md("you").pronoun.unwrap().is_subject.unwrap());
            }
            #[test]
            fn you_is_object_pronoun() {
                assert!(md("you").pronoun.unwrap().is_object.unwrap());
            }
            #[test]
            fn yourself_is_pronoun() {
                assert!(md("yourself").pronoun.is_some());
            }
            #[test]
            fn yourself_is_personal_pronoun() {
                assert!(md("yourself").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn yourself_is_singular_pronoun() {
                assert!(md("yourself").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn yourself_is_reflexive_pronoun() {
                assert!(md("yourself").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        mod he_him_himself {
            use crate::word_metadata::tests::md;

            #[test]
            fn he_is_pronoun() {
                assert!(md("he").pronoun.is_some());
            }
            #[test]
            fn he_is_personal_pronoun() {
                assert!(md("he").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn he_is_singular_pronoun() {
                assert!(md("he").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn he_is_subject_pronoun() {
                assert!(md("he").pronoun.unwrap().is_subject.unwrap());
            }

            #[test]
            fn him_is_pronoun() {
                assert!(md("him").pronoun.is_some());
            }
            #[test]
            fn him_is_personal_pronoun() {
                assert!(md("him").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn him_is_singular_pronoun() {
                assert!(md("him").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn him_is_object_pronoun() {
                assert!(md("him").pronoun.unwrap().is_object.unwrap());
            }

            #[test]
            fn himself_is_pronoun() {
                assert!(md("himself").pronoun.is_some());
            }
            #[test]
            fn himself_is_personal_pronoun() {
                assert!(md("himself").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn himself_is_singular_pronoun() {
                assert!(md("himself").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn himself_is_reflexive_pronoun() {
                assert!(md("himself").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        mod she_her_herself {
            use crate::word_metadata::tests::md;

            #[test]
            fn she_is_pronoun() {
                assert!(md("she").pronoun.is_some());
            }
            #[test]
            fn she_is_personal_pronoun() {
                assert!(md("she").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn she_is_singular_pronoun() {
                assert!(md("she").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn she_is_subject_pronoun() {
                assert!(md("she").pronoun.unwrap().is_subject.unwrap());
            }

            #[test]
            fn her_is_pronoun() {
                assert!(md("her").pronoun.is_some());
            }
            #[test]
            fn her_is_personal_pronoun() {
                assert!(md("her").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn her_is_singular_pronoun() {
                assert!(md("her").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn her_is_object_pronoun() {
                assert!(md("her").pronoun.unwrap().is_object.unwrap());
            }

            #[test]
            fn herself_is_pronoun() {
                assert!(md("herself").pronoun.is_some());
            }
            #[test]
            fn herself_is_personal_pronoun() {
                assert!(md("herself").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn herself_is_singular_pronoun() {
                assert!(md("herself").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn herself_is_reflexive_pronoun() {
                assert!(md("herself").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        mod it_itself {
            use crate::word_metadata::tests::md;

            #[test]
            fn it_is_pronoun() {
                assert!(md("it").pronoun.is_some());
            }
            #[test]
            fn it_is_personal_pronoun() {
                assert!(md("it").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn it_is_singular_pronoun() {
                assert!(md("it").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn it_is_subject_pronoun() {
                assert!(md("it").pronoun.unwrap().is_subject.unwrap());
            }
            #[test]
            fn it_is_object_pronoun() {
                assert!(md("it").pronoun.unwrap().is_object.unwrap());
            }

            #[test]
            fn itself_is_pronoun() {
                assert!(md("itself").pronoun.is_some());
            }
            #[test]
            fn itself_is_personal_pronoun() {
                assert!(md("itself").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn itself_is_singular_pronoun() {
                assert!(md("itself").pronoun.unwrap().is_singular.unwrap());
            }
            #[test]
            fn itself_is_reflexive_pronoun() {
                assert!(md("itself").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        mod they_them_themselves {
            use crate::word_metadata::tests::md;

            #[test]
            fn they_is_pronoun() {
                assert!(md("they").pronoun.is_some());
            }
            #[test]
            fn they_is_personal_pronoun() {
                assert!(md("they").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn they_is_plural_pronoun() {
                assert!(md("they").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn they_is_subject_pronoun() {
                assert!(md("they").pronoun.unwrap().is_subject.unwrap());
            }

            #[test]
            fn them_is_pronoun() {
                assert!(md("them").pronoun.is_some());
            }
            #[test]
            fn them_is_personal_pronoun() {
                assert!(md("them").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn them_is_plural_pronoun() {
                assert!(md("them").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn them_is_object_pronoun() {
                assert!(md("them").pronoun.unwrap().is_object.unwrap());
            }

            #[test]
            fn themselves_is_pronoun() {
                assert!(md("themselves").pronoun.is_some());
            }
            #[test]
            fn themselves_is_personal_pronoun() {
                assert!(md("themselves").pronoun.unwrap().is_personal.unwrap());
            }
            #[test]
            fn themselves_is_plural_pronoun() {
                assert!(md("themselves").pronoun.unwrap().is_plural.unwrap());
            }
            #[test]
            fn themselves_is_reflexive_pronoun() {
                assert!(md("themselves").pronoun.unwrap().is_reflexive.unwrap());
            }
        }

        // Possessive pronouns (not to be confused with possessive adjectives/determiners)
        #[test]
        fn mine_is_pronoun() {
            assert!(md("mine").pronoun.is_some());
        }
        #[test]
        fn ours_is_pronoun() {
            assert!(md("ours").pronoun.is_some());
        }
        #[test]
        fn yours_is_pronoun() {
            assert!(md("yours").pronoun.is_some());
        }
        #[test]
        fn his_is_pronoun() {
            assert!(md("his").pronoun.is_some());
        }
        #[test]
        fn hers_is_pronoun() {
            assert!(md("hers").pronoun.is_some());
        }
        #[test]
        fn its_is_pronoun() {
            assert!(md("its").pronoun.is_some());
        }
        #[test]
        fn theirs_is_pronoun() {
            assert!(md("theirs").pronoun.is_some());
        }

        // archaic pronouns
        #[test]
        fn archaic_pronouns() {
            assert!(md("thou").pronoun.is_some());
            assert!(md("thee").pronoun.is_some());
            assert!(md("thyself").pronoun.is_some());
            assert!(md("thine").pronoun.is_some());
        }

        // generic pronouns
        #[test]
        fn generic_pronouns() {
            assert!(md("one").pronoun.is_some());
            assert!(md("oneself").pronoun.is_some());
        }

        // relative and interrogative pronouns
        #[test]
        fn relative_and_interrogative_pronouns() {
            assert!(md("who").pronoun.is_some());
            assert!(md("whom").pronoun.is_some());
            assert!(md("whose").pronoun.is_some());
            assert!(md("which").pronoun.is_some());
            assert!(md("what").pronoun.is_some());
        }

        // nonstandard pronouns
        #[test]
        #[ignore = "not in dictionary"]
        fn nonstandard_pronouns() {
            assert!(md("themself").pronoun.is_some());
            assert!(md("y'all'").pronoun.is_some());
        }
    }

    #[test]
    fn the_is_determiner() {
        assert!(md("the").determiner.is_some());
    }
    #[test]
    fn this_is_demonstrative_determiner() {
        assert!(md("this").determiner.unwrap().is_demonstrative.unwrap());
    }
    #[test]
    fn your_is_possessive_determiner() {
        assert!(md("your").determiner.unwrap().is_possessive.unwrap());
    }
}