#morpher-ru

Библиотека для склонения по падежам слов и словосочетаний на русском языке, использующая веб-сервис "Морфер".

Библиотека позволяет:

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

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

##Установка

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

API библиотеки предоставляет три метода для работы с веб-сервисом "Морфер":

• declension(text) — для склонения слов и словосочетаний;
• declensionName(name) — для склонения имён;
• declensionNumber(number, unit) — для преобразования чисел в прописной вид.

Каждый из этих методов возвращает промис, результатом работы которого будет соответствующий объект: EntityDeclension, EntityName или EntityNumber.

###declension

Для склонения слов и словосочетаний используется метод 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

Для склонения имён и определения пола используется метод 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

Метод 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) — единица измерения.

Свойства число и единица измерения возвращают объекты со свойствами-падежами.