8000 minor #9304 Add documentation about manipulating console output (pier… · symfony/symfony-docs@944e534 · GitHub
[go: up one dir, main page]
Skip to content

Commit 944e534

Browse files
javiereguiluzjaviereguiluz
committed
minor #9304 Add documentation about manipulating console output (pierredup)
This PR was squashed before being merged into the 4.1 branch (closes #9304). Discussion ---------- Add documentation 10000 about manipulating console output Add documentation about manipulating console output (symfony/symfony#24363) Commits ------- 3b0e00c Add documentation about manipulating console output
2 parents 2c01e73 + 3b0e00c commit 944e534

File tree

1 file changed

+150
-0
lines changed

1 file changed

+150
-0
lines changed

‎console/manipulating_output.rst

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
How To Manipulate Console Output
2+
================================
3+
4+
The console comes with a powerful class to print information to the terminal. This
5+
information can be manipulated by clearing or overwriting the displayed content.
6+
7+
In order to manipulate the content, you need to create a new output section. An output section is
8+
a part in the terminal where information will be displayed from the console.
9+
10+
A section can be manipulated individually, and multiple sections can be appended to the output.
11+
12+
To create a new output section, you need to use the
13+
:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method::
14+
15+
class MyCommand extends Command
16+
{
17+
protected function execute(InputInterface $input, OutputInterface $output)
18+
{
19+
$section = $output->section();
20+
}
21+
}
22+
23+
This will return an instance of the :class:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput`
24+
25+
.. tip::
26+
27+
You can create multiple sections by calling the
28+
:method:`Symfony\\Component\\Console\\Output\\ConsoleOutput::section` method multiple times.
29+
This will append a new section after the previous one.
30+
31+
.. caution::
32+
33+
Displaying information in a section will always append a new line to the output.
34+
35+
Overwriting Output
36+
------------------
37+
38+
When displaying information in the console, you can overwrite the output by using the
39+
:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::overwrite` method::
40+
41+
$section->writeln('Hello');
42+
$section->overwrite('World!');
43+
44+
The only information displayed in the terminal will be ``World!`` as the first part will
45+
be overwritten.
46+
47+
Clearing a Section
48+
------------------
49+
50+
You can clear all the content in a section by using the
51+
:method:`Symfony\\Component\\Console\\Output\\ConsoleSectionOutput::clear` method.
52+
53+
Clearing a section will erase all the content that is displayed in that section::
54+
55+
$section->writeln('Hello World!');
56+
$section->clear();
57+
58+
This will leave your terminal clean without any output displayed.
59+
60+
You can also clear a specific number of lines from the output instead of clearing all the
61+
output::
62+
63+
$section->writeln('One!');
64+
$section->writeln('Two!');
65+
$section->writeln('Three!');
66+
$section->writeln('Four!');
67+
68+
$section->clear(2);
69+
70+
This will only leave the lines ``One!`` and ``Two!`` displaying in the terminal.
71+
72+
Modifying Content In Previous Sections
73+
--------------------------------------
74+
75+
When you append multiple sections to the terminal, you can manipulate the output of
76+
only a specific section, leaving the rest intact::
77+
78+
$section1 = $output->section();
79+
$section2 = $output->section();
80+
81+
$section1->writeln('Hello World!');
82+
$section2->writeln('This is comes second');
83+
84+
$section1->overwrite('This comes first');
85+
86+
This will result in the following output in the terminal:
87+
88+
.. code-block:: text
89+
90+
This comes first
91+
This comes second
92+
93+
Displaying Multiple Progress Bars
94+
---------------------------------
95+
96+
You can display multiple progress bars underneath each other, and changing the progress
97+
of one of the bars at a time::
98+
99+
$section1 = $output->section();
100+
$section2 = $output->section();
101+
102+
$progress1 = new ProgressBar($section1);
103+
$progress2 = new ProgressBar($section2);
104+
105+
$progress1->start(100);
106+
$progress2->start(100);
107+
108+
$c = 0;
109+
while (++$c < 100) {
110+
$progress1->advance();
111+
112+
if ($c % 2 === 0) {
113+
$progress2->advance(4);
114+
}
115+
116+
usleep(500000);
117+
}
118+
119+
After a couple of iterations, the output in the terminal will look like this:
120+
121+
.. code-block:: text
122+
123+
34/100 [=========>------------------] 34%
124+
68/100 [===================>--------] 68%
125+
126+
Appending Rows To a Table
127+
-------------------------
128+
129+
If you are displaying a table in the terminal, you can append rows to an already rendered table
130+
by using the :method:`Symfony\\Component\\Console\\Helper\\Table::appendRow` method.
131+
132+
This method takes the same arguments as the :method:`Symfony\\Component\\Console\\Helper\\Table::addRow`
133+
method, but if the table is already rendered, then it will append the row to the table.
134+
135+
$section = $output->section();
136+
$table = new Table($section);
137+
138+
$table->addRow(['Row 1']);
139+
$table->render();
140+
141+
$table->addRow(['Row 2']);
142+
143+
This will display the following table in the terminal:
144+
145+
.. code-block:: text
146+
147+
+-------+
148+
| Row 1 |
149+
| Row 2 |
150+
+-------+

0 commit comments

Comments
 (0)
0