Components/Console improvements

components/console/helpers/dialoghelper.rst

@@ -148,3 +148,30 @@ You can also ask and validate a hidden response::
 
 If you want to allow the response to be visible if it cannot be hidden for
 some reason, pass true as the fifth argument.
+
+Let the user choose from a list of answers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.2
+    The ``select`` method was added in Symfony 2.2.
+
+If you have a predefined set of answers the user can choose from, you
+could use the ``ask`` method described above or, to make sure the user
+provided a correct answer, the ``askAndValidate`` method. Both have
+the disadvantage that you need to handle incorrect values yourself.
+
+Instead, you can use the ``select`` method, which makes sure that the user
+can only enter a valid string from a predefined list::
+
+    $dialog = $app->getHelperSet()->get('dialog');
+    $colors = array('red', 'blue', 'yellow');
+
+    $color = $dialog->select($output, 'Please select your favorite color (default to red)', $colors, 0);
+
+    // Work with the color
+
+If the user enters an invalid string, an error message is shown and the user
+is asked to provide the answer another time, till he enters a valid string.
+
+The last parameter is the index of the default value in the array or ``null`` if
+no default should be provided.

components/console/helpers/index.rst

@@ -9,6 +9,7 @@ The Console Helpers
 
     dialoghelper
     formatterhelper
+    progresshelper
 
 The Console Components comes with some usefull helpers. These helpers contain
 function to ease some common tasks.

components/console/helpers/map.rst.inc

@@ -1,2 +1,3 @@
 * :doc:`/components/console/helpers/dialoghelper`
 * :doc:`/components/console/helpers/formatterhelper`
+* :doc:`/components/console/helpers/progresshelper`

components/console/helpers/progresshelper.rst

@@ -0,0 +1,73 @@
+.. index::
+    single: Console Helpers; Progress Helper
+
+Progress Helper
+===============
+
+.. versionadded:: 2.2
+    The ``progress`` helper was added in Symfony 2.2.
+
+When executing longer-running commands, it may be helpful to show progress
+information, which updates as your command runs:
+
+.. image:: /images/components/console/progress.png
+
+To display progress details, use the :class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`,
+pass it a total number of units, and advance the progress as your command executes::
+
+    $progress = $this->getHelperSet()->get('progress');
+
+    $progress->start($output, 50);
+    $i = 0;
+    while ($i++ < 50) {
+        // do some work
+
+        // advance the progress bar 1 unit
+        $progress->advance();
+    }
+
+    $progress->finish();
+
+The appearance of the progress output can be customized as well, with a number
+of different levels of verbosity. Each of these displays different possible
+items - like percentage completion, a moving progress bar, or current/total
+information (e.g. 10/50)::
+
+    $progress->setFormat(ProgressHelper::FORMAT_QUIET);
+    $progress->setFormat(ProgressHelper::FORMAT_NORMAL);
+    $progress->setFormat(ProgressHelper::FORMAT_VERBOSE);
+    $progress->setFormat(ProgressHelper::FORMAT_QUIET_NOMAX);
+    // the default value
+    $progress->setFormat(ProgressHelper::FORMAT_NORMAL_NOMAX);
+    $progress->setFormat(ProgressHelper::FORMAT_VERBOSE_NOMAX);
+
+You can also control the different characters and the width used for the
+progress bar::
+
+    // the finished part of the bar
+    $progress->setBarCharacter('<comment>=</comment>');
+    // the unfinished part of the bar
+    $progress->setEmptyBarCharacter(' ');
+    $progress->setProgressCharacter('|');
+    $progress->setBarWidth(50);
+
+To see other available options, check the API documentation for
+:class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`.
+
+.. caution::
+
+    For performance reasons, be careful to not set the total number of steps
+    to a high number. For example, if you're iterating over a large number
+    of items, consider a smaller "step" number that updates on only some
+    iterations::
+
+        $progress->start($output, 500);
+        $i = 0;
+        while ($i++ < 50000) {
+            // ... do some work
+
+            // advance every 100 iterations
+            if ($i % 100 == 0) {
+                $progress->advance();
+            }
+        }

components/console/introduction.rst

@@ -278,77 +278,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
             1
         );
 
-Displaying a Progress Bar
--------------------------
-
-.. versionadded:: 2.2
-    The ``progress`` helper was added in Symfony 2.2.
-
-When executing longer-running commands, it may be helpful to show progress
-information, which updates as your command runs:
-
-.. image:: /images/components/console/progress.png
-
-To display progress details, use the :class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`,
-pass it a total number of units, and advance the progress as your command executes::
-
-    $progress = $this->getHelperSet()->get('progress');
-
-    $progress->start($output, 50);
-    $i = 0;
-    while ($i++ < 50) {
-        // do some work
-
-        // advance the progress bar 1 unit
-        $progress->advance();
-    }
-
-    $progress->finish();
-
-The appearance of the progress output can be customized as well, with a number
-of different levels of verbosity. Each of these displays different possible
-items - like percentage completion, a moving progress bar, or current/total
-information (e.g. 10/50)::
-
-    $progress->setFormat(ProgressHelper::FORMAT_QUIET);
-    $progress->setFormat(ProgressHelper::FORMAT_NORMAL);
-    $progress->setFormat(ProgressHelper::FORMAT_VERBOSE);
-    $progress->setFormat(ProgressHelper::FORMAT_QUIET_NOMAX);
-    // the default value
-    $progress->setFormat(ProgressHelper::FORMAT_NORMAL_NOMAX);
-    $progress->setFormat(ProgressHelper::FORMAT_VERBOSE_NOMAX);
-
-You can also control the different characters and the width used for the
-progress bar::
-
-    // the finished part of the bar
-    $progress->setBarCharacter('<comment>=</comment>');
-    // the unfinished part of the bar
-    $progress->setEmptyBarCharacter(' ');
-    $progress->setProgressCharacter('|');
-    $progress->setBarWidth(50);
-
-To see other available options, check the API documentation for
-:class:`Symfony\\Component\\Console\\Helper\\ProgressHelper`.
-
-.. caution::
-
-    For performance reasons, be careful to not set the total number of steps
-    to a high number. For example, if you're iterating over a large number
-    of items, consider a smaller "step" number that updates on only some
-    iterations::
-
-        $progress->start($output, 500);
-        $i = 0;
-        while ($i++ < 50000) {
-            // ... do some work
-
-            // advance every 100 iterations
-            if ($i % 100 == 0) {
-                $progress->advance();
-            }
-        }
-
 Console Helpers
 ---------------
 
@@ -357,6 +286,7 @@ tools capable of helping you with different tasks:
 
 * :doc:`/components/console/helpers/dialoghelper`: interactively ask the user for information
 * :doc:`/components/console/helpers/formatterhelper`: customize the output colorization
+* :doc:`/components/console/helpers/progresshelper`: shows a progress bar
 
 Testing Commands
 ----------------