Added exceptions, titles groups, updated docs. Small rewrite.

ecommercebox · Jul 11, 2016 · c23f2e6 · c23f2e6
1 parent 9ea3179
commit c23f2e6
Show file tree

Hide file tree

Showing 5 changed files with 8,656 additions and 8,606 deletions.
diff --git a/README.md b/README.md
@@ -20,17 +20,34 @@ $input = 'MARIUSZ';
 
 //optional
 $encoding = "UTF-8";
-//default ['U' => '', 'M' => 'Panie', 'W' => 'Pani'];
-//define own titles
-$titles = ['U' => '', 'M' => 'Szanowny Panie', 'W' => 'Szanowna Pani'];
+//default group ['U' => 'Panie/Pani', 'M' => 'Panie', 'W' => 'Pani'];
+//override default group titles
+$titles = ['U' => '', 'M' => 'Drogi Panie', 'W' => 'Droga Pani'];
+//override or add new exeptions, where W = Woman, M = Man
+$exeptions = [
+    'Ola' => ['W', 'Oluu'],
+    'Jan' => ['M', 'Janku']
+];
 
 //init object
-$name = new \ecbox\VocativePolishFirstName($input, $encoding, $titles);
+$name = new \ecbox\VocativePolishFirstName($input, $encoding, $titles, $exeptions);
 ```
 
-Get vocative first name with title. Optional argument $delimiter, default is space
+Setup additional titles group
+```php
+$titles = ['U' => 'Szanowna(y) Pani(e)', 'M' => 'Szanowny Panie', 'W' => 'Szanowna Pani'];
+$name->setTitles($titles, 'polite');
+```
+
+Get vocative first name with default title definition. Optional argument $delimiter, default is space and title definition group name
 ```php
 echo $name->getVocativeString();
+// output: Drogi Panie Mariuszu
+```
+
+Get vocative first name with custom title definition. Optional argument $delimiter, default is space and title definition group name
+```php
+echo $name->getVocativeString('polite');
 // output: Szanowny Panie Mariuszu
 ```
 
@@ -40,9 +57,15 @@ echo $name->getVocativeFirstName();
 // output: Mariuszu
 ```
 
-Get title for first name
+Get default title for first name
 ```php
 echo $name->getDetectedTitle();
+// output: Drogi Panie
+```
+
+Get custom group title for first name
+```php
+echo $name->getDetectedTitle('polite');
 // output: Szanowny Panie
 ```
 
