Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@wapmorgan
wapmorgan committed Apr 8, 2017
1 parent a4ce3ee commit e141e71
Showing 1 changed file with 72 additions and 75 deletions.
147 changes: 72 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,12 @@ Tests & Quality: [![Build Status](https://travis-ci.org/wapmorgan/Morphos.svg)](
2. Quick start
3. Russian
1. Personal names
2. Nouns
3. Numerals
2. Geographical names
3. Nouns
4. Numerals
1. Cardinal
2. Ordinal
4. Cases
5. Cases
4. English
1. Nouns
2. Numerals
Expand All @@ -40,7 +41,7 @@ Adapters:
## Quick Start
- Decline russian names:
```php
var_dump(morphos\Russian\name('Иванов Петр', 'родительный', morphos\NamesDeclension::MAN)); // Иванова Петра
var_dump(morphos\Russian\name('Иванов Петр', 'родительный', morphos\Gender::MALE)); // Иванова Петра
```

- Pluralize russian nouns:
Expand All @@ -50,12 +51,12 @@ Adapters:

- Generate russian cardinal numerals:
```php
var_dump(morphos\Russian\CardinalNumeral::generate(567)); // пятьсот шестьдесят семь
var_dump(morphos\Russian\CardinalNumeral::getCase(567, 'именительный')); // пятьсот шестьдесят семь
```

- Generate russian ordinal numerals:
```php
var_dump(morphos\Russian\OrdinalNumeral::generate(961)); // девятьсот шестьдесят первый
var_dump(morphos\Russian\OrdinalNumeral::getCase(961, 'именительный')); // девятьсот шестьдесят первый
```

- Pluralize english nouns:
Expand All @@ -74,8 +75,6 @@ Russian morphology shortcuts:

* `morphos\Russian\name($fullname, $case, $gender = AUTO)`
* `morphos\Russian\pluralize($noun, $count = 2, $animateness = false)`
* `morphos\Russian\CardinalNumeral::generate($number, $gender = self::MALE)`
* `morphos\Russian\OrdinalNumeral::generate($number, $gender = self::MALE)`

Russian class hierarchy:

Expand Down Expand Up @@ -104,7 +103,7 @@ Arguments:

- `$name` - full name as `Фамилия Имя` or `Фамилия Имя Отчество`.
- `$case` - can be `null`, one of `Cases` constants, a string (described below). If not null, a string will be returned. If null, an array will be returned.
- `$gender` - a string (`NamesDeclension::MAN` or `"m"` for male name, `NamesDeclension::WOMAN` or `"w"` for female name), `null` for autodetection.
- `$gender` - one of `Gender` constants, a string (`"m"` for male name, `"w"` for female name), `null` for autodetection.

There is three declension classes:

Expand All @@ -119,7 +118,7 @@ All declension classes are similar and have four common methods:
- `array getCases($word, $gender = null)` - Declines name to all cases.
- `string detectGender($word)` - Tries to detect gender for given name.

`$gender` is `NamesDeclension::MAN` or `NamesDeclension::WOMAN` or `null` for autodetection. **Note that detection of middle name and last name can make right decision, but first names sometimes can not be used to determine gender of it's owner. Especially if name is not native Russian name.** So just specify gender if you want to declinate first names.
`$gender` is `morphos\Gender::MALE` (or `"m"`) or `morphos\Gender::FEMALE` (or `"f"`) or `null` for autodetection. **Note that detection of middle name and last name can make right decision, but first names sometimes can not be used to determine gender of it's owner. Especially if name is not native Russian name.** So better to specify gender if you want to declinate first names.

Cases in russian language:

Expand All @@ -135,16 +134,15 @@ Examples:
**FirstNamesDeclension**

```php
$dec = new morphos\Russian\FirstNamesDeclension();

use morphos\Russian\FirstNamesDeclension;
// Get any form of a name:
// for example, let it be Иван
$user_name = 'Иван';

$name = $dec->getCase($user_name, 'родительный'); // Ивана
$name = FirstNamesDeclension::getCase($user_name, 'родительный'); // Ивана

// If you need all forms, you can get all forms of a name:
var_dump($dec->getCases($user_name));
var_dump(FirstNamesDeclension::getCases($user_name));
/* Will produce something like
array(6) {
["nominative"]=>
Expand All @@ -166,16 +164,15 @@ var_dump($dec->getCases($user_name));
**MiddleNamesDeclension**

```php
$dec = new morphos\Russian\MiddleNamesDeclension();

use morphos\Russian\MiddleNamesDeclension;
// Get any form of a name:
// for example, let it be Сергеевич
$user_name = 'Сергеевич';

$name = $dec->getCase($user_name, 'родительный'); // Сергеевича
$name = MiddleNamesDeclension::getCase($user_name, 'родительный'); // Сергеевича

// If you need all forms, you can get all forms of a name:
var_dump($dec->getCases($user_name));
var_dump(MiddleNamesDeclension::getCases($user_name));
/* Will produce something like
array(6) {
["nominative"]=>
Expand All @@ -197,17 +194,16 @@ var_dump($dec->getCases($user_name));
**LastNamesDeclension**

```php
$dec = new morphos\Russian\LastNamesDeclension();

use morphos\Russian\LastNamesDeclension;
// Get any case of a last name
$user_last_name = 'Иванов';

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

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

// If you need all forms, you can get all forms of a name:
var_dump($dec->getCases($user_last_name));
var_dump(LastNamesDeclension::getCases($user_last_name));
/* Will produce something like
array(6) {
["nominative"]=>
Expand All @@ -226,6 +222,40 @@ var_dump($dec->getCases($user_last_name));
*/
```

## Geographical names

You can decline geographical names like cities, countries, streets and so on. It has similar methods:

- `boolean isMutable($name)` - Check if name is mutable.
- `string getCase($name, $case)` - Declines name. `$case` is one constant of `morphos\Cases` or `morphos\Russian\Cases` class constants.
- `array getCases($word null)` - Declines name to all cases.

Example:

```php
use morphos\Russian\GeographicalNamesDeclension;

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

## Nouns

### Nouns declension
Expand All @@ -240,14 +270,11 @@ Usage:

```php
use morphos\Russian\GeneralDeclension;

$dec = new GeneralDeclension();

// Following code will return original word if it's immutable:
$form = $dec->getCase('поле', 'родительный'); // поля
$form = GeneralDeclension::getCase('поле', 'родительный'); // поля

// Get all forms of a word at once:
var_dump($dec->getCases('линейка'));
var_dump(GeneralDeclension::getCases('линейка'));
/* Will produce something like
array(6) {
["nominative"]=>
Expand All @@ -272,20 +299,18 @@ var_dump($dec->getCases('линейка'));

- `string getCase($word, $case, $animateness = false)` - Pluralizes noun and declines.
- `array getCases($word, $animateness = false)` - Pluralizes noun and declines to all cases.
- `string @pluralize($word, $count, $animateness = false)` - Pluralizes noun to coincide with numeral.
- `string pluralize($word, $count, $animateness = false)` - Pluralizes noun to coincide with numeral.

Usage:

```php
use morphos\Russian\Plurality;

$plu = new Plurality();

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

// Pluralize word and get all forms:
var_dump($plu->getCases('поле'));
var_dump(Plurality::getCases('поле'));
/* Result will be like
array(6) {
["nominative"]=>
Expand Down Expand Up @@ -315,11 +340,11 @@ echo $count.' '.morphos\Russian\pluralize('дом', $count, false); // result: 1

All number creation classes are similar and have three common methods:

- `string getCase($number, $case, $gender = NumeralCreation::MALE)` - Get one case of a numeral for a number.
- `array getCases($number, $gender = NumeralCreation::MALE)` - Get all case of a numeral for a number.
- `string @generate($number, $gender = NumeralCreation::MALE)` - Generates a cardinal or ordinal numeral for a number.
- `string getCase($number, $case, $gender = Gender::MALE)` - Get one case of a numeral for a number.
- `array getCases($number, $gender = Gender::MALE)` - Get all case of a numeral for a number.
- `string generate($number, $gender = Gender::MALE)` - Generates a cardinal or ordinal numeral for a number.

`$gender` is one of `morphos\NumeralCreation` constants: `MALE` or `FEMALE` or `NEUTER`.
`$gender` is one of `morphos\Gender` constants: `MALE` or `FEMALE` or `NEUTER`.

### Cardinal (`CardinalNumeral`)

Expand All @@ -328,25 +353,20 @@ _Creation of cardinal numerals in russian language._
Create generation class object:

```php
use morphos\NumeralCreation;
use morphos\Gender;
use morphos\Russian\CardinalNumeral;

$cardinal = new CardinalNumeral();
```

Get text representation of a number:

```php
// Get text representation of a number:
$number = 4351;

$numeral = $cardinal->getCase($number, 'именительный'); // четыре тысячи триста пятьдесят один
$numeral = $cardinal->getCase($number, 'именительный', NumeralCreation::FEMALE); // четыре тысячи триста пятьдесят одна
$numeral = CardinalNumeral::getCase($number, 'именительный'); // четыре тысячи триста пятьдесят один
$numeral = CardinalNumeral::getCase($number, 'именительный', Gender::FEMALE); // четыре тысячи триста пятьдесят одна
```

If you need all forms, you can get all cases of a numeral:

```php
var_dump($cardinal->getCases($number));
var_dump(CardinalNumeral::getCases($number));
/* Will produce something like
array(6) {
["nominative"]=>
Expand All @@ -365,41 +385,27 @@ var_dump($cardinal->getCases($number));
*/
```

Generate numeral of a number:

```php
use morphos\Russian\CardinalNumeral;

echo CardinalNumeral::generate(4351);
// result: четыре тысячи триста пятьдесят один
```

### Ordinal (`OrdinalNumeral`)

_Creation of ordinal numerals in russian language._

Create generation class object:

```php
use morphos\NumeralCreation;
use morphos\Gender;
use morphos\Russian\OrdinalNumeral;

$ordinal = new OrdinalNumeral();
```

Get text representation of a number:

```php
// Get text representation of a number:
$number = 67945;

$numeral = $ordinal->getCase($number, 'именительный'); // шестьдесят семь тысяч девятьсот сорок пятый
$numeral = $ordinal->getCase($number, 'именительный', NumeralCreation::FEMALE); // шестьдесят семь тысяч девятьсот сорок пятая
$numeral = OrdinalNumeral::getCase($number, 'именительный'); // шестьдесят семь тысяч девятьсот сорок пятый
$numeral = OrdinalNumeral::getCase($number, 'именительный', Gender::FEMALE); // шестьдесят семь тысяч девятьсот сорок пятая
```

If you need all forms, you can get all cases of a numeral:

```php
var_dump($ordinal->getCases($number));
var_dump(OrdinalNumeral::getCases($number));
/* Will produce something like
array(6) {
["nominative"]=>
Expand All @@ -418,15 +424,6 @@ var_dump($ordinal->getCases($number));
*/
```

Generate numeral of a number:

```php
use morphos\Russian\OrdinalNumeral;

echo CardinalNumeral::generate(67945);
// result: шестьдесят семь тысяч девятьсот сорок пятый
```

# English

English morphology shortcuts:
Expand Down Expand Up @@ -457,7 +454,7 @@ echo '10 '.Plurality::pluralize('foot');

All number creation classes are similar and have one common methods:

- `string @generate($number)` - Generates a cardinal numeral for a number.
- `string generate($number)` - Generates a cardinal numeral for a number.

### Cardinal (`CardinalNumeral`)

Expand Down

0 comments on commit e141e71

Please sign in to comment.