Morpher

JavaScript-клиент веб-сервиса "Морфер 3.0"

Библиотека реализует следующие функции веб-сервиса

На русском языке:

• Склонение по падежам;
• Выделение в строке фамилии, имени и отчества;
• Пропись чисел и склонение единицы измерения (3 новых письма, 10 комментариев);
• Пропись чисел в виде порядковых числительных («сто первый километр»);
• Пропись дат в любом падеже («пятого мая две тысячи первого года»);
• Склонение прилагательных по родам;
• Образование прилагательных от названий городов и стран;
• Расстановка ударений в текстах.

На украинском языке:

• Склонение по падежам;
• Пропись чисел и склонение единицы измерения (3 рублі, 10 листів).

На казахском языке:

• Склонение по падежам, числам и лицам.

Общие:

• Остаток запросов на данный момент.

Пользовательский словарь

Веб-сервис поддерживает исправление склонения по требованию пользователя. Для этого имеются 3 метода:

• Получить список всех добавленных исправлений;
• Добавить или изменить исправление;
• Удалить исправление.

Веб-сервис "Морфер 3.0" предусматривает бесплатное (с ограничениями) и платное использование. Подробнее смотрите на сайте проекта.

Загрузка

• morpher.zip

Установка

Браузер

<script src="morpher.min.js"></script>

Node.js

При использовании npm:

npm i morpher-ws3-client

Примечание: добавьте --save, если вы используете npm < 5.0.0

Использование

const morpher = new Morpher({
  baseUrl: 'https://localhost', // по умолчанию https://ws3.morpher.ru
  token: 'YOUR_TOKEN',          // по умолчанию null
  timeoutMs: 1000,              // по умолчанию 3000
});

Можно вызвать конструктор без аргументов, в этом случае будут использоваться параметры по умолчанию.

const morpher = new Morpher();

Склонение по падежам на русском языке

Для склонения слов и словосочетаний используется метод russian.declension(phrase, flags):

morpher.russian.declension('Программист').then(
    result => {
      console.log(result['родительный']);                  // Программиста
      console.log(result['множественное']['родительный']); // Программистов
      console.log(result.множественное.родительный);       // Программистов
      console.log(result.plural.genitive);                 // Программистов
    },
    error => {
      if (typeof error === 'MorpherError') {
        console.error(error.message + ' Код ошибки: ' + error.code);
      } else {
        console.error(error);
      }
    }
);

result — объект DeclensionResult со следующими свойствами:

• именительный (nominative) — текст в именительном падеже;
• родительный (genitive) — текст в родительном падеже;
• дательный (dative) — текст в дательном падеже;
• винительный (accusative) — текст в винительном падеже;
• творительный (instrumental) — текст в творительном падеже;
• предложный (prepositional) — текст в предложном падеже;
• множественное (plural) — объект со свойствами-падежами для текста во множественном числе.

При использовании платного аккаунта на сервисе, определяются дополнительные свойства:

• предложный_О (prepositional_O) — предложный падеж с предлогом О/ОБ/ОБО, предлог выбирается автоматически;
• род (gender) — род (мужской, женский или средний);
• где (gde, where, locative) — в местном падеже (локатив) с предлогом;
• куда (kuda, where_to) — в направительном падеже (аллатив) с предлогом;
• откуда (otkuda, where_from, whence) — в исходном падеже (аблатив) с предлогом.

Флаги для разрешения неоднозначностей

Есть слова, которые могут склоняться по-разному, например:

• фамилия Резник склоняется у мужчин и не склоняется у женщин;
• Ростов в творительном падеже будет Ростовым, если это фамилия, и Ростовом, если это город;
• тестер в винительном падеже будет тестера, если это человек, и тестер, если имеется в виду прибор.

Для повышения качества склонения вы можете сообщить веб-сервису дополнительную информацию через флаги. Несколько флагов можно передать через запятую:

