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

SEE ALSO

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

BUGS

338       The following issues or changes are under consideration for future
339       releases:
340
341       •   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
344             http://rt.cpan.org/Public/Bug/Display.html?id=19766
345
346       •   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
351       •   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
356       •   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

VERSION

361       This is version 2010.002.
362

INSTALLATION

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

SUPPORT

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
375       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
382       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
387       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
392       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

AUTHOR

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

LICENSE

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