From 771f95275a21272346cb2b352ab7cc0e6a994126 Mon Sep 17 00:00:00 2001 From: Alessandro Lai Date: Tue, 13 Dec 2016 15:22:26 +0100 Subject: [PATCH 1/3] Fix invalid ProgressBar message examples This fixes #6544 --- components/console/helpers/progressbar.rst | 47 +++++++++------------- 1 file changed, 20 insertions(+), 27 deletions(-) diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index 9b77d168955..1210ab0843f 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -175,7 +175,6 @@ current progress of the bar. Here is a list of the built-in placeholders: * ``remaining``: The remaining time to complete the task (not available if no max is defined); * ``estimated``: The estimated time to complete the task (not available if no max is defined); * ``memory``: The current memory usage; -* ``message``: The current message attached to the progress bar. For instance, here is how you could set the format to be the same as the ``debug`` one:: @@ -186,20 +185,6 @@ Notice the ``:6s`` part added to some placeholders? That's how you can tweak the appearance of the bar (formatting and alignment). The part after the colon (``:``) is used to set the ``sprintf`` format of the string. -The ``message`` placeholder is a bit special as you must set the value -yourself:: - - $bar->setMessage('Task starts'); - $bar->start(); - - $bar->setMessage('Task in progress...'); - $bar->advance(); - - // ... - - $bar->setMessage('Task is finished'); - $bar->finish(); - Instead of setting the format for a given instance of a progress bar, you can also define global formats:: @@ -313,25 +298,33 @@ that displays the number of remaining steps:: Custom Messages ~~~~~~~~~~~~~~~ -The ``%message%`` placeholder allows you to specify a custom message to be -displayed with the progress bar. But if you need more than one, just define -your own:: +If you want to show some fixed text or generic message, you can define custom +placeholders to be displayed with the progress bar, after defining them in a +custom format. - $bar->setMessage('Task starts'); - $bar->setMessage('', 'filename'); - $bar->start(); +By default, the ``setMessage()`` method implies ``message`` as the name of the +placeholder, but if you need more than one, you have just to just define your +own:: + + $progressBar = new ProgressBar($output, 100); + $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message% %filename%'); + $progressBar->setFormat('custom'); + $progressBar->setMessage('Start'); + + $progressBar->start(); + // 0/100 -- Start + + $progressBar->advance(); + $progressBar->setMessage('Task is in progress...'); + // 1/100 -- Task is in progress... - $bar->setMessage('Task is in progress...'); while ($file = array_pop($files)) { $bar->setMessage($filename, 'filename'); $bar->advance(); + // 2/100 -- Task is in progress... $filename } $bar->setMessage('Task is finished'); $bar->setMessage('', 'filename'); $bar->finish(); - -For the ``filename`` to be part of the progress bar, just add the -``%filename%`` placeholder in your format:: - - $bar->setFormat(" %message%\n %current%/%max%\n Working on %filename%"); + // 100/100 -- Task is finished From 89a2843e2d96974666a3c4fb4ddca3bc489907e6 Mon Sep 17 00:00:00 2001 From: Alessandro Lai Date: Tue, 13 Dec 2016 15:25:27 +0100 Subject: [PATCH 2/3] Fix explanation of custom placeholder --- components/console/helpers/progressbar.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index 1210ab0843f..b6f8af56984 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -299,12 +299,11 @@ Custom Messages ~~~~~~~~~~~~~~~ If you want to show some fixed text or generic message, you can define custom -placeholders to be displayed with the progress bar, after defining them in a -custom format. +placeholders in a custom format to be displayed with the progress bar, and use +them afterwards. By default, the ``setMessage()`` method implies ``message`` as the name of the -placeholder, but if you need more than one, you have just to just define your -own:: +placeholder, but if you need more than one, you have just to define your own:: $progressBar = new ProgressBar($output, 100); $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message% %filename%'); From da7fd2d4058ecdb40a11a4624e2ce4b7663e480c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 16 Jan 2017 17:49:46 +0100 Subject: [PATCH 3/3] Reworded some explanations and expanded examples --- components/console/helpers/progressbar.rst | 44 +++++++++++++--------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst index b6f8af56984..495b0b26817 100644 --- a/components/console/helpers/progressbar.rst +++ b/components/console/helpers/progressbar.rst @@ -175,6 +175,7 @@ current progress of the bar. Here is a list of the built-in placeholders: * ``remaining``: The remaining time to complete the task (not available if no max is defined); * ``estimated``: The estimated time to complete the task (not available if no max is defined); * ``memory``: The current memory usage; +* ``message``: used to display arbitrary messages in the progress bar (as explained later). For instance, here is how you could set the format to be the same as the ``debug`` one:: @@ -298,18 +299,19 @@ that displays the number of remaining steps:: Custom Messages ~~~~~~~~~~~~~~~ -If you want to show some fixed text or generic message, you can define custom -placeholders in a custom format to be displayed with the progress bar, and use -them afterwards. - -By default, the ``setMessage()`` method implies ``message`` as the name of the -placeholder, but if you need more than one, you have just to define your own:: +Progress bars define a placeholder called ``message`` to display arbitrary +messages. However, none of the built-in formats include that placeholder, so +before displaying these messages, you must define your own custom format:: $progressBar = new ProgressBar($output, 100); - $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message% %filename%'); + $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message%'); $progressBar->setFormat('custom'); - $progressBar->setMessage('Start'); +Now, use the ``setMessage()`` method to set the value of the ``%message%`` +placeholder before displaying the progress bar: + + // ... + $progressBar->setMessage('Start'); $progressBar->start(); // 0/100 -- Start @@ -317,13 +319,21 @@ placeholder, but if you need more than one, you have just to define your own:: $progressBar->setMessage('Task is in progress...'); // 1/100 -- Task is in progress... - while ($file = array_pop($files)) { - $bar->setMessage($filename, 'filename'); - $bar->advance(); - // 2/100 -- Task is in progress... $filename - } +Messages can be combined with custom placeholders too. In this example, the +progress bar uses the ``%message%`` and ``%filename%`` placeholders:: - $bar->setMessage('Task is finished'); - $bar->setMessage('', 'filename'); - $bar->finish(); - // 100/100 -- Task is finished + $progressBar = new ProgressBar($output, 100); + $progressBar->setFormatDefinition('custom', ' %current%/%max% -- %message% (%filename%)'); + $progressBar->setFormat('custom'); + +The ``setMessage()`` method accepts a second optional argument to set the value +of the custom placeholders:: + + // ... + // $files = array('client-001/invoices.xml', '...'); + foreach ($files as $filename) { + $progressBar->setMessage('Importing invoices...'); + $progressBar->setMessage($filename, 'filename'); + $progressBar->advance(); + // 2/100 -- Importing invoices... (client-001/invoices.xml) + }