From a708da8744c61724b460cfb3d40c0d55012a3df4 Mon Sep 17 00:00:00 2001 From: Sebastian Goettschkes Date: Sun, 30 Dec 2012 20:34:45 +0100 Subject: [PATCH 1/4] Moving the documentation of the ProgressHelper into it's own document --- components/console/helpers/index.rst | 1 + components/console/helpers/map.rst.inc | 1 + components/console/helpers/progresshelper.rst | 73 +++++++++++++++++++ components/console/introduction.rst | 72 +----------------- 4 files changed, 76 insertions(+), 71 deletions(-) create mode 100644 components/console/helpers/progresshelper.rst diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst index c11b6e1a994..83a1e9c53cd 100644 --- a/components/console/helpers/index.rst +++ b/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. diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc index d324d8c2aeb..cbc819ad832 100644 --- a/components/console/helpers/map.rst.inc +++ b/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` diff --git a/components/console/helpers/progresshelper.rst b/components/console/helpers/progresshelper.rst new file mode 100644 index 00000000000..0b3b8b7743e --- /dev/null +++ b/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('='); + // 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(); + } + } \ No newline at end of file diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 5d4af908c42..548a72c05f7 100755 --- a/components/console/introduction.rst +++ b/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('='); - // 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 ---------------- From 66c94e41b518d51329058547f993287270fe25e6 Mon Sep 17 00:00:00 2001 From: Sebastian Goettschkes Date: Sun, 30 Dec 2012 20:49:27 +0100 Subject: [PATCH 2/4] Documenting the DialogHelper select method. --- components/console/helpers/dialoghelper.rst | 27 +++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst index 6528b4154ee..5adc5194a90 100644 --- a/components/console/helpers/dialoghelper.rst +++ b/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. \ No newline at end of file From 61abc9588b8f20c03791e6f2f9efe646239e897d Mon Sep 17 00:00:00 2001 From: Sebastian Goettschkes Date: Mon, 31 Dec 2012 11:41:36 +0100 Subject: [PATCH 3/4] Updating description of the DialogHelper select method --- components/console/helpers/dialoghelper.rst | 24 +++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst index 5adc5194a90..95420fe9f0b 100644 --- a/components/console/helpers/dialoghelper.rst +++ b/components/console/helpers/dialoghelper.rst @@ -160,18 +160,30 @@ 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:: +Instead, you can use the +:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::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); + $colorKey = $dialog->select($output, 'Please select your favorite color (default to red)', $colors, 0); + $output->writeln('You have just selected: ' . $colors[$color]); - // Work with the color + // ... do something 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. \ No newline at end of file +The ``select`` method takes 6 parameters: + +* ``output``: The output instance +* ``question``: The question to ask +* ``choices``: An array of strings with the choices the user can pick +* ``default``: The index of the default value in the array or ``null`` if no + default should be provided (default ``null``) +* ``attempts``: Maximum number of times to ask or ``false`` for infinite times + (default ``false``) +* ``errorMessage``: Error message to display when wrong answer is entered (default + ``Value "%s" is invalid``) \ No newline at end of file From f002cea050ecdd782e1b3d2b0f99084b7ca65be3 Mon Sep 17 00:00:00 2001 From: Sebastian Goettschkes Date: Tue, 1 Jan 2013 22:15:58 +0100 Subject: [PATCH 4/4] Reworking the documentation on the DialogHelper select method Bugfixing a wording in the ProgressHelper --- components/console/helpers/dialoghelper.rst | 27 +++++++++---------- components/console/helpers/progresshelper.rst | 2 +- 2 files changed, 14 insertions(+), 15 deletions(-) diff --git a/components/console/helpers/dialoghelper.rst b/components/console/helpers/dialoghelper.rst index 95420fe9f0b..80354b0897d 100644 --- a/components/console/helpers/dialoghelper.rst +++ b/components/console/helpers/dialoghelper.rst @@ -168,22 +168,21 @@ from a predefined list:: $dialog = $app->getHelperSet()->get('dialog'); $colors = array('red', 'blue', 'yellow'); - $colorKey = $dialog->select($output, 'Please select your favorite color (default to red)', $colors, 0); + $color = $dialog->select( + $output, + 'Please select your favorite color (default to red)', + $colors, + 0 + ); $output->writeln('You have just selected: ' . $colors[$color]); // ... do something with the color +The option which should be selected by default is provided with the fourth +parameter. The default is ``null``, which means that no option is the default one. + 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 ``select`` method takes 6 parameters: - -* ``output``: The output instance -* ``question``: The question to ask -* ``choices``: An array of strings with the choices the user can pick -* ``default``: The index of the default value in the array or ``null`` if no - default should be provided (default ``null``) -* ``attempts``: Maximum number of times to ask or ``false`` for infinite times - (default ``false``) -* ``errorMessage``: Error message to display when wrong answer is entered (default - ``Value "%s" is invalid``) \ No newline at end of file +is asked to provide the answer another time, till he enters a valid string +or the maximum attempts is reached (which you can define in the fifth +parameter). The default value for the attempts is ``false``, which means infinite +attempts. You can define your own error message in the sixth parameter. diff --git a/components/console/helpers/progresshelper.rst b/components/console/helpers/progresshelper.rst index 0b3b8b7743e..757091ba20d 100644 --- a/components/console/helpers/progresshelper.rst +++ b/components/console/helpers/progresshelper.rst @@ -20,7 +20,7 @@ pass it a total number of units, and advance the progress as your command execut $progress->start($output, 50); $i = 0; while ($i++ < 50) { - // do some work + // ... do some work // advance the progress bar 1 unit $progress->advance();