Merge branch 'issue-31' into develop

Author: wandersonwhcr

README.md

@@ -42,8 +42,9 @@ stable version.
 
 ## Advanced Usage
 
-The `Romans` package uses a Lexer-Parser approach to convert Roman number to
-Integer, using a Grammar Token library.
+The `Romans` package uses a Lexer-Parser approach and a Deterministic Finite
+Automaton (DFA) to convert Roman number to Integer, using a Grammar Token
+library.
 
 ```php
 use Romans\Grammar\Grammar;
@@ -58,10 +59,13 @@ $tokens = $lexer->tokenize('MCMXCIX');
 
 /*
 $tokens = [
-    0 => 'M',  // Grammar::T_M
-    1 => 'CM', // Grammar::T_CM
-    2 => 'XC', // Grammar::T_XC
-    3 => 'IX', // Grammar::T_IX
+    0 => 'M'  // Grammar::T_M
+    1 => 'C', // Grammar::T_C
+    2 => 'M', // Grammar::T_M
+    3 => 'X', // Grammar::T_X
+    4 => 'C', // Grammar::T_C
+    5 => 'I', // Grammar::T_I
+    6 => 'X', // Grammar::T_X
 ];
 */
 
@@ -125,10 +129,42 @@ $filter = new IntToRoman();
 $result = $filter->filter(0); // N
 ```
 
