1Escape(3) User Contributed Perl Documentation Escape(3)
2
6 String::Escape - Backslash escapes, quoted phrase, word elision, etc.
7
9 This module provides a flexible calling interface to some frequently-
10 performed string conversion functions, including applying and removing
11 backslash escapes like \n and \t, wrapping and removing double-quotes,
12 and truncating to fit within a desired length.
13 use String::Escape qw( printable unprintable );
15 # Convert control, high-bit chars to \n or \xxx escapes
16 $output = printable($value);
17 # Convert escape sequences back to original chars
18 $value = unprintable($input);
19 use String::Escape qw( elide );
21 # Shorten strings to fit, if necessary
22 foreach (@_) { print elide( $_, 79 ) . "\n"; }
23 use String::Escape qw( string2list list2string );
25 # Pack and unpack simple lists by quoting each item
26 $list = list2string( @list );
27 @list = string2list( $list );
28 use String::Escape qw( escape );
30 # Defer selection of escaping routines until runtime
31 $escape_name = $use_quotes ? 'qprintable' : 'printable';
32 @escaped = escape($escape_name, @values);
33
35 All of the public functions described below are available as optional
36 exports.
37 You can either import the specific functions you want, or import only
39 the escape() function and pass it the names of the functions to invoke.
40 Quoting
42 Each of these functions takes a single simple scalar argument and
43 returns its escaped (or unescaped) equivalent.
44 quote($value) : $escaped
46 Add double quote characters to each end of the string.
47 unquote($value) : $escaped
49 If the string both begins and ends with double quote characters,
50 they are removed, otherwise the string is returned unchanged.
51 quote_non_words($value) : $escaped
53 As above, but only quotes empty, punctuated, and multiword values;
54 simple values consisting of alphanumerics without special
55 characters are not quoted.
56 singlequote($value) : $escaped
58 Add single quote characters to each end of the string.
59 unsinglequote($value) : $escaped
61 If the string both begins and ends with single quote characters,
62 they are removed, otherwise the string is returned unchanged.
63 Backslash Escaping Functions
65 Each of these functions takes a single simple scalar argument and
66 returns its escaped (or unescaped) equivalent.
67 These functions recognize common whitespace sequences "\r", "\n", and
69 "\t", as well as hex escapes "\x4F" and ocatal "\020".
70 When escaping, alphanumeric characters and most punctuation is passed
72 through unchanged; only the return, newline, tab, backslash, dollar, at
73 sign and unprintable control and high-bit characters are escaped.
74 backslash($value) : $escaped
76 Converts special characters to their backslash-escaped equivalents.
77 unbackslash($value) : $escaped
79 Converts backslash escape sequences in a string back to their
80 original characters.
81 qqbackslash($value) : $escaped
83 Converts special characters to their backslash-escaped equivalents
84 and then wraps the results with double quotes.
85 unqqbackslash($value) : $escaped
87 Strips surrounding double quotes then converts backslash escape
88 sequences back to their original characters.
89 Here are a few examples:
91 •
93 print backslash( "\tNow is the time\nfor all good folks\n" );
96 \tNow is the time\nfor all good folks\n
98 •
100 print unbackslash( '\\tNow is the time\\nfor all good folks\\n' );
103 Now is the time
105 for all good folks
106 Legacy Backslash Functions
108 In addition to the four functions listed above, there is a
109 corresponding set which use a slightly different set of escape
110 sequences.
111 These functions do not support as many escape sequences and use a non-
113 standard format for hex escapes. In general, the above backslash()
114 functions are recommended, while these functions are retained for
115 legacy compatibility purposes.
116 printable($value) : $escaped
118 Converts return, newline, tab, backslash and unprintable characters
119 to their backslash-escaped equivalents.
120 unprintable($value) : $escaped
122 Converts backslash escape sequences in a string back to their
123 original value.
124 qprintable($value) : $escaped
126 Converts special characters to their backslash-escaped equivalents
127 and then wraps the results with double quotes.
128 (Note that this is not MIME quoted-printable encoding.)
130 unqprintable($value) : $escaped
132 Strips surrounding double quotes then converts backslash escape
133 sequences back to their original value.
134 Other Backslash Functions
136 In addition to the functions listed above, there is also one function
137 that mirrors the behavior of Perl's built-in quotemeta() function.
138 unquotemeta($value) : $escaped
140 Strips out backslashes before any character.
141 Elision Function
143 This function extracts the leading portion of a provided string and
144 appends ellipsis if it's longer than the desired maximum excerpt
145 length.
146 elide($string) : $elided_string
148 elide($string, $length) : $elided_string
149 elide($string, $length, $word_boundary_strictness) : $elided_string
150 elide($string, $length, $word_boundary_strictness, $elipses) :
151 $elided_string
152 Return a single-quoted, shortened version of the string, with
153 ellipsis.
154 If the original string is shorter than $length, it is returned
156 unchanged. At most $length characters are returned; if called with
157 a single argument, $length defaults to $DefaultLength.
158 Up to $word_boundary_strictness additional characters may be
160 ommited in order to make the elided portion end on a word boundary;
161 you can pass 0 to ignore word boundaries. If not provided,
162 $word_boundary_strictness defaults to $DefaultStrictness.
163 $Elipses
165 The string of characters used to indicate the end of the excerpt.
166 Initialized to '...'.
167 $DefaultLength
169 The default target excerpt length, used when the elide function is
170 called with a single argument. Initialized to 60.
171 $DefaultStrictness
173 The default word-boundary flexibility, used when the elide function
174 is called without the third argument. Initialized to 10.
175 Here are a few examples:
177 •
179 $string = 'foo bar baz this that the other';
182 print elide( $string, 12 );
184 # foo bar...
185 print elide( $string, 12, 0 );
187 # foo bar b...
188 print elide( $string, 100 );
190 # foo bar baz this that the other
191 escape()
193 These functions provide for the registration of string-escape
194 specification names and corresponding functions, and then allow the
195 invocation of one or several of these functions on one or several
196 source string values.
197 escape($escapes, $value) : $escaped_value
199 escape($escapes, @values) : @escaped_values
200 Returns an altered copy of the provided values by looking up the
201 escapes string in a registry of string-modification functions.
202 If called in a scalar context, operates on the single value passed
204 in; if called in a list contact, operates identically on each of
205 the provided values.
206 Space-separated compound specifications like 'quoted uppercase' are
208 expanded to a list of functions to be applied in order.
209 Valid escape specifications are:
211 one of the keys defined in %Escapes
213 The coresponding specification will be looked up and used.
214 a sequence of names separated by whitespace,
216 Each name will be looked up, and each of the associated
217 functions will be applied successively, from left to right.
218 a reference to a function
220 The provided function will be called on with each value in
221 turn.
222 a reference to an array
224 Each item in the array will be expanded as provided above.
225 A fatal error will be generated if you pass an unsupported escape
227 specification, or if the function is called with multiple values in
228 a scalar context.
229 String::Escape::names() : @defined_escapes
231 Returns a list of defined escape specification strings.
232 String::Escape::add( $escape_name, \&escape_function );
234 Add a new escape specification and corresponding function.
235 By default, all of the public functions described below are available
237 as named escape commands, as well as the following built-in functions:
238 • none: Return the string unchanged.
240 • uppercase: Calls the built-in uc function.
242 • lowercase: Calls the built-in lc function.
244 • initialcase: Calls the built-in lc and ucfirst functions.
246 Here are a few examples:
248 • "print escape('qprintable', "\tNow is the time\nfor all good
250 folks\n" );"
251 "\tNow is the time\nfor all good folks\n"
253 • "print escape('uppercase qprintable', "\tNow is the time\nfor all
255 good folks\n" );"
256 "\tNOW IS THE TIME\nFOR ALL GOOD FOLKS\n"
258 • "print join '--', escape('printable', "\tNow is the time\n", "for
260 all good folks\n" );"
261 \tNow is the time\n--for all good folks\n
263 • You can add more escaping functions to the supported set by calling
265 add().
266 "String::Escape::add( 'html', \&HTML::Entities::encode_entities );"
268 "print escape('html', "AT&T" );"
270 AT&T
272 Space-separated Lists and Hashes
274 @words = string2list( $space_separated_phrases );
275 Converts a space separated string of words and quoted phrases to an
276 array;
277 $space_sparated_string = list2string( @words );
279 Joins an array of strings into a space separated string of words
280 and quoted phrases;
281 %hash = string2hash( $string );
283 Converts a space separated string of equal-sign-associated
284 key=value pairs into a simple hash.
285 $string = hash2string( %hash );
287 Converts a simple hash into a space separated string of equal-sign-
288 associated key=value pairs.
289 %hash = list2hash( @words );
291 Converts an array of equal-sign-associated key=value strings into a
292 simple hash.
293 @words = hash2list( %hash );
295 Converts a hash to an array of equal-sign-associated key=value
296 strings.
297 Here are a few examples:
299 • "print list2string('hello', 'I move next march');"
301 hello "I move next march"
303 • "@list = string2list('one "second item" 3
305 "four\nlines\nof\ntext"');"
306 "print $list[1];"
308 second item
310 • "print hash2string( 'foo' => 'Animal Cities', 'bar' => 'Cheap' );"
312 foo="Animal Cities" bar=Cheap
314 • "%hash = string2hash('key=value "undefined key" words="the cat in
316 the hat"');"
317 "print $hash{'words'};"
319 the cat in the hat
321 "print exists $hash{'undefined_key'} and ! defined
323 $hash{'undefined_key'};"
324 1
326
328 Numerous modules provide collections of string escaping functions for
329 specific contexts.
330 The string2list function is similar to to the quotewords function in
332 the standard distribution; see Text::ParseWords.
333 Use other packages to stringify more complex data structures; see
335 Storable, Data::Dumper, or other similar package.
336
338 The following issues or changes are under consideration for future
339 releases:
340 • Does this problem with the \r character only show up on Windows?
342 (And is it, in fact, a feature rather than a bug?)
343 http://rt.cpan.org/Public/Bug/Display.html?id=19766
345 • Consider changes to word parsing in string2list: Perhaps use \b
347 word-boundary test in elide's regular expression rather than \s|\Z?
348 Perhaps quotes embedded in a word (eg: a@"!a) shouldn't cause
349 phrase breaks?
350 • Check for possible problems in the use of printable escaping
352 functions and list2hash. For example, are the encoded strings for
353 hashes with high-bit characters in their keys properly unquoted and
354 unescaped?
355 • We should allow escape specifications to contain = signs and
357 optional arguments, so that users can request certain string
358 lengths with "escape("lowercase elide=20 quoted", @_".
359
361 This is version 2010.002.
362
364 This package should run on any standard Perl 5 installation.
365 To install this package, download the distribution from a CPAN mirror,
367 unpack the archive file, and execute the standard "perl Makefile.PL",
368 "make test", "make install" sequence or your local equivalent.
369
371 Once installed, this module's documentation is available as a manual
372 page via "perldoc String::Escape" or on CPAN sites such as
373 "http://search.cpan.org/dist/String-Escape".
374 If you have questions or feedback about this module, please feel free
376 to contact the author at the address shown below. Although there is no
377 formal support program, I do attempt to answer email promptly. Bug
378 reports that contain a failing test case are greatly appreciated, and
379 suggested patches will be promptly considered for inclusion in future
380 releases.
381 You can report bugs and request features via the CPAN web tracking
383 system at
384 "http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Escape" or by
385 sending mail to "bug-string-escape at rt.cpan.org".
386 If you've found this module useful or have feedback about your
388 experience with it, consider sharing your opinion with other Perl users
389 by posting your comment to CPAN's ratings system
390 ("http://cpanratings.perl.org/rate/?distribution=String-Escape").
391 For more general discussion, you may wish to post a message on
393 PerlMonks ("http://perlmonks.org/?node=Seekers%20of%20Perl%20Wisdom")
394 or on the comp.lang.perl.misc newsgroup
395 ("http://groups.google.com/group/comp.lang.perl.misc/topics").
396
398 Matthew Simon Cavalletto, "<simonm at cavalletto.org>"
399 Initial versions developed at Evolution Online Systems with Eleanor J.
401 Evans and Jeremy G. Bishop.
402
404 Copyright 2010, 2002 Matthew Simon Cavalletto.
405 Portions copyright 1996, 1997, 1998, 2001 Evolution Online Systems,
407 Inc.
408 You may use, modify, and distribute this software under the same terms
410 as Perl.
411 See http://dev.perl.org/licenses/ for more information.
413perl v5.36.0 2023-01-20 Escape(3)