@@ -71,17 +94,14 @@ You can check quality using test file: [testVocativePolishFirstName](test/testVo
 
 We are using dictionary test. [See results!](https://htmlpreview.github.io/?https://github.com/ecommercebox/vocative-polish-firstname/blob/master/test/test_results.html)
 
-Test date: 2015-10-28
+Test date: 2016-07-11
 
 Total dictionary names: 1704 
 
-Differences: 18 (Unknowns: 3)
-
-The percentage of errors: 1% 
+Differences: 0
 
-# TODO
+The percentage of errors: 0% 
 
-* add manual exceptions
 
 License
 -------

diff --git a/src/VocativePolishFirstName.php b/src/VocativePolishFirstName.php
@@ -4,7 +4,7 @@
  *
  * Component for remake first name to Polish vocative
  *
- * @author  Mariusz Mielnik <mariusz@ecbox.io>
+ * @author  Mariusz Mielnik <mariusz@ecbox.pl>
  * @license  MIT
  *
  */
@@ -14,14 +14,14 @@
 class VocativePolishFirstName
 {
     /**
-     * Polish title definitions array
+     * Polish definitions array for default group
      *
      * U = Unknown (not detected)
      * M = Male
      * W = Woman
      *
      */
-    private $_titles = ['U' => '', 'M' => 'Panie', 'W' => 'Pani'];
+    private $_titles = ['default' => ['U' => 'Panie/Pani', 'M' => 'Panie', 'W' => 'Pani']];
 
     /**
      * Vocative array
@@ -38,38 +38,71 @@ class VocativePolishFirstName
     private $_encoding;
 
     /**
-     * @var array
+     * List of exceptions
      *
-     * [
-     *  'Ola' => ['W', 'Olu'],
-     *  'Jan' => ['M', 'Janie']
-     * ]
+     * @var array
      */
-    public $_exceptions = [];
+    public $exceptions = [
+        'Ola' => ['W', 'Olu'],
+        'Saba' => ['W', 'Sabo'],
+        'Noemi' => ['W', 'Noemi'],
+        'Sonia' => ['W', 'Soniu'],
+        'Luba' => ['W', 'Lubo'],
+        'Jeremi' => ['M', 'Jeremi'],
+        'Kirył' => ['M', 'Kiryle'],
+        'Miriam' => ['W', 'Miriam'],
+        'Margot' => ['W', 'Margot'],
+        'Ingrid' => ['W', 'Ingrid'],
+        'Lew' => ['M', 'Lwie'],
+        'Narcyz' => ['M', 'Narcyzie'],
+        'Kosma' => ['M', 'Kosmo'],
+        'Bonawentura' => ['M', 'Bonawenturo'],
+        'Carmen' => ['W', 'Carmen'],
+        'Doris' => ['W', 'Doris'],
+        'Dolores' => ['W', 'Dolores'],
+        'Abigail' => ['W', 'Abigail'],
+    ];
 
     /**
      * @param string $first_name
      * @param string $encoding
-     * @param null /array $titles
+     * @param array|null $titles
+     * @param array|null $exceptions
      * @throws \Exception
      */
-    public function __construct($first_name, $encoding = "UTF-8", $titles = null)
+    public function __construct($first_name, $encoding = "UTF-8", $titles = null, $exceptions = null)
     {
         if (!is_null($titles)) {
             $this->setTitles($titles);
         }
+
+        if (!is_null($exceptions)) {
+            $this->exceptions = array_merge($this->exceptions, $exceptions);
+        }
+
         $this->setEncoding($encoding);
         $this->remakeToVocative($first_name);
     }
 
     /**
-     * Returns titles definition
+     * Return default titles definition
      *
      * @return array
      */
     public function getTitles()
     {
-        return $this->_titles;
+        return $this->_titles['default'];
+    }
+
+    /**
+     * Returns titles definition by group name
+     *
+     * @param string $group
+     * @return array
+     */
+    public function getTitlesByGroup($group = 'default')
+    {
+        return $this->_titles[$group];
     }
 
     /**
@@ -78,11 +111,16 @@ public function getTitles()
      * for english ex. ['U' => '', 'M' => 'Mrs.', 'W' => 'Mr.'];
      * for polish ex. ['U' => '', 'M' => 'Szanowny Panie', 'W' => 'Szanowna Pani'];
      *
+     * For multiple titles definitions use group name
+     * for polish ex. group: 'default' => ['U' => 'Panie/Pani', 'M' => 'Panie', 'W' => 'Pani'];
+     * for polish ex. group: 'polite' => ['U' => '', 'M' => 'Szanowny Panie', 'W' => 'Szanowna Pani'];
+     *
      * @param array $titles
+     * @param string $group
      */
-    public function setTitles($titles)
+    public function setTitles($titles, $group = 'default')
     {
-        $this->_titles = $titles;
+        $this->_titles[$group] = $titles;
     }
 
     /**
@@ -118,11 +156,12 @@ public function getVocativeFirstName()
     /**
      * Returns title
      *
+     * @param string $group
      * @return string
      */
-    public function getDetectedTitle()
+    public function getDetectedTitle($group = 'default')
     {
-        return $this->_titles[$this->_vocative[0]];
+        return $this->_titles[$group][$this->_vocative[0]];
     }
 
     /**
@@ -168,11 +207,12 @@ public function isWoman()
      * Return vocative first name with title
      *
      * @param string $delimiter default " " (space)
+     * @param string $group
      * @return string
      */
-    public function getVocativeString($delimiter = ' ')
+    public function getVocativeString($delimiter = ' ', $group = 'default')
     {
-        return $this->getDetectedTitle() . $delimiter . $this->getVocativeFirstName();
+        return $this->getDetectedTitle($group) . $delimiter . $this->getVocativeFirstName();
     }
 
     /**
@@ -186,31 +226,31 @@ public function nameCaseConvert($name)
         return mb_convert_case(mb_strtolower($name), MB_CASE_TITLE, $this->_encoding);
     }
 
+
     /**
      * @param string $first_name
-     *
      * @return array|null
-     * @throws Exception
+     * @throws \Exception
      */
     protected function checkExceptions($first_name)
     {
-        if (!isset($this->_exceptions[$first_name])) {
+        if (!isset($this->exceptions[$first_name])) {
             return null;
         }
 
-        if (count($this->_exceptions[$first_name]) != 2) {
-            throw new Exception('Invalid format');
+        if (count($this->exceptions[$first_name]) != 2) {
+            throw new \Exception('Invalid format');
         }
 
-        switch ($this->_exceptions[$first_name][0]) {
+        switch ($this->exceptions[$first_name][0]) {
             case 'M':
             case 'W':
             case 'U':
-                return $this->_exceptions[$first_name];
+                return $this->exceptions[$first_name];
                 break;
 
             default:
-                throw new Exception('Undefined gender');
+                throw new \Exception('Undefined gender');
         }
     }
 
@@ -347,4 +387,4 @@ protected function remakeToVocative($first_name)
             }
         }
     }
-}
+}
diff --git a/test/imiona.csv b/test/imiona.csv
@@ -1090,7 +1090,7 @@
 "Pelagiusz","Pelagiuszu","M"
 "Perpetua","Perpetuo","W"
 "Petronela","Petronelo","W"
-"Petronia","Petroniu","W"
+"Petronia","Petronio","W"
 "Petroniusz","Petroniuszu","M"
 "Pęcisław","Pęcisławie","M"
 "Pęcisława","Pęcisławo","W"
@@ -1703,4 +1703,5 @@
 "Zygfryda","Zygfrydo","W"
 "Hermenia","Hermenio","W"
 "Hermes","Hermesie","M"
-"Humbert","Humbercie","M"
+"Humbert","Humbercie","M"
+"Ola","Olu","W"
diff --git a/test/testVocativePolishFirstName.php b/test/testVocativePolishFirstName.php
@@ -66,7 +66,7 @@
 
 <h3>Tests from dictionary with first names:</h3>
 
-<a href="<?php echo (isset($_SERVER["DOCUMENT_URI"]) ? $_SERVER["DOCUMENT_URI"] : '');?>">Show all</a>
+<a href="<?php echo(isset($_SERVER["DOCUMENT_URI"]) ? $_SERVER["DOCUMENT_URI"] : ''); ?>">Show all</a>
 <br/>by differences:
 <a href="?diff">all diff</a> |
 <a href="?diff=M">male</a> |
@@ -85,7 +85,7 @@
         <th class="ok">Gender</th>
         <th class="ok">Detected gender</th>
     </tr>
-<?php
+    <?php
     $showDiffOnly = false;
 
     if (isset($_GET['diff'])) {
@@ -111,7 +111,7 @@
             $patternName = $data[1];
             $patternGender = $data[2];
 
-            $v = new \ecbox\VocativePolishFirstName($input);
+            $v = new \ecbox\VocativePolishFirstName($input, 'UTF-8', null);
             $vocativeFirstName = $v->getVocativeFirstName();
             $vocativeArray = $v->getVocativeArray();
             $vocativeGender = $vocativeArray[0];
@@ -131,7 +131,7 @@
             if ($patternGender != $vocativeGender) {
                 $html .= "    <td class='error'>" . $vocativeGender . "</td>\n";
                 $diff = true;
-                if($vocativeGender == 'U') {
+                if ($vocativeGender == 'U') {
                     $unknown = true;
                 }
             } else {
@@ -167,7 +167,7 @@
         # Close the File.
         fclose($handle);
     }
-?>
+    ?>
 </table>
 <br/>