NAME¶
String::Truncate - a module for when strings are too long to be displayed in...
VERSION¶
version 1.100600
SYNOPSIS¶
This module handles the simple but common problem of long strings and finite
terminal width. It can convert:
"this is your brain" -> "this is your ..."
or "...is your brain"
or "this is... brain"
or "... is your b..."
It's simple:
use String::Truncate qw(elide);
my $brain = "this is your brain";
elide($brain, 16); # first option
elide($brain, 16, { truncate => 'left' }); # second option
elide($brain, 16, { truncate => 'middle' }); # third option
elide($brain, 16, { truncate => 'ends' }); # fourth option
String::Trunc::trunc($brain, 16); # => "this is your bra"
FUNCTIONS¶
elide¶
elide($string, $length, \%arg)
This function returns the string, if it is less than or equal to $length
characters long. If it is longer, it truncates the string and marks the
elision.
Valid arguments are:
truncate - elide at left, right, middle, or ends? (default: right)
marker - how to mark the elision (default: ...)
at_space - if true, strings will be broken at whitespace if possible
trunc¶
trunc($string, $length, \%arg)
This acts just like "elide", but assumes an empty marker, so it
actually truncates the string normally.
IMPORTING¶
String::Truncate exports both "elide" and "trunc", and also
supports the Exporter-style ":all" tag.
use String::Truncate (); # export nothing
use String::Truncate qw(elide); # export just elide()
use String::Truncate qw(:all); # export both elide() and trunc()
use String::Truncate qw(-all); # export both elide() and trunc()
When exporting, you may also supply default values:
use String::Truncate -all => defaults => { length => 10, marker => '--' };
# or
use String::Truncate -all => { length => 10, marker => '--' };
These values affect only the imported version of the functions. You may pass
arguments as usual to override them, and you may call the subroutine by its
fully-qualified name to get the standard behavior.
BUILDING CODEREFS¶
The imported builds and installs lexical closures (code references) that merge
in given values to the defaults. You can build your own closures without
importing them into your namespace. To do this, use the
"elide_with_defaults" and "trunc_with_defaults" routines.
elide_with_defaults¶
my $elider = String::Truncate::elide_with_defaults(\%arg);
This routine, never exported, builds a coderef which behaves like
"elide", but uses default values when needed. All the valud
arguments to "elide" are valid here, as well as "length".
trunc_with_defaults¶
This routine behaves exactly like elide_with_defaults, with one obvious
exception: it retuns code that works like "trunc" rather than
"elide". If a "marker" argument is passed, it is ignored.
SEE ALSO¶
Text::Truncate does a very similar thing. So does Text::Elide.
BUGS¶
Please report any bugs or feature requests through the web interface at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Truncate>. I will
be notified, and then you'll automatically be notified of progress on your bug
as I make changes.
ACKNOWLEDGEMENTS¶
Ian Langworth gave me some good advice about naming things. (Also some bad
jokes. Nobody wants String::ETOOLONG, Ian.) Hans Dieter Pearcey suggested
allowing defaults just in time for a long bus ride, and I was rescued from
boredom by that suggestion
AUTHOR¶
Ricardo Signes <rjbs@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2011 by Ricardo Signes.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.