morpher.russian.declension('Слепов Сергей Николаевич', Morpher.FLAG_NAME, Morpher.FLAG_MASCULINE).then(
    result => {
      console.log(result['родительный']); // Слепова Сергея Николаевича
      console.log(result.fullName.name);  // Сергей
    }
);

Флаги поддерживаемые для russian.declension(phrase, flags):

• Morpher.FLAG_FEMININE — Женский род;
• Morpher.FLAG_MASCULINE — Мужской род;
• Morpher.FLAG_ANIMATE — Одушевлённое;
• Morpher.FLAG_INANIMATE — Неодушевлённое;
• Morpher.FLAG_COMMON — Нарицательное;
• Morpher.FLAG_NAME — ФИО.

Выделение в строке фамилии, имени и отчества

Если входная строка распознана как ФИО, то объект DeclensionResult будет содержать разбивку строки на фамилию, имя и отчество:

• родительный (genitive) — ФИО в родительном падеже;
• дательный (dative) — ФИО в дательном падеже;
• винительный (accusative) — ФИО в винительном падеже;
• творительный (instrumental) — ФИО в творительном падеже;
• предложный (prepositional) — ФИО в предложном падеже;
• имя (name);
• фамилия (surname);
• отчество (patronymic).

Пропись чисел и согласование с числом

Метод russian.spell(number, unit) решает задачу получения прописи числа (тысяча сто двадцать пять) и согласование единицы измерения с предшествующем числом (1 попугай, 2 попугая, 5 попугаев):

morpher.russian.spell(235, 'рубль').then(
    result => {
      console.log(result['n']['родительный']);    // двухсот тридцати пяти
      console.log(result.n.genitive);             // двухсот тридцати пяти

      console.log(result['unit']['родительный']); // рублей
      console.log(result.unit.genitive);          // рублей
    }
);

Комбинируя соответствующие падежные формы n и unit, можно получить вывод «суммы прописью» на любой вкус:

• 235 рублей
• Двести тридцать пять рублей
• 235 (двести тридцать пять) рублей и т.п.

Пропись чисел в виде порядковых числительных

Метод russian.spellOrdinal(number, unit) похож на russian.spell(number, unit), но возвращает пропись числа в форме порядкового числительного:

morpher.russian.spellOrdinal(5, 'колесо').then(
    result => {
      console.log(result['n']['родительный']);    // пятого
      console.log(result['unit']['родительный']); // колеса

      console.log(result.n.genitive);             // пятого
      console.log(result.unit.genitive);          // колеса
    }
);

Пропись дат

Метод russian.spellDate(date) склоняет по падежам дату, заданную в формате ГГГГ-ММ-ДД:

morpher.russian.spellDate('2019-06-29').then(
    result => {
      console.log(result['родительный']);  // двадцать девятого июня две тысячи девятнадцатого года
      console.log(result.genitive);        // двадцать девятого июня две тысячи девятнадцатого года

      console.log(result['творительный']); // двадцать девятому июня две тысячи девятнадцатого года
      console.log(result.instrumental);    // двадцать девятому июня две тысячи девятнадцатого года
    }
);

Склонение прилагательных по родам

Метод russian.adjectiveGenders(adjective) склоняет данное ему прилагательное, преобразуя его из мужского рода в женский, средний и во множественное число:

morpher.russian.adjectiveGenders('уважаемый').then(
    result => {
      console.log(result['женский']);    // уважаемая
      console.log(result.feminine);      // уважаемая

      console.log(result.средний);       // уважаемое
      console.log(result.neuter);        // уважаемое

      console.log(result.множественное); // уважаемые
      console.log(result.plural);        // уважаемые
    }
);

Требования к входному прилагательному:

• Оно должно быть в мужском роде, в единственном числе.
• Оно должно быть полным, т.е. "полный", а не "полон".
• Оно должно быть одним словом. Внутри слова допустимы дефис и апостроф: рабоче-крестьянский, Кот-д'Ивуарский. Вокруг слова допустимы пробелы, кавычки и другие знаки.

