NAME

       String::Truncate - a module for when strings are too long to be displayed in...

VERSION

       version 1.100601

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) 2013 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.