From 08069d4322f4621505bef2a614d7450f70172bea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim=20D=C3=BCsterhus?= <timwolla@bastelstu.be>
Date: Thu, 27 Feb 2014 15:09:04 +0100
Subject: [PATCH] Improve documentation of the Text provider

---
 readme.md                        |  4 +++
 src/Faker/Generator.php          |  2 ++
 src/Faker/Provider/Text.php      | 58 ++++++++++++++++----------------
 test/Faker/Provider/TextTest.php | 22 ++++++++++--
 4 files changed, 54 insertions(+), 32 deletions(-)

diff --git a/readme.md b/readme.md
index b271c186..497f8e1e 100644
--- a/readme.md
+++ b/readme.md
@@ -117,6 +117,10 @@ Each of the generator properties (like `name`, `address`, and `lorem`) are calle
     paragraphs($nb = 3)     // array('Quidem ut sunt et quidem est accusamus aut. Fuga est placeat rerum ut. Enim ex eveniet facere sunt.', 'Aut nam et eum architecto fugit repellendus illo. Qui ex esse veritatis.', 'Possimus omnis aut incidunt sunt. Asperiores incidunt iure sequi cum culpa rem. Rerum exercitationem est rem.')
     text($maxNbChars = 200) // 'Fuga totam reiciendis qui architecto fugiat nemo. Consequatur recusandae qui cupiditate eos quod.'
 
+### `Faker\Provider\Text`
+
+    realText($maxNbChars = 200, $indexSize = 2) // 'At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur.'
+
 ### `Faker\Provider\Internet`
 
     email                   // 'tkshlerin@collins.com'
diff --git a/src/Faker/Generator.php b/src/Faker/Generator.php
index 9545a317..9ca58a03 100644
--- a/src/Faker/Generator.php
+++ b/src/Faker/Generator.php
@@ -39,6 +39,8 @@ namespace Faker;
  * @method string paragraphs()
  * @method string text()
  *
+ * @method string realText()
+ *
  * @property string email
  * @property string safeEmail
  * @property string freeEmail
