Marty O'Brien > Text-Shorten > Text::Shorten

Download:
Text-Shorten-0.06.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.06   Source  

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.

syntax highlighting: