petrovich 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 291b554af39a55c68a42696020da4267eead218c
-  data.tar.gz: 8b1b99e5cb9e78d82e2ef87604888c917ab155bd
+  metadata.gz: 8e6066940e4b5258379235c3252ff522958d539b
+  data.tar.gz: 5ecd85e3a147030e003819d3866061a927eb1552
 SHA512:
-  metadata.gz: d3ad699a3a7abb3dbccabc0ca5c3c7ede00c128bea6a509bd6a154ec441ed8be6b457a3388dfa725b9f9e2eec912e639ff37ce7c27cc5fc8693daf7633861396
-  data.tar.gz: 84c671a9e76c5cc738f3ea3b62f1092d57353b51efe0f95421540c730c2e19509aa1992ea637808c6735659aac3c9b78746bbb943c676b9cfb204e9ae32611c0
+  metadata.gz: 95f3fd34b305b733f233df19c9bb31a71e712c7a8d298104f0a2764baa2f56deeb07876cd6f2fbb62915c8d64ff060229505cc0d484014044a5140728c55484f
+  data.tar.gz: da1eac52ca78014e3ecf10fcda4ecee604d35a7d05dff8a78d3d24a3ae39c0f4af150ae74b13d23f1951c331ccba9163956dc7ac2b51d4a910126e4b828ea6ec

data/README.md

@@ -3,16 +3,16 @@
 Склонение падежей русских имён, фамилий и отчеств. Вы задаёте начальное имя
 в именительном падеже, а получаете в нужном вам.
 
