From 0d4a2636b4f877d2af09da5093b7dfa6a070e38d Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Tue, 26 Jan 2016 15:40:53 +0000 Subject: [PATCH 1/4] Add FormatterHelper::truncate docs --- .../console/helpers/formatterhelper.rst | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index 12386d04c3f..e07d8b865fb 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -63,3 +63,55 @@ messages and 2 spaces on the left and right). The exact "style" you use in the block is up to you. In this case, you're using the pre-defined ``error`` style, but there are other styles, or you can create your own. See :ref:`components-console-coloring`. + +Print Truncated Messages +------------------------ + +.. versionadded:: 3.1 + The ``truncate`` method was introduced in Symfony 3.1. + +Sometimes you want to print a message truncated to an explicit character length. This is possible with the +:method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::truncate` method. + +If you would like to truncate a very long message, for example, to 7 characters, you can write:: + + $message = "This is a very long message, which should be truncated"; + $truncatedMessage = $formatter->truncate($message, 7); + $output->writeln($truncatedMessage); + +And the output will be:: + + This is... +Message is truncated to the given length, then the suffix is appended to end of that string. + +Negative String Length +~~~~~~~~~~~~~~~~~~~~~~ + +If the length is negative, number of letters to truncate is counted from the end of the message:: + + $truncatedMessage = $formatter->truncate($message, -5); +Will result with:: + + This is a very long message, which should be trun... +Custom Suffix +~~~~~~~~~~~~~ + +By default ``...`` suffix is used. If you wish to use a different suffix, simply pass it as the third argument to the method:: + + $truncatedMessage = $formatter->truncate($message, 7, '!!'); +Will result with:: + + This is!! +Or if you don't want to use suffix at all, just pass an empty string:: + + $truncatedMessage = $formatter->truncate($message, 7, ''); +Which will result with:: + + This is +Suffix is always appended, unless truncate length is longer than a message and a suffix length:: + + $output->writeln($formatter->truncate('test', 10)); +will output:: + + test +because length of the ``test...`` string is shorter than 10. From 69817de72a12e70c60642b9420e1a392427a491a Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Tue, 26 Jan 2016 15:57:21 +0000 Subject: [PATCH 2/4] cs fix --- components/console/helpers/formatterhelper.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index e07d8b865fb..58724aae20f 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -82,6 +82,7 @@ If you would like to truncate a very long message, for example, to 7 characters, And the output will be:: This is... + Message is truncated to the given length, then the suffix is appended to end of that string. Negative String Length @@ -90,28 +91,36 @@ Negative String Length If the length is negative, number of letters to truncate is counted from the end of the message:: $truncatedMessage = $formatter->truncate($message, -5); + Will result with:: This is a very long message, which should be trun... + Custom Suffix ~~~~~~~~~~~~~ By default ``...`` suffix is used. If you wish to use a different suffix, simply pass it as the third argument to the method:: $truncatedMessage = $formatter->truncate($message, 7, '!!'); + Will result with:: This is!! + Or if you don't want to use suffix at all, just pass an empty string:: $truncatedMessage = $formatter->truncate($message, 7, ''); + Which will result with:: This is + Suffix is always appended, unless truncate length is longer than a message and a suffix length:: $output->writeln($formatter->truncate('test', 10)); + will output:: test + because length of the ``test...`` string is shorter than 10. From d2dd033c3b1317a00ada5ba0c021fa8b9111e692 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Sun, 31 Jan 2016 20:45:02 +0000 Subject: [PATCH 3/4] Change wording and fix column length --- components/console/helpers/formatterhelper.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index 58724aae20f..0c1e4d0d76d 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -70,10 +70,12 @@ Print Truncated Messages .. versionadded:: 3.1 The ``truncate`` method was introduced in Symfony 3.1. -Sometimes you want to print a message truncated to an explicit character length. This is possible with the +Sometimes you want to print a message truncated to an explicit character length. +This is possible with the :method:`Symfony\\Component\\Console\\Helper\\FormatterHelper::truncate` method. -If you would like to truncate a very long message, for example, to 7 characters, you can write:: +If you would like to truncate a very long message, for example, to 7 characters, +you can write:: $message = "This is a very long message, which should be truncated"; $truncatedMessage = $formatter->truncate($message, 7); @@ -83,12 +85,14 @@ And the output will be:: This is... -Message is truncated to the given length, then the suffix is appended to end of that string. +Message is truncated to the given length, then the suffix is appended to end +of that string. Negative String Length ~~~~~~~~~~~~~~~~~~~~~~ -If the length is negative, number of letters to truncate is counted from the end of the message:: +If the length is negative, number of characters to truncate is counted +from the end of the string:: $truncatedMessage = $formatter->truncate($message, -5); @@ -99,7 +103,8 @@ Will result with:: Custom Suffix ~~~~~~~~~~~~~ -By default ``...`` suffix is used. If you wish to use a different suffix, simply pass it as the third argument to the method:: +By default ``...`` suffix is used. If you wish to use a different suffix, +simply pass it as the third argument to the method:: $truncatedMessage = $formatter->truncate($message, 7, '!!'); @@ -115,7 +120,8 @@ Which will result with:: This is -Suffix is always appended, unless truncate length is longer than a message and a suffix length:: +Suffix is always appended, unless truncate length is longer than a message +and a suffix length:: $output->writeln($formatter->truncate('test', 10)); From 2f8a6b489a1472910ff0f564ce5d0d0adadd4f38 Mon Sep 17 00:00:00 2001 From: Marek Pietrzak Date: Sun, 7 Feb 2016 10:02:47 +0000 Subject: [PATCH 4/4] Move suffix examples into one code block, fix wording --- .../console/helpers/formatterhelper.rst | 41 ++++++------------- 1 file changed, 13 insertions(+), 28 deletions(-) diff --git a/components/console/helpers/formatterhelper.rst b/components/console/helpers/formatterhelper.rst index 0c1e4d0d76d..5f26563f471 100644 --- a/components/console/helpers/formatterhelper.rst +++ b/components/console/helpers/formatterhelper.rst @@ -85,48 +85,33 @@ And the output will be:: This is... -Message is truncated to the given length, then the suffix is appended to end +The message is truncated to the given length, then the suffix is appended to end of that string. Negative String Length ~~~~~~~~~~~~~~~~~~~~~~ -If the length is negative, number of characters to truncate is counted +If the length is negative, the number of characters to truncate is counted from the end of the string:: $truncatedMessage = $formatter->truncate($message, -5); -Will result with:: +This will result in:: This is a very long message, which should be trun... Custom Suffix ~~~~~~~~~~~~~ -By default ``...`` suffix is used. If you wish to use a different suffix, -simply pass it as the third argument to the method:: +By default, the ``...`` suffix is used. If you wish to use a different suffix, +simply pass it as the third argument to the method. +The suffix is always appended, unless truncate length is longer than a message +and a suffix length. +If you don't want to use suffix at all, just pass an empty string:: - $truncatedMessage = $formatter->truncate($message, 7, '!!'); + $truncatedMessage = $formatter->truncate($message, 7, '!!'); // result: This is!! + $truncatedMessage = $formatter->truncate($message, 7, ''); // result: This is + $truncatedMessage = $formatter->truncate('test', 10)); + /* result: test + because length of the "test..." string is shorter than 10 */ -Will result with:: - - This is!! - -Or if you don't want to use suffix at all, just pass an empty string:: - - $truncatedMessage = $formatter->truncate($message, 7, ''); - -Which will result with:: - - This is - -Suffix is always appended, unless truncate length is longer than a message -and a suffix length:: - - $output->writeln($formatter->truncate('test', 10)); - -will output:: - - test - -because length of the ``test...`` string is shorter than 10.