[pull] master from DefinitelyTyped:master

types/russian-nouns-js/index.d.ts

@@ -1,80 +1,46 @@
 /* tslint:disable:no-redundant-jsdoc-2 */
 
-import { Case as CaseEnum } from "./src/Case";
+import { Case } from "./src/Case";
 import Engine from "./src/Engine";
-import { Gender as GenderEnum } from "./src/Gender";
+import { Gender } from "./src/Gender";
 import { Lemma, LemmaOptions } from "./src/Lemma";
+import { LocativeForm, LocativeFormAttribute } from "./src/LocativeForm";
 
 export as namespace RussianNounsJS;
 
-/**
- * Case
- */
-export const Case: { [key in keyof typeof CaseEnum]: typeof CaseEnum[key] };
-
-/**
- * Gender
- */
-export const Gender: { [key in keyof typeof GenderEnum]: typeof GenderEnum[key] };
+export { Case, Gender };
 
 /**
- * Cases
+ * Падежи в обычном порядке.
  */
-export const CASES: Array<typeof CaseEnum[keyof typeof CaseEnum]>;
+export const CASES: [Case];
 
 /**
  * Интерфейс с именованными параметрами для создания лемм.
  * Если параметр — уже лемма, вернет тот же объект, а не копию.
  *
- * Леммы, которые в коде используются много раз, следует
- * конструировать через эту функцию, иначе они будут
- * неявно конструироваться на каждый вызов любой функции
- * или метода в этой библиотеке.
- *
  * @param {RussianNouns.Lemma|Object} o
- * @throws {RussianNouns.LemmaException} Ошибки из конструктора леммы.
+ * @throws {Error} Ошибки из конструктора леммы.
  * @returns {RussianNouns.Lemma} Иммутабельный объект.
  */
-export function createLemma(o: LemmaOptions): Lemma;
+export function createLemma(o: Lemma | LemmaOptions): Lemma;
 
 /**
- * Склонение существительного.
- *
- * Возможные значения:
- * + -1 — несклоняемые, в основном заимствованные слова;
- * + 0 — разносклоняемые "путь" и "дитя";
- * + 1 — мужской и средний род без окончания;
- * + 2 — слова на "а", "я" (м., ж. и общий род);
- * + 3 — жен. род без окончания; слова, оканчивающиеся на "мя".
- *
- * Понятие "склонение" сложно применить к словам pluralia tantum,
- * поэтому этот метод возвращает для них undefined.
+ * Безопасное создание леммы с минимальными накладными расходами.
  *
- * @param {RussianNouns.Lemma|Object} lemma
- * @returns {number|undefined}
+ * @param {Object} options
+ * @returns {RussianNouns.Lemma|null}
  */
-export function getDeclension(lemma: Lemma | object): number | undefined;
+export function createLemmaOrNull(options: LemmaOptions): Lemma | null;
 
 /**
- * «Названия „первое склонение“ и „второе склонение“ в школьной практике и вузовском преподавании
- * нередко закрепляются за разными разрядами слов. В школьных учебниках первым склонением называют изменение
- * слов с окончанием -а (вода), во многих вузовских пособиях и академических грамматиках — слов мужского
- * рода (стол) и среднего рода (окно)».
- *
- * Современный русский язык. Морфология — Камынина А.А., 1999, стр. 67
- *
- * Почти везде указывают это число. Например, в Викисловаре.
- * Иногда в школьных учебниках 10 слов на «-мя» относят к разносклоняемым.
- * Здесь это третье склонение.
- *
- * Понятие "склонение" сложно применить к словам pluralia tantum,
- * поэтому этот метод возвращает для них undefined.
- *
- * @param lemma
- * @returns {number} «Школьный» вариант склонения:
- * «вода» — 1; «стол», «окно» — 2,
- * разносклоняемые — 0; несклоняемые — минус единица.
+ * @deprecated since version 2.3.0
+ */
+export function getDeclension(lemma: Lemma | object): number;
+
+/**
+ * @deprecated since version 2.3.0
  */
 export function getSchoolDeclension(lemma: Lemma): number;
 
-export { Engine };
+export { Engine, Lemma, LocativeForm, LocativeFormAttribute };

types/russian-nouns-js/package.json

