From e141e715bb42b1ca6db46296b0644023730380e1 Mon Sep 17 00:00:00 2001
From: wapmorgan <wapmorgan@gmail.com>
Date: Sat, 8 Apr 2017 16:13:56 +0300
Subject: [PATCH] Update readme

---
 README.md | 147 ++++++++++++++++++++++++++----------------------------
 1 file changed, 72 insertions(+), 75 deletions(-)

diff --git a/README.md b/README.md
index b0755cc..b08920e 100644
--- a/README.md
+++ b/README.md
@@ -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
@@ -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:
@@ -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:
@@ -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:
 
@@ -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:
 
@@ -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:
 
@@ -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"]=>
@@ -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"]=>
@@ -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"]=>
@@ -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
@@ -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"]=>
@@ -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"]=>
@@ -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`)
 
@@ -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"]=>
@@ -365,15 +385,6 @@ 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._
@@ -381,25 +392,20 @@ _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"]=>
@@ -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:
@@ -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`)