+## Techniques
+
+This section describes some techniques this package uses to convert Roman
+numbers into integer and vice-versa.
+
+### Deterministic Finite Automaton (DFA)
+
+A DFA was developed to check if a string with Roman number is valid. This
+technique was choiced because some implementations simply convert the `$input`
+without checking some rules, like four chars sequentially.
+
+The current automaton definition is declared below.
+
+```plain
+M  = (Q, Σ, δ, q0, F)
+Q  = { a, b, c, d, e, f, g, y, z }
+Σ  = { I, V, X, L, C, D, M, N }
+q0 = g
+F  = { z }
+
+z -> ε
+y -> $z
+a -> y | Iy  | IIy | IIIy
+b -> a | IVy | Va  | IXy
+c -> b | Xb  | XXb | XXXb
+d -> c | XLb | Lc  | XCb
+e -> d | Cd  | CCd | CCCd
+f -> e | CDd | De  | CMd
+g -> f | Nz  | Mg
+```
+
 ## References
 
 * Rapid Tables: [How to Convert Roman Numerals to Numbers](http://www.rapidtables.com/convert/number/how-roman-numerals-to-number.htm)
 * Wikipedia: [Zero in Roman Numerals](https://en.wikipedia.org/wiki/Roman_numerals#Zero)
+* Wikipedia: [Deterministic Finite Automaton](https://en.wikipedia.org/wiki/Deterministic_finite_automaton)
 
 ## License
 

src/Filter/IntToRoman.php

@@ -39,20 +39,25 @@ public function filter(int $value) : string
         }
 
         $tokens = $this->getGrammar()->getTokens();
-        $values = array_reverse($this->getGrammar()->getValues());
+        $values = array_reverse($this->getGrammar()->getValuesWithModifiers(), true /* preserve keys */);
+        $result = '';
 
         if ($value === 0) {
-            $token = array_search(0, $values);
+            $dataset = $values[0];
 
-            return $tokens[$token];
-        }
+            foreach ($dataset as $token) {
+                $result = $result . $tokens[$token];
+            }
 
-        $result = '';
+            return $result;
+        }
 
-        foreach ($values as $token => $current) {
+        foreach ($values as $current => $dataset) {
             while ($current > 0 && $value >= $current) {
-                $value  = $value - $current;
-                $result = $result . $tokens[$token];
+                $value = $value - $current;
+                foreach ($dataset as $token) {
+                    $result = $result . $tokens[$token];
+                }
             }
         }
 

src/Grammar/Grammar.php

@@ -7,20 +7,14 @@
  */
 class Grammar
 {
-    const T_N  = 'N';
-    const T_I  = 'I';
-    const T_IV = 'IV';
-    const T_V  = 'V';
-    const T_IX = 'IX';
-    const T_X  = 'X';
-    const T_XL = 'XL';
-    const T_L  = 'L';
-    const T_XC = 'XC';
-    const T_C  = 'C';
-    const T_CD = 'CD';
-    const T_D  = 'D';
-    const T_CM = 'CM';
-    const T_M  = 'M';
+    const T_N = 'N';
+    const T_I = 'I';
+    const T_V = 'V';
+    const T_X = 'X';
+    const T_L = 'L';
+    const T_C = 'C';
+    const T_D = 'D';
+    const T_M = 'M';
 
     /**
      * Get Tokens
@@ -30,20 +24,14 @@ class Grammar
     public function getTokens() : array
     {
         return [
-            'T_N'  => self::T_N,
-            'T_I'  => self::T_I,
-            'T_IV' => self::T_IV,
-            'T_V'  => self::T_V,
-            'T_IX' => self::T_IX,
-            'T_X'  => self::T_X,
-            'T_XL' => self::T_XL,
-            'T_L'  => self::T_L,
-            'T_XC' => self::T_XC,
-            'T_C'  => self::T_C,
-            'T_CD' => self::T_CD,
-            'T_D'  => self::T_D,
-            'T_CM' => self::T_CM,
-            'T_M'  => self::T_M,
+            'T_N' => self::T_N,
+            'T_I' => self::T_I,
+            'T_V' => self::T_V,
+            'T_X' => self::T_X,
+            'T_L' => self::T_L,
+            'T_C' => self::T_C,
+            'T_D' => self::T_D,
+            'T_M' => self::T_M,
         ];
     }
 
@@ -55,20 +43,49 @@ public function getTokens() : array
     public function getValues()
     {
         return [
-            'T_N'  => 0,
-            'T_I'  => 1,
-            'T_IV' => 4,
-            'T_V'  => 5,
-            'T_IX' => 9,
-            'T_X'  => 10,
-            'T_XL' => 40,
-            'T_L'  => 50,
-            'T_XC' => 90,
-            'T_C'  => 100,
-            'T_CD' => 400,
-            'T_D'  => 500,
-            'T_CM' => 900,
-            'T_M'  => 1000,
+            'T_N' => 0,
+            'T_I' => 1,
+            'T_V' => 5,
+            'T_X' => 10,
+            'T_L' => 50,
+            'T_C' => 100,
+            'T_D' => 500,
+            'T_M' => 1000,
         ];
     }
+
+    /**
+     * Get Modifiers
+     *
+     * @return array Modifiers Available
+     */
+    public function getModifiers()
+    {
+        return [
+            4   => ['T_I', 'T_V'],
+            9   => ['T_I', 'T_X'],
+            40  => ['T_X', 'T_L'],
+            90  => ['T_X', 'T_C'],
+            400 => ['T_C', 'T_D'],
+            900 => ['T_C', 'T_M'],
+        ];
+    }
+
+    /**
+     * Get Values with Modifiers
+     *
+     * @return array Values with Modifiers Available
+     */
+    public function getValuesWithModifiers()
+    {
+        $values = array_map(function ($value) {
+            return [$value];
+        }, array_flip($this->getValues()));
+
+        $valuesWithModifiers = $values + $this->getModifiers(); // merge and keep keys (append)
+
+        ksort($valuesWithModifiers);
+
+        return $valuesWithModifiers;
+    }
 }

src/Lexer/Lexer.php

@@ -57,15 +57,6 @@ public function tokenize(string $content) : array
                 throw $exception;
             }
 
-            // Lookahead
-            if ($position + 1 < $length) {
-                $next = $content[$position + 1];
-                if (isset($numerals[$current . $next])) {
-                    $current  = $current . $next;
-                    $position = $position + 1;
-                }
-            }
-
             $result[] = $current;
             $position = $position + 1;
         }