petrovich: A Ruby repository from kadder

Склонение падежей русских имён, фамилий и отчеств. Вы задаёте начальное имя в именительном падеже, а получаете в нужном вам.

Установка

Добавьте в Gemfile:

gem 'petrovich'

Установите гем cредствами Bundler:

$ bundle

Или установите его отдельно:

$ gem install petrovich

Зависимости

Для работы гема требуется Ruby не младше версии 1.9.1. Petrovich не привязан к Ruby on Rails и может свободно использоваться практически в любых приложениях и библиотеках на Ruby.

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

Вы задаёте начальные значения (фамилию, имя и отчество) в именительном падеже.

p = Petrovich.new(:male)
p.lastname('Иванов', :dative)      # => Иванову
p.firstname('Пётр', :dative)       # => Петру
p.middlename('Сергеевич', :dative) # => Сергеевичу

Конструктор класса Petrovich принимает пол в качестве единственного аргумента. Пол может принимать значения :male, :female или :androgynous. Последнее означает, что слово не склоняется по родам. По нормам языка, некоторые фамилии не склоняются. Например, такие украинские фамилии, как Симоненко, а также заимствованные фамилии, такие как Нельсон.

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

Продвинутое использование

Вы можете подмешать модуль Petrovich::Extension в любой класс. Это особенно полезно при использовании ActiveRecord и подобных ORM.

class User < ActiveRecord::Base
  include Petrovich::Extension

  petrovich :firstname  => :my_firstname,
            :middlename => :my_middlename,
            :lastname   => :my_lastname,
            :gender     => :my_gender

  def my_firstname
    'Пётр'
  end

  def my_middlename
    'Петрович'
  end

  def my_lastname
    'Петренко'
  end

  # Если пол не был указан, используется автоматическое определение
  # пола на основе отчества. Если отчество также не было указано,
  # пытаемся определить правильное склонение на основе файла правил.
  def my_gender
    :male # :male, :female или :androgynous
  end
end

Ничего не мешает подмешать модуль Petrovich::Extension в самый обычный класс.

class Person
  include Petrovich::Extension

  # А здесь мы не указали пол - он будет определяться на основе отчества
  petrovich :firstname  => :name,
            :middlename => :patronymic,
            :lastname   => :surname

  def name
    'Иван'
  end

  def patronymic
    'Олегович'
  end

  def surname
    'Сафронов'
  end
end

При помощи метода petrovich указываются методы, представляющие фамилию, имя и отчество. В данном примере указано, что метод name представляет имя, метод lastname представляет фамилию, метод patronymic представляет отчество.

После конфигурации Petrovich можно легко выполнять склонение необходимых строк.

user = User.new
user.my_firstname         # => Пётр

user.my_firstname_dative  # => Петру
user.my_middlename_dative # => Петровичу
user.my_lastname_dative   # => Петренко

person = Person.new
person.name # => Иван

person.my_firstname_dative  # => Ивану
person.my_middlename_dative # => Олеговичу
person.my_lastname_dative   # => Сафронову

Базовое имя должно быть в именительном падеже. Вы просто добавляете _падеж в конец имени оригинального метода и получаете заданное имя в требуемом падеже.

Вот список суффиксов, которые вы можете добавить к имени метода, чтобы получить имя в нужном падеже:

genitive — родительный;
dative — дательный;
accusative — винительный;
instrumental — творительный;
prepositional — предложный.

Оценка точности

Тестирование гема при склонении коллекции фамилий из морфологического словаря АОТ показало точность около 99%. Оригинальный словарь распространяется по лицензии LGPL версии 2.1, однако используется только в задаче оценки точности данного гема.

Для оценки точности достаточно выполнить команду rake evaluate. После выполнения этой команды в поток стандартного вывода будут напечатаны результаты оценки с данными в словаре АОТ.

Pr(nominative|male) = 100.0000%
Pr(genitive|male) = 99.6763%
Pr(dative|male) = 99.7012%
Pr(accusative|male) = 99.7261%
Pr(instrumental|male) = 97.9485%
Pr(prepositional|male) = 99.6888%

Pr(nominative|female) = 100.0000%
Pr(genitive|female) = 99.8652%
Pr(dative|female) = 99.8952%
Pr(accusative|female) = 99.9251%
Pr(instrumental|female) = 99.4189%
Pr(prepositional|female) = 99.8952%

В настоящий момент наблюдается точность в 99.6275% на основе обработки 88314 примеров.

Модульные тесты

Чтобы запустить тесты, тестирующие фамилии, нужно установить переменную окружения TEST_SURNAMES:

TEST_SURNAMES=1 rspec

Разработчики

Андрей Козлов — идея, реализация.
Дмитрий Усталов — неоценимая помощь.

Дальнейшее развитие

Мы планируем и далее улучшать этот проект. Поэтому нам важен отклик от пользователей данного гема. Вот наши планы:

добавить отладочный режим, чтобы видеть, какое именно правило было использовано при словообразовании;
интерфейс командной строки, чтобы работать с гемом из командной строки;
Web-интерфейс для обработки ФИО;
проверка совместимости с различными ORM и сторонними библиотеками.

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

Содействие

Если вы нашли баги, как программной части, так и в базе правил, то вы всегда можете форкнуть репозиторий и внести необходимые изменения. Ваша помощь не останется незамеченной! Если вы заметили ошибки при склонении падежей имён, фамилий или отчеств, можете написать об этом в Issues на GitHub. Проблема будет сразу же исследована и, по возможности, решена.

Не стесняйтесь добавлять улучшения.

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

kadder/petrovich