Образование прилагательных

Метод russian.adjectivize(lemma) образует прилагательные от названий городов и стран: Москва – московский, Ростов – ростовский, Швеция – шведский, Греция – греческий.

Пример:

morpher.russian.adjectivize('Москва').then(
    result => {
      console.log(result); // ['московский']
    }
);

Метод возвращает массив строк. Что они означают, описано здесь.

Расстановка ударений в текстах

Метод russian.addStressMarks(text) расставляет ударения в текстах на русском языке:

morpher.russian.addStressMarks('Три девицы под окном').then(
    result => {
      console.log(result); // Три деви́цы под окно́м
    }
);

Ударение отмечается символом с кодом U+0301, который вставляется сразу после ударной гласной. Односложные слова не получают знака ударения, за исключением случаев, когда предлог или частица несет на себе ударение: за́ руку, не́ за что. Варианты прочтения разделяются вертикальной чертой, например:

morpher.russian.addStressMarks('Белки питаются белками').then(
    result => {
      console.log(result); // Бе́лки|Белки́ пита́ются бе́лками|белка́ми
    }
);

Склонение по падежам на украинском языке

Украинский вариант склонения — метод ukrainian.declension(phrase, flags):

morpher.ukrainian.declension('Крутько Катерина Володимирiвна').then(
    result => {
      console.log(result['родовий']); // Крутько Катерини Володимирівни
      console.log(result.давальний);  // Крутько Катерині Володимирівні
      console.log(result.vocative);   // Крутько Катерино Володимирівно
    },
);

result — объект DeclensionResult со следующими свойствами:

• називний (nominative) — текст в именительном падеже;
• родовий (genitive) — текст в родительном падеже;
• давальний (dative) — текст в дательном падеже;
• знахідний (accusative) — текст в винительном падеже;
• орудний (instrumental) — текст в творительном падеже;
• місцевий (prepositional) — текст в местном падеже;
• кличний (vocative) — текст в звательном падеже.

При использовании платного аккаунта на сервисе, определяются дополнительные свойства:

• рід (gender) — род (чоловічий, жіночий);

Украинская версия лучше всего справляется с именами, фамилиями и отчествами.

Флаги для разрешения неоднозначностей

morpher.ukrainian.declension('Любовь Соколова', Morpher.FLAG_FEMININE).then(
    result => {
      console.log(result['родовий']); // Любовь Соколової
    }
);

Флаги поддерживаемые для ukrainian.declension(phrase, flags):

• Morpher.FLAG_FEMININE — Женский род;
• Morpher.FLAG_MASCULINE — Мужской род;
• Morpher.FLAG_NEUTER — Средний род;
• Morpher.FLAG_PLURAL — Множественное число.

Пропись чисел и согласование с числом на украинском языке

Метод ukrainian.spell(number, unit) решает задачу получения прописи числа (одна тисяча сто двадцять п'ять) и согласование единицы измерения с предшествующем числом (один попугай, два попугайи, п'ять попугайів):

morpher.ukrainian.spell(235, 'рубль').then(
    result => {
      console.log(result['n']['родовий']);    // двохсот тридцяти п'яти
      console.log(result.n.genitive);         // двохсот тридцяти п'яти

      console.log(result['unit']['родовий']); // рублів
      console.log(result.unit.genitive);      // рублів
    }
);

Склонение по падежам, числам и лицам на казахском языке

Для склонения слов и словосочетаний используется метод qazaq.declension(phrase):

morpher.qazaq.declension('Нұрсултан Әбішұлы Назарбаев').then(
    result => {
      console.log(result['ілік']);          // Нұрсултан Әбішұлы Назарбаевтың
      console.log(result.genitive);         // Нұрсултан Әбішұлы Назарбаевтың

      console.log(result['көпше']['ілік']); // Нұрсултан Әбішұлы Назарбаевтартың
      console.log(result.plural.genitive);  // Нұрсултан Әбішұлы Назарбаевтартың
    }
);

