Библиотека для склонения по падежам слов и словосочетаний на русском языке, использующая веб-сервис "Морфер".
Библиотека позволяет:
- склонять фамилии, имена и отчества; названия должностей, городов, стран и т.д.;
- формировать "сумму прописью" в любом падеже;
- согласовывать единицы измерения с числом;
- определять пол по имени.
Веб-сервис "Морфер" предусматривает бесплатное (с ограничениями) и платное использование. Подробнее смотрите на сайте проекта.
npm install morpher-ru --save
Для подключение библиотеки необходимо создать объект Morpher
.
Конструктор может принимать два аргумента: параметры подключения и объект кеширования.
Можно вызвать конструктор без аргументов, в этом случае будут использоваться параметры по умолчанию.
const Morpher = require('morpher-ru');
let morpher = new Morpher();
В качестве первого аргумента можно передать объект с параметрами подключения к сервису:
let morpher = new Morpher({
hosts: ['api.morpher.ru', 'morpher.ru'],
login: 'USERNAME',
password: 'PASSWORD',
timeout: 10000
});
- hosts (
String
,Array[String]
) — хосты для подключения к сервису (по умолчанию['api.morpher.ru', 'morpher.ru']
). - login, password (
String
) — имя пользователя и пароль для зарегистрированных пользователей. - timeout (
Int
) — таймаут подключения (по умолчанию 10000). Если в качестве хостов определён массив, то при таймауте, будет произведена попытка отправить запрос следующему хосту.
У сервиса "Морфер" реализован лимит на количество одинаковых запросов в сутки, при превышении которого будет возвращаться ошибка "Превышен лимит на количество одинаковых запросов в сутки. Реализуйте кеширование".
По умолчанию библиотека использует встроенный объект кеширования типа in-memory
,
кеширующий запросы в память. Вы можете подключить собственный объект кеширования
(например, использующий базу данных), передав его в качестве аргумента конструктора.
API библиотеки предоставляет три метода для работы с веб-сервисом "Морфер":
declension(text)
— для склонения слов и словосочетаний;declensionName(name)
— для склонения имён;declensionNumber(number, unit)
— для преобразования чисел в прописной вид.
Каждый из этих методов возвращает промис, результатом работы которого
будет соответствующий объект: EntityDeclension
, EntityName
или EntityNumber
.
Для склонения слов и словосочетаний используется метод declension(text)
:
let morpher = new Morpher();
morpher.declension('Программист').then(
result => {
console.log(result['именительный']); // Программист
console.log(result['множественное']['родительный']); // Программистов
},
error => console.error(error)
);
result
— объект EntityDeclension
со следующими свойствами:
именительный
(i
,nominativus
,кто
,что
) — текст в именительном падеже;родительный
(r
,genitivus
,кого
,чего
) — текст в родительном падеже;дательный
(d
,dativus
,кому
,чему
) — текст в дательном падеже;винительный
(v
,accusativus
) — текст в винительном падеже;творительный
(t
,ablativus
,кем
,чем
) — текст в творительном падеже;предложный
(p
,praepositionalis
) — текст в предложном падеже;множественное
(multiple
) — возвращает объект со свойствами-падежами для текста во множественном числе.
При использовании платного аккаунта на сервисе, определяются дополнительные свойства:
po
(о
,о ком
,о чём
) — предложный падёж с предлогом о/об/обо;род
(gender
) — род (masculine, feminine или neuter);где
(gde
) — в местном падеже (локатив) с предлогом;куда
(kuda
) — в направительном падеже (аллатив) с предлогом;откуда
(otkuda
) — в исходном падеже (аблатив) с предлогом.
Для склонения имён и определения пола используется метод declensionName(name)
:
let morpher = new Morpher();
morpher.declensionName('Иван Иванович Петров').then(
result => {
console.log(result['именительный']); // Петров Иван Иванович
console.log(result['имя']['именительный']); // Иван
console.log(result['пол']); // male (только для платных аккаунтов)
},
error => console.error(error)
);
Для корректной работы метода, передаваемое полное имя должно содержать как минимум два из следующих идентификаторов:
- личное имя;
- фамилия;
- отчество.
Например: Иван Васильевич Петров, Владимир Сергеевич, Владимир Петров. В результате, возвращаемом методом, имя будет преведено к виду "Фамилия Имя Отчество" (за исключением пропущенных идентификаторов).
Свойства объекта EntityName
:
именительный
(i
,nominativus
,кто
) — имя в именительном падеже;родительный
(r
,genitivus
,кого
) — имя в родительном падеже;дательный
(d
,dativus
,кому
) — имя в дательном падеже;винительный
(v
,accusativus
) — имя в винительном падеже;творительный
(t
,ablativus
,кем
) — имя в творительном падеже;предложный
(p
,praepositionalis
) — имя в предложном падеже;пол
(sex
) — пол: male|female (только для платных аккаунтов);имя
(firstName
,first
) — личное имя (если определено);фамилия
(lastName
,last
) — фамилия (если определена);отчество
(middleName
,middle
) — отчество (если определено).
Свойства имя
, фамилия
и отчество
возвращают объекты со свойствами-падежами.
Метод declensionNumber(number, unit)
используется для преобразования
числа в прописной вид, а также для согласования единицы измерения с числом:
let morpher = new Morpher();
morpher.declensionNumber(38, 'попугай').then(
result => {
console.log(result['именительный']); // тридцать восемь попугаев
console.log(result['число']['родительный']); // тридцати восьми
console.log(result['единица измерения']['родительный']); // попугаев
},
error => console.error(error)
);
Свойства объекта EntityNumber
:
именительный
(i
,nominativus
,кто
) — число и единица измерения в именительном падеже;родительный
(r
,genitivus
,кого
) — число и единица измерения в родительном падеже;дательный
(d
,dativus
,кому
) — число и единица измерения в дательном падеже;винительный
(v
,accusativus
) — число и единица измерения в винительном падеже;творительный
(t
,ablativus
,кем
) — число и единица измерения в творительном падеже;предложный
(p
,praepositionalis
) — число и единица измерения в предложном падеже;значение
(value
) — числовое значение типаInteger
;число
(number
) — число прописью;единица измерения
(unit
) — единица измерения.
Свойства число
и единица измерения
возвращают объекты со свойствами-падежами.