feature #11852 [Console] add overwrite flag to ProgressBar helper to allow non-decorated output (kbond)

This PR was merged into the 2.6-dev branch.

Discussion
----------

[Console] add overwrite flag to ProgressBar helper to allow non-decorated output

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | yes, but not critical
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #11542, #10011
| License       | MIT
| Doc PR        | symfony/symfony-docs#4206

By default, the `ProgressBar` helper overwrites the output to give the nice progress bar look.  To prevent the output from blowing up in non-decorated environments, the output was hidden in these environments (see #9846).

This PR enables using the `ProgressBar` in non-decorated environments by adding an `overwrite` flag.  When `false`, instead of overwriting the bar, it is rendered on a new line.  To prevent flooding the output, you can adjust the `redrawFrequency`.

By default, when using the `ProgressBar` in a non-decorated environment, the `overwrite` flag is set to false.  If a `max` is set, the `redrawFrequency` is set to a sensible default (10% of the max).  If a `max` isn't set, the bar is output for every advance so to prevent flooding, a sensible `redrawFrequency` should be manually set.

The only BC break is that output will now display where it didn't before.

Commits
-------

cdee6f6 add overwrite flag to allow non-decorated output

Author: fabpot

Helper/ProgressBar.php

@@ -11,7 +11,6 @@
 
 namespace Symfony\Component\Console\Helper;
 
-use Symfony\Component\Console\Output\NullOutput;
 use Symfony\Component\Console\Output\OutputInterface;
 
 /**
@@ -42,6 +41,7 @@ class ProgressBar
     private $lastMessagesLength = 0;
     private $formatLineCount;
     private $messages;
+    private $overwrite = true;
 
     private static $formatters;
     private static $formats;
@@ -54,10 +54,19 @@ class ProgressBar
      */
     public function __construct(OutputInterface $output, $max = 0)
     {
-        // Disabling output when it does not support ANSI codes as it would result in a broken display anyway.
-        $this->output = $output->isDecorated() ? $output : new NullOutput();
+        $this->output = $output;
         $this->setMaxSteps($max);
 
+        if (!$this->output->isDecorated()) {
+            // disable overwrite when output does not support ANSI codes.
+            $this->overwrite = false;
+
+            if ($this->max > 10) {
+                // set a reasonable redraw frequency so output isn't flooded
+                $this->setRedrawFrequency($max / 10);
+            }
+        }
+
         $this->setFormat($this->determineBestFormat());
 
         $this->startTime = time();
@@ -360,6 +369,16 @@ public function setCurrent($step)
         $this->setProgress($step);
     }
 
+    /**
+     * Sets whether to overwrite the progressbar, false for new line
+     *
+     * @param bool $overwrite
+     */
+    public function setOverwrite($overwrite)
+    {
+        $this->overwrite = (bool) $overwrite;
+    }
+
     /**
      * Sets the current progress.
      *
@@ -396,6 +415,11 @@ public function finish()
             $this->max = $this->step;
         }
 
+        if ($this->step === $this->max && !$this->overwrite) {
+            // prevent double 100% output
+            return;
+        }
+
         $this->setProgress($this->max);
     }
 
@@ -438,6 +462,10 @@ public function display()
      */
     public function clear()
     {
+        if (!$this->overwrite) {
+            return;
+        }
+
         $this->overwrite(str_repeat("\n", $this->formatLineCount));
     }
 
@@ -470,8 +498,14 @@ private function overwrite($message)
             }
         }
 
-        // move back to the beginning of the progress bar before redrawing it
-        $this->output->write("\x0D");
+        if ($this->overwrite) {
+            // move back to the beginning of the progress bar before redrawing it
+            $this->output->write("\x0D");
+        } elseif ($this->step > 0) {
+            // move to new line
+            $this->output->writeln('');
+        }
+
         if ($this->formatLineCount) {
             $this->output->write(sprintf("\033[%dA", $this->formatLineCount));
         }

Tests/Helper/ProgressBarTest.php

@@ -311,13 +311,63 @@ public function testPercentNotHundredBeforeComplete()
     }
 
     public function testNonDecoratedOutput()
+    {
+        $bar = new ProgressBar($output = $this->getOutputStream(false), 200);
+        $bar->start();
+
+        for ($i = 0; $i < 200; $i++) {
+            $bar->advance();
+        }
+
+        $bar->finish();
+
+        rewind($output->getStream());
+        $this->assertEquals(
+            "   0/200 [>---------------------------]   0%\n".
+            "  20/200 [==>-------------------------]  10%\n".
+            "  40/200 [=====>----------------------]  20%\n".
+            "  60/200 [========>-------------------]  30%\n".
+            "  80/200 [===========>----------------]  40%\n".
+            " 100/200 [==============>-------------]  50%\n".
+            " 120/200 [================>-----------]  60%\n".
+            " 140/200 [===================>--------]  70%\n".
+            " 160/200 [======================>-----]  80%\n".
+            " 180/200 [=========================>--]  90%\n".
+            " 200/200 [============================] 100%",
+            stream_get_contents($output->getStream())
+        );
+    }
+
+    public function testNonDecoratedOutputWithClear()
+    {
+        $bar = new ProgressBar($output = $this->getOutputStream(false), 50);
+        $bar->start();
+        $bar->setProgress(25);
+        $bar->clear();
+        $bar->setProgress(50);
+        $bar->finish();
+
+        rewind($output->getStream());
+        $this->assertEquals(
+            "  0/50 [>---------------------------]   0%\n".
+            " 25/50 [==============>-------------]  50%\n".
+            " 50/50 [============================] 100%",
+            stream_get_contents($output->getStream())
+        );
+    }
+
+    public function testNonDecoratedOutputWithoutMax()
     {
         $bar = new ProgressBar($output = $this->getOutputStream(false));
         $bar->start();
         $bar->advance();
 
         rewind($output->getStream());
-        $this->assertEquals('', stream_get_contents($output->getStream()));
+        $this->assertEquals(
+            "    0 [>---------------------------]\n".
+            "    1 [->--------------------------]",
+            stream_get_contents($output->getStream())
+        );
     }
 
     public function testParallelBars()