1Escape(3)             User Contributed Perl Documentation            Escape(3)
2
3
4

NAME

6       String::Escape - Backslash escapes, quoted phrase, word elision, etc.
7

SYNOPSIS

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
14         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
20         use String::Escape qw( elide );
21         # Shorten strings to fit, if necessary
22         foreach (@_) { print elide( $_, 79 ) . "\n"; }
23
24         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
29         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

INTERFACE

35       All of the public functions described below are available as optional
36       exports.
37
38       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
42   Quoting
43       Each of these functions takes a single simple scalar argument and
44       returns its escaped (or unescaped) equivalent.
45
46       quote($value) : $escaped
47           Add double quote characters to each end of the string.
48
49       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
53       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
58       singlequote($value) : $escaped
59           Add single quote characters to each end of the string.
60
61       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
65   Backslash Escaping Functions
66       Each of these functions takes a single simple scalar argument and
67       returns its escaped (or unescaped) equivalent.
68
69       These functions recognize common whitespace sequences "\r", "\n", and
70       "\t", as well as hex escapes "\x4F" and ocatal "\020".
71
72       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
76       backslash($value) : $escaped
77           Converts special characters to their backslash-escaped equivalents.
78
79       unbackslash($value) : $escaped
80           Converts backslash escape sequences in a string back to their
81           original characters.
82
83       qqbackslash($value) : $escaped
84           Converts special characters to their backslash-escaped equivalents
85           and then wraps the results with double quotes.
86
87       unqqbackslash($value) : $escaped
88           Strips surrounding double quotes then converts backslash escape
89           sequences back to their original characters.
90
91       Here are a few examples:
92
93       ·
94
95
96             print backslash( "\tNow is the time\nfor all good folks\n" );
97
98             \tNow is the time\nfor all good folks\n
99
100       ·
101
102
103             print unbackslash( '\\tNow is the time\\nfor all good folks\\n' );
104
105                   Now is the time
106             for all good folks
107
108   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
113       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
118       printable($value) : $escaped
119           Converts return, newline, tab, backslash and unprintable characters
120           to their backslash-escaped equivalents.
121
122       unprintable($value) : $escaped
123           Converts backslash escape sequences in a string back to their
124           original value.
125
126       qprintable($value) : $escaped
127           Converts special characters to their backslash-escaped equivalents
128           and then wraps the results with double quotes.
129
130           (Note that this is not MIME quoted-printable encoding.)
131
132       unqprintable($value) : $escaped
133           Strips surrounding double quotes then converts backslash escape
134           sequences back to their original value.
135
136   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
140       unquotemeta($value) : $escaped
141           Strips out backslashes before any character.
142
143   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
148       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
156           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
160           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
165       $Elipses
166           The string of characters used to indicate the end of the excerpt.
167           Initialized to '...'.
168
169       $DefaultLength
170           The default target excerpt length, used when the elide function is
171           called with a single argument. Initialized to 60.
172
173       $DefaultStrictness
174           The default word-boundary flexibility, used when the elide function
175           is called without the third argument. Initialized to 10.
176
177       Here are a few examples:
178
179       ·
180
181
182             $string = 'foo bar baz this that the other';
183
184             print elide( $string, 12 );
185             # foo bar...
186
187             print elide( $string, 12, 0 );
188             # foo bar b...
189
190             print elide( $string, 100 );
191             # foo bar baz this that the other
192
193   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
199       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
204           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
208           Space-separated compound specifications like 'quoted uppercase' are
209           expanded to a list of functions to be applied in order.
210
211           Valid escape specifications are:
212
213           one of the keys defined in %Escapes
214               The coresponding specification will be looked up and used.
215
216           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
220           a reference to a function
221               The provided function will be called on with each value in
222               turn.
223
224           a reference to an array
225               Each item in the array will be expanded as provided above.
226
227           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
231       String::Escape::names() : @defined_escapes
232           Returns a list of defined escape specification strings.
233
234       String::Escape::add( $escape_name, \&escape_function );
235           Add a new escape specification and corresponding function.
236
237       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
240       ·   none: Return the string unchanged.
241
242       ·   uppercase: Calls the built-in uc function.
243
244       ·   lowercase: Calls the built-in lc function.
245
246       ·   initialcase: Calls the built-in lc and ucfirst functions.
247
248       Here are a few examples:
249
250       ·   "print escape('qprintable', "\tNow is the time\nfor all good
251           folks\n" );"
252
253             "\tNow is the time\nfor all good folks\n"
254
255       ·   "print escape('uppercase qprintable', "\tNow is the time\nfor all
256           good folks\n" );"
257
258             "\tNOW IS THE TIME\nFOR ALL GOOD FOLKS\n"
259
260       ·   "print join '--', escape('printable', "\tNow is the time\n", "for
261           all good folks\n" );"
262
263             \tNow is the time\n--for all good folks\n
264
265       ·   You can add more escaping functions to the supported set by calling
266           add().
267
268           "String::Escape::add( 'html', \&HTML::Entities::encode_entities );"
269
270           "print escape('html', "AT&T" );"
271
272             AT&T
273
274   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
279       $space_sparated_string = list2string( @words );
280           Joins an array of strings into a space separated string of words
281           and quoted phrases;
282
283       %hash = string2hash( $string );
284           Converts a space separated string of equal-sign-associated
285           key=value pairs into a simple hash.
286
287       $string = hash2string( %hash );
288           Converts a simple hash into a space separated string of equal-sign-
289           associated key=value pairs.
290
291       %hash = list2hash( @words );
292           Converts an array of equal-sign-associated key=value strings into a
293           simple hash.
294
295       @words = hash2list( %hash );
296           Converts a hash to an array of equal-sign-associated key=value
297           strings.
298
299       Here are a few examples:
300
301       ·   "print list2string('hello', 'I move next march');"
302
303             hello "I move next march"
304
305       ·   "@list = string2list('one "second item" 3
306           "four\nlines\nof\ntext"');"
307
308           "print $list[1];"
309
310             second item
311
312       ·   "print hash2string( 'foo' => 'Animal Cities', 'bar' => 'Cheap' );"
313
314             foo="Animal Cities" bar=Cheap
315
316       ·   "%hash = string2hash('key=value "undefined key" words="the cat in
317           the hat"');"
318
319           "print $hash{'words'};"
320
321             the cat in the hat
322
323           "print exists $hash{'undefined_key'} and ! defined
324           $hash{'undefined_key'};"
325
326             1
327

