Documenting the Console Helpers

components/console/helpers/dialoghelper.rst

@@ -0,0 +1,97 @@
+.. index::
+    single: Console Helpers; Dialog Helper
+
+Dialog Helper
+=============
+
+The Dialog Helper provides functions to ask the user for more information. 
+It is included in the default helper set, which you can get
+by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
+
+    $dialog = $this->getHelperSet()->get('dialog');
+
+All the methods inside the Dialog Helper have an 
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first argument,
+the question as second argument and the default value as last argument.
+
+Asking the User for confirmation
+--------------------------------
+
+Suppose you want to confirm an action before actually executing it. Add 
+the following to your command::
+
+    // ...
+    if (!$dialog->askConfirmation(
+            $output,
+            '<question>Continue with this action?</question>',
+            false
+        )) {
+        return;
+    }
+
+In this case, the user will be asked "Continue with this action", and will return
+``true`` if the user answers with ``y`` or false in any other case. The third 
+argument to ``askConfirmation`` is the default value to return if the user doesn't 
+enter any input.
+
+Asking the User for information
+-------------------------------
+
+You can also ask question with more than a simple yes/no answer. For instance,
+if you want to know a bundle name, you can add this to your command::
+
+    // ...
+    $bundle = $dialog->ask(
+        $output,
+        'Please enter the name of the bundle',
+        'AcmeDemoBundle'
+    );
+
+The user will be asked "Please enter the name of the bundle". They can type
+some name which will be returned by the ``ask`` method. If they leave it empty
+the default value (``AcmeDemoBundle`` here) is returned.
+
+Validating the answer
+---------------------
+
+You can even validate the answer. For instance, in our last example we asked
+for the bundle name. Following the Symfony2 naming conventions, it should
+be suffixed with ``Bundle``. We can validate that by using the 
+:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::askAndValidate` 
+method::
+
+    // ...
+    $bundle = $dialog->askAndValidate(
+        $output,
+        'Please enter the name of the bundle',
+        function ($answer) {
+            if ('Bundle' !== substr($answer, -6)) {
+                throw new \RunTimeException(
+                    'The name of the bundle should be suffixed with \'Bundle\''
+                );
+            }
+        },
+        false,
+        'AcmeDemoBundle'
+    );
+
+This methods has 2 new arguments, the full signature is::
+
+    askAndValidate(
+        OutputInterface $output, 
+        string|array $question, 
+        callback $validator, 
+        integer $attempts = false, 
+        string $default = null
+    )
+
+The ``$validator`` is a callback which handles the validation. It should
+throw an exception if there is something wrong. The exception message is displayed
+in the console, so it is a good practice to put some usefull information 
+in it.
+
+You can set the max number of times to ask in the ``$attempts`` argument.
+If we reach this max number it will use the default value, which is given
+in the last argument. Using ``false`` means the amount of attempts is infinite.
+The user will be asked as long as he provides an invalid answer and will only
+be able to proceed if his input is valid.

components/console/helpers/formatterhelper.rst

@@ -0,0 +1,52 @@
+.. index::
+    single: Console Helpers; Formatter Helper
+
+Formatter Helper
+================
+
+The Formatter helpers provides functions to format the output with colors.
+You can do more advanced things with this helper than the things in
+:ref:`components-console-coloring`.
+
+The Formatter Helper is included in the default helper set, which you can
+get by calling
+:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`::
+
+    $formatter = $this->getHelperSet()->get('formatter');
+
+The methods return a string which in most cases you want to write
+that data to the console with
+:method:`Symfony\\Component\\Console\\Output\\Output::writeln`.
+
+Print messages in a section
+---------------------------
+
+Symfony uses a defined style when printing to the command line.
+It prints the section in color and with brackets around and the
+actual message behind this section indication.
+
+To reproduce this style, you can use the 
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatSection`::
+
+    $formattedLine = $formatter->formatSection('SomeCommand', 'Some output from within the SomeCommand');
+    $output->writeln($formattedLine);
+
+Print messages in a block
+-------------------------
+
+Sometimes you want to be able to print a whole block of text with a background
+color. Symfony uses this when printing error messages.
+
+If you print your error message on more than one line manually, you will 
+notice that the background is only as long as each individual line. Use the
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
+togenerate a block output::
+
+    $errorMessages = array('Error!', 'Something went wrong');
+    $formattedBlock = $formatter->formatBlock($errorMessages, 'error');
+
+As you can see, passing an array of messages to the 
+:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::formatBlock`
+method creates the desired output. If you pass ``true`` as third parameter, the 
+block will be  formatted with more padding (one blank line above and below the
+messages and 2 spaces on the left and right).

components/console/helpers/index.rst

@@ -0,0 +1,16 @@
+.. index::
+    single: Console; Console Helpers
+
+The Console Helpers
+===================
+
+.. toctree::
+    :hidden:
+
+    dialoghelper
+    formatterhelper
+
+The Console Components comes with some usefull helpers. These helpers contain
+function to ease some common tasks.
+
+.. include:: map.rst.inc

components/console/helpers/map.rst.inc

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

components/console/index.rst

@@ -7,3 +7,5 @@ Console
     introduction
     usage
     single_command_tool
+
+    helpers/index

components/console/introduction.rst

@@ -108,6 +108,8 @@ This prints::
 
     HELLO FABIEN
 
+.. _components-console-coloring:
+
 Coloring the Output
 ~~~~~~~~~~~~~~~~~~~
 
@@ -255,38 +257,6 @@ You can combine VALUE_IS_ARRAY with VALUE_REQUIRED or VALUE_OPTIONAL like this:
             1
         );
 
-Asking the User for Information
--------------------------------
-
-When creating commands, you have the ability to collect more information
-from the user by asking him/her questions. For example, suppose you want
-to confirm an action before actually executing it. Add the following to your
-command::
-
-    $dialog = $this->getHelperSet()->get('dialog');
-    if (!$dialog->askConfirmation(
-            $output,
-            '<question>Continue with this action?</question>',
-            false
-        )) {
-        return;
-    }
-
-In this case, the user will be asked "Continue with this action", and unless
-they answer with ``y``, the task will stop running. The third argument to
-``askConfirmation`` is the default value to return if the user doesn't enter
-any input.
-
-You can also ask questions with more than a simple yes/no answer. For example,
-if you needed to know the name of something, you might do the following::
-
-    $dialog = $this->getHelperSet()->get('dialog');
-    $name = $dialog->ask(
-        $output,
-        'Please enter the name of the widget',
-        'foo'
-    );
-
 Testing Commands
 ----------------
 
@@ -407,4 +377,4 @@ Learn More!
 * :doc:`/components/console/usage`
 * :doc:`/components/console/single_command_tool`
 
-.. _Packagist: https://packagist.org/packages/symfony/console
+.. _Packagist: https://packagist.org/packages/symfony/console

components/map.rst.inc

@@ -14,6 +14,7 @@
   * :doc:`/components/console/introduction`
   * :doc:`/components/console/usage`
   * :doc:`/components/console/single_command_tool`
+  * :doc:`/components/console/helpers/index`
 
 * **CSS Selector**