[Console] Document console cursor

noniagriconomie · wouterj · commit 232c519980c3 · 2021-06-17T13:02:08.000+02:00
diff --git a/_images/components/console/cursor.gif b/_images/components/console/cursor.gif
diff --git a/components/console/helpers/cursor.rst b/components/console/helpers/cursor.rst
@@ -0,0 +1,101 @@
+.. 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/Commande/MyCommand.php
+    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)
+        {
+            // ...
+
+            $cursor = new Cursor($output);
+
+            // moves the cursor to a specific column and row 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 position from its current position
+    $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.
diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.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.
diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc
@@ -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`
diff --git a/components/console/helpers/progressbar.rst b/components/console/helpers/progressbar.rst
@@ -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
diff --git a/console.rst b/console.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