diff --git a/src/Faker/Provider/Text.php b/src/Faker/Provider/Text.php
index fb14a0a6..9306ebbe 100644
--- a/src/Faker/Provider/Text.php
+++ b/src/Faker/Provider/Text.php
@@ -4,7 +4,7 @@ namespace Faker\Provider;
 
 class Text extends \Faker\Provider\Base
 {
-    protected static $baseText = <<<EOT
+    protected static $baseText = <<<'EOT'
 Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit
 amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et
@@ -14,39 +14,42 @@ EOT;
     protected static $tables = array();
 
     /**
-     * Generate a text string.
-     * Depending on the $maxNbChars, returns a random valid looking text.
+     * Generate a text string by the Markov chain algorithm.
+     * Depending on the $maxNbChars, returns a random valid looking text. The algorithm
+     * generates a weighted table with the specified number of words as the index and the
+     * possible following words as the value.
      *
      * @example 'Lorem ipsum dolor sit amet'
-     * @param  integer $maxNbChars Maximum number of characters the text should contain
-     * @param  integer $indexSize Determines how many words / chars are considered for the generation of the next token (higher number = correcter, lower number = more random)
-     * @param  string $indexUnit Determines whether 'words' or 'chars' represent the basis of the generator.
+     * @param  integer $maxNbChars Maximum number of characters the text should contain (minimum: 10)
+     * @param  integer $indexSize Determines how many words are considered for the generation of the next word. The minimum is 1, and it produces the higher level of randomness, although the
+     *                            generated text usually doesn't make sense. Higher index size (up to 10) produce more correct text, at the price of less randomness.
      * @return string
      */
-    public static function text($maxNbChars = 200, $indexSize = 2, $indexUnit = 'words')
+    public static function realText($maxNbChars = 200, $indexSize = 2)
     {
-        if (!isset(static::$tables[$indexUnit.'-'.$indexSize])) {
+        if ($maxNbChars < 10) {
+            throw new \InvalidArgumentException('maxNbChars must be at least 10');
+        }
+
+        if ($indexSize < 1) {
+            throw new \InvalidArgumentException('indexSize must be at least 1');
+        }
+
+        if ($indexSize > 10) {
+            throw new \InvalidArgumentException('indexSize must be at most 10');
+        }
+
+        if (!isset(static::$tables[$indexSize])) {
             $text = static::getNormalizedText();
 
-            switch ($indexUnit) {
-                case 'words':
-                    $delimiter = ' ';
-                break;
-                case 'chars':
-                    $delimiter = '';
-                break;
-                default:
-                    throw new \InvalidArgumentException('Unexpected indexUnit');
-            }
-
             // split into look up parts
-            $parts = preg_split('/'.preg_quote($delimiter, '/').'/u', $text, -1, PREG_SPLIT_NO_EMPTY);
+            $parts = preg_split('/ /u', $text, -1, PREG_SPLIT_NO_EMPTY);
 
             // generate look up table
             $table = array();
             for ($i = $indexSize, $max = count($parts) - 1; $i < $max; $i++) {
                 // calculate index
-                $index = implode($delimiter, array_slice($parts, $i - $indexSize, $indexSize));
+                $index = implode(' ', array_slice($parts, $i - $indexSize, $indexSize));
                 if (!isset($table[$index])) $table[$index] = array();
 
                 // value: next part
@@ -54,13 +57,10 @@ EOT;
             }
 
             // cache look up table for performance
-            static::$tables[$indexUnit.'-'.$indexSize] = array(
-                $delimiter,
-                $table
-            );
+            static::$tables[$indexSize] = $table;
         }
 
-        list($delimiter, $table) = static::$tables[$indexUnit.'-'.$indexSize];
+        $table = static::$tables[$indexSize];
         $result = array();
         $resultLength = 0;
 
@@ -71,10 +71,10 @@ EOT;
             $append = static::randomElement($table[$next]);
 
             // calculate next index
-            $next = preg_split('/'.preg_quote($delimiter, '/').'/u', $next, -1, PREG_SPLIT_NO_EMPTY);
+            $next = preg_split('/ /u', $next, -1, PREG_SPLIT_NO_EMPTY);
             $next[] = $append;
             array_shift($next);
-            $next = implode($delimiter, $next);
+            $next = implode(' ', $next);
 
             // ensure text starts with an uppercase letter
             if ($resultLength == 0 && !preg_match('/^\p{Lu}/u', $append)) continue;
@@ -88,7 +88,7 @@ EOT;
         array_pop($result);
 
         // build result
-        $result = implode($delimiter, $result);
+        $result = implode(' ', $result);
 
         return $result.'.';
     }
diff --git a/test/Faker/Provider/TextTest.php b/test/Faker/Provider/TextTest.php
index af4a6efa..70ec4732 100644
--- a/test/Faker/Provider/TextTest.php
+++ b/test/Faker/Provider/TextTest.php
@@ -15,15 +15,31 @@ class TextTest extends \PHPUnit_Framework_TestCase
         $lengths = array(10, 20, 50, 70, 90, 120, 150, 200, 500);
 
         foreach ($lengths as $length) {
-            $this->assertLessThan($length, $generator->text($length));
+            $this->assertLessThan($length, $generator->realText($length));
         }
     }
 
     /**
      * @expectedException \InvalidArgumentException
      */
-    public function testTextInvalidUnit()
+    public function testTextMaxIndex()
     {
-        Text::text(200, 2, 'invalid');
+        Text::realText(200, 11);
+    }
+
+    /**
+     * @expectedException \InvalidArgumentException
+     */
+    public function testTextMinIndex()
+    {
+        Text::realText(200, 0);
+    }
+
+    /**
+     * @expectedException \InvalidArgumentException
+     */
+    public function testTextMinLength()
+    {
+        Text::realText(9);
     }
 }