#morpher-ru

[![Build Status](https://travis-ci.org/atreslesne/lib-node-morpher-ru.svg?branch=master)](https://travis-ci.org/atreslesne/lib-node-morpher-ru)
[![Coverage Status](https://coveralls.io/repos/github/atreslesne/lib-node-morpher-ru/badge.svg?branch=master)](https://coveralls.io/github/atreslesne/lib-node-morpher-ru?branch=master)
[![npm version](https://badge.fury.io/js/morpher-ru.svg)](https://badge.fury.io/js/morpher-ru)
[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/atreslesne/lib-node-morpher-ru/master/LICENSE)

Библиотека для склонения по падежам слов и словосочетаний на русском языке,
использующая веб-сервис ["Морфер"](http://morpher.ru/).

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

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

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

##Установка

```
npm install morpher-ru --save
```

##Инициализация библиотеки

Для подключение библиотеки необходимо создать объект `Morpher`.
Конструктор может принимать два аргумента: параметры подключения и объект кеширования.

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

```javascript
const Morpher = require('morpher-ru');
let morpher = new Morpher();
```

###Параметры подключения

В качестве первого аргумента можно передать объект с параметрами подключения к сервису:

```javascript
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)`:

```javascript
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)`:

```javascript
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)` используется для преобразования
числа в прописной вид, а также для согласования единицы измерения с числом:

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

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