-[![Build Status](https://secure.travis-ci.org/petrovich/petrovich-ruby.png)](http://travis-ci.org/petrovich/petrovich-ruby)
+Petrovich также позволяет определять пол по имени, фамилии, отчеству.
 
-#### Посмотреть в действии: http://petrovich.rocketscience.it
+[![Build Status](https://travis-ci.org/petrovich/petrovich-ruby.svg?branch=dev-1.0)](https://travis-ci.org/petrovich/petrovich-ruby)
 
 ## Установка
 
 Добавьте в Gemfile:
 
 ```ruby
-gem 'petrovich'
+gem 'petrovich', '~> 1.0'
 ```
 
 Установите гем cредствами Bundler:
@@ -25,199 +25,100 @@ gem 'petrovich'
 
 ## Зависимости
 
-Для работы гема требуется Ruby не младше версии 1.9.1. Petrovich не
+Для работы гема требуется Ruby не младше версии 1.9.3. Petrovich не
 привязан к Ruby on Rails и может свободно использоваться практически
 в любых приложениях и библиотеках на языке Ruby.
 
 ## Использование
 
 Вы задаёте начальные значения (фамилию, имя и отчество) в именительном
-падеже, а библиотека делает всё остальное.
+падеже, а библиотека делает всё остальное. Если вам известен пол - укажите его, это повысит скорость работы и даст более точные результаты. Если пол не указан, то Petrovich попытается определить его автоматически. Примеры:
 
 ```ruby
-p = Petrovich.new(:male)
-p.lastname('Иванов', :dative)      # => Иванову
-p.firstname('Пётр', :dative)       # => Петру
-p.middlename('Сергеевич', :dative) # => Сергеевичу
+# Склонение в дательный падеж при помощи метода `dative`. Существуют методы `genitive`,
+# `dative`, `accusative`, `instrumental`, `prepositional`.
+Petrovich(
+  lastname: 'Салтыков-Щедрин',
+  firstname: 'Михаил',
+  middlename: 'Евграфович',
+).dative.to_s # => Салтыкову-Щедрину Михаилу Евграфовичу
+
+# Склонение в творительный падеж с использованием метода `to` и возвратом отчества.
+# Аналогично можно вызвать метод `firstname`, чтобы получить имя.
+Petrovich(
+  firstname: 'Иван',
+  middlename: 'Петрович',
+).to(:instrumental).middlename # => Петровича Ивана
+
+# Склонение с указанием пола. В данном случае по имени и фамилии не возможно определить пол
+# человека, поэтому, если вам известен пол, всегда передавайте его в аргументах,
+# чтобы склонение было верным.
+# Если пол неизвестен, то гем попытается определить его самостоятельно.
+# Пол должен быть указан в виде строки или символа, возможные значения: male, female.
+Petrovich(
+  lastname: 'Андрейчук',
+  firstname: 'Саша',
+  gender: :male
+).to(:instrumental).to_s # => Андрейчуку Саше
 ```
 
-Конструктор класса `Petrovich` принимает пол в качестве единственного
-аргумента. Пол может принимать значения `:male`, `:female` или
-`:androgynous`. Последнее означает, что слово не склоняется по родам.
-По нормам языка, некоторые фамилии не склоняются. Например, такие
-украинские фамилии, как Симоненко, а также заимствованные фамилии,
-такие как Нельсон.
-
-Важно понимать, что явное указание пола повышает аккуратность обработки слов.
-Если пол неизвестен, однако известно отчество, то гем постарается
-определить пол по отчеству на основе простой эвристики.
-
-### Продвинутое использование
-
-Вы можете подмешать модуль `Petrovich::Extension` в любой класс. Это
-особенно полезно при использовании ActiveRecord и подобных ORM.
-
-```ruby
-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` в самый обычный
-класс.
-
-```ruby
-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 можно легко выполнять склонение необходимых
-строк.
-
-```ruby
-user = User.new
-user.my_firstname         # => Пётр
-
-user.my_firstname_dative  # => Петру
-user.my_middlename_dative # => Петровичу
-user.my_lastname_dative   # => Петренко
-```
-
-```ruby
-person = Person.new
-person.name # => Иван
-
-person.my_firstname_dative  # => Ивану
-person.my_middlename_dative # => Олеговичу
-person.my_lastname_dative   # => Сафронову
-```
-
-Базовое имя должно быть в именительном падеже. Вы просто добавляете
-`_<суффикс>` в конец имени оригинального метода и получаете заданное имя
-в требуемом падеже.
-
-Названия суффиксов для методов образованы от английских названий
-соответствующих падежей. Полный список поддерживаемых падежей приведён
+Полный список поддерживаемых методов склонения приведён
 в таблице ниже.
 
-| Суффикс метода | Падеж        | Характеризующий вопрос |
+| Метод          | Падеж        | Характеризующий вопрос |
 |----------------|--------------|------------------------|
-| genitive       | родительный  | Кого? Чего?            |
-| dative         | дательный    | Кому? Чему?            |
-| accusative     | винительный  | Кого? Что?             |
-| instrumental   | творительный | Кем? Чем?              |
-| prepositional  | предложный   | О ком? О чём?          |
-
-## Лемматизация
-
-Petrovich умеет выполнять преобразовывание фамилии, имени и отчества
-в произвольном падеже к нормальной форме, а именно в именительный падеж.
-Такой процесс называется *лемматизацией*.
-
-Для выполнения лемматизации нужно передать в методы склонения третий
-аргумент, означающий текущий падеж слова, а во втором аргументе указать
-желаемый падеж — именительный.
+| genitive       | родительный  | Кого?                  |
+| dative         | дательный    | Кому?                  |
+| accusative     | винительный  | Кого?                  |
+| instrumental   | творительный | Кем?                   |
+| prepositional  | предложный   | О ком?                 |
 
-```ruby
-p = Petrovich.new(:male )
-p.firstname('Савве', :nominative, :dative)         # => Савва
-p.middlename('Палладиевичу', :nominative, :dative) # => Палладиевич
-p.lastname('Солунскому', :nominative, :dative)     # => Солунский
-```
+### Определение пола
 
-Также Petrovich позволяет преобразовывать слово сразу в любой падеж,
-отличный от именительного:
+Примеры:
 
 ```ruby
-p = Petrovich.new(:female )
-p.firstname('Марфе', :accusative, :dative)     # => Марфу
-p.middlename('Золовне', :accusative, :dative)  # => Золовну
-p.lastname('Соловецкой', :accusative, :dative) # => Соловецкую
+Petrovich(
+  lastname: 'Склифасовский'
+).gender # => :male
+
+Petrovich(
+  firstname: 'Александра',
+  lastname: 'Склифасовская'
+).female? # => true
+
+Petrovich(
+  lastname: 'Склифасовский'
+).male? # => true
+
+Petrovich(
+  firstname: 'Саша',
+  lastname: 'Андрейчук'
+).androgynous? # => true
+
+Petrovich(
+  firstname: 'Саша',
+  lastname: 'Андрейчук'
+  gender: :male,
+).male? # => true
 ```
 
-## Оценка аккуратности
+## CLI
 
-Тестирование гема при склонении коллекции фамилий из морфологического
-словаря [АОТ] показало аккуратность около 99%. Оригинальный словарь
-распространяется по лицензии LGPL версии 2.1, однако используется
-только в задаче оценки аккуратности данного гема.
+Примеры вызовов:
 
-Для оценки аккуратности достаточно выполнить команду `rake evaluate`. После
-выполнения этой команды в поток стандартного вывода будут напечатаны
-результаты оценки с данными в словаре АОТ.
-
-```
-Ac(nominative|male) = 100.0000%
-Ac(genitive|male) = 99.7635%
-Ac(dative|male) = 99.7884%
-Ac(accusative|male) = 99.8008%
-Ac(instrumental|male) = 99.3037%
-Ac(prepositional|male) = 99.7759%
-```
-```
-Ac(nominative|female) = 100.0000%
-Ac(genitive|female) = 99.9102%
-Ac(dative|female) = 99.9401%
-Ac(accusative|female) = 99.9701%
-Ac(instrumental|female) = 99.4636%
-Ac(prepositional|female) = 99.9401%
+```bash
+petrovich -l Иванов -f Иван -m Иванович -g male -t accusative
+petrovich -l Иванов -f Иван -m Иванович -t accusative -d
+petrovich -l Иванов -f Иван -m Иванович -t accusative -o
 ```
 
-В настоящий момент наблюдается аккуратность в 99.7984% на основе обработки
-88314 примеров.
-
-[АОТ]: http://seman.svn.sourceforge.net/viewvc/seman/trunk/Docs/Morph_UNIX.txt?revision=HEAD&view=markup
+Подробное руководство: `petrovich inflect --help`
 
 ## Модульные тесты
 
-Для запуска тестов достаточно выполнить `rake spec` или просто `rake`.
+Для запуска тестов достаточно выполнить команду `rake`.
+Чтобы запустить тесты "аккуратности" по словарю фамилий, выполните команду `rake evaluate`, после выполнения вы увидите подробный отчёт.
 
 ## Разработчики
 
@@ -237,20 +138,21 @@ Ac(prepositional|female) = 99.9401%
 ## Дальнейшее развитие
 
 Мы планируем и далее улучшать этот проект. Поэтому нам важен отклик от
-пользователей данного гема. Вот наши планы:
+пользователей данного гема.
+
+Наши приоритеты следующие:
 
- * добавить отладочный режим, чтобы видеть, какое именно правило было
-использовано при словообразовании;
- * интерфейс командной строки, чтобы работать с гемом из командной строки;
- * проверка совместимости с различными ORM и сторонними библиотеками.
+* Повысить аккуратность склонения женских фамилий до 98%
+* Обрабатывать ФИО в тексте. Например, чтобы выделить ФИО в виде гиперссылки. Не обязательно только ФИО, возможно просто фамилии, имена и так далее.
+* Перевести реализацию на язык Rust. Это даст возможность использовать библиотеку в различных языках, подключая её через FFI и не потребует отдельной реализации в каждом языке. Это также увеличит скорость работы библиотеки.
 
 Если вы хотите помочь этому проекту, вы можете реализовать любую
 вышеперечисленную идею. Перед этим желательно связаться с нами,
-чтобы мы были в курсе.
+чтобы мы были в курсе. Если у вас появилось такое желание, напишите в issues.
 
 ## Содействие
 
-Если вы нашли баги, как программной части, так и в базе правил, то вы всегда
+Если вы нашли баги как программной части, так и в базе правил, то вы всегда
 можете форкнуть репозиторий и внести необходимые изменения. Ваша помощь не
 останется незамеченной! Если вы заметили ошибки при склонении падежей имён,
 фамилий или отчеств, можете написать об этом в Issues на GitHub.

data/Rakefile

@@ -1,20 +1,18 @@
 #!/usr/bin/env rake
 # encoding: utf-8
 
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rake/testtask"
 
-Rake::TestTask.new(:spec) do |test|
-  test.libs << 'spec'
-  test.test_files = Dir['spec/**/*_spec.rb']
-  test.verbose = true
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*_test.rb']
 end
 
+task default: :test
+
+# We need this to avoid loading the library in tasks directly.
 task :petrovich do
   require 'petrovich'
 end
 
-# Run tests and perform evaluation by default
-task :default => [:spec, :evaluate]
-
 Dir.glob('lib/tasks/*.rake').each { |r| import r }

data/lib/petrovich.rb

@@ -1,91 +1,92 @@
 # encoding: utf-8
-require 'yaml'
+require 'forwardable'
+require 'petrovich/value'
+require 'petrovich/inflector'
+require 'petrovich/inflected'
+require 'petrovich/gender'
 require 'petrovich/unicode'
-require 'petrovich/rules'
-require 'petrovich/extension'
+require 'petrovich/rule_set'
+require 'petrovich/case/rule'
+require 'petrovich/case/rule/modifier'
+require 'petrovich/case/rule/test'
+require 'petrovich/gender/rule'
 
-# Склонение падежей русских имён фамилий и отчеств. Вы задаёте начальное имя в именительном падеже,
-# а получаете в нужном вам.
-#
-# Использование
-#
-#   # Склонение в дательном падеже
-#   rn = Petrovich.new
-#   puts rn.firstname('Иван', :dative)       # => Ивану
-#   puts rn.middlename('Сергеевич', :dative) # => Сергеевичу
-#   puts rn.lastname('Воронов', :dative)     # => Воронову
-#
-#
-# Если известен пол, то его можно передать в конструктор. Это повышает точность склонений
-#
-#   rn = Petrovich.new('male')
-#
-# Если пол не известен, его можно определить по отчеству, при помощи метода +detect_gender+
-#
-#   gender = Petrovich.detect_gender('Сергеевич')
-#   rn = Petrovich.new(gender)
-#
-# Возможные падежи
-#
-# * +:nominative+ - именительный
-# * +:genitive+ - родительный
-# * +:dative+ - дательный
-# * +:accusative+ - винительный
-# * +:instrumental+ - творительный
-# * +:prepositional+ - предложный
-#
-class Petrovich
-  CASES = [:nominative, :genitive, :dative, :accusative, :instrumental, :prepositional]
+# A library to inflect Russian anthroponyms such as first names, last names, and middle names.
+module Petrovich
+  # Possible cases
+  CASES = [
+    :nominative,
+    :genitive,
+    :dative,
+    :accusative,
+    :instrumental,
+    :prepositional
+  ]
 
-  NOMINATIVE      = :nominative    # именительный
-  GENITIVE        = :genitive      # родительный
-  DATIVE          = :dative        # дательный
-  ACCUSATIVE      = :accusative    # винительный
-  INSTRUMENTAL    = :instrumental  # творительный
-  PREPOSITIONAL   = :prepositional # предложный
-
-  def initialize(gender = nil)
-    @gender = gender.to_s
-  end
-
-  def lastname(name, gcase, scase = :nominative)
-    Rules.new(@gender).lastname(name, gcase, scase)
-  end
-
-  def firstname(name, gcase, scase = :nominative)
-    Rules.new(@gender).firstname(name, gcase, scase)
-  end
-
-  def middlename(name, gcase, scase = :nominative)
-    Rules.new(@gender).middlename(name, gcase, scase)
-  end
-
-  alias :patronymic :middlename
+  class << self
+    # A place that keeps inflection and gender rules loaded from yaml file.
+    #
+    # @return Petrovich::RuleSet
+    attr_accessor :rule_set
 
-  def gender
-    @gender
-  end
+    # Checks name that should be value object, instance of {Petrovich::Value}
+    #
+    # Raises an ArgumentError if passed argument not of type Petrovich::Value or
+    # all values is empty in this object.
+    #
+    # @example
+    #   Petrovich.assert_name!(name)
+    #
+    # @param [Foo] name Value to check
+    def assert_name!(name)
+      unless name.is_a?(Value)
+        fail ArgumentError, 'Passed argument should be Petrovich::Value instace'.freeze
+      end
 
-  class << self
-    include Petrovich::Unicode
+      if [name.lastname, name.firstname, name.middlename].compact.size == 0
+        fail ArgumentError, 'You should set at least one of :lastname, :firstname or :middlename'.freeze
+      end
+    end
 
-    # Определение пола по отчеству
+    # Checks passed argument that should be member of {CASES}
     #
-    #   detect_gender('Алексеевич') # => male
+    # Raises an ArgumentError if passed argument not in {CASES}
     #
-    # Если пол не был определён, метод возвращает значение +androgynous+
+    # @example
+    #   Petrovich.assert_case!(name_case)
     #
-    #   detect_gender('блаблабла') # => androgynous
+    # @param [Foo] name_case Value to check
+    def assert_case!(name_case)
+      return if CASES.include?(name_case)
+      fail ArgumentError, "Unknown case #{name_case}"
+    end
+
+    # Converts hash to {Petrovich::Value} value object
     #
-    def detect_gender(midname)
-      case downcase(midname[-2, 2])
-        when /ич|ыч/
-          'male'
-        when 'на'
-          'female'
-        else
-          'androgynous'
-      end
+    # @example
+    #   Petrovich.normalize_name(firstname: 'Иван', lastname: 'Иванов')
+    #
+    # @param [Hash] name Value hash with lastname, firstname, middlename
+    # @return [Petrovich::Value] Value object
+    def normalize_name(name)
+      name = Value.new(name) if name.is_a?(Hash)
+      name
+    end
+
+    # Loads YAML rules into {Petrovich::RuleSet} object
+    # @return [void]
+    def load_rules!
+      self.rule_set ||= RuleSet.new
+      self.rule_set.load!
     end
   end
+
+  load_rules!
+
+  require 'petrovich/name'
+end
+
+# Main entry point
+def Petrovich(opts)
+  Petrovich::Name.new(opts)
 end