The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Shorten-0.06
River stage zero No dependents
++
/ Text::Shorten

NAME

Text::Shorten - Abbreviate long output

VERSION

0.06

SYNOPSIS

    use Text::Shorten ':all';
    $short_string = shorten_scalar($really_long_string, 40);
    @short_array = shorten_array(\@really_long_array, 80);
    @short_hash = shorten_hash(\%really_large_hash, 80);

DESCRIPTION

Text::Shorten creates small strings and small arrays from larger values for display purposes. The output will include the string "..." to indicate that the value being displayed is abbreviated.

FUNCTIONS

shorten_scalar($SCALAR, $MAXLEN)

Returns a representation of $SCALAR that is no longer than $MAXLEN characters. It usually works by chopping characters off the end of the string and replacing them with the abbreviation indicator "...".

    $m = join('foo','A'..'Z');
    print shorten_scalar($m, 20); # => "AfooBfooCfooDfooE..."
    print shorten_scalar($m, 10); # => "AfooBfo..."

If $SCALAR looks like a number, then this method will use scientific notation and reduce the precision of the number to fit it into the alloted space.

    $m = "123456789" x 9;
    print shorten_scalar($m, 20); # => "12345678912345679e64"
    print shorten_scalar($m, 10); # => "1234568e74"

The output of this function is not guaranteed to make sense when $MAXLEN is small, say, less than 10.

shorten_array($ARRAYREF, $MAXLEN [,$SEPARATOR=1 [,@KEY=()]])

Returns a list that is representative of the list in $ARRAYREF and which will be no longer than $MAXLEN characters when it is displayed.

  $m = [ 'aa' .. 'zz' ];
  print join',', shorten_array($m,20);    # "aa,ab,ac,ad,ae,..."

The default assumption is that displayed array elements will be separated with a comma or other single-character delimiter. Specify $SEPARATOR as either a delimiting-string or as a number representing the length of the delimiter to override this.

  $m = [ 'aa' .. 'zz' ];
  $s = ", ";
  print join $s, shorten_array($m,20,2);  # "aa, ab, ac, ad, ..."
  print join $s, shorten_array($m,20,$s); # "aa, ab, ac, ad, ..."

@KEY is a (possibly empty) set of array indices for array elements that must be returned in the output. All of the array indices in @KEY will be included in the output, even if that makes the output length exceed $MAXLEN,

  $m = [ 'aa' .. 'zz' ];
  $s = ',';
  print join $s, shorten_array($m,20,1,77);     # "aa,ab,ac,...,cz,..."
  print join $s, shorten_array($m,20,1,76..78); # "aa,...,cy,cz,da,..."

The output of this function is not guaranteed to make sense when $MAXLEN is small (say, less than 15).

shorten_hash($HASHREF, $MAXLEN [, $SEP1=1, $SEP2=2 [, @KEY=() ]])

Returns a list suitable for displaying representative elements of the hashtable in $HASHREF such that the displayed length will be no longer than $MAXLEN characters.

The return value is a list of list references. Each element of the return value contains a key-value pair to be displayed, except for the last element of the list, which may either contain a key-value pair, or a list reference containing the single token .... This token indicates that some key-value pairs are not to be displayed. Here is an example of how one print the output of shorten_hash, using ":" as a key-value pair separator, and "; " to separate different elements of the hash.

  $m = { foo => 'bar', 123 => 456 };
  @m = shorten_hash($m,20);

  # to display shortened results, do something like this
  print "{", join("; ", map { join ":", @$_ } @m), "}";
  # the above line prints "{abc:def; 123:456}"

It is assumed that each key-value pair in the output will be separated by a single-character delimiter, and that the hash keys will be separated from their associated hash values by a two-character delimiter. Specify a delimiter or delimiter length to $SEP1 and $SEP2 to override these assumptions.

@KEY is a (possibly empty) set of hash keys that must be returned in the output. The key-value pair for any valid key that is specified in @KEY will be included in the output, even if that would make the output length exceed $MAXLEN.

The output of this function is not guaranteed to make sense when $MAXLEN is small (say, less than 20).

EXPORT

Nothing by default. The three functions shorten_scalar, shorten_array, and shorten_hash may be exported individually, or they may be exported as a group with the tag :all.

AUTHOR

Marty O'Brien, <mob at cpan.org>

BUGS

Please report any bugs or feature requests to bug-text-shorten at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-Shorten. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::Shorten

You can also look for information at:

ACKNOWLEDGEMENTS

Dumpvalue / dumpvars.pl.

LICENSE AND COPYRIGHT

Copyright 2010-2013 Marty O'Brien.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.