Библиотека Morpher.jar

Библиотека реализует следующие функции:

склонение по падежам слов и словосочетаний на русском языке;
определение пола человека по имени (грамматического рода слова);
выделение в строке фамилии, имени и отчества;
склонение прилагательных по родам;
пропись чисел.

См. также:

Интерфейс командной строки
Оперативная коррекция склонения при помощи пользовательского словаря
Технические характеристики и комплект поставки
Установка в Maven-проект
История изменений

Склонение по падежам и числам

За склонение в библиотеке отвечает класс Declension. Вот как им пользоваться:

        
            Declension declension = new Declension();
            IParse parse = declension.parse("Соединенные Штаты Америки (США)");
            String form = parse.getForm(Case.Gen, false);
            assertEquals("Соединенных Штатов Америки (США)", form);

Метод getForm возвращает форму заданного падежа.

Case	Описание, примеры
Case.Nom	именительный (кто? что?):
	Иванов	Петрова	Крым	Урал
Case.Gen	родительный (кого? чего?):
	Иванова	Петровой	Крыма	Урала
Case.Dat	дательный (кому? чему?):
	Иванову	Петровой	Крыму	Уралу
Case.Acc	винительный (кого? что?):
	Иванова	Петрову	Крым	Урал
Case.Ins	творительный (кем? чем?):
	Ивановым	Петровой	Крымом	Уралом
Case.Pre	предложный (о ком? о чем?):
	Иванове	Петровой	Крыме	Урале
Case.Loc	местный (где?):
	Иванове	Петровой	Крыму	Урале

Метод parse выбрасывает DeclensionParseExcepion, если входная строка не была распознана как словосочетание на русском языке.

