morpher-ru

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

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