.\" 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 "Escape 3pm"
.TH Escape 3pm "2022-12-12" "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::Escape \- Backslash escapes, quoted phrase, word elision, etc.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This module provides a flexible calling interface to some frequently-performed string conversion functions, including applying and removing backslash escapes like \en and \et, wrapping and removing double-quotes, and truncating to fit within a desired length.
.PP
.Vb 5
\&  use String::Escape qw( printable unprintable );
\&  # Convert control, high\-bit chars to \en or \exxx escapes
\&  $output = printable($value);
\&  # Convert escape sequences back to original chars
\&  $value = unprintable($input);
\&
\&  use String::Escape qw( elide );
\&  # Shorten strings to fit, if necessary
\&  foreach (@_) { print elide( $_, 79 ) . "\en"; }
\&
\&  use String::Escape qw( string2list list2string );
\&  # Pack and unpack simple lists by quoting each item
\&  $list = list2string( @list );
\&  @list = string2list( $list );
\&
\&  use String::Escape qw( escape );
\&  # Defer selection of escaping routines until runtime
\&  $escape_name = $use_quotes ? \*(Aqqprintable\*(Aq : \*(Aqprintable\*(Aq;
\&  @escaped = escape($escape_name, @values);
.Ve
.SH "INTERFACE"
.IX Header "INTERFACE"
All of the public functions described below are available as optional exports.
.PP
You can either import the specific functions you want, or import only the \f(CW\*(C`escape()\*(C'\fR function and pass it the names of the functions to invoke.
.SS "Quoting"
.IX Subsection "Quoting"
Each of these functions takes a single simple scalar argument and
returns its escaped (or unescaped) equivalent.
.ie n .IP "quote($value) : $escaped" 4
.el .IP "quote($value) : \f(CW$escaped\fR" 4
.IX Item "quote($value) : $escaped"
Add double quote characters to each end of the string.
.ie n .IP "unquote($value) : $escaped" 4
.el .IP "unquote($value) : \f(CW$escaped\fR" 4
.IX Item "unquote($value) : $escaped"
If the string both begins and ends with double quote characters, they are removed, otherwise the string is returned unchanged.
.ie n .IP "quote_non_words($value) : $escaped" 4
.el .IP "quote_non_words($value) : \f(CW$escaped\fR" 4
.IX Item "quote_non_words($value) : $escaped"
As above, but only quotes empty, punctuated, and multiword values; simple values consisting of alphanumerics without special characters are not quoted.
.ie n .IP "singlequote($value) : $escaped" 4
.el .IP "singlequote($value) : \f(CW$escaped\fR" 4
.IX Item "singlequote($value) : $escaped"
Add single quote characters to each end of the string.
.ie n .IP "unsinglequote($value) : $escaped" 4
.el .IP "unsinglequote($value) : \f(CW$escaped\fR" 4
.IX Item "unsinglequote($value) : $escaped"
If the string both begins and ends with single quote characters, they are removed, otherwise the string is returned unchanged.
.SS "Backslash Escaping Functions"
.IX Subsection "Backslash Escaping Functions"
Each of these functions takes a single simple scalar argument and
returns its escaped (or unescaped) equivalent.
.PP
These functions recognize common whitespace sequences \f(CW\*(C`\er\*(C'\fR, \f(CW\*(C`\en\*(C'\fR, and \f(CW\*(C`\et\*(C'\fR, as well as hex escapes \f(CW\*(C`\ex4F\*(C'\fR and ocatal \f(CW\*(C`\e020\*(C'\fR.
.PP
When escaping, alphanumeric characters and most punctuation is passed through unchanged; only the return, newline, tab, backslash, dollar, at sign and unprintable control and high-bit characters are escaped.
.ie n .IP "backslash($value) : $escaped" 4
.el .IP "backslash($value) : \f(CW$escaped\fR" 4
.IX Item "backslash($value) : $escaped"
Converts special characters to their backslash-escaped equivalents.
.ie n .IP "unbackslash($value) : $escaped" 4
.el .IP "unbackslash($value) : \f(CW$escaped\fR" 4
.IX Item "unbackslash($value) : $escaped"
Converts backslash escape sequences in a string back to their original characters.
.ie n .IP "qqbackslash($value) : $escaped" 4
.el .IP "qqbackslash($value) : \f(CW$escaped\fR" 4
.IX Item "qqbackslash($value) : $escaped"
Converts special characters to their backslash-escaped equivalents and then wraps the results with double quotes.
.ie n .IP "unqqbackslash($value) : $escaped" 4
.el .IP "unqqbackslash($value) : \f(CW$escaped\fR" 4
.IX Item "unqqbackslash($value) : $escaped"
Strips surrounding double quotes then converts backslash escape sequences back to their original characters.
.PP
Here are a few examples:
.IP "\(bu" 4

.Sp
.Vb 1
\&  print backslash( "\etNow is the time\enfor all good folks\en" );
\&
\&  \etNow is the time\enfor all good folks\en
.Ve
.IP "\(bu" 4

.Sp
.Vb 1
\&  print unbackslash( \*(Aq\e\etNow is the time\e\enfor all good folks\e\en\*(Aq );
\&
\&        Now is the time
\&  for all good folks
.Ve
.SS "Legacy Backslash Functions"
.IX Subsection "Legacy Backslash Functions"
In addition to the four functions listed above, there is a corresponding set which use a slightly different set of escape sequences.
.PP
These functions do not support as many escape sequences and use a non-standard
format for hex escapes. In general, the above \f(CW\*(C`backslash()\*(C'\fR functions are
recommended, while these functions are retained for legacy compatibility
purposes.
.ie n .IP "printable($value) : $escaped" 4
.el .IP "printable($value) : \f(CW$escaped\fR" 4
.IX Item "printable($value) : $escaped"
Converts return, newline, tab, backslash and unprintable
characters to their backslash-escaped equivalents.
.ie n .IP "unprintable($value) : $escaped" 4
.el .IP "unprintable($value) : \f(CW$escaped\fR" 4
.IX Item "unprintable($value) : $escaped"
Converts backslash escape sequences in a string back to their original value.
.ie n .IP "qprintable($value) : $escaped" 4
.el .IP "qprintable($value) : \f(CW$escaped\fR" 4
.IX Item "qprintable($value) : $escaped"
Converts special characters to their backslash-escaped equivalents and then wraps the results with double quotes.
.Sp
(Note that this is \fInot\fR \s-1MIME\s0 quoted-printable encoding.)
.ie n .IP "unqprintable($value) : $escaped" 4
.el .IP "unqprintable($value) : \f(CW$escaped\fR" 4
.IX Item "unqprintable($value) : $escaped"
Strips surrounding double quotes then converts backslash escape sequences back to their original value.
.SS "Other Backslash Functions"
.IX Subsection "Other Backslash Functions"
In addition to the functions listed above, there is also one function that mirrors the behavior of Perl's built-in \f(CW\*(C`quotemeta()\*(C'\fR function.
.ie n .IP "unquotemeta($value) : $escaped" 4
.el .IP "unquotemeta($value) : \f(CW$escaped\fR" 4
.IX Item "unquotemeta($value) : $escaped"
Strips out backslashes before any character.
.SS "Elision Function"
.IX Subsection "Elision Function"
This function extracts the leading portion of a provided string and appends ellipsis if it's longer than the desired maximum excerpt length.
.ie n .IP "elide($string) : $elided_string" 4
.el .IP "elide($string) : \f(CW$elided_string\fR" 4
.IX Item "elide($string) : $elided_string"
.PD 0
.ie n .IP "elide($string, $length) : $elided_string" 4
.el .IP "elide($string, \f(CW$length\fR) : \f(CW$elided_string\fR" 4
.IX Item "elide($string, $length) : $elided_string"
.ie n .IP "elide($string, $length, $word_boundary_strictness) : $elided_string" 4
.el .IP "elide($string, \f(CW$length\fR, \f(CW$word_boundary_strictness\fR) : \f(CW$elided_string\fR" 4
.IX Item "elide($string, $length, $word_boundary_strictness) : $elided_string"
.ie n .IP "elide($string, $length, $word_boundary_strictness, $elipses) : $elided_string" 4
.el .IP "elide($string, \f(CW$length\fR, \f(CW$word_boundary_strictness\fR, \f(CW$elipses\fR) : \f(CW$elided_string\fR" 4
.IX Item "elide($string, $length, $word_boundary_strictness, $elipses) : $elided_string"
.PD
Return a single-quoted, shortened version of the string, with ellipsis.
.Sp
If the original string is shorter than \f(CW$length\fR, it is returned unchanged. At most \f(CW$length\fR characters are returned; if called with a single argument, \f(CW$length\fR defaults to \f(CW$DefaultLength\fR.
.Sp
Up to \f(CW$word_boundary_strictness\fR additional characters may be ommited in order to make the elided portion end on a word boundary; you can pass 0 to ignore word boundaries. If not provided, \f(CW$word_boundary_strictness\fR defaults to \f(CW$DefaultStrictness\fR.
.ie n .IP "$Elipses" 4
.el .IP "\f(CW$Elipses\fR" 4
.IX Item "$Elipses"
The string of characters used to indicate the end of the excerpt. Initialized to '...'.
.ie n .IP "$DefaultLength" 4
.el .IP "\f(CW$DefaultLength\fR" 4
.IX Item "$DefaultLength"
The default target excerpt length, used when the elide function is called with a single argument. Initialized to 60.
.ie n .IP "$DefaultStrictness" 4
.el .IP "\f(CW$DefaultStrictness\fR" 4
.IX Item "$DefaultStrictness"
The default word-boundary flexibility, used when the elide function is called without the third argument. Initialized to 10.
.PP
Here are a few examples:
.IP "\(bu" 4

.Sp
.Vb 1
\&  $string = \*(Aqfoo bar baz this that the other\*(Aq;
\&
\&  print elide( $string, 12 );
\&  # foo bar...
\&
\&  print elide( $string, 12, 0 );
\&  # foo bar b...
\&
\&  print elide( $string, 100 );
\&  # foo bar baz this that the other
.Ve
.SS "\fBescape()\fP"
.IX Subsection "escape()"
These functions provide for the registration of string-escape specification
names and corresponding functions, and then allow the invocation of one or
several of these functions on one or several source string values.
.ie n .IP "escape($escapes, $value) : $escaped_value" 4
.el .IP "escape($escapes, \f(CW$value\fR) : \f(CW$escaped_value\fR" 4
.IX Item "escape($escapes, $value) : $escaped_value"
.PD 0
.ie n .IP "escape($escapes, @values) : @escaped_values" 4
.el .IP "escape($escapes, \f(CW@values\fR) : \f(CW@escaped_values\fR" 4
.IX Item "escape($escapes, @values) : @escaped_values"
.PD
Returns an altered copy of the provided values by looking up the escapes string in a registry of string-modification functions.
.Sp
If called in a scalar context, operates on the single value passed in; if
called in a list contact, operates identically on each of the provided values.
.Sp
Space-separated compound specifications like 'quoted uppercase' are expanded to a list of functions to be applied in order.
.Sp
Valid escape specifications are:
.RS 4
.ie n .IP "one of the keys defined in %Escapes" 4
.el .IP "one of the keys defined in \f(CW%Escapes\fR" 4
.IX Item "one of the keys defined in %Escapes"
The coresponding specification will be looked up and used.
.IP "a sequence of names separated by whitespace," 4
.IX Item "a sequence of names separated by whitespace,"
Each name will be looked up, and each of the associated functions will be applied successively, from left to right.
.IP "a reference to a function" 4
.IX Item "a reference to a function"
The provided function will be called on with each value in turn.
.IP "a reference to an array" 4
.IX Item "a reference to an array"
Each item in the array will be expanded as provided above.
.RE
.RS 4
.Sp
A fatal error will be generated if you pass an unsupported escape specification, or if the function is called with multiple values in a scalar context.
.RE
.ie n .IP "\fBString::Escape::names()\fR : @defined_escapes" 4
.el .IP "\fBString::Escape::names()\fR : \f(CW@defined_escapes\fR" 4
.IX Item "String::Escape::names() : @defined_escapes"
Returns a list of defined escape specification strings.
.ie n .IP "String::Escape::add( $escape_name, \e&escape_function );" 4
.el .IP "String::Escape::add( \f(CW$escape_name\fR, \e&escape_function );" 4
.IX Item "String::Escape::add( $escape_name, &escape_function );"
Add a new escape specification and corresponding function.
.PP
By default, all of the public functions described below are available as named escape commands, as well as the following built-in functions:
.IP "\(bu" 4
none: Return the string unchanged.
.IP "\(bu" 4
uppercase: Calls the built-in uc function.
.IP "\(bu" 4
lowercase: Calls the built-in lc function.
.IP "\(bu" 4
initialcase: Calls the built-in lc and ucfirst functions.
.PP
Here are a few examples:
.IP "\(bu" 4
\&\f(CW\*(C`print escape(\*(Aqqprintable\*(Aq, "\etNow is the time\enfor all good folks\en" );\*(C'\fR
.Sp
.Vb 1
\&  "\etNow is the time\enfor all good folks\en"
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`print escape(\*(Aquppercase qprintable\*(Aq, "\etNow is the time\enfor all good folks\en" );\*(C'\fR
.Sp
.Vb 1
\&  "\etNOW IS THE TIME\enFOR ALL GOOD FOLKS\en"
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`print join \*(Aq\-\-\*(Aq, escape(\*(Aqprintable\*(Aq, "\etNow is the time\en", "for all good folks\en" );\*(C'\fR
.Sp
.Vb 1
\&  \etNow is the time\en\-\-for all good folks\en
.Ve
.IP "\(bu" 4
You can add more escaping functions to the supported set by calling \fBadd()\fR.
.Sp
\&\f(CW\*(C`String::Escape::add( \*(Aqhtml\*(Aq, \e&HTML::Entities::encode_entities );\*(C'\fR
.Sp
\&\f(CW\*(C`print escape(\*(Aqhtml\*(Aq, "AT&T" );\*(C'\fR
.Sp
.Vb 1
\&  AT&amp;T
.Ve
.SS "Space-separated Lists and Hashes"
.IX Subsection "Space-separated Lists and Hashes"
.ie n .IP "@words = string2list( $space_separated_phrases );" 4
.el .IP "\f(CW@words\fR = string2list( \f(CW$space_separated_phrases\fR );" 4
.IX Item "@words = string2list( $space_separated_phrases );"
Converts a space separated string of words and quoted phrases to an array;
.ie n .IP "$space_sparated_string = list2string( @words );" 4
.el .IP "\f(CW$space_sparated_string\fR = list2string( \f(CW@words\fR );" 4
.IX Item "$space_sparated_string = list2string( @words );"
Joins an array of strings into a space separated string of words and quoted phrases;
.ie n .IP "%hash = string2hash( $string );" 4
.el .IP "\f(CW%hash\fR = string2hash( \f(CW$string\fR );" 4
.IX Item "%hash = string2hash( $string );"
Converts a space separated string of equal-sign-associated key=value pairs into a simple hash.
.ie n .IP "$string = hash2string( %hash );" 4
.el .IP "\f(CW$string\fR = hash2string( \f(CW%hash\fR );" 4
.IX Item "$string = hash2string( %hash );"
Converts a simple hash into a space separated string of equal-sign-associated key=value pairs.
.ie n .IP "%hash = list2hash( @words );" 4
.el .IP "\f(CW%hash\fR = list2hash( \f(CW@words\fR );" 4
.IX Item "%hash = list2hash( @words );"
Converts an array of equal-sign-associated key=value strings into a simple hash.
.ie n .IP "@words = hash2list( %hash );" 4
.el .IP "\f(CW@words\fR = hash2list( \f(CW%hash\fR );" 4
.IX Item "@words = hash2list( %hash );"
Converts a hash to an array of equal-sign-associated key=value strings.
.PP
Here are a few examples:
.IP "\(bu" 4
\&\f(CW\*(C`print list2string(\*(Aqhello\*(Aq, \*(AqI move next march\*(Aq);\*(C'\fR
.Sp
.Vb 1
\&  hello "I move next march"
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`@list = string2list(\*(Aqone "second item" 3 "four\enlines\enof\entext"\*(Aq);\*(C'\fR
.Sp
\&\f(CW\*(C`print $list[1];\*(C'\fR
.Sp
.Vb 1
\&  second item
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`print hash2string( \*(Aqfoo\*(Aq => \*(AqAnimal Cities\*(Aq, \*(Aqbar\*(Aq => \*(AqCheap\*(Aq );\*(C'\fR
.Sp
.Vb 1
\&  foo="Animal Cities" bar=Cheap
.Ve
.IP "\(bu" 4
\&\f(CW\*(C`%hash = string2hash(\*(Aqkey=value "undefined key" words="the cat in the hat"\*(Aq);\*(C'\fR
.Sp
\&\f(CW\*(C`print $hash{\*(Aqwords\*(Aq};\*(C'\fR
.Sp
.Vb 1
\&  the cat in the hat
.Ve
.Sp
\&\f(CW\*(C`print exists $hash{\*(Aqundefined_key\*(Aq} and ! defined $hash{\*(Aqundefined_key\*(Aq};\*(C'\fR
.Sp
.Vb 1
\&  1
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Numerous modules provide collections of string escaping functions for specific contexts.
.PP
The string2list function is similar to to the quotewords function in the standard distribution; see Text::ParseWords.
.PP
Use other packages to stringify more complex data structures; see Storable, Data::Dumper, or other similar package.
.SH "BUGS"
.IX Header "BUGS"
The following issues or changes are under consideration for future releases:
.IP "\(bu" 4
Does this problem with the \er character only show up on Windows? (And is it, in fact, a feature rather than a bug?)
.Sp
.Vb 1
\&  http://rt.cpan.org/Public/Bug/Display.html?id=19766
.Ve
.IP "\(bu" 4
Consider changes to word parsing in string2list: Perhaps use \eb word-boundary test in elide's regular expression rather than \es|\eZ? Perhaps quotes embedded in a word (eg: a@"!a) shouldn't cause phrase breaks?
.IP "\(bu" 4
Check for possible problems in the use of printable escaping functions and list2hash. For example, are the encoded strings for hashes with high-bit characters in their keys properly unquoted and unescaped?
.IP "\(bu" 4
We should allow escape specifications to contain = signs and optional arguments, so that users can request certain string lengths with \f(CW\*(C`escape("lowercase elide=20 quoted", @_\*(C'\fR.
.SH "VERSION"
.IX Header "VERSION"
This is version 2010.002.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
This package should run on any standard Perl 5 installation.
.PP
To install this package, download the distribution from a \s-1CPAN\s0 mirror,
unpack the archive file, and execute the standard \*(L"perl Makefile.PL\*(R",
\&\*(L"make test\*(R", \*(L"make install\*(R" sequence or your local equivalent.
.SH "SUPPORT"
.IX Header "SUPPORT"
Once installed, this module's documentation is available as a
manual page via \f(CW\*(C`perldoc String::Escape\*(C'\fR or on \s-1CPAN\s0 sites
such as \f(CW\*(C`http://search.cpan.org/dist/String\-Escape\*(C'\fR.
.PP
If you have questions or feedback about this module, please feel free to
contact the author at the address shown below. Although there is no formal
support program, I do attempt to answer email promptly.  Bug reports that
contain a failing test case are greatly appreciated, and suggested patches
will be promptly considered for inclusion in future releases.
.PP
You can report bugs and request features via the \s-1CPAN\s0 web tracking system
at \f(CW\*(C`http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String\-Escape\*(C'\fR or by 
sending mail to \f(CW\*(C`bug\-string\-escape at rt.cpan.org\*(C'\fR.
.PP
If you've found this module useful or have feedback about your
experience with it, consider sharing your opinion with other Perl users
by posting your comment to \s-1CPAN\s0's ratings system
(\f(CW\*(C`http://cpanratings.perl.org/rate/?distribution=String\-Escape\*(C'\fR).
.PP
For more general discussion, you may wish to post a message on PerlMonks
(\f(CW\*(C`http://perlmonks.org/?node=Seekers%20of%20Perl%20Wisdom\*(C'\fR) or on the
comp.lang.perl.misc newsgroup
(\f(CW\*(C`http://groups.google.com/group/comp.lang.perl.misc/topics\*(C'\fR).
.SH "AUTHOR"
.IX Header "AUTHOR"
Matthew Simon Cavalletto, \f(CW\*(C`<simonm at cavalletto.org>\*(C'\fR
.PP
Initial versions developed at Evolution Online Systems with Eleanor J. Evans and Jeremy G. Bishop.
.SH "LICENSE"
.IX Header "LICENSE"
Copyright 2010, 2002 Matthew Simon Cavalletto.
.PP
Portions copyright 1996, 1997, 1998, 2001 Evolution Online Systems, Inc.
.PP
You may use, modify, and distribute this software under the same terms as Perl.
.PP
See http://dev.perl.org/licenses/ for more information.