.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "String::Truncate 3pm" .TH String::Truncate 3pm "2023-01-05" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" String::Truncate \- a module for when strings are too long to be displayed in... .SH "VERSION" .IX Header "VERSION" version 1.100603 .SH "SYNOPSIS" .IX Header "SYNOPSIS" This module handles the simple but common problem of long strings and finite terminal width. It can convert: .PP .Vb 4 \& "this is your brain" \-> "this is your ..." \& or "...is your brain" \& or "this is... brain" \& or "... is your b..." .Ve .PP It's simple: .PP .Vb 1 \& use String::Truncate qw(elide); \& \& my $brain = "this is your brain"; \& \& elide($brain, 16); # first option \& elide($brain, 16, { truncate => \*(Aqleft\*(Aq }); # second option \& elide($brain, 16, { truncate => \*(Aqmiddle\*(Aq }); # third option \& elide($brain, 16, { truncate => \*(Aqends\*(Aq }); # fourth option \& \& String::Trunc::trunc($brain, 16); # => "this is your bra" .Ve .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "elide" .IX Subsection "elide" .Vb 1 \& elide($string, $length, \e%arg) .Ve .PP This function returns the string, if it is less than or equal to \f(CW$length\fR characters long. If it is longer, it truncates the string and marks the elision. .PP Valid arguments are: .PP .Vb 3 \& 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 .Ve .SS "trunc" .IX Subsection "trunc" .Vb 1 \& trunc($string, $length, \e%arg) .Ve .PP This acts just like \f(CW\*(C`elide\*(C'\fR, but assumes an empty marker, so it actually truncates the string normally. .SH "IMPORTING" .IX Header "IMPORTING" String::Truncate exports both \f(CW\*(C`elide\*(C'\fR and \f(CW\*(C`trunc\*(C'\fR, and also supports the Exporter-style \*(L":all\*(R" tag. .PP .Vb 4 \& 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() .Ve .PP When exporting, you may also supply default values: .PP .Vb 1 \& use String::Truncate \-all => defaults => { length => 10, marker => \*(Aq\-\-\*(Aq }; \& \& # or \& \& use String::Truncate \-all => { length => 10, marker => \*(Aq\-\-\*(Aq }; .Ve .PP 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. .SH "BUILDING CODEREFS" .IX Header "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 \f(CW\*(C`elide_with_defaults\*(C'\fR and \f(CW\*(C`trunc_with_defaults\*(C'\fR routines. .SS "elide_with_defaults" .IX Subsection "elide_with_defaults" .Vb 1 \& my $elider = String::Truncate::elide_with_defaults(\e%arg); .Ve .PP This routine, never exported, builds a coderef which behaves like \f(CW\*(C`elide\*(C'\fR, but uses default values when needed. All the valid arguments to \f(CW\*(C`elide\*(C'\fR are valid here, as well as \f(CW\*(C`length\*(C'\fR. .SS "trunc_with_defaults" .IX Subsection "trunc_with_defaults" This routine behaves exactly like elide_with_defaults, with one obvious exception: it returns code that works like \f(CW\*(C`trunc\*(C'\fR rather than \f(CW\*(C`elide\*(C'\fR. If a \&\f(CW\*(C`marker\*(C'\fR argument is passed, it is ignored. .SH "SEE ALSO" .IX Header "SEE ALSO" Text::Truncate does a very similar thing. So does Text::Elide. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "ACKNOWLEDGEMENTS" .IX Header "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 .SH "AUTHOR" .IX Header "AUTHOR" Ricardo Signes .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Ricardo \s-1SIGNES\s0 .IP "\(bu" 4 Ricardo Signes .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2022 by Ricardo Signes. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.