@@ -1,7 +1,7 @@
 {
     "private": true,
     "name": "@types/russian-nouns-js",
-    "version": "1.2.9999",
+    "version": "2.3.9999",
     "projects": [
         "https://github.com/georgy7/RussianNounsJS"
     ],

types/russian-nouns-js/src/Engine.d.ts

@@ -2,6 +2,7 @@
 
 import { Case } from "./Case";
 import { Lemma, LemmaOptions } from "./Lemma";
+import { LocativeForm } from "./LocativeForm";
 import StressDictionary from "./StressDictionary";
 
 export default class Engine {
@@ -13,20 +14,24 @@ export default class Engine {
     constructor();
 
     /**
-     * @param {RussianNouns.Lemma|Object} lemma Слово в именительном падеже с метаинформацией.
-     * @param {string} grammaticalCase Падеж.
-     * @param {string} pluralForm Форма во множественном числе.
-     * Если указана, результат будет тоже во множественном.
-     * У pluralia tantum игнорируется.
-     * @returns {Array} Список, т.к. бывают вторые родительный, винительный падежи. Существительные
-     * женского рода в творительном могут иметь как окончания -ей -ой, так и -ею -ою.
+     * Просклонять лемму в указанном падеже.
+     * Метод возвращает список, т.к. бывают вторые родительный, винительный падежи,
+     * и просто в некоторых падежах слова могут иметь по два окончания (например, -ой, -ою).
      * Второй предложный падеж (местный падеж, локатив) не включен в предложный.
      */
-    decline(lemma: LemmaOptions | Lemma, grammaticalCase?: Case[keyof Case], pluralForm?: string): [string];
+    decline(lemma: LemmaOptions | Lemma, grammaticalCase: Case, pluralForm?: string): [string];
 
     /**
-     * @param {RussianNouns.Lemma|Object} lemma
-     * @returns {Array}
+     * Получить формы множественного числа в именительном падеже.
      */
     pluralize(lemma: LemmaOptions | Lemma): [string];
+
+    /**
+     * Возвращает формы слов с условиями их использования (там смешаны
+     * семантические классы и некоторые синтаксические обстоятельства).
+     *
+     * Экспериментальная возможность.
+     * Заточено под ед. число.
+     */
+    getLocativeForms(lemma: LemmaOptions | Lemma): [LocativeForm];
 }

types/russian-nouns-js/src/Lemma.d.ts

@@ -4,31 +4,61 @@ import { Gender } from "./Gender";
 
 export interface LemmaOptions {
     text: string;
-    gender?: Gender[keyof Gender] | undefined;
-    indeclinable?: boolean | undefined;
+
     pluraleTantum?: boolean | undefined;
+    gender?: Gender | undefined;
+    indeclinable?: boolean | undefined;
     animate?: boolean | undefined;
+
+    surname?: boolean | undefined;
+    name?: boolean | undefined;
+    transport?: boolean | undefined;
 }
 
 export class Lemma {
     constructor(o: LemmaOptions | Lemma);
 
+    /**
+     * @deprecated since version 2.0.0
+     */
     newText(f: (o: string) => string): Lemma;
+
+    /**
+     * @deprecated since version 2.0.0
+     */
     newGender(f: (o: string) => string): Lemma;
+
     equals(o: Lemma): boolean;
-    fuzzyEquals(o: Lemma): boolean;
     text(): string;
     lower(): string;
+
     isPluraleTantum(): boolean;
-    /**
-     * @deprecated Используйте isPluraleTantum(), т.к. речь об одной лемме, а pluralia — во мн.ч. на латыни.
-     * @returns {boolean}
-     */
-    isPluraliaTantum(): boolean;
-    getGender(): string;
+    getGender(): Gender | undefined;
     isIndeclinable(): boolean;
     isAnimate(): boolean;
+
     isASurname(): boolean;
-    isASurname(): boolean;
+    isAName(): boolean;
     isATransport(): boolean;
+
+    /**
+     * Склонение существительного.
+     *
+     * Возможные значения:
+     * -1 (несклоняемые, в основном заимствованные слова);
+     * 0 (разносклоняемые "путь" и "дитя");
+     * 1 (мужской и средний род без окончания);
+     * 2 (слова на "а", "я" — м., ж. и общий род);
+     * 3 (жен. род без окончания; слова, оканчивающиеся на "мя").
+     *
+     * Понятие «склонение» сложно применить к словам plurale tantum,
+     * поэтому этот метод возвращает для них -2 (вместо undefined).
+     */
+    getDeclension(): number;
+
+    /**
+     * Возвращает «школьный» вариант склонения:
+     * «вода» — первое склонение; «стол», «окно» — второе склонение.
+     */
+    getSchoolDeclension(): number;
 }

types/russian-nouns-js/src/LocativeForm.d.ts

@@ -0,0 +1,113 @@
+/* tslint:disable:no-redundant-jsdoc-2 */
+
+/**
+ * Форма слова с условиями её использования.
+ * Ключом является комбинация предлога и атрибутов, т.е. объект должен игнорироваться,
+ * если что-либо из этого набора не соответствует ситуации.
+ *
+ * Результат метода getLocativeForms движка может содержать повторяющиеся формы слова
+ * с разными комбинациями условий в виде отдельных объектов.
+ */
+export class LocativeForm {
+    constructor(preposition: string, word: string, attributes: number);
+
+    /**
+     * Предлог (часть условия применения).
+     * Правило должно быть отброшено, если предлог побуквенно не совпадает
+     * ("в" и "во" — разные предлоги).
+     */
+    preposition: string;
+
+    /**
+     * Атрибуты в виде битовых флагов (часть условия применения).
+     * Все выставленные в единицу флаги должны соответствовать.
+     * Например, если мы используем слово "край" с прилагательным,
+     * правило, где бит атрибута WITHOUT_ADJECTIVE установлен в единицу, должно быть отброшено,
+     * даже если другие атрибуты соответствуют ситуации.
+     */
+    attributes: number;
+
+    /**
+     * Форма слова.
+     */
+    word: string;
+}
+
+export enum LocativeFormAttribute {
+    /**
+     * Вместилище, сосуд.
+     */
+    CONTAINER = 1,
+
+    /**
+     * Пространство.
+     */
+    LOCATION = 2,
+
+    /**
+     * Конфигурация объектов, образующая устойчивую структуру.
+     */
+    STRUCTURE = 4,
+
+    /**
+     * Поверхность.
+     */
+    SURFACE = 8,
+
+    /**
+     * Метафорический путь. Луч времени, на (или в) котором лежат события.
+     */
+    WAY = 16,
+
+    /**
+     * Объект с функциональной (не обязательно плоской) поверхностью.
+     */
+    OBJECT_WITH_FUNCTIONAL_SURFACE = 32,
+
+    /**
+     * Вещество (обволакивающее или покрывающее).
+     */
+    SUBSTANCE = 64,
+
+    /**
+     * Материал, средство изготовления, приготовления (еды), ремонта.
+     */
+    RESOURCE = 128,
+
+    /**
+     * Состояние, свойство, положение дел.
+     */
+    CONDITION = 256,
+
+    /**
+     * Испытываемое воздействие (стихии или внимания/отношения человека).
+     */
+    EXPOSURE = 512,
+
+    /**
+     * Перемещение или кратковременное пространственное положение.
+     */
+    MOTION = 1024,
+
+    /**
+     * Мероприятие.
+     */
+    EVENT = 2048,
+
+    /**
+     * Используется только в присутствии прилагательного.
+     */
+    WITH_ADJECTIVE = 4096,
+
+    /**
+     * Не используется в присутствии прилагательного.
+     */
+    WITHOUT_ADJECTIVE = 8192,
+
+    /**
+     * Я еще не до конца понял этот аспект.
+     * Этот флаг наверняка исчезнет в будущих релизах.
+     * @deprecated
+     */
+    RELIGIOUS = 16384,
+}

types/russian-nouns-js/src/StressDictionary.d.ts

@@ -1,47 +1,27 @@
 /* tslint:disable:no-redundant-jsdoc-2 */
 
+import { Case } from "./Case";
 import { Lemma, LemmaOptions } from "./Lemma";
 
 export default class StressDictionary {
-    data: {};
-
     constructor();
 
     /**
-     * @param {RussianNouns.Lemma|Object} lemma
-     * @param {string} settings Строка настроек в формате 1234567-123456.
+     * Строка задаётся в формате 1234567-123456.
      * До дефиса — единственное число, после дефиса — множественное.
-     * Номер символа — номер падежа в {@link RussianNouns.CASES}.
+     * Номер символа — номер падежа в RussianNouns.CASES.
      * Возможные значения каждого символа:
      * S — ударение только на основу;
      * s — чаще на основу;
      * b — оба варианта употребляются одинаково часто;
      * e — чаще на окончание;
      * E — только на окончание.
-     * @throws {RussianNouns.StressDictionaryException}
+     *
+     * @throws {Error} Если некорректный формат строки.
      */
     put(lemma: LemmaOptions | Lemma, settings: string): void;
 
-    /**
-     * @param {RussianNouns.Lemma|Object} lemma
-     * @param {boolean} fuzzy Если не найдено, игнорировать букву Ё и второстепенные поля у леммы.
-     * @returns {*} Строка настроек или undefined.
-     */
-    get(lemma: LemmaOptions | Lemma, fuzzy: boolean): string | undefined;
-
-    remove(lemma: LemmaOptions | Lemma): void;
+    hasStressedEndingSingular(lemma: Lemma, grCase: Case): boolean[];
 
-    hasStressedEndingSingular(lemma: LemmaOptions | Lemma, grCase: string): boolean[];
-
-    hasStressedEndingPlural(lemma: LemmaOptions | Lemma, grCase: string): boolean[];
-
-    /**
-     * Благодаря этому методу, словарь можно использовать для других целей.
-     * Например, если там есть слово, можно посмотреть его род и признаки.
-     *
-     * @param word Слово, по которому производится поиск.
-     * Буква Ё и регистр игнорируются.
-     * @returns {Array} Список лемм.
-     */
-    find(word: string): string[];
+    hasStressedEndingPlural(lemma: Lemma, grCase: Case): boolean[];
 }