Skip to content

Latest commit

 

History

History
512 lines (382 loc) · 27.9 KB

README-ru.md

File metadata and controls

512 lines (382 loc) · 27.9 KB
Raw

Русский язык

Склонение частей речи:

Трансформация в текст:

Дополнительно:

Internals:

Краткий обзор

Для русского языка доступны следующие классы и функции из пространства имён morphos\Russian\:

Классы:

  • для склонение личных имён:
    • FirstNamesInflection
    • LastNamesInflection
    • MiddleNamesInflection
  • для склонения географических названий:
    • GeographicalNamesInflection
  • для склонения и плюрализации существительных:
    • NounDeclension
    • NounPluralization
  • для генерации количественных и порядковых числительных:
    • CardinalNumeralGenerator
    • OrdinalNumeralGenerator
  • для генерации текстом различных данных:
    • MoneySpeller
    • TimeSpeller
  • для добавления предлогов и окончаний:
    • RussianLanguage

Функции:

  • inflectName($fullname, $case, $gender = null): string - возвращает имя в определенном падеже.
  • getNameCases($fullname, $gender = null): array - возвращает массив со всеми склонениями имени.
  • detectGender($fullname) - определяет пол владельца имени.
  • pluralize($count, $noun, $animateness = false): string - ставит существительное в форму, согласуемую с количеством предметов, возвращает число предметов и существительное.

Склонение частей речи

Имена собственные

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

  • string inflectName($fullname, $case, $gender = null)
    • API: GET /ru/name?fullname=...&case=...&gender=...

Аргументы:

  • $fullname - имя в формате Имя, Фамилия Имя или Фамилия Имя Отчество.
  • $case - нужный падеж. Одна из констант morphos\Russian\Cases ИЛИ строка (родительный, дательный, винительный, творительный или предложный).
  • $gender - пол владельца имени. одна из констант Gender (morphos\Gender::MALE или morphos\Gender::FEMALE) ИЛИ строка (m для мужского имени, f для женского имени). Если не указывать, будет прозведена попытка автоматического определения.

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

Пример.

use function morphos\Russian\inflectName;

inflectName('Базанов Иосиф Валерьянович', 'родительный') => 'Базанова Иосифа Валерьяновича'
inflectName('Базанов Иосиф', 'дательный') => 'Базанову Иосифу'
inflectName('Иосиф', 'творительный') => 'Иосифом'

Чтобы получить сразу все склонения для имени, используйте другую функцию (либо вызов API без указания case):

array getNameCases($fullname, $gender = null)

Аргументы:

  • $fullname - имя в формате Имя, Фамилия Имя или Фамилия Имя Отчество.
  • $gender - пол владельца. Одна из констант Gender (morphos\Gender::MALE или morphos\Gender::FEMALE) ИЛИ строка (m для мужского имени, "f" для женского имени) ИЛИ null для автоматического определения.

Возвращает массив, где ключи - константы класса Cases, а значения - имя в определенном падеже.

Пример.

use function morphos\Russian\getNameCases;

getNameCases('Базанов Иосиф Валерьянович') => array(6) {
  'nominative' => 'Базанов Иосиф Валерьянович',
  'genitive' => 'Базанова Иосифа Валерьяновича',
  'dative' => 'Базанову Иосифу Валерьяновичу',
  'accusative' => 'Базанова Иосифа Валерьяновича',
  'ablative' => 'Базановым Иосифом Валерьяновичем',
  'prepositional' => 'Базанове Иосифе Валерьяновиче'
}

Если есть необходимость определить пол по имени, воспользуйтесь функцией:

  • string|null detectGender($name)
    • API: GET /ru/detectGender?name=... Если удалось определить пол, будет возвращена одна из констант класса morphos\Gender, null в ином случае.

