1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390
/******************************************************************************* * Copyright 2021 Stefan Majewsky <majewsky@gmx.net> * SPDX-License-Identifier: Apache-2.0 * Refer to the file "LICENSE" for details. *******************************************************************************/ //! The [JMdict file](https://www.edrdg.org/jmdict/j_jmdict.html) is a comprehensive multilingual //! dictionary of the Japanese language. The original JMdict file, included in this repository (and //! hence, in releases of this crate) comes as XML. Instead of stuffing the XML in the binary //! directly, this crate parses the XML at compile-time and generates an optimized representation //! that is compiled into the binary. The crate's API affords type-safe access to this embedded //! database. //! //! # WARNING: Licensing on database files //! //! The database files compiled into the crate are licensed from the Electronic Dictionary Research //! and Development Group under Creative Commons licenses. Applications linking this crate directly //! oder indirectly must display appropriate copyright notices to users. Please refer to the //! [EDRDG's license statement](https://www.edrdg.org/edrdg/licence.html) for details. //! //! # Basic usage //! //! The database is accessed through the [entries() function](entries) which provides an iterator //! over all database entries compiled into the application. While traversing the database and its //! entries, you will find that, whenever you expect a list of something, you will get an iterator //! instead. These iterators provide an abstraction between you as the user of the library, and the //! physical representation of the database as embedded in the binary. //! //! The following example looks up the reading for お母さん in the database: //! //! ``` //! let kanji_form = "お母さん"; //! //! let entry = jmdict::entries().find(|e| { //! e.kanji_elements().any(|k| k.text == kanji_form) //! }).unwrap(); //! //! let reading_form = entry.reading_elements().next().unwrap().text; //! assert_eq!(reading_form, "おかあさん"); //! ``` //! //! # Cargo features //! //! ### Common configurations //! //! * The `default` feature includes the most common words (about 30000 entries) and only their //! English translations. //! * The `full` feature includes everything in the JMdict. //! //! ### Entry selection //! //! * The `scope-uncommon` feature includes uncommon words and glosses. //! * The `scope-archaic` feature includes glosses with the "archaic" label. If disabled, the //! [PartOfSpeech] enum will not include variants that are only relevant for archaic vocabulary, //! such as obsolete conjugation patterns. (The [AllPartOfSpeech] enum always contains all //! variants.) //! //! ### Target languages //! //! At least one target language must be selected. Selecting a target language will include all //! available translations in that language. Entries that do not have any translation in any of the //! selected languages will be skipped. //! //! * `translations-eng`: English (included in `default`) //! * `translations-dut`: Dutch //! * `translations-fre`: French //! * `translations-ger`: German //! * `translations-hun`: Hungarian //! * `translations-rus`: Russian //! * `translations-slv`: Slovenian //! * `translations-spa`: Spanish //! * `translations-swe`: Swedish //! //! The [GlossLanguage] enum will only contain variants corresponding to the enabled target //! languages. For example, in the default configuration, `GlossLanguage::English` will be the only //! variant. (The [AllGlossLanguage] enum always contains all variants.) //! //! ### Crippled builds: `db-minimal` //! //! When the `db-minimal` feature is enabled, only a severly reduced portion of the JMdict will //! be parsed (to be exact, only chunks 000, 100 and 999). This is also completely useless for //! actual usage, but allows for quick edit-compile-test cycles while working on this crate's //! code. //! //! ### Crippled builds: `db-empty` //! //! When the `db-empty` feature is enabled, downloading and parsing of the JMdict contents is //! disabled entirely. The crate is compiled as usual, but `entries()` will be an empty list. //! This is useful for documentation builds like for `docs.rs`, where `--all-features` is given. pub use jmdict_enums::{ AllGlossLanguage, AllPartOfSpeech, Dialect, DisabledVariant, Enum, GlossLanguage, GlossType, KanjiInfo, PartOfSpeech, Priority, PriorityInCorpus, ReadingInfo, SenseInfo, SenseTopic, }; mod payload; use payload::*; #[cfg(test)] mod test_consistency; #[cfg(test)] mod test_feature_matrix; #[cfg(test)] mod test_ordering; ///Returns an iterator over all entries in the database. pub fn entries() -> Entries { Entries::new() } ///An entry in the JMdict dictionary. /// ///Each entry has zero or more [kanji elements](KanjiElement), one or more ///[reading elements](ReadingElement) and one or more [senses](Sense). Elements contain the ///Japanese representation of the vocabulary or phrase. Whereas reading elements consist of only ///kana, kanji elements will contain characters from non-kana scripts, most commonly kanji. Senses ///contain the translation of the vocabulary or phrase in other languages, most commonly English. #[derive(Clone, Copy, Debug)] pub struct Entry { ///The sequence number for this Entry as it appears in the JMdict. Numbers start around 1000000 ///and typically increment in steps of 5 or 10. (It's like BASIC line numbers, if you're old ///enough to understand that reference.) The [Entries] iterator guarantees entries to appear ///ordered by sequence number. pub number: u32, kanji_elements_iter: KanjiElements, reading_elements_iter: ReadingElements, senses_iter: Senses, } impl Entry { pub fn kanji_elements(&self) -> KanjiElements { self.kanji_elements_iter } pub fn reading_elements(&self) -> ReadingElements { self.reading_elements_iter } pub fn senses(&self) -> Senses { self.senses_iter } } ///A representation of a dictionary entry using kanji or other non-kana scripts. /// ///Each [Entry] may have any number of these (including none). For each kanji element, the entry ///will also have [reading elements](ReadingElement) to indicate how to read this kanji element. #[derive(Clone, Copy, Debug)] pub struct KanjiElement { pub text: &'static str, pub priority: Priority, info_iter: KanjiInfos, } impl KanjiElement { pub fn infos(&self) -> KanjiInfos { self.info_iter } } ///A representation of a dictionary entry using only kana. /// ///Each [Entry] will have zero or more of these. When an entry has both kanji elements and reading ///elements, the kana usage will be consistent between them, that is: If the kanji element contains ///katakana, there is also a corresponding reading element that contains katakana as well. #[derive(Clone, Copy, Debug)] pub struct ReadingElement { pub text: &'static str, pub priority: Priority, info_iter: ReadingInfos, } impl ReadingElement { pub fn infos(&self) -> ReadingInfos { self.info_iter } } ///The translational equivalent of a Japanese word or phrase. /// ///Where there are several distinctly different meanings of the word, its [Entry] will have ///multiple senses. Each particular translation is a [Gloss], of which there may be multiple within ///a single sense. /// ///For instance, the entry for 折角 contains one sense with the glosses "with trouble" and "at ///great pains". Those glosses all represent the same meaning, so they appear in one sense. There ///is also a sense with the glosses "rare", "precious", "valuable" and "long-awaited". Those ///glosses represent a different meaning from "with trouble" or "at great pains", so they appear in ///a separate sense. (And in fact, 折角 has even more senses.) #[derive(Clone, Copy, Debug)] pub struct Sense { stagk_iter: Strings, stagr_iter: Strings, pos_iter: PartsOfSpeech, cross_refs_iter: Strings, antonyms_iter: Strings, topics_iter: SenseTopics, info_iter: SenseInfos, freetext_info_iter: Strings, loanword_sources_iter: LoanwordSources, dialects_iter: Dialects, glosses_iter: Glosses, } impl Sense { ///If not empty, this sense only applies to these [KanjiElements] out of all the ///[KanjiElements] in this [Entry]. pub fn applicable_kanji_elements(&self) -> Strings { self.stagk_iter } ///If not empty, this sense only applies to these [ReadingElements] out of all the ///[ReadingElements] in this [Entry]. pub fn applicable_reading_elements(&self) -> Strings { self.stagr_iter } pub fn parts_of_speech(&self) -> PartsOfSpeech { self.pos_iter } ///If not empty, contains the text of [KanjiElements] or [ReadingElements] of other [Entries] ///with a similar meaning or sense. In some cases, a [KanjiElement]'s text will be followed by ///a [Reading Element]'s text and/or a sense number to provide a precise target for the ///cross-reference. Where this happens, a katakana middle dot (`・`, U+30FB) is placed between ///the components of the cross-reference. /// ///TODO: Provide a structured type for these kinds of references. pub fn cross_references(&self) -> Strings { self.cross_refs_iter } ///If not empty, contains the text of [KanjiElements] or [ReadingElements] of other [Entries] ///which are antonyms of this sense. pub fn antonyms(&self) -> Strings { self.antonyms_iter } pub fn topics(&self) -> SenseTopics { self.topics_iter } pub fn infos(&self) -> SenseInfos { self.info_iter } ///If not empty, contains additional information about this sence (e.g. level of currency or ///other nuances) that cannot be expressed by the other, more structured fields. pub fn freetext_infos(&self) -> Strings { self.freetext_info_iter } ///If not empty, contains source words in other languages from which this vocabulary has been ///borrowed in this sense. pub fn loanword_sources(&self) -> LoanwordSources { self.loanword_sources_iter } ///If not empty, this [Sense] of the [Entry] only appears in the given [Dialects] of Japanese. pub fn dialects(&self) -> Dialects { self.dialects_iter } pub fn glosses(&self) -> Glosses { self.glosses_iter } } ///A source word in other language which a particular [Sense] of an [Entry] has been borrowed from. /// ///There may be multiple sources for a single [Sense] when it is not clear from which language a ///word has been borrowed (e.g. "セレナーデ" lists both the French word "sérénade" and the German ///word "Serenade" as loanword sources), or if the vocabulary is a composite word with multiple ///distinct sources (e.g. "サブリュック" is a combination of the English prefix "sub-" and the ///German word "Rucksack"). /// ///Within an [Entry], glosses appear in the [Sense]. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct LoanwordSource { pub text: &'static str, ///The [ISO 639-2/B code](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) for the ///language from which the word was borrowed, e.g. "ger" for German or "chi" for Chinese. pub language: &'static str, ///Whether this source applies only to part of the loanword. Note that this flag is not always ///present in the JMdict when it should be. pub is_partial: bool, ///Whether this loanword is a [Wasei-eigo](https://en.wikipedia.org/wiki/Wasei-eigo). pub is_wasei: bool, } ///A particular translation or explanation for a Japanese word or phrase in a different language. /// ///Within an [Entry], glosses appear in the [Sense]. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Gloss { pub language: GlossLanguage, pub text: &'static str, pub gloss_type: GlossType, } ///We cannot do `pub type KanjiElements = Range<KanjiElement, N>` etc. because Range<T, N> is ///private to the crate, so instead we declare a bunch of iterator types that wrap Range<T, N>. macro_rules! wrap_iterator { ($val: ty, $size: literal, $iter: ident) => { ///An iterator providing fast access to objects in the database. Instances of this iterator ///can be copied cheaply. #[derive(Clone, Copy, Debug)] pub struct $iter(Range<$val, $size>); impl From<Range<$val, $size>> for $iter { fn from(r: Range<$val, $size>) -> $iter { $iter(r) } } impl std::iter::Iterator for $iter { type Item = $val; fn next(&mut self) -> Option<Self::Item> { self.0.next() } fn size_hint(&self) -> (usize, Option<usize>) { self.0.size_hint() } } impl std::iter::ExactSizeIterator for $iter { fn len(&self) -> usize { self.0.len() } } }; } wrap_iterator!(KanjiElement, 5, KanjiElements); wrap_iterator!(KanjiInfo, 1, KanjiInfos); wrap_iterator!(ReadingElement, 5, ReadingElements); wrap_iterator!(ReadingInfo, 1, ReadingInfos); wrap_iterator!(Sense, 5, Senses); wrap_iterator!(&'static str, 2, Strings); wrap_iterator!(PartOfSpeech, 1, PartsOfSpeech); wrap_iterator!(SenseTopic, 1, SenseTopics); wrap_iterator!(SenseInfo, 1, SenseInfos); wrap_iterator!(LoanwordSource, 4, LoanwordSources); wrap_iterator!(Dialect, 1, Dialects); wrap_iterator!(Gloss, 2, Glosses); ///An iterator providing fast access to objects in the database. Instances of this iterator ///can be copied cheaply. #[derive(Clone, Copy)] pub struct Entries { //This iterator is very similar to Range<T, N>, but cannot be implemented in terms of it //because it iterates over ALL_ENTRY_OFFSETS instead of ALL_DATA. start: usize, end: usize, } impl Entries { fn new() -> Self { Self { start: 0, end: entry_count(), } } } impl std::iter::Iterator for Entries { type Item = Entry; fn next(&mut self) -> Option<Self::Item> { if self.start < self.end { let entry = get_entry(self.start); self.start += 1; Some(entry) } else { None } } fn size_hint(&self) -> (usize, Option<usize>) { let count = self.end - self.start; (count, Some(count)) } } impl std::iter::ExactSizeIterator for Entries { fn len(&self) -> usize { self.end - self.start } }