diff --git a/docs/interfaces/translator-types.ts b/docs/interfaces/translator-types.ts new file mode 100644 index 00000000..060bc4ca --- /dev/null +++ b/docs/interfaces/translator-types.ts @@ -0,0 +1,177 @@ +/* + * Copyright (C) 2022 Yomichan Authors + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +namespace Translation { + // Kanji + + /** + * An options object for use with `Translator.findKanji`. + */ + export interface FindKanjiOptions { + /** + * The mapping of dictionaries to search for kanji in. + * The key is the dictionary name. + */ + enabledDictionaryMap: Map; + } + + /** + * Details about a dictionary. + */ + export interface FindKanjiDictionary { + /** + * The index of the dictionary + */ + index: number; + /** + * The priority of the dictionary + */ + priority: number; + } + + // Terms + + /** + * An options object for use with `Translator.findTerms`. + */ + export interface FindTermsOptions { + /** + * The matching type for looking up terms. + */ + matchType: FindTermsMatchType; + /** + * The name of the primary dictionary to search. + */ + mainDictionary: string; + /** + * The name of the frequency dictionary used for sorting + */ + sortFrequencyDictionary: string | null; + /** + * The order used when using a sorting dictionary. + */ + sortFrequencyDictionaryOrder: FindTermsSortOrder; + /** + * Whether or not non-Japanese characters should be searched. + */ + removeNonJapaneseCharacters: boolean; + /** + * Whether or not half-width characters should be converted to full-width characters. + */ + convertHalfWidthCharacters: FindTermsVariantMode; + /** + * Whether or not ASCII numeric characters should be converted to full-width numeric characters. + */ + convertNumericCharacters: FindTermsVariantMode; + /** + * Whether or not alphabetic characters should be converted to kana. + */ + convertAlphabeticCharacters: FindTermsVariantMode; + /** + * Whether or not hiragana characters should be converted to katakana. + */ + convertHiraganaToKatakana: FindTermsVariantMode; + /** + * Whether or not katakana characters should be converted to hiragana. + */ + convertKatakanaToHiragana: FindTermsVariantMode; + /** + * How emphatic character sequences should be collapsed. + */ + collapseEmphaticSequences: FindTermsEmphaticSequencesMode; + /** + * An iterable sequence of text replacements to be applied during the term lookup process. + */ + textReplacements: Iterable<(FindTermsTextReplacement | null)> | null; + /** + * The mapping of dictionaries to search for terms in. + * The key is the dictionary name. + */ + enabledDictionaryMap: Map; + /** + * A set of dictionary names which should have definitions removed. + */ + excludeDictionaryDefinitions: Set | null; + } + + /** + * The matching type for looking up terms. + */ + export enum FindTermsMatchType { + Exact = 'exact', + Prefix = 'prefix', + Suffix = 'suffix', + } + + /** + * A sorting order to use when finding terms. + */ + export enum FindTermsSortOrder { + Ascending = 'ascending', + Descending = 'descending', + } + + /** + * Mode describing how to handle variations. + */ + export enum FindTermsVariantMode { + False = 'false', + True = 'true', + Variant = 'variant', + } + + /** + * Mode describing how to handle emphatic sequence variations. + */ + export enum FindTermsEmphaticSequencesMode { + False = 'false', + True = 'true', + Full = 'full', + } + + /** + * Information about how text should be replaced when looking up terms. + */ + export interface FindTermsTextReplacement { + /** + * The pattern to replace. + */ + pattern: RegExp; + /** + * The replacement string. This can contain special sequences, such as `$&`. + */ + replacement: string; + } + + /** + * Details about a dictionary. + */ + export interface FindTermDictionary { + /** + * The index of the dictionary + */ + index: number; + /** + * The priority of the dictionary + */ + priority: number; + /** + * Whether or not secondary term searches are allowed for this dictionary. + */ + allowSecondarySearches: boolean; + } +} diff --git a/ext/js/background/backend.js b/ext/js/background/backend.js index 54e8ff08..66f80351 100644 --- a/ext/js/background/backend.js +++ b/ext/js/background/backend.js @@ -1958,6 +1958,13 @@ class Backend { this._applyOptions(source); } + /** + * Creates an options object for use with `Translator.findTerms`. + * @param {string} mode The display mode for the dictionary entries. + * @param {{matchType: string, deinflect: boolean}} details Custom info for finding terms. + * @param {object} options The options. + * @returns {FindTermsOptions} An options object. + */ _getTranslatorFindTermsOptions(mode, details, options) { let {matchType, deinflect} = details; if (typeof matchType !== 'string') { matchType = 'exact'; } @@ -2006,6 +2013,11 @@ class Backend { }; } + /** + * Creates an options object for use with `Translator.findKanji`. + * @param {object} options The options. + * @returns {FindKanjiOptions} An options object. + */ _getTranslatorFindKanjiOptions(options) { const enabledDictionaryMap = this._getTranslatorEnabledDictionaryMap(options); return {enabledDictionaryMap}; diff --git a/ext/js/language/translator.js b/ext/js/language/translator.js index 9ccec9dd..fafd1bfb 100644 --- a/ext/js/language/translator.js +++ b/ext/js/language/translator.js @@ -27,8 +27,9 @@ class Translator { /** * Creates a new Translator instance. - * @param japaneseUtil An instance of JapaneseUtil. - * @param database An instance of DictionaryDatabase. + * @param {object} details The details for the class. + * @param {JapaneseUtil} details.japaneseUtil An instance of JapaneseUtil. + * @param {DictionaryDatabase} details.database An instance of DictionaryDatabase. */ constructor({japaneseUtil, database}) { this._japaneseUtil = japaneseUtil; @@ -42,7 +43,7 @@ class Translator { /** * Initializes the instance for use. The public API should not be used until * this function has been called. - * @param deinflectionReasons The raw deinflections reasons data that the Deinflector uses. + * @param {object} deinflectionReasons The raw deinflections reasons data that the Deinflector uses. */ prepare(deinflectionReasons) { this._deinflector = new Deinflector(deinflectionReasons); @@ -57,42 +58,11 @@ class Translator { /** * Finds term definitions for the given text. - * @param mode The mode to use for finding terms, which determines the format of the resulting array. + * @param {string} mode The mode to use for finding terms, which determines the format of the resulting array. * One of: 'group', 'merge', 'split', 'simple' - * @param text The text to find terms for. - * @param options An object using the following structure: - * ``` - * { - * matchType: (enum: 'exact', 'prefix', 'suffix'), - * mainDictionary: (string), - * sortFrequencyDictionary: (null or string), - * sortFrequencyDictionaryOrder: (enum: 'ascending', 'descending'), - * removeNonJapaneseCharacters: (boolean), - * convertHalfWidthCharacters: (enum: 'false', 'true', 'variant'), - * convertNumericCharacters: (enum: 'false', 'true', 'variant'), - * convertAlphabeticCharacters: (enum: 'false', 'true', 'variant'), - * convertHiraganaToKatakana: (enum: 'false', 'true', 'variant'), - * convertKatakanaToHiragana: (enum: 'false', 'true', 'variant'), - * collapseEmphaticSequences: (enum: 'false', 'true', 'full'), - * textReplacements: [ - * (null or [ - * {pattern: (RegExp), replacement: (string)} - * ... - * ]) - * ... - * ], - * enabledDictionaryMap: (Map of [ - * (string), - * { - * index: (number), - * priority: (number), - * allowSecondarySearches: (boolean) - * } - * ]), - * excludeDictionaryDefinitions: (Set of (string) or null) - * } - * ``` - * @returns An object of the structure `{dictionaryEntries, originalTextLength}`. + * @param {string} text The text to find terms for. + * @param {Translation.FindTermsOptions} options A object describing settings about the lookup. + * @returns {{dictionaryEntries: Translation.TermDictionaryEntry[], originalTextLength: number}} An object containing dictionary entries and the length of the original source text. */ async findTerms(mode, text, options) { const {enabledDictionaryMap, excludeDictionaryDefinitions, sortFrequencyDictionary, sortFrequencyDictionaryOrder} = options; @@ -136,20 +106,11 @@ class Translator { /** * Finds kanji definitions for the given text. - * @param text The text to find kanji definitions for. This string can be of any length, + * @param {string} text The text to find kanji definitions for. This string can be of any length, * but is typically just one character, which is a single kanji. If the string is multiple * characters long, each character will be searched in the database. - * @param options An object using the following structure: - * { - * enabledDictionaryMap: (Map of [ - * (string), - * { - * index: (number), - * priority: (number) - * } - * ]) - * } - * @returns An array of definitions. See the _createKanjiDefinition() function for structure details. + * @param {Translation.FindKanjiOptions} options A object describing settings about the lookup. + * @returns {Translation.KanjiDictionaryEntry[]} An array of definitions. See the _createKanjiDefinition() function for structure details. */ async findKanji(text, options) { const {enabledDictionaryMap} = options; @@ -185,11 +146,10 @@ class Translator { /** * Gets a list of frequency information for a given list of term-reading pairs * and a list of dictionaries. - * @param termReadingList An array of `{term, reading}` pairs. If reading is null, + * @param {{term: string, reading: string|null}[]} termReadingList An array of `{term, reading}` pairs. If reading is null, * the reading won't be compared. - * @param dictionaries An array of dictionary names. - * @returns An array of objects with the format - * `{term, reading, dictionary, hasReading, frequency}`. + * @param {Iterable} dictionaries An array of dictionary names. + * @returns {TermFrequency[]} An array of term frequencies. */ async getTermFrequencies(termReadingList, dictionaries) { const dictionarySet = new Set();