SEE ALSO

329       Numerous modules provide collections of string escaping functions for
330       specific contexts.
331
332       The string2list function is similar to to the quotewords function in
333       the standard distribution; see Text::ParseWords.
334
335       Use other packages to stringify more complex data structures; see
336       Storable, Data::Dumper, or other similar package.
337

BUGS

339       The following issues or changes are under consideration for future
340       releases:
341
342       ·   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
345             http://rt.cpan.org/Public/Bug/Display.html?id=19766
346
347       ·   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
352       ·   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
357       ·   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

VERSION

362       This is version 2010.002.
363

INSTALLATION

365       This package should run on any standard Perl 5 installation.
366
367       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

SUPPORT

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
376       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
383       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
388       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
393       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

AUTHOR

399       Matthew Simon Cavalletto, "<simonm at cavalletto.org>"
400
401       Initial versions developed at Evolution Online Systems with Eleanor J.
402       Evans and Jeremy G. Bishop.
403

LICENSE

405       Copyright 2010, 2002 Matthew Simon Cavalletto.
406
407       Portions copyright 1996, 1997, 1998, 2001 Evolution Online Systems,
408       Inc.
409
410       You may use, modify, and distribute this software under the same terms
411       as Perl.
412
413       See http://dev.perl.org/licenses/ for more information.
414
415
416
417perl v5.12.0                      2010-02-01                         Escape(3)
Impressum