From 3bc11859c6c946905946496bf54e0c3f6a1f3d3d Mon Sep 17 00:00:00 2001 From: Pierre du Plessis Date: Wed, 21 Feb 2018 07:14:14 +0200 Subject: [PATCH 1/3] Add documentation about manipulating console output --- console/manipulating_output.rst | 152 ++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 console/manipulating_output.rst diff --git a/console/manipulating_output.rst b/console/manipulating_output.rst new file mode 100644 index 00000000000..c9591030986 --- /dev/null +++ b/console/manipulating_output.rst @@ -0,0 +1,152 @@ +How To Manipulate Console Output +================================ + +The console comes with a powerful class to print information to the terminal. This +information can be manipulated by clearing or overwriting the displayed content. + +In order to manipulate the content, you need to create a new output section. An output section is +a part in the terminal where information will be displayed from the console. + +A section can be manipulated individually, and multiple sections can appended to the output. + +To create a new output section, you need to use the +:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method:: + + class MyCommand extends Command + { + protected function execute(InputInterface $input, OutputInterface $output) + { + $section = $output->section(); + } + } +} + +This will return an instance of of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput` + +.. tip:: + + You can create multiple sections by calling the + :method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method multiple times. + This will append a new section after the previous one. + +.. caution:: + + Displaying information in a section will always append a new line to the output. + + +Overwriting Output +------------------ + +When displaying information in the console, you can overwrite the output by using the +:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::overwrite` method:: + + $section->writeln('Hello'); + $section->overwrite('World!'); + +The only information displayed in the terminal will be ``World!`` as the first part will +be overwritten. + +Clearing s Section +------------------ + +You can clear all the content in a section by using the +:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::overwrite` method. + +Clearing a section will erase all the content that is displayed in that section:: + + $section->writeln('Hello World!'); + $section->clear(); + +This will leave your terminal clean without any output displayed. + +You can also clear a specific number of lines from the output instead of clearing all the +output:: + + $section->writeln('One!'); + $section->writeln('Two!'); + $section->writeln('Three!'); + $section->writeln('Four!'); + + $section->clear(2); + +This will only leave the lines ``One!`` and ``Two!`` displaying in the terminal. + +Modifying Content In Previous Sections +-------------------------------------- + +When you append multiple sections to the terminal, you can manipulate the output of +only a specific section, leaving the rest intact:: + + $section1 = $output->section(); + $section2 = $output->section(); + + $section1->writeln('Hello World!'); + $section2->writeln('This is comes second'); + + $section1->overwrite('This comes first'); + +This will result in the following output in the terminal: + +.. code-block:: text + + This comes first + This comes second + +Displaying Multiple Progress Bars +--------------------------------- + +You can display multiple progress bars underneath each other, and changing the progress +of one of the bars at a time:: + + $section1 = $output->section(); + $section2 = $output->section(); + + $progress1 = new ProgressBar($section1); + $progress2 = new ProgressBar($section2); + + $progress1->start(100); + $progress2->start(100); + + $c = 0; + while (++$c < 100) { + $progress1->advance(); + + if ($c % 2 === 0) { + $progress2->advance(4); + } + + usleep(500000); + } + +After a couple of iterations, the output in the terminal will look like this: + +.. code-block:: text + + 34/100 [=========>------------------] 34% + 68/100 [===================>--------] 68% + +Appending Rows To a Table +------------------------- + +If you are displaying a table in the terminal, you can append rows to an already rendered table +by using the :method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method. + +This method takes the same arguments as the :method:`Symfony\\Component\\Console\\Helper\\Table::addRow` +method, but if the table is already rendered, then it will append the row to the table. + + $section = $output->section(); + $table = new Table($section); + + $table->addRow(['Row 1']); + $table->render(); + + $table->addRow(['Row 2']); + +This will display the following table in the terminal: + +.. code-block:: text + + +-------+ + | Row 1 | + | Row 2 | + +-------+ From 30bfe8af5585252fff1c2bac40a978f43893c54c Mon Sep 17 00:00:00 2001 From: Pierre du Plessis Date: Wed, 21 Feb 2018 07:23:48 +0200 Subject: [PATCH 2/3] Remove extra character --- console/manipulating_output.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/console/manipulating_output.rst b/console/manipulating_output.rst index c9591030986..caa70aff8b5 100644 --- a/console/manipulating_output.rst +++ b/console/manipulating_output.rst @@ -19,7 +19,6 @@ To create a new output section, you need to use the $section = $output->section(); } } -} This will return an instance of of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput` From 1b3c18821a0cfca1a28c068e3138c62c75b36d7e Mon Sep 17 00:00:00 2001 From: Pierre du Plessis Date: Wed, 21 Feb 2018 07:26:59 +0200 Subject: [PATCH 3/3] Fix typos --- console/manipulating_output.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/console/manipulating_output.rst b/console/manipulating_output.rst index caa70aff8b5..3c361c5ef69 100644 --- a/console/manipulating_output.rst +++ b/console/manipulating_output.rst @@ -7,7 +7,7 @@ information can be manipulated by clearing or overwriting the displayed content. In order to manipulate the content, you need to create a new output section. An output section is a part in the terminal where information will be displayed from the console. -A section can be manipulated individually, and multiple sections can appended to the output. +A section can be manipulated individually, and multiple sections can be appended to the output. To create a new output section, you need to use the :method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method:: @@ -20,7 +20,7 @@ To create a new output section, you need to use the } } -This will return an instance of of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput` +This will return an instance of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput` .. tip:: @@ -32,7 +32,6 @@ This will return an instance of of the :class:`Symfony\\Component\\Console\\Outp Displaying information in a section will always append a new line to the output. - Overwriting Output ------------------ @@ -45,11 +44,11 @@ When displaying information in the console, you can overwrite the output by usin The only information displayed in the terminal will be ``World!`` as the first part will be overwritten. -Clearing s Section +Clearing a Section ------------------ You can clear all the content in a section by using the -:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::overwrite` method. +:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::clear` method. Clearing a section will erase all the content that is displayed in that section::