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..ef4219fdb5d --- /dev/null +++ b/components/console/helpers/prettywordwrapper.rst @@ -0,0 +1,273 @@ +.. index:: +single: Console Helpers; Word Wrapper Helper + +Word Wrapper Helper +=================== + +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\\WordWrapperHelper` 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, WordWrapperHelper::CUT_ALL) + ); + + // OR, you can set the default cutting option + $output->getFormatter()->setDefaultWrapCutOption(WordWrapperHelper::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(WordWrapperHelper::CUT_DISABLE) + ->setColumnMaxWidth(1, 40) // Here will use the set default cut option + ->setColumnMaxWidth(2, 20, WordWrapperHelper::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 ``WordWrapperHelper::CUT_LONG_WORDS``. + +Default parameters: + +============== =========================================================================================== +Parameter Value +============== =========================================================================================== +``$width`` ``120`` +``$cutOption`` ``WordWrapperHelper::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, WordWrapperHelper::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, WordWrapperHelper::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, WordWrapperHelper::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, WordWrapperHelper::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, + WordWrapperHelper::CUT_DISABLE | WordWrapperHelper::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, WordWrapperHelper::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, WordWrapperHelper::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, WordWrapperHelper::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, WordWrapperHelper::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 ``WordWrapperHelper::CUT_NO_REPLACE_EOL``. diff --git a/components/console/helpers/table.rst b/components/console/helpers/table.rst index 20067ba5127..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); + $table->setColumnMaxWidth(1, 10, WordWrapperHelper::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:`WordWrapperHelper ` 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`::