result — объект DeclensionResult со следующими свойствами:

• атау (nominative) — текст в именительном падеже;
• ілік (genitive) — текст в родительном падеже;
• барыс (dative) — текст в дательно-направительном падеже;
• табыс (accusative) — текст в винительном падеже;
• шығыс (ablative) — текст в исходном падеже;
• жатыс (locative) — текст в местном падеже;
• көмектес (instrumental) — текст в творительном падеже;
• көпше (plural) — возвращает объект со свойствами-падежами для текста во множественном числе.

Остаток запросов

Метод getQueriesLeft() возвращает остаток запросов на данный момент. Лимит на запросы восстанавливается в 00:00 UTC.

morpher.getQueriesLeft().then(
    result => {
      console.log(result); // 100
    }
);

Получить список исправлений

Для того чтобы получить список всех исправлений, нужно использовать метод russian.userDict.getAll() или ukrainian.userDict.getAll():

morpher.russian.userDict.getAll().then(
    result => {
      console.log(result); // Массив с объектами СorrectionEntry
    }
);

Объект СorrectionEntry со следующими свойствами:

• singular — объект CorrectionForms с формами в единственном числе;
• plural — объект CorrectionForms с формами во множественном числе;
• gender — род (мужской, женский или средний).

Объект CorrectionForms со следующими свойствами:

• именительный (nominative) — текст в именительном падеже;
• родительный (genitive) — текст в родительном падеже;
• дательный (dative) — текст в дательном падеже;
• винительный (accusative) — текст в винительном падеже;
• творительный (instrumental) — текст в творительном падеже;
• предложный (prepositional) — текст в предложном падеже;
• местный (locative) — текст в местном падеже;

Для украинского языка:

Объект СorrectionEntry со следующими свойствами:

• singular — объект CorrectionForms с формами в единственном числе;
• gender — род (чоловічий, жіночий).

Объект CorrectionForms со следующими свойствами:

• називний (nominative) — текст в именительном падеже;
• родовий (genitive) — текст в родительном падеже;
• давальний (dative) — текст в дательном падеже;
• знахідний (accusative) — текст в винительном падеже;
• орудний (instrumental) — текст в творительном падеже;
• місцевий (prepositional) — текст в местном падеже;
• кличний (vocative) — текст в звательном падеже.

Добавить или изменить исправление

Для добавления или изменения исправления использовать метод russian.userDict.addOrUpdate(entry).

const entry = {
  singular: {
    nominative: 'Кошка',
    dative: 'Пантере',
  },
  plural: {
    dative: 'Пантерам',
  },
};

morpher.russian.userDict.addOrUpdate(entry).then(
    result => {
      console.log(result); // true
    }
);

Для украинского языка:

const entry = {
  singular: {
    nominative: 'Кiшка',
    dative: 'Пантерi',
  },
};

morpher.ukrainian.userDict.addOrUpdate(entry).then(
    result => {
      console.log(result); // true
    }
);

Удаление исправления

Для того чтобы удалить исправление, достаточно передать строку в именительном падеже в метод russian.userDict.remove(nominativeForm):

morpher.russian.userDict.remove('Кошка').then(
    result => {
      console.log(result); // true
    }
);

Для украинского языка:

morpher.ukrainian.userDict.remove('Кiшка').then(
    result => {
      console.log(result); // true
    }
);

Разработка

Node: Убедитесь, что установлена версия Node.js не ниже ^12. Проверить это можно с помощью node -v.

Установка

Сделайте форк репозитория morpher-ws3-js-client.

Затем выполните:

$ git clone https://github.com/<your-github-username>/morpher-ws3-js-client
$ cd morpher-ws3-js-client

Запуск тестов

unit:

$ npm test

e2e:

$ npm test:e2e

Сборка

$ npm build

License

MIT