Для получения падежных форм множественного числа нужно передать true в метод getForm:

        
            Declension declension = new Declension();
            IParse parse = declension.parse("воздушный шар");
            assertEquals("воздушные шары", parse.getForm(Case.Nom, true);

Метод getForm со вторым параметром равным true возвращает null для сочетаний фамилии, имени и отчества, а также если исходное словосочетание уже во множественном числе.

Объект Declension потребляет относительно много памяти (десятки мегабайт), а его создание занимает относительно много времени (порядка сотни миллисекунд), поэтому его рекомендуется кэшировать или сохранять в статическом поле и использовать многократно.

Флаги для разрешения неоднозначностей (Hints)

Метод parse имеет перегрузку с параметром hints:

        
            IParse animate =
                declension.parse("коллектор", Arrays.asList(Hint.Animate));
            IParse inanimate =
                declension.parse("коллектор", Arrays.asList(Hint.Inanimate));
            assertEquals("коллектора",  animate.getForm(Case.Acc, false));
            assertEquals("коллектор", inanimate.getForm(Case.Acc, false));

Подробнее см. Снятие неоднозначности дополнительными признаками.

Определение рода и пола

        
            Declension declension = new Declension();
            IParse parse = declension.parse("Уитни");
            assertEquals(Gender.Feminine, parse.getGender());

Метод getGender возвращает автоматически определенный род входного словосочетания:

Gender.Masculine	мужской род или пол
Gender.Feminine	женский род или пол
Gender.Neuter	средний род
Gender.Plural	множественное число

Определение рода может понадобиться, например, чтобы правильно написать уважаемый или уважаемая, действующий на основании или действующая, оставил комментарий или оставила.

Выделение в строке компонентов ФИО

        
            Declension declension = new Declension();
            IParse parse = declension.parse("Александр Сергеевич Пушкин");
            IFIO fio = parse.getFIO();
            if (fio != null) {
                assertEquals("Пушкин",    fio.getLastName());
                assertEquals("Александр", fio.getFirstName());
                assertEquals("Сергеевич", fio.getMiddleName());
            } else {
                // Словосочетание не распознано как ФИО.
            }

Склонение прилагательных по родам

        
            Declension declension = new Declension();
            String dear = declension.changeGender("Уважаемый", Gender.Feminine);
            assertEquals("Уважаемая", dear);

Функция прописи чисел

        
            NumberSpeller speller = new NumberSpeller(new Declension());
            SpellResult r = speller.spell(38, "попугай");
            assertEquals("тридцать восемь попугаев", r.Number + " " + r.Unit);

Функция spell выбрасывает исключение DeclensionParseException, если единица измерения нерусская или не имеет нужной формы.

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

        
            SpellResult r = speller.spell(new BigDecimal("1.2"), "процент годовых");
            assertEquals("одна целая две десятых процента годовых", r.Number + " " + r.Unit);

При этом учитываются замыкающие нули:

        
            SpellResult r = speller.spell(new BigDecimal("1.20"), "процент годовых");
            assertEquals("ноль целых двадцать сотых процента годовых", r.Number + " " + r.Unit);

Оперативная коррекция склонения при помощи пользовательского словаря

В ситуации, когда необходимо оперативно изменить склонение заданного словосочетания, не прибегая к техподдержке, удобен пользовательский словарь. Словарь представлен в библиотеке интерфейсом UserDictionary:

        
            public interface UserDictionary {
                IParse lookup(String nominativeSingular);
            }

Если передать объект UserDictionary в конструктор класса Declension, то он сначала будет искать в пользовательском словаре, а если не найдено или найдены не все грамматические формы, то результат дополняется автоматически построенными формами.

В библиотеке имеется метод XmlUserDictionaryLoader.load, который читает словарь данные из XML-файла (формат файла). Вот так может выглядеть код создания объекта Declension с пользовательским словарем:

        
            InputStream file = new FileInputStream("dict.xml");
            UserDictionary dict = XmlUserDictionaryLoader.load(file);
            Declension declension = new Declension(dict);

Вы можете также самостоятельно реализовать этот интерфейс для любого другого хранилища, например, БД Oracle.

Интерфейс командной строки (CLI)

Если вы программируете на языке, отличном от Java, но имеете на машине среду выполнения Java, то вы можете вызвать morpher.jar через интерфейс командной строки:

C:\Users\Sergey\Documents\morpher>java -jar morpher.jar declension "Джава"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
    <И>Джава</И>
    <Р>Джавы</Р>
    <Д>Джаве</Д>
    <В>Джаву</В>
    <Т>Джавой</Т>
    <П>Джаве</П>
    <П-о>о Джаве</П-о>
    <М>в Джаве</М>
    <множественное>
        <И>Джавы</И>
        <Р>Джав</Р>
        <Д>Джавам</Д>
        <В>Джав</В>
        <Т>Джавами</Т>
        <П>Джавах</П>
        <П-о>о Джавах</П-о>
        <М>в Джавах</М>
    </множественное>
    <род>женский</род>
</xml>

Имена автоматически разбиваются на фамилию, имя и отчество:

C:\Users\Sergey\Documents\morpher>java -jar morpher.jar declension "Билл Гейтс"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml>
    <И>Билл Гейтс</И>
    <Р>Билла Гейтса</Р>
    <Д>Биллу Гейтсу</Д>
    <В>Билла Гейтса</В>
    <Т>Биллом Гейтсом</Т>
    <П>Билле Гейтсе</П>
    <П-о>о Билле Гейтсе</П-о>
    <М>в Билле Гейтсе</М>
    <ФИО>
        <Ф>Гейтс</Ф>
        <И>Билл</И>
        <О></О>
    </ФИО>
    <род>мужской</род>
</xml>

Пример склонения прописи числа и единицы измерения:

C:\Users\Sergey\Documents\morpher>java -jar morpher.jar spell 38 "попугай"
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PropisResult>
    <n>
        <И>тридцать восемь</И>
        <Р>тридцати восьми</Р>
        <Д>тридцати восьми</Д>
        <В>тридцать восемь</В>
        <Т>тридцатью восьмью</Т>
        <П>тридцати восьми</П>
        <М>тридцати восьми</М>
    </n>
    <unit>
        <И>попугаев</И>
        <Р>попугаев</Р>
        <Д>попугаям</Д>
        <В>попугаев</В>
        <Т>попугаями</Т>
        <П>попугаях</П>
        <М>попугаях</М>
    </unit>
</PropisResult>

Если в выдаче программы русские буквы не читаются, введите команду chcp 65001, чтобы изменить кодировку консоли на UTF-8.

XML, выдаваемый утилитой, аналогичен тому, что выдает веб-сервис. Поэтому если вы ранее работали с веб-сервисом, то для перехода на утилиту вам потребуются минимальные изменения в программе.

Технические характеристики и комплект поставки

В дистрибутив входят два файла: Java-библиотека morpher.jar и файл с комментариями morpher-javadoc.jar.

Технические характеристики morpher.jar:

Выполняется на Java версий 6 и выше.
Не имеет зависимостей.
Не требует прав доступа ни к диску, ни к сети.
Все классы неизменяемы (immutable) и, как следствие, потокобезопасны (thread-safe).
Размер ~ 400K.

Установка в Maven-проект

Для установки библиотеки в Maven-проект нужно выполнить следующие шаги:

Установить morpher.jar в локальный Maven-репозиторий. Для этого в папку, где находится файл Maven-проекта pom.xml, нужно поместить файлы morpher.jar и morpher-javadoc.jar и выполнить команду:
mvn org.apache.maven.plugins:maven-install-plugin:2.5:install-file -Dfile="morpher.jar" -Djavadoc="morpher-javadoc.jar"

Добавить зависимость от модуля в pom.xml:

               
                   <dependency>
                       <groupId>ru.morpher</groupId>
                       <artifactId>russian</artifactId>
                       <version>3.0.2</version>
                   </dependency>

Чтобы синхронизировать проект IDEA с проектом Maven, нажмите Ctrl-Shift-A, введите слово "reload", и выберите команду "Reload All Maven Projects":

Библиотека готова к использованию.

Чтобы увидеть документацию (javadoc), наведите курсор на метод и нажмите Ctrl-Q (на Маке Cmd-J):

История изменений

Implementation-Version	Версия	Описание
2024-09-21	3.0.5	Библиотека morpher.jar избавлена от зависимостей. Ранее библиотека зависела от commons-lang.
2024-05-08	3.0.4	Исправлено склонение фраз с несколькими закавыченными словами на примере: Исполнительный Вице-Президент – управляющий по Южному региону – управляющий Филиалом Банка "Южный" – управляющий Филиалом Банка «Северо-Кавказский»
2023-05-20	3.0.3	Исправлено склонение фразы "Пашкевич С." с указанием женского рода (Hints.Feminine).
2022-12-18	3.0.2	Этот релиз сохранил обратную совместимость, поэтому увеличен лишь третий номер версии. На самом деле изменений в нем много: В словарь программы добавлено 818 новых слов из словаря odict.ru, а также новые слова из Викисловаря. Исправлен warning "Provides transitive vulnerable dependency maven:junit:junit:4.12" при включении morpher.jar в Maven-проект. Исключено склонение предлога для (по образцу слова тля) в некоторых редких случаях, например, во фразе документация, необходимая для выполнения работ. Исправлено склонение фамилии Курячий. Исправлено склонение фразы Броненосец «Потемкин». Исправлено склонение примеров, присланных пользователями: Член Правления, директор по операциям главный конструктор турбомашин Несклонение аббревиатуры УФПС ("УФПС города Москвы") В том числе довольно много примеров, записанных большими буквами: ПРЕДСЕДАТЕЛЬ СОВЕТА ДЕПУТАТОВ МИНИСТР ФИНАНСОВ ПЕРМСКОГО КРАЯ ИСПОЛНЯЮЩИЙ ОБЯЗАННОСТИ ДИРЕКТОРА ЛУЧШИЙ ПРОГРАММИСТ ИДУЩИЙ ПРЯМО СПЕЦИАЛИСТ ТЕХНИЧЕСКОЙ ПОДДЕРЖКИ ВРЕМЕННО ВЫПОЛНЯЮЩИЙ ФУНКЦИИ МЕНЕДЖЕРА Правильный выбор предлога в сочетаниях во многом, обо всех. Улучшено склонение названий типа улица Ленина, ул. Таганская. Слова перевал, застава, месторождение и др. теперь получают предлог «на» в местном падеже. Предлог «на» для сокращения «ул.»: на ул. Фрунзе, на Тенистой ул. Исправлено склонение топонима Красный боец. Исправлено склонение имен типа Аслан-бек, Джалил-бек.
2021-04-26	3.0	В этом релизе множество полезных изменений, накопленных за полтора года: Добавлено 25 тысяч слов из русского Викисловаря. Добавлено более 14600 новых слов (новое издание словаря Зализняка + пополнение словаря odict.ru). Добавлены 752 фамилии из Википедии. Функция spell теперь считает единицы измерения нарицательными и учитывает замыкающие нули. Specification-Version повышена до 4.0.0 в связи с нарушением обратной совместимости: метод Declension.parse() теперь выбрасывает DeclensionParseException вместо возврата null. Исправлена ошибка, приводившая к NullPointerException в методе parse, если создавать объект Declension в нескольких потоках одновременно. Исправлено склонение сокращения «Вр.и.о.» Улучшено склонение несловарных ФИО, а также фамилий с дефисом (Тер-Оганесян, Кул-Мухаммед) Функция склонения больше не заменяет латинские буквы на русские. Исправлено склонение ряда женских имен Ближнего Востока: Алмаз, Анушик, Алтнат и др. Исправлено склонение отдельных словосочетаний: Кива Владимир, Кабинет Министров, мешок, Гай. Функция склонения прилагательных теперь учитывает притяжательные прилагательные (лисий, третий). Теперь не склоняются слова в кавычках: Сторожевой корабль «Сметливый». Исправлено склонение Шугыла Нурсабикызы и подобных (где -кызы пишется слитно). Исправлено склонение нестандартной фамилии Василив. Исправлено склонение нестандартного топонима Уторгош, который склоняется и по мужскому, и по женскому типу: Малая Уторгош и Малый Уторгош. Орёл теперь склоняется как неодушевленное (название города). Исправлено склонение Илон Маск, контакт-центр. Исправлено склонение смартфон samsung galaxy j3 sm-j330f ds черный. Исправлено склонение Смартфон Apple iPhone 11 Pro Max 256GB Midnight Green (MWHM2RU/A).
2019-11-11	2.0	В этой версии было сделано много полезных изменений, но при этом пришлось нарушить обратную совместимость: Конструктор класса Declension теперь не выбрасывает проверяемых исключений. Метод parse класса Declension теперь выбрасывает проверяемые исключения. Тип параметра hints метода parse изменен с ArrayList на List. Удалена чуждая Джаве буква I в названии интерфейса UserDictionary. Specification-Version повышена с 2.0.0 до 3.0.0 в связи с нарушением обратной совместимости. Версия morpher.jar впервые увеличена. До этого все релизы были под номером 1.0. Добавлена Javadoc документация.
2019-05-06	1.0	Исправлена ошибка определения пола женских имен.
2019-04-23	1.0	Пополнение словаря. Исправлена ошибка функции прописи чисел при обработке дробных чисел. Например, для числа 22,6 неправильно выдавалось "двадцати трёх целых десятых". Слово Армавир само по себе теперь склоняется как неодушевленное.
2018-04-01	1.0	Исправлено склонение "г. Москва" и других с сокращением "г."
2017-03-05	1.0	Исправлены дефекты, обнаруженные в предыдущей версии. Неправильно склонялись слова с беглыми гласными. В частности, слово "кошка" в родительном множественного программа выдавала как "кошк".
2017-03-01	1.0	Добавлены функции склонения прилагательных по родам и прописи чисел. Методы getGenitive, getDative и т.п. интерфейса IParse заменены на метод getForm. Многие недокументированные public классы "спрятаны" (сделаны package-private). Убрана спецификация throws Exception у метода Declension.parse. Так как API библиотеки изменился, Specification-Version изменена с 1.0.0 на 2.0.0.
2017-02-15	1.0	Обеспечена совместимость с Oracle 11.2.0.4.
2017-02-11	1.0	Библиотека пересобрана под JDK 1.6. Ранняя версия была по ошибке собрана под JDK 1.8.
2017-01-26	1.0	Исправлена ошибка (NullPointerException), возникавшая при создании класса Declension в приложениях на Spring.
2017-01-25	1.0	В morpher.jar добавлен файл MANIFEST.MF с информацией о версии. Налажена работа интерфейса командной строки (CLI), нарушенная в одной из предыдущих версий.

Купить