1String::Truncate(3)   User Contributed Perl Documentation  String::Truncate(3)
2
3
4

NAME

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

VERSION

10       version 1.100602
11

SYNOPSIS

13       This module handles the simple but common problem of long strings and
14       finite terminal width.  It can convert:
15
16        "this is your brain" -> "this is your ..."
17                             or "...is your brain"
18                             or "this is... brain"
19                             or "... is your b..."
20
21       It's simple:
22
23        use String::Truncate qw(elide);
24
25        my $brain = "this is your brain";
26
27        elide($brain, 16); # first option
28        elide($brain, 16, { truncate => 'left' });   # second option
29        elide($brain, 16, { truncate => 'middle' }); # third option
30        elide($brain, 16, { truncate => 'ends' });   # fourth option
31
32        String::Trunc::trunc($brain, 16); # => "this is your bra"
33

FUNCTIONS

35   elide
36         elide($string, $length, \%arg)
37
38       This function returns the string, if it is less than or equal to
39       $length characters long.  If it is longer, it truncates the string and
40       marks the elision.
41
42       Valid arguments are:
43
44        truncate - elide at left, right, middle, or ends? (default: right)
45        marker   - how to mark the elision (default: ...)
46        at_space - if true, strings will be broken at whitespace if possible
47
48   trunc
49         trunc($string, $length, \%arg)
50
51       This acts just like "elide", but assumes an empty marker, so it
52       actually truncates the string normally.
53

IMPORTING

55       String::Truncate exports both "elide" and "trunc", and also supports
56       the Exporter-style ":all" tag.
57
58         use String::Truncate ();        # export nothing
59         use String::Truncate qw(elide); # export just elide()
60         use String::Truncate qw(:all);  # export both elide() and trunc()
61         use String::Truncate qw(-all);  # export both elide() and trunc()
62
63       When exporting, you may also supply default values:
64
65         use String::Truncate -all => defaults => { length => 10, marker => '--' };
66
67         # or
68
69         use String::Truncate -all => { length => 10, marker => '--' };
70
71       These values affect only the imported version of the functions.  You
72       may pass arguments as usual to override them, and you may call the
73       subroutine by its fully-qualified name to get the standard behavior.
74

BUILDING CODEREFS

76       The imported builds and installs lexical closures (code references)
77       that merge in given values to the defaults.  You can build your own
78       closures without importing them into your namespace.  To do this, use
79       the "elide_with_defaults" and "trunc_with_defaults" routines.
80
81   elide_with_defaults
82         my $elider = String::Truncate::elide_with_defaults(\%arg);
83
84       This routine, never exported, builds a coderef which behaves like
85       "elide", but uses default values when needed.  All the valid arguments
86       to "elide" are valid here, as well as "length".
87
88   trunc_with_defaults
89       This routine behaves exactly like elide_with_defaults, with one obvious
90       exception: it returns code that works like "trunc" rather than "elide".
91       If a "marker" argument is passed, it is ignored.
92

SEE ALSO

94       Text::Truncate does a very similar thing.  So does Text::Elide.
95

BUGS

97       Please report any bugs or feature requests through the web interface at
98       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Truncate>.  I
99       will be notified, and then you'll automatically be notified of progress
100       on your bug as I make changes.
101

ACKNOWLEDGEMENTS

103       Ian Langworth gave me some good advice about naming things.  (Also some
104       bad jokes.  Nobody wants String::ETOOLONG, Ian.)  Hans Dieter Pearcey
105       suggested allowing defaults just in time for a long bus ride, and I was
106       rescued from boredom by that suggestion
107

AUTHOR

109       Ricardo Signes <rjbs@cpan.org>
110

112       This software is copyright (c) 2014 by Ricardo Signes.
113
114       This is free software; you can redistribute it and/or modify it under
115       the same terms as the Perl 5 programming language system itself.
116
117
118
119perl v5.30.1                      2020-01-30               String::Truncate(3)
Impressum