Географические названия

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

  • boolean isMutable($name) - проверяет, что имя склоняемо.
    • API: GET /ru/geo/isMutable?name=...
  • string getCase($name, $case) - склоняет имя и возвращает результат.$case - это одна из констант morphos\Cases или morphos\Russian\Cases.
  • array getCases($word) - склоняет имя во всех падежах и возвращает результат в виде массива. В отличие от всех других склоняещих компонентов, GeographicalNamesInflection возвращает не 6, а 7 форм слова - с локативным падежом (вторым предложным) - morphos\Russian\Cases::LOCATIVE.
    • API: GET /ru/geo/cases?word=...

Что склоняется:

  • Название населённого пункта, страны без приставки: Москва, Россия, Франция.
  • Названия с приставкой или суффиксом: город N, село N, пгт N, хутор N, N область, N край.

Пример.

use morphos\Russian\GeographicalNamesInflection;

echo 'Пора бы поехать в '.GeographicalNamesInflection::getCase('Москва', 'винительный'); // Москву
// If you need all forms, you can get all forms of a name:
GeographicalNamesInflection::getCases('Саратов') => array(6) {
    "nominative" => "Саратов",
    "genitive" => "Саратова",
    "dative" => "Саратову",
    "accusative" => "Саратов",
    "ablative" => "Саратовом",
    "prepositional" => "Саратове",
    "locative" => "Саратове",
}

Существительные

Для склонения существительных, используемых с количеством предметов/чего-либо предназначена функция pluralize:

  • pluralize($count, $noun, $animateness = false, $case = null)
    • API: GET /ru/pluralize?count=...&noun=...&animateness=...&case=...

Аргументы:

  • $count - количество предметов.
  • $noun - существительное ИЛИ существительное с прилагательными. Примеры: "сообщение", "новое сообщение", "небольшая лампа", "новый и свободный дом".
  • bool $animateness - флаг, указывающий на одушевленность существительного. Если получаемая форма неверная, попробуйте указать true.
  • $case - если необходимо поставить фразу в определенный падеж, передаётся одна из констант morphos\Cases или morphos\Russian\Cases. Если не указано, то падеж выбирается автоматически по правилам русского языка.

Пример.

use function morphos\Russian\pluralize;

echo pluralize(10, 'машина'); // => 10 машин
echo pluralize(10, 'новый и свободный дом', false, morphos\Russian\Cases::TVORIT); // => 10 новыми и свободными домами

Более подробное склонение существительных (по падежам и числам) описано в разделе Internals.

Трансформация в текст

Числа

Оба класса по генерации числительных (количественных и порядковых) из чисел имеют два похожих метода:

  • getCase($number, $case, $gender = Gender::MALE): string - получить одну форму числительного
  • getCases($number, $gender = Gender::MALE): array - получить все формы числительного.
    • API: GET /ru/(cardinal|ordinal)/cases?number=...&gender=...

$gender может быть morphos\Gender::MALE (или просто m) или morphos\Gender::FEMALE (или просто f) or morphos\Gender::NEUTER (средний род; или просто n).

Количественные числительные

Генерация количественных числительных производится с помощью класса CardinalNumeralGenerator:

use morphos\Gender;
use morphos\Russian\CardinalNumeralGenerator;

$number = 4351;

CardinalNumeralGenerator::getCase($number, 'именительный') => 'четыре тысячи триста пятьдесят один'
CardinalNumeralGenerator::getCase($number, 'именительный', Gender::FEMALE) => 'четыре тысячи триста пятьдесят одна'
CardinalNumeralGenerator::getCases($number) => array(6) {
    "nominative" => "четыре тысячи триста пятьдесят один",
    "genitive" => "четырех тысяч трехсот пятидесяти одного",
    "dative" => "четырем тысячам тремстам пятидесяти одному",
    "accusative" => "четыре тысячи триста пятьдесят один",
    "ablative" => "четырьмя тысячами тремястами пятьюдесятью одним",
    "prepositional" => "четырех тысячах трехстах пятидесяти одном"
}

Порядковые числительные

Генерация порядковых числительных производится с помощью класса OrdinalNumeralGenerator:

use morphos\Gender;
use morphos\Russian\OrdinalNumeralGenerator;

$number = 67945;

