From 0383f72bb72c7d89c106eb661acf42824ff8d585 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kriszti=C3=A1n=20Ferenczi?= Date: Tue, 19 Mar 2019 16:50:25 +0100 Subject: [PATCH 1/2] Add the prettywordwrapper console helper documentation --- components/console/helpers/index.rst | 1 + components/console/helpers/map.rst.inc | 1 + .../console/helpers/prettywordwrapper.rst | 273 ++++++++++++++++++ components/console/helpers/table.rst | 8 +- 4 files changed, 282 insertions(+), 1 deletion(-) create mode 100644 components/console/helpers/prettywordwrapper.rst diff --git a/components/console/helpers/index.rst b/components/console/helpers/index.rst index 87c62ca7629..8e8ece66493 100644 --- a/components/console/helpers/index.rst +++ b/components/console/helpers/index.rst @@ -11,6 +11,7 @@ The Console Helpers processhelper progressbar questionhelper + prettywordwrapper table debug_formatter diff --git a/components/console/helpers/map.rst.inc b/components/console/helpers/map.rst.inc index 68e1e722a87..a66bc57831a 100644 --- a/components/console/helpers/map.rst.inc +++ b/components/console/helpers/map.rst.inc @@ -2,5 +2,6 @@ * :doc:`/components/console/helpers/processhelper` * :doc:`/components/console/helpers/progressbar` * :doc:`/components/console/helpers/questionhelper` +* :doc:`/components/console/helpers/prettywordwrapper` * :doc:`/components/console/helpers/table` * :doc:`/components/console/helpers/debug_formatter` diff --git a/components/console/helpers/prettywordwrapper.rst b/components/console/helpers/prettywordwrapper.rst new file mode 100644 index 00000000000..3494d4b1e73 --- /dev/null +++ b/components/console/helpers/prettywordwrapper.rst @@ -0,0 +1,273 @@ +.. index:: +single: Console Helpers; Pretty Word Wrapper Helper + +Pretty Word Wrapper Helper +========================== + +The Pretty word wrapper provides a :method:`Symfony\\Component\\Console\\Helper\\PrettyWordWrapperHelper::wordwrap` +function to create well wrapped text messages. + +The :class:`Symfony\\Component\\Console\\Helper\\PrettyWordWrapperHelper` is included +in the default helper set, which you can get by calling +:method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`:: + + $wrapper = $this->getHelper('prettywordwrapper'); + +The method returns a string, which you'll usually render to the console by +passing it to the +:method:`OutputInterface::writeln ` method. + +Other using +----------- + +You can use it with the default :class:`OutputFormatter ` or +other formatter that implements +:class:`WrappableOutputFormatterInterface ` + +.. note:: + + See the ``CUT_*`` options below. + +.. code-block:: php + + $text = '...'; + $wrappedText = $output->getFormatter()->format( + $output->getFormatter()->wordwrap($text, 30, PrettyWordWrapperHelper::CUT_ALL) + ); + + // OR, you can set the default cutting option + $output->getFormatter()->setDefaultWrapCutOption(PrettyWordWrapperHelper::CUT_ALL); + $wrappedText = $output->getFormatter()->formatAndWrap($text, 30); + +You can use it with :class:`Table ` also: + +.. code-block:: php + + $table = $this->getHelper('table'); + $table + ->setDefaultColumnWordWrapCutOption(PrettyWordWrapperHelper::CUT_DISABLE) + ->setColumnMaxWidth(1, 40) // Here will use the set default cut option + ->setColumnMaxWidth(2, 20, PrettyWordWrapperHelper::CUT_ALL) // Here will use the CUT_ALL option + ; + +.. note:: + + More information about table helper: :doc:`/components/console/helpers/table` + +Cut options +----------- + +You can configure how to behave the wrapper. + +======================== ====== ====================================================================================== +Name Value Description +======================== ====== ====================================================================================== +``CUT_DISABLE`` ``0`` It disables all of options. Always break the text at word boundary. +``CUT_LONG_WORDS`` ``1`` "Long words" means the length of word is longer than one line. If it is set, the + long words will cut. +``CUT_WORDS`` ``3`` Always break at set length, it will cut all words. It would be useful if you have + little space. (Info: It "contains" the ``CUT_LONG_WORDS`` option) +``CUT_URLS`` ``4`` Lots of terminal can recognize URL-s in text and make them clickable (if there isn't + break inside the URL) The URLs can be long, default we keep it in one block even if + it gets ugly response. You can switch this behavior off with this option. The result + will be pretty, but the URL won't be clickable. +``CUT_ALL`` ``7`` Switch every "word cut" options on. +``CUT_FILL_UP_MISSING`` ``8`` End of lines will fill up with spaces in order to every line to be same length. +``CUT_NO_REPLACE_EOL`` ``16`` The program will replace the PHP_EOL in the input string to $break by default. You + switch it off with this. +======================== ====== ====================================================================================== + +Examples +~~~~~~~~ + +.. note:: + + The default option is ``PrettyWordWrapperHelper::CUT_LONG_WORDS``. + +Default parameters: + +============== =========================================================================================== +Parameter Value +============== =========================================================================================== +``$width`` ``120`` +``$cutOption`` ``PrettyWordWrapperHelper::CUT_LONG_WORDS`` +``$break`` ``\n`` +============== =========================================================================================== + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + // Default parameters + $default = $wrapper->wordwrap($text); + +.. code-block:: text + + Lorem ipsum dolor sit amet. + +Short lines, **disable** cuts ( ``CUT_DISABLE`` ) + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_DISABLE); + +.. code-block:: text + + Lorem + ipsum + dolor + sit + amet. + +Short lines, **enable** word cutting only for long words ( ``CUT_LONG_WORDS`` ) + +.. note:: + + Long words in this example: ``Lorem``, ``ipsum`` and ``dolor``. The ``sit`` won't be cut here. + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_LONG_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r + sit + amet + . + +Short lines, **enable** cut for every word ( ``CUT_WORDS`` ) + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r si + t am + et. + +Short lines, **disable** word cutting ( ``CUT_DISABLE`` ) + **set** custom break + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + // The width is 6 here, not 4 like above. + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_DISABLE, "<\n") . "<"; + +.. code-block:: text + + Lorem< + ipsum< + dolor< + sit< + amet.< + +Short lines, **disable** word cutting ( ``CUT_DISABLE`` ) + **enable** fill up ( ``CUT_FILL_UP_MISSING`` ) + **set** custom break + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + // The width is 6 here, not 4 like above. + $default = $wrapper->wordwrap( + $text, + 6, + PrettyWordWrapperHelper::CUT_DISABLE | PrettyWordWrapperHelper::CUT_FILL_UP_MISSING, + "<\n" + ) . "<"; + +.. code-block:: text + + Lorem < + ipsum < + dolor < + sit < + amet. < + +Text with URL + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet: http://symfony.com"; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_DISABLE); + +.. code-block:: text + + Lorem + ipsum + dolor + sit + amet: + http://symofny.com + +Text with URL, **enable** word cut ( ``CUT_WORDS`` ) + **disable** URL cut + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet: http://symfony.com"; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r si + t am + et: + http://symofny.com + +Text with URL, **disable** word cut + **enable** URL cut ( ``CUT_URLS`` ) + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet: http://symfony.com"; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_URLS); + +.. code-block:: text + + Lorem + ipsum + dolor + sit + amet: + http + ://s + ymof + ny.c + om + +Text with style tags + +.. code-block:: php + + $text = "Lorem ipsum dolor sit amet."; + $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_WORDS); + +.. code-block:: text + + Lore + m ip + sum + dolo + r si + t am + et. + +Line endings +------------ + +There are different line endings on different operating systems. It can cause some problems, so we unify it to ``\n``. +You can switch this behavior off with ``PrettyWordWrapperHelper::CUT_NO_REPLACE_EOL``. diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index 20067ba5127..fe61b2f3e4f 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -134,7 +134,7 @@ If you prefer to wrap long contents in multiple rows, use the // ... $table->setColumnMaxWidth(0, 5); - $table->setColumnMaxWidth(1, 10); + $table->setColumnMaxWidth(1, 10, PrettyWordWrapperHelper::CUT_ALL); $table->render(); The output of this command will be: @@ -150,6 +150,12 @@ The output of this command will be: | (the rest of rows...) | +-------+------------+--------------------------------+ +.. note:: + + More information about + :class:`PrettyWordWrapperHelper ` and the available + cut options: :doc:`/components/console/helpers/prettywordwrapper` + The table style can be changed to any built-in styles via :method:`Symfony\\Component\\Console\\Helper\\Table::setStyle`:: From fd9416a0662c2a2d870f1e79d9c98634c674f7bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kriszti=C3=A1n=20Ferenczi?= Date: Fri, 22 Mar 2019 12:35:12 +0100 Subject: [PATCH 2/2] Console: Rename WordWrapperHelper --- .../console/helpers/prettywordwrapper.rst | 42 +++++++++---------- components/console/helpers/table.rst | 4 +- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/components/console/helpers/prettywordwrapper.rst b/components/console/helpers/prettywordwrapper.rst index 3494d4b1e73..ef4219fdb5d 100644 --- a/components/console/helpers/prettywordwrapper.rst +++ b/components/console/helpers/prettywordwrapper.rst @@ -1,13 +1,13 @@ .. index:: -single: Console Helpers; Pretty Word Wrapper Helper +single: Console Helpers; Word Wrapper Helper -Pretty Word Wrapper Helper -========================== +Word Wrapper Helper +=================== -The Pretty word wrapper provides a :method:`Symfony\\Component\\Console\\Helper\\PrettyWordWrapperHelper::wordwrap` +The word wrapper provides a :method:`Symfony\\Component\\Console\\Helper\\WordWrapperHelper::wordwrap` function to create well wrapped text messages. -The :class:`Symfony\\Component\\Console\\Helper\\PrettyWordWrapperHelper` is included +The :class:`Symfony\\Component\\Console\\Helper\\WordWrapperHelper` is included in the default helper set, which you can get by calling :method:`Symfony\\Component\\Console\\Command\\Command::getHelperSet`:: @@ -32,11 +32,11 @@ other formatter that implements $text = '...'; $wrappedText = $output->getFormatter()->format( - $output->getFormatter()->wordwrap($text, 30, PrettyWordWrapperHelper::CUT_ALL) + $output->getFormatter()->wordwrap($text, 30, WordWrapperHelper::CUT_ALL) ); // OR, you can set the default cutting option - $output->getFormatter()->setDefaultWrapCutOption(PrettyWordWrapperHelper::CUT_ALL); + $output->getFormatter()->setDefaultWrapCutOption(WordWrapperHelper::CUT_ALL); $wrappedText = $output->getFormatter()->formatAndWrap($text, 30); You can use it with :class:`Table ` also: @@ -45,9 +45,9 @@ You can use it with :class:`Table ` $table = $this->getHelper('table'); $table - ->setDefaultColumnWordWrapCutOption(PrettyWordWrapperHelper::CUT_DISABLE) + ->setDefaultColumnWordWrapCutOption(WordWrapperHelper::CUT_DISABLE) ->setColumnMaxWidth(1, 40) // Here will use the set default cut option - ->setColumnMaxWidth(2, 20, PrettyWordWrapperHelper::CUT_ALL) // Here will use the CUT_ALL option + ->setColumnMaxWidth(2, 20, WordWrapperHelper::CUT_ALL) // Here will use the CUT_ALL option ; .. note:: @@ -82,7 +82,7 @@ Examples .. note:: - The default option is ``PrettyWordWrapperHelper::CUT_LONG_WORDS``. + The default option is ``WordWrapperHelper::CUT_LONG_WORDS``. Default parameters: @@ -90,7 +90,7 @@ Default parameters: Parameter Value ============== =========================================================================================== ``$width`` ``120`` -``$cutOption`` ``PrettyWordWrapperHelper::CUT_LONG_WORDS`` +``$cutOption`` ``WordWrapperHelper::CUT_LONG_WORDS`` ``$break`` ``\n`` ============== =========================================================================================== @@ -109,7 +109,7 @@ Short lines, **disable** cuts ( ``CUT_DISABLE`` ) .. code-block:: php $text = "Lorem ipsum dolor sit amet."; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_DISABLE); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_DISABLE); .. code-block:: text @@ -128,7 +128,7 @@ Short lines, **enable** word cutting only for long words ( ``CUT_LONG_WORDS`` ) .. code-block:: php $text = "Lorem ipsum dolor sit amet."; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_LONG_WORDS); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_LONG_WORDS); .. code-block:: text @@ -146,7 +146,7 @@ Short lines, **enable** cut for every word ( ``CUT_WORDS`` ) .. code-block:: php $text = "Lorem ipsum dolor sit amet."; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_WORDS); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_WORDS); .. code-block:: text @@ -164,7 +164,7 @@ Short lines, **disable** word cutting ( ``CUT_DISABLE`` ) + **set** custom brea $text = "Lorem ipsum dolor sit amet."; // The width is 6 here, not 4 like above. - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_DISABLE, "<\n") . "<"; + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_DISABLE, "<\n") . "<"; .. code-block:: text @@ -183,7 +183,7 @@ Short lines, **disable** word cutting ( ``CUT_DISABLE`` ) + **enable** fill up ( $default = $wrapper->wordwrap( $text, 6, - PrettyWordWrapperHelper::CUT_DISABLE | PrettyWordWrapperHelper::CUT_FILL_UP_MISSING, + WordWrapperHelper::CUT_DISABLE | WordWrapperHelper::CUT_FILL_UP_MISSING, "<\n" ) . "<"; @@ -200,7 +200,7 @@ Text with URL .. code-block:: php $text = "Lorem ipsum dolor sit amet: http://symfony.com"; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_DISABLE); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_DISABLE); .. code-block:: text @@ -216,7 +216,7 @@ Text with URL, **enable** word cut ( ``CUT_WORDS`` ) + **disable** URL cut .. code-block:: php $text = "Lorem ipsum dolor sit amet: http://symfony.com"; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_WORDS); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_WORDS); .. code-block:: text @@ -234,7 +234,7 @@ Text with URL, **disable** word cut + **enable** URL cut ( ``CUT_URLS`` ) .. code-block:: php $text = "Lorem ipsum dolor sit amet: http://symfony.com"; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_URLS); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_URLS); .. code-block:: text @@ -254,7 +254,7 @@ Text with style tags .. code-block:: php $text = "Lorem ipsum dolor sit amet."; - $default = $wrapper->wordwrap($text, 4, PrettyWordWrapperHelper::CUT_WORDS); + $default = $wrapper->wordwrap($text, 4, WordWrapperHelper::CUT_WORDS); .. code-block:: text @@ -270,4 +270,4 @@ Line endings ------------ There are different line endings on different operating systems. It can cause some problems, so we unify it to ``\n``. -You can switch this behavior off with ``PrettyWordWrapperHelper::CUT_NO_REPLACE_EOL``. +You can switch this behavior off with ``WordWrapperHelper::CUT_NO_REPLACE_EOL``. diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index fe61b2f3e4f..7c248d9c4ba 100644 --- a/components/console/helpers/table.rst +++ b/components/console/helpers/table.rst @@ -134,7 +134,7 @@ If you prefer to wrap long contents in multiple rows, use the // ... $table->setColumnMaxWidth(0, 5); - $table->setColumnMaxWidth(1, 10, PrettyWordWrapperHelper::CUT_ALL); + $table->setColumnMaxWidth(1, 10, WordWrapperHelper::CUT_ALL); $table->render(); The output of this command will be: @@ -153,7 +153,7 @@ The output of this command will be: .. note:: More information about - :class:`PrettyWordWrapperHelper ` and the available + :class:`WordWrapperHelper ` and the available cut options: :doc:`/components/console/helpers/prettywordwrapper` The table style can be changed to any built-in styles via