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
40 invoke.
41 Quoting
43 Each of these functions takes a single simple scalar argument and
44 returns its escaped (or unescaped) equivalent.
45 quote($value) : $escaped
47 Add double quote characters to each end of the string.
48 unquote($value) : $escaped
50 If the string both begins and ends with double quote characters,
51 they are removed, otherwise the string is returned unchanged.
52 quote_non_words($value) : $escaped
54 As above, but only quotes empty, punctuated, and multiword values;
55 simple values consisting of alphanumerics without special
56 characters are not quoted.
57 singlequote($value) : $escaped
59 Add single quote characters to each end of the string.
60 unsinglequote($value) : $escaped
62 If the string both begins and ends with single quote characters,
63 they are removed, otherwise the string is returned unchanged.
64 Backslash Escaping Functions
66 Each of these functions takes a single simple scalar argument and
67 returns its escaped (or unescaped) equivalent.
68 These functions recognize common whitespace sequences "\r", "\n", and
70 "\t", as well as hex escapes "\x4F" and ocatal "\020".
71 When escaping, alphanumeric characters and most punctuation is passed
73 through unchanged; only the return, newline, tab, backslash, dollar, at
74 sign and unprintable control and high-bit characters are escaped.
75 backslash($value) : $escaped
77 Converts special characters to their backslash-escaped equivalents.
78 unbackslash($value) : $escaped
80 Converts backslash escape sequences in a string back to their
81 original characters.
82 qqbackslash($value) : $escaped
84 Converts special characters to their backslash-escaped equivalents
85 and then wraps the results with double quotes.
86 unqqbackslash($value) : $escaped
88 Strips surrounding double quotes then converts backslash escape
89 sequences back to their original characters.
90 Here are a few examples:
92 •
94 print backslash( "\tNow is the time\nfor all good folks\n" );
97 \tNow is the time\nfor all good folks\n
99 •
101 print unbackslash( '\\tNow is the time\\nfor all good folks\\n' );
104 Now is the time
106 for all good folks
107 Legacy Backslash Functions
109 In addition to the four functions listed above, there is a
110 corresponding set which use a slightly different set of escape
111 sequences.
112 These functions do not support as many escape sequences and use a non-
114 standard format for hex escapes. In general, the above "backslash()"
115 functions are recommended, while these functions are retained for
116 legacy compatibility purposes.
117 printable($value) : $escaped
119 Converts return, newline, tab, backslash and unprintable characters
120 to their backslash-escaped equivalents.
121 unprintable($value) : $escaped
123 Converts backslash escape sequences in a string back to their
124 original value.
125 qprintable($value) : $escaped
127 Converts special characters to their backslash-escaped equivalents
128 and then wraps the results with double quotes.
129 (Note that this is not MIME quoted-printable encoding.)
131 unqprintable($value) : $escaped
133 Strips surrounding double quotes then converts backslash escape
134 sequences back to their original value.
135 Other Backslash Functions
137 In addition to the functions listed above, there is also one function
138 that mirrors the behavior of Perl's built-in "quotemeta()" function.
139 unquotemeta($value) : $escaped
141 Strips out backslashes before any character.
142 Elision Function
144 This function extracts the leading portion of a provided string and
145 appends ellipsis if it's longer than the desired maximum excerpt
146 length.
147 elide($string) : $elided_string
149 elide($string, $length) : $elided_string
150 elide($string, $length, $word_boundary_strictness) : $elided_string
151 elide($string, $length, $word_boundary_strictness, $elipses) :
152 $elided_string
153 Return a single-quoted, shortened version of the string, with
154 ellipsis.
155 If the original string is shorter than $length, it is returned
157 unchanged. At most $length characters are returned; if called with
158 a single argument, $length defaults to $DefaultLength.
159 Up to $word_boundary_strictness additional characters may be
161 ommited in order to make the elided portion end on a word boundary;
162 you can pass 0 to ignore word boundaries. If not provided,
163 $word_boundary_strictness defaults to $DefaultStrictness.
164 $Elipses
166 The string of characters used to indicate the end of the excerpt.
167 Initialized to '...'.
168 $DefaultLength
170 The default target excerpt length, used when the elide function is
171 called with a single argument. Initialized to 60.
172 $DefaultStrictness
174 The default word-boundary flexibility, used when the elide function
175 is called without the third argument. Initialized to 10.
176 Here are a few examples:
178 •
180 $string = 'foo bar baz this that the other';
183 print elide( $string, 12 );
185 # foo bar...
186 print elide( $string, 12, 0 );
188 # foo bar b...
189 print elide( $string, 100 );
191 # foo bar baz this that the other
192 escape()
194 These functions provide for the registration of string-escape
195 specification names and corresponding functions, and then allow the
196 invocation of one or several of these functions on one or several
197 source string values.
198 escape($escapes, $value) : $escaped_value
200 escape($escapes, @values) : @escaped_values
201 Returns an altered copy of the provided values by looking up the
202 escapes string in a registry of string-modification functions.
203 If called in a scalar context, operates on the single value passed
205 in; if called in a list contact, operates identically on each of
206 the provided values.
207 Space-separated compound specifications like 'quoted uppercase' are
209 expanded to a list of functions to be applied in order.
210 Valid escape specifications are:
212 one of the keys defined in %Escapes
214 The coresponding specification will be looked up and used.
215 a sequence of names separated by whitespace,
217 Each name will be looked up, and each of the associated
218 functions will be applied successively, from left to right.
219 a reference to a function
221 The provided function will be called on with each value in
222 turn.
223 a reference to an array
225 Each item in the array will be expanded as provided above.
226 A fatal error will be generated if you pass an unsupported escape
228 specification, or if the function is called with multiple values in
229 a scalar context.
230 String::Escape::names() : @defined_escapes
232 Returns a list of defined escape specification strings.
233 String::Escape::add( $escape_name, \&escape_function );
235 Add a new escape specification and corresponding function.
236 By default, all of the public functions described below are available
238 as named escape commands, as well as the following built-in functions:
239 • none: Return the string unchanged.
241 • uppercase: Calls the built-in uc function.
243 • lowercase: Calls the built-in lc function.
245 • initialcase: Calls the built-in lc and ucfirst functions.
247 Here are a few examples:
249 • "print escape('qprintable', "\tNow is the time\nfor all good
251 folks\n" );"
252 "\tNow is the time\nfor all good folks\n"
254 • "print escape('uppercase qprintable', "\tNow is the time\nfor all
256 good folks\n" );"
257 "\tNOW IS THE TIME\nFOR ALL GOOD FOLKS\n"
259 • "print join '--', escape('printable', "\tNow is the time\n", "for
261 all good folks\n" );"
262 \tNow is the time\n--for all good folks\n
264 • You can add more escaping functions to the supported set by calling
266 add().
267 "String::Escape::add( 'html', \&HTML::Entities::encode_entities );"
269 "print escape('html', "AT&T" );"
271 AT&T
273 Space-separated Lists and Hashes
275 @words = string2list( $space_separated_phrases );
276 Converts a space separated string of words and quoted phrases to an
277 array;
278 $space_sparated_string = list2string( @words );
280 Joins an array of strings into a space separated string of words
281 and quoted phrases;
282 %hash = string2hash( $string );
284 Converts a space separated string of equal-sign-associated
285 key=value pairs into a simple hash.
286 $string = hash2string( %hash );
288 Converts a simple hash into a space separated string of equal-sign-
289 associated key=value pairs.
290 %hash = list2hash( @words );
292 Converts an array of equal-sign-associated key=value strings into a
293 simple hash.
294 @words = hash2list( %hash );
296 Converts a hash to an array of equal-sign-associated key=value
297 strings.
298 Here are a few examples:
300 • "print list2string('hello', 'I move next march');"
302 hello "I move next march"
304 • "@list = string2list('one "second item" 3
306 "four\nlines\nof\ntext"');"
307 "print $list[1];"
309 second item
311 • "print hash2string( 'foo' => 'Animal Cities', 'bar' => 'Cheap' );"
313 foo="Animal Cities" bar=Cheap
315 • "%hash = string2hash('key=value "undefined key" words="the cat in
317 the hat"');"
318 "print $hash{'words'};"
320 the cat in the hat
322 "print exists $hash{'undefined_key'} and ! defined
324 $hash{'undefined_key'};"
325 1
327
329 Numerous modules provide collections of string escaping functions for
330 specific contexts.
331 The string2list function is similar to to the quotewords function in
333 the standard distribution; see Text::ParseWords.
334 Use other packages to stringify more complex data structures; see
336 Storable, Data::Dumper, or other similar package.
337
339 The following issues or changes are under consideration for future
340 releases:
341 • Does this problem with the \r character only show up on Windows?
343 (And is it, in fact, a feature rather than a bug?)
344 http://rt.cpan.org/Public/Bug/Display.html?id=19766
346 • Consider changes to word parsing in string2list: Perhaps use \b
348 word-boundary test in elide's regular expression rather than \s|\Z?
349 Perhaps quotes embedded in a word (eg: a@"!a) shouldn't cause
350 phrase breaks?
351 • Check for possible problems in the use of printable escaping
353 functions and list2hash. For example, are the encoded strings for
354 hashes with high-bit characters in their keys properly unquoted and
355 unescaped?
356 • We should allow escape specifications to contain = signs and
358 optional arguments, so that users can request certain string
359 lengths with "escape("lowercase elide=20 quoted", @_".
360
362 This is version 2010.002.
363
365 This package should run on any standard Perl 5 installation.
366 To install this package, download the distribution from a CPAN mirror,
368 unpack the archive file, and execute the standard "perl Makefile.PL",
369 "make test", "make install" sequence or your local equivalent.
370
372 Once installed, this module's documentation is available as a manual
373 page via "perldoc String::Escape" or on CPAN sites such as
374 "http://search.cpan.org/dist/String-Escape".
375 If you have questions or feedback about this module, please feel free
377 to contact the author at the address shown below. Although there is no
378 formal support program, I do attempt to answer email promptly. Bug
379 reports that contain a failing test case are greatly appreciated, and
380 suggested patches will be promptly considered for inclusion in future
381 releases.
382 You can report bugs and request features via the CPAN web tracking
384 system at
385 "http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Escape" or by
386 sending mail to "bug-string-escape at rt.cpan.org".
387 If you've found this module useful or have feedback about your
389 experience with it, consider sharing your opinion with other Perl users
390 by posting your comment to CPAN's ratings system
391 ("http://cpanratings.perl.org/rate/?distribution=String-Escape").
392 For more general discussion, you may wish to post a message on
394 PerlMonks ("http://perlmonks.org/?node=Seekers%20of%20Perl%20Wisdom")
395 or on the comp.lang.perl.misc newsgroup
396 ("http://groups.google.com/group/comp.lang.perl.misc/topics").
397
399 Matthew Simon Cavalletto, "<simonm at cavalletto.org>"
400 Initial versions developed at Evolution Online Systems with Eleanor J.
402 Evans and Jeremy G. Bishop.
403
405 Copyright 2010, 2002 Matthew Simon Cavalletto.
406 Portions copyright 1996, 1997, 1998, 2001 Evolution Online Systems,
408 Inc.
409 You may use, modify, and distribute this software under the same terms
411 as Perl.
412 See http://dev.perl.org/licenses/ for more information.
414perl v5.34.0 2022-01-21 Escape(3)