OrdinalNumeralGenerator::getCase($number, 'именительный') => 'шестьдесят семь тысяч девятьсот сорок пятый'
OrdinalNumeralGenerator::getCase($number, 'именительный', Gender::FEMALE) => 'шестьдесят семь тысяч девятьсот сорок пятая'
OrdinalNumeralGenerator::getCases($number) => array(6) {
    "nominative" => "шестьдесят семь тысяч девятьсот сорок пятый",
    "genitive" => "шестьдесят семь тысяч девятьсот сорок пятого",
    "dative" => "шестьдесят семь тысяч девятьсот сорок пятому",
    "accusative" => "шестьдесят семь тысяч девятьсот сорок пятый",
    "ablative" => "шестьдесят семь тысяч девятьсот сорок пятым",
    "prepositional" => "шестьдесят семь тысяч девятьсот сорок пятом"
}

Валюты

Вы можете генерировать значения денежных сумм, записанных в виде текста с помощью класса MoneySpeller.

  • spell($value, $currency, $format = self::NORMAL_FORMAT, $case = null, $skipFractionalPartIfZero = null)
    • API: GET /ru/money/spell?value=...&currency=...&format=...&case=...&skipFractionalPartIfZero=...

Пример.

use morphos\Russian\MoneySpeller;

MoneySpeller::spell(123.45, MoneySpeller::RUBLE) => 'сто двадцать три рубля сорок пять копеек'
MoneySpeller::spell(123.45, MoneySpeller::RUBLE, MoneySpeller::CLARIFICATION_FORMAT) => '123 (сто двадцать три) рубля 45 (сорок пять) копеек'

Все доступные форматы вывода:

Формат Формат вывода Пример
MoneySpeller::SHORT_FORMAT Сумма записывается цифрами, а валюта словами 1 рубль 50 копеек
MoneySpeller::NORMAL_FORMAT Сумма и валюта записываются словами один рубль пятьдесят копеек
MoneySpeller::DUPLICATION_FORMAT Сумма и валюта записываются словами. Сумма дублируется цифрами в скобках один (1) рубль пятьдесят (50) копеек
MoneySpeller::CLARIFICATION_FORMAT Сумма записывается словами и цифрами (в скобках), валюта - словами. 1 (один) рубль 50 (пятьдесят) копеек

При указании валюты используйте знак валюты (например, ₽) или трехзначный код валюты (\morphos\Currency::RUBLE).

Также можно указать падеж для склонения четвёртым параметром:

use morphos\Russian\MoneySpeller;

MoneySpeller::spell(123.45, MoneySpeller::RUBLE, MoneySpeller::NORMAL_FORMAT, 'родительный') => 'ста двадцати трех рублей сорока пяти копеек'

Доступные валюты:

Знак Идентификатор Валюта
$ \morphos\Currency::DOLLAR доллар
€ \morphos\Currency::EURO евро
¥ \morphos\Currency::YEN иена
£ \morphos\Currency::POUND фунт
Fr \morphos\Currency::FRANC франк
元 \morphos\Currency::YUAN юань
Kr \morphos\Currency::KRONA крона
MXN \morphos\Currency::PESO песо
₩ \morphos\Currency::WON вон
₺ \morphos\Currency::LIRA лира
₽ \morphos\Currency::RUBLE рубль
₹ \morphos\Currency::RUPEE рупия
R$ \morphos\Currency::REAL реал
R \morphos\Currency::RAND рэнд
₴ \morphos\Currency::HRYVNIA гривна

Временные интервалы

Класс TimeSpeller позволяет генерировать временной интервал. В классе есть методы для генерации:

  • TimeSpeller::spellDifference($dateTime, $options = 0, $limit = 0 ) - временной интервал между текущим временем и $dateTime. $dateTime может быть:
    • объектом DateTime
    • числом секунд с эпохи Unix (unix timestamp)
    • строкой с датой & временем (которую может прочитать strtotime())
    • API: GET /ru/time/spellDifference?dateTime=...&options=...&limit=...
  • TimeSpeller::spellInterval(DateInterval $interval, $options = 0, $limit = 0) - $dateTime, задаваемый объектом DateInterval
    • API: GET /ru/time/spellInterval?interval=...&options=...&limit=...

