From 31a2a4413b1d8d31b4119f7499d7eeb5335ea116 Mon Sep 17 00:00:00 2001 From: Robin Chalas Date: Fri, 13 Jan 2017 18:40:02 +0100 Subject: [PATCH 1/3] Document how to exclude irrelevant messages from command output using SymfonyStyle --- console/style.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/console/style.rst b/console/style.rst index 4b2f616c0dc..197474c72ec 100644 --- a/console/style.rst +++ b/console/style.rst @@ -373,3 +373,31 @@ of your commands to change their appearance:: // ... } } + +Writing to the error output +--------------------------- + +If you rely on the output of a command (e.g. by redirecting it to a file for later reuse), +you may want to get only the relevant information outputted by the command, excluding progress +bars, notes, warnings and other error messages which have, most of the time, no value for reuse. + +For excluding irrelevant messages from the output, you need to make your command write them to the error +output. Fortunately, the :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` provides a convenient +method to easily switch between both outputs: +:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::getErrorStyle`. +This method returns a new ``SymfonyStyle`` instance which makes use of the error output: + + $io = new SymfonyStyle($input, $output); + + // Write to the output + $io->write('Reusable information'); + + // Write to the error output + $io->getErrorStyle()->warning('Irrelevant warning'); + +.. note:: + + If you created the original ``SymfonyStyle`` instance with an ``OutputInterface`` object that is + not an instance of :class:`Symfony\\Component\\Console\\Output\\ConsoleOutputInterface`, using + ``getErrorStyle()`` will return an instance which makes use of the normal output instead of + the error one, as if you did not called the method. From ff0ccdeef96aac4fbf296522a0b4e10847a048d0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 15 Apr 2017 11:15:29 +0200 Subject: [PATCH 2/3] Reworded the description --- console/style.rst | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/console/style.rst b/console/style.rst index 197474c72ec..774960a2868 100644 --- a/console/style.rst +++ b/console/style.rst @@ -377,27 +377,31 @@ of your commands to change their appearance:: Writing to the error output --------------------------- -If you rely on the output of a command (e.g. by redirecting it to a file for later reuse), -you may want to get only the relevant information outputted by the command, excluding progress -bars, notes, warnings and other error messages which have, most of the time, no value for reuse. +If you reuse the output of a command as the input of other commands or dump it +into a file for later reuse, you probably want to exclude progress bars, notes +and other output that provides no real value. -For excluding irrelevant messages from the output, you need to make your command write them to the error -output. Fortunately, the :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` provides a convenient -method to easily switch between both outputs: -:method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::getErrorStyle`. -This method returns a new ``SymfonyStyle`` instance which makes use of the error output: +Commands can output information in two different streams: ``stdout`` (standard +output) is the stream where the real contents should be output and ``stderr`` +(standard error) is the stream where the errors and the debugging messages +should be output. + +The :class:`Symfony\\Component\\Console\\Style\\SymfonyStyle` class provides a +convenient method called :method:`Symfony\\Component\\Console\\Style\\SymfonyStyle::getErrorStyle` +to switch between both streams. This method returns a new ``SymfonyStyle`` +instance which makes use of the error output:: $io = new SymfonyStyle($input, $output); - // Write to the output + // Write to the standard output $io->write('Reusable information'); // Write to the error output - $io->getErrorStyle()->warning('Irrelevant warning'); + $io->getErrorStyle()->warning('Debugging information or errors'); .. note:: - If you created the original ``SymfonyStyle`` instance with an ``OutputInterface`` object that is - not an instance of :class:`Symfony\\Component\\Console\\Output\\ConsoleOutputInterface`, using - ``getErrorStyle()`` will return an instance which makes use of the normal output instead of - the error one, as if you did not called the method. + If you create a ``SymfonyStyle`` instance with an ``OutputInterface`` object + that is not an instance of :class:`Symfony\\Component\\Console\\Output\\ConsoleOutputInterface`, + the ``getErrorStyle()`` method will have no effect and the returned object + will still output to the standard output instead of the error output. From a5c552470ee8a8306e1eda17aed4c15388c15a6e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 28 Apr 2017 16:00:27 +0200 Subject: [PATCH 3/3] Minor fix --- console/style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/console/style.rst b/console/style.rst index 774960a2868..db4af516969 100644 --- a/console/style.rst +++ b/console/style.rst @@ -404,4 +404,4 @@ instance which makes use of the error output:: If you create a ``SymfonyStyle`` instance with an ``OutputInterface`` object that is not an instance of :class:`Symfony\\Component\\Console\\Output\\ConsoleOutputInterface`, the ``getErrorStyle()`` method will have no effect and the returned object - will still output to the standard output instead of the error output. + will still write to the standard output instead of the error output.