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.100603
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

PERL VERSION

35       This library should run on perls released even a long time ago.  It
36       should work on any version of perl released in the last five years.
37
38       Although it may work on older versions of perl, no guarantee is made
39       that the minimum required version will not be increased.  The version
40       may be increased for any reason, and there is no promise that patches
41       will be accepted to lower the minimum required perl.
42

FUNCTIONS

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

IMPORTING

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

BUILDING CODEREFS

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

SEE ALSO

103       Text::Truncate does a very similar thing.  So does Text::Elide.
104

BUGS

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

ACKNOWLEDGEMENTS

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

AUTHOR

118       Ricardo Signes <cpan@semiotic.systems>
119

CONTRIBUTORS

121       •   David Steinbrunner <dsteinbrunner@pobox.com>
122
123       •   Ricardo SIGNES <rjbs@codesimply.com>
124
125       •   Ricardo Signes <rjbs@semiotic.systems>
126

128       This software is copyright (c) 2022 by Ricardo Signes.
129
130       This is free software; you can redistribute it and/or modify it under
131       the same terms as the Perl 5 programming language system itself.
132
133
134
135perl v5.38.0                      2023-07-21               String::Truncate(3)
Impressum