Merge remote-tracking branch 'upstream/5.2' into 5.2

* upstream/5.2: [#15270] Minor fixes [Console] Document console cursor

Author: javiereguiluz

.doctor-rst.yaml

@@ -103,3 +103,4 @@ whitelist:
  - '.. code-block:: twig'
  - '.. versionadded:: 3.6' # MonologBundle
  - 'End to End Tests (E2E)'
+ - '.. code-block:: php'

_images/components/console/cursor.gif

@@ -0,0 +1,104 @@
+.. index::
+ single: Console Helpers; Cursor Helper
+
+Cursor Helper
+=============
+
+.. versionadded:: 5.1
+
+ The :class:`Symfony\\Component\\Console\\Cursor` class was introduced
+ in Symfony 5.1.
+
+The :class:`Symfony\\Component\\Console\\Cursor` allows you to change the
+cursor position in a console command. This allows you to write on any position
+of the output:
+
+.. image:: /_images/components/console/cursor.gif
+ :align: center
+
+.. code-block:: php
+
+ // src/Command/MyCommand.php
+ namespace App\Command;
+
+ use Symfony\Component\Console\Command\Command;
+ use Symfony\Component\Console\Cursor;
+ use Symfony\Component\Console\Input\InputInterface;
+ use Symfony\Component\Console\Output\OutputInterface;
+
+ class MyCommand extends Command
+ {
+ // ...
+
+ public function execute(InputInterface $input, OutputInterface $output): int
+ {
+ // ...
+
+ $cursor = new Cursor($output);
+
+ // moves the cursor to a specific column (1st argument) and
+ // row (2nd argument) position
+ $cursor->moveToPosition(7, 11);
+
+ // and write text on this position using the output
+ $output->write('My text');
+
+ // ...
+ }
+ }
+
+Using the cursor
+----------------
+
+Moving the cursor
+.................
+
+There are fews methods to control moving the command cursor::
+
+ // moves the cursor 1 line up from its current position
+ $cursor->moveUp();
+
+ // moves the cursor 3 lines up from its current position
+ $cursor->moveUp(3);
+
+ // same for down
+ $cursor->moveDown();
+
+ // moves the cursor 1 column right from its current position
+ $cursor->moveRight();
+
+ // moves the cursor 3 columns right from its current position
+ $cursor->moveRight(3);
+
+ // same for left
+ $cursor->moveLeft();
+
+ // move the cursor to a specific (column, row) position from the
+ // top-left position of the terminal
+ $cursor->moveToPosition(7, 11);
+
+You can get the current command's cursor position by using::
+
+ $position = $cursor->getCurrentPosition();
+ // $position[0] // columns (aka x coordinate)
+ // $position[1] // rows (aka y coordinate)
+
+Clearing output
+...............
+
+The cursor can also clear some output on the screen::
+
+ // clears all the output from the current line
+ $cursor->clearLine();
+
+ // clears all the output from the current line after the current position
+ $cursor->clearLineAfter();
+
+ // clears all the output from the cursors' current position to the end of the screen
+ $cursor->clearOutput();
+
+ // clears the entire screen
+ $cursor->clearScreen();
+
+You also can leverage the :method:`Symfony\\Component\\Console\\Cursor::show`
+and :method:`Symfony\\Component\\Console\\Cursor::hide` methods on the cursor.

components/console/helpers/cursor.rst

@@ -13,6 +13,7 @@ The Console Helpers
  questionhelper
  table
  debug_formatter
+ cursor
 
 The Console component comes with some useful helpers. These helpers contain
 functions to ease some common tasks.

components/console/helpers/index.rst

@@ -4,3 +4,4 @@
 * :doc:`/components/console/helpers/questionhelper`
 * :doc:`/components/console/helpers/table`
 * :doc:`/components/console/helpers/debug_formatter`
+* :doc:`/components/console/helpers/cursor`

components/console/helpers/map.rst.inc

@@ -349,7 +349,7 @@ placeholder before displaying the progress bar::
  // 0/100 -- Start
 
  $progressBar->setMessage('Task is in progress...');
- $progressBar->advance(); 
+ $progressBar->advance();
  // 1/100 -- Task is in progress...
 
 Messages can be combined with custom placeholders too. In this example, the

components/console/helpers/progressbar.rst

@@ -446,5 +446,6 @@ tools capable of helping you with different tasks:
 * :doc:`/components/console/helpers/table`: displays tabular data as a table
 * :doc:`/components/console/helpers/debug_formatter`: provides functions to
  output debug information when running an external program
+* :doc:`/components/console/helpers/cursor`: allows to manipulate the cursor in the terminal
 
 .. _`exit status`: https://en.wikipedia.org/wiki/Exit_status