GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRING::TRUNCATE (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

version 1.100602

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 valid 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 returns 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) 2014 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 STRING::TRUNCATE (3) 2014-03-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.