Пример.

use morphos\Russian\TimeSpeller;

TimeSpeller::spellDifference('+4 hours') => '4 часа'
TimeSpeller::spellDifference(time() + 14400) => '4 часа'
TimeSpeller::spellDifference('-2 minutes') => '2 минуты'
TimeSpeller::spellDifference(time() - 120) => '2 минуты'

Пример.

use morphos\Russian\TimeSpeller;

TimeSpeller::spellInterval(new DateInterval('P5YT2M')) => '5 лет 2 часа'

Также можно передать вторым аргументом в оба метода одну из следующих опций или их комбинацию (побитовое или |):

  • TimeSpeller::DIRECTION - добавляет "назад" для положительных интвералов и "через" для отрицательных.
  • TimeSpeller::SEPARATE - добавляет запятые между составными интервала и союз перед последней частью.

Третьим аргументом можно ограничить количество частей, которые будут сгенерированы.

TimeSpeller::spellDifference(time() - 120, TimeSpeller::DIRECTION) => '2 минуты назад'
TimeSpeller::spellInterval(new DateInterval('P5YT2M'), TimeSpeller::DIRECTION) => '5 лет 2 часа назад'
TimeSpeller::spellInterval(new DateInterval('P5YT2M'), TimeSpeller::SEPARATE) => '5 лет и 2 часа'
TimeSpeller::spellInterval(new DateInterval('P5YT2M'), TimeSpeller::DIRECTION | TimeSpeller::SEPARATE) => '5 лет и 2 часа назад'
TimeSpeller::spellInterval(new DateInterval('P5YT2M'), TimeSpeller::DIRECTION) => '5 лет 2 часа назад'
TimeSpeller::spellInterval(new DateInterval('P5Y1DT10H2M'), TimeSpeller::SEPARATE, 2) => '5 лет и 1 день'

Дополнительно

Предлоги и окончания

В классе morphos\Russian\RussianLanguage есть следующие методы для добавления предлогов или изменения окончаний разных слов:

  • in($word) - добавляет предлог в или во в зависимости от того, с каких букв начинается слово.
    • API: GET /ru/prep/in?word=...
  • with($word) - добавляет предлог с или со в зависимости от того, с каких букв начинается слово.
    • API: GET /ru/prep/with?word=...
  • about($word) - добавляет предлог о, об или обо в зависимости от того, с каких букв начинается слово.
    • API: GET /ru/prep/about?word=...
  • verb($verb, $gender) - изменяет окончание глагола в прошедшем времени в зависимости от рода.
    • API: GET /ru/verb/ending?verb=...&gender=...

Предлоги

Чтобы добавить предлог о или об в зависимости от того, с чего начинается следующее слово, используйте метод about():

use morphos\Russian\FirstNamesInflection;
use morphos\Russian\RussianLanguage;

RussianLanguage::about('Иване') => 'об Иване'
// или комбинируйте с другими функциями склонения
$name = 'Андрей';
RussianLanguage::about(FirstNamesInflection::getCase($name, 'п')) => 'об Андрее'

Окончания глаголов

Глаголы в прошедшем времени в русском языке имеют признак рода. Чтобы упростить подбор правильной формы глаголы используйте функцию:

string RussianLanguage::verb($verb, $gender)

Аргументы:

  • $verb - глагол в мужском роде и прошедшем времени.
  • $gender - необходимый род глагола. Если указано не Gender::MALE, то будет произведено преобразование в женский род.

Пример.

use morphos\Russian\RussianLanguage;

$name = 'Анастасия';
$gender = morphos\Gender::FEMALE;

$name.' '.RussianLanguage::verb('добавил', $gender) => 'Анастасия добавила'
$name.' '.RussianLanguage::verb('поделился', $gender).' публикацией' => 'Анастасия поделилась публикацией'

Internals

Данная глава описывает ранее перечисленные функции и/или возможности более подробно.

Склонение отдельных частей имени

