Text::Stripper - a module for shortening text

  use Text::Stripper;

  my $text = "Lorem ipsum dolor sit amet, consectetur, adipisci velit";
  my $len  = 30;
  my $tol  = 10;
  my $max  = 1;
  my $dots = 1;

  print Text::Stripper::stripof( $text, $len, $tol, $max, $dots );

  # prints "Lorem ipsum dolor sit amet, consectetur,..."

  

Text::Stripper shortens text and avoids cutting the text in the middle of a word.

There may be situations, when you have a reasonably long text in your perl-application, which should be displayed to the user. But you may not want to print out all of the text, because it would consume too much space of your screen. So, you might want to display a shortened version of the information, and let the user decide, if he wants to view the full text or not.

In many cases, a "print substr($text, 0, 50).'...';" will be sufficient. Unfortunatly nearly all uses of the above example will cut your text in the middle of a word. So you might get phrases saying "This is an a..." or similar. For most users, this kind of text-stripping is hard to read and also offers some space for misinterpreting the cutted word.

A cleaner solution for the user is to print out "This is an..." or "This is an abstract...". This way, the user doesn't get confused about wondering what the "a..." stands for. This is where Text::Stripper comes in.

The module Text::Stripper consists of a single function named "stripof". You can give "stripof" a text, a "length" and a "tolerance", and it will give you a text shortend to at least "length" characters, with at maximum "tolerance" characters more to complete the next word(s).

The "stripof"-function tries to find all possible "breakpoints" in the text and cuts the text at an apropriate position. It consideres the following characters as "breakpoints":

' '

'\t'

'.'

','

';'

':'

'!'

'-'

'?'

'\n'

'\r'

'/'

'|'

'('

')'

There are two modes, in which the stripof-function may operate:

* maximum-mode: try to find the latest possible breakpoint

* minimum-mode: try to find the first possible breakpoint

See the examples-section for more details.

Optionally you can tell "stripof" to add three dots at the end of the text, to indicate that the text was shortend.

Under certain circumstances you might need more or less, or completely other characters as the predefined breakpoints. To achieve this, you have to redefine the breakpoints by overriding the modules global variable @Text::Stripper::breakpoints:

  use Text::Stripper;

  my $text = "abc1xyz2asdfg3zoo4gogo5gadgetto6";
  my $len  = 10;
  my $tol  = 10;
  my $max  = 1;
  my $dots = 0;

  # use 0...9 as breakpoints only:
  @Text::Stripper::breakpoints = ('0', '1', '2', '3', '4', '5', '6', '7', '8', '9');

  print Text::Stripper::stripof( $text, $len, $tol, $max, $dots );

  # prints "abc1xyz2asdfg3zoo"

Important: each entry in the breakpoints-list must contain a single character only! Definig something like:

  @Text::Stripper::breakpoints = ( '10', '20', '30' );  #  WRONG...!!!

does not work! This definition may result in the following behaviour: on maximum-search: breakpoints '0', '1', '2' and '3' are matched; on minimum-seach: no breakpoint will match at all.

Special characters must be escaped. So the following definition to use some paranthesis as breakpoints does not work:

  @Text::Stripper::breakpoints = ( '(', ')', '[', ']' );  #  WRONG...!!!

The correct definiton is:

  @Text::Stripper::breakpoints = ( '\(', '\)', '\[', '\]' );  #  RIGHT...!!!

This is because the breakpoint-characters are used in a regular expression. Therefore, they are not treated as usual charaters unless they are escaped.

  use Text::Stripper qw(stripof);
  my $text = "Lorem ipsum dolor sit amet, consectetur, adipisci velit";

  print stripof( $text, 30, 10, 1, 1 );
  # prints "Lorem ipsum dolor sit amet, consectetur..."
  # orig.: "Lorem ipsum dolor sit amet, consectetur, adipisci velit";
  #         1----------------------------^---------^ 
  #                                      30      +10
  #         one space: ----------------------------^
  #         $max set to 1 => use last space, which equals first space.

  print stripof( $text, 30, 10, 0, 1 );
  # prints "Lorem ipsum dolor sit amet, consectetur..."
  # orig.: "Lorem ipsum dolor sit amet, consectetur, adipisci velit";
  #         1-----------------------------^--------^ 
  #                                       30      +10
  #         one space: ----------------------------^
  #         $max set to 0 => use first space, which equals last space.

  print stripof( $text, 25, 14, 1, 1 );
  # prints "Lorem ipsum dolor sit amet,..."
  # orig.: "Lorem ipsum dolor sit amet, consectetur, adipisci velit";
  #         1-----------------------^-------------^ 
  #                                 25           +14
  #         two spaces: --------------^^
  #         $max set to 1 => use last space.

  


  print stripof( $text, 20, 10, 1, 1 );
  # prints "Lorem ipsum dolor sit amet,..."
  # orig.: "Lorem ipsum dolor sit amet, consectetur, adipisci velit";
  #         1------------------^---------^
  #                            20       +10
  #         3 spaces: -----------^----^^
  #         $max set to 1 => use last space. 

  print stripof( $text, 20, 10, 0, 1 );
  # prints "Lorem ipsum dolor sit..."
  # orig.: "Lorem ipsum dolor sit amet, consectetur, adipisci velit";
  #         1------------------^---------^
  #                            20       +10
  #         3 spaces: -----------^----^^
  #         $max set to 0 => use first space.

None by default.

You may import the function "stripof" and the list "breakpoints".

$Revision: 1.18 $

No bugs known. Please report bugs to <marcus@beranek.de>.

http://www.beranek.de

Marcus Beranek, <marcus@beranek.de>

Copyright (C) 2007 by Marcus Beranek

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.