Для склонения отдельных частей имени есть три класса:

  • FirstNamesInflection - класс для склонения имён.
  • MiddleNamesInflection - класс для склонения отчеств.
  • LastNamesInflection - класс для склонения фамилий.

Все классы похожи друг на друга и имеют следующие методы:

  • boolean isMutable($word, $gender = null) - проверяет, что часть имени склоняема.
  • string getCase($word, $case, $gender = null) - склоняет часть имени и возвращает результат. $case - это одна из констант morphos\Cases или morphos\Russian\Cases.
  • array getCases($word, $gender = null) - склоняет имя во всех падежах и возвращает результат в виде массива.
  • string detectGender($word) - пытается определить пол по части имени.

Примеры.

FirstNamesInflection

use morphos\Russian\FirstNamesInflection;
// Возьмем имя Иван
$user_name = 'Иван';

FirstNamesInflection::getCase($user_name, 'родительный') => 'Ивана'

// получаем имя во всех падежах
FirstNamesInflection::getCases($user_name) => array(6) {
    "nominative" => "Иван",
    "genitive" => "Ивана",
    "dative" => "Ивану",
    "accusative" => "Ивана",
    "ablative" => "Иваном",
    "prepositional" => "Иване"
}

MiddleNamesInflection

use morphos\Russian\MiddleNamesInflection;
$user_name = 'Сергеевич';

MiddleNamesInflection::getCase($user_name, 'родительный') => 'Сергеевича'

MiddleNamesInflection::getCases($user_name) => array(6) {
    "nominative" => "Сергеевич",
    "genitive" => "Сергеевича",
    "dative" => "Сергеевичу",
    "accusative" => "Сергеевича",
    "ablative" => "Сергеевичем",
    "prepositional" => "Сергеевиче"
}

LastNamesInflection

use morphos\Russian\LastNamesInflection;
$user_last_name = 'Иванов';

$dative_last_name = LastNamesInflection::getCase($user_last_name, 'дательный'); // Иванову

echo 'Мы хотим подарить товарищу '.$dative_last_name.' небольшой презент.';

LastNamesInflection::getCases($user_last_name) => array(6) {
    "nominative" => "Иванов",
    "genitive" => "Иванова",
    "dative" => "Иванову",
    "accusative" => "Иванова",
    "ablative" => "Ивановым",
    "prepositional" => "Иванове"
}

Полное склонение существительных

Склонение в единственном числе

Функциональность по склонению имени существительных (а также существительных, перешедших из прилагательных/причастий) определена в классе NounDeclension:

  • boolean isMutable($word, bool $animateness = false) - проверяет, изменяемо ли слово.
  • string getCase($word, $case, $animateness = false) - склоняет слово в определённый падеж.
  • array getCases($word, $animateness = false) - склоняет слово во всех падежах.
  • string detectGender($word) - пытается определить пол существительного.

Пример.

use morphos\Russian\NounDeclension;
// Following code will return original word if it's immutable:
NounDeclension::getCase('поле', 'родительный') => 'поля'

// Get all forms of a word at once:
NounDeclension::getCases('линейка') => array(6) {
    "nominative" => "линейка",
    "genitive" => "линейки",
    "dative" => "линейке",
    "accusative" => "линейку",
    "ablative" => "линейкой",
    "prepositional" => "линейке"
}

Склонение во множественном числе

Обеспечивается классом NounPluralization, который имеет похожие методы:

  • string getCase($word, $case, $animateness = false) - получает один из падежей слова во множественном числе.
  • array getCases($word, $animateness = false) - склоняет слово во множественном числе.
  • string pluralize($count, $word, $animateness = false) - возвращает правильную форму существительного для сопряжения с числом.

Пример.

use morphos\Russian\NounPluralization;

$word = 'дом';
echo 'Множественное число для '.$word.' - '.NounPluralization::getCase($word, 'именительный'); // дома

// Pluralize word and get all forms:
NounPluralization::getCases('поле') => array(6) {
    "nominative" => "поля",
    "genitive" => "полей",
    "dative" => "полям",
    "accusative" => "поля",
    "ablative" => "полями",
    "prepositional" => "полях"
}