The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
String-Escape-1998.1204
River stage two • 25 direct dependents • 55 total dependents
6 ++
/ String::Escape

NAME

String::Escape - Registry of string functions, including backslash escapes

SYNOPSIS

  use String::Escape qw( printable unprintable );
  # Convert control, high-bit chars to \n or \xxx 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 ) . "\n"; } 
  
  use String::Escape qw( escape );
  # Defer selection of escaping routines until runtime
  $escape_name = $use_quotes ? 'qprintable' : 'printable';
  @escaped = escape($escape_name, @values);

DESCRIPTION

This module provides a flexible calling interface to some frequently-performed string conversion functions, including applying and removing C/Unix-style backslash escapes like \n and \t, wrapping and removing double-quotes, and truncating to fit within a desired length.

The escape() function provides for dynamic selection of operations by using a package hash variable to map escape specification strings to the functions which implement them. The lookup imposes a bit of a performance penalty, but allows for some useful late-binding behaviour. Compound specifications (ex. 'quoted uppercase') are expanded to a list of functions to be applied in order. Other modules may also register their functions here for later general use.

REFERENCE

Escaping And Unescaping Functions

Each of these functions takes a single simple scalar argument and returns its escaped (or unescaped) equivalent.

quote($value) : $escaped

Add double quote characters to each end of the string.

quote_non_words($value) : $escaped

As above, but only quotes empty, punctuated, and multiword values.

unquote($value) : $escaped

If the string both begins and ends with double quote characters, they are removed, otherwise the string is returned unchanged.

printable($value) : $escaped
unprintable($value) : $escaped

These functions convert return, newline, tab, backslash and unprintable characters to their backslash-escaped equivalents and back again.

qprintable($value) : $escaped
unqprintable($value) : $escaped

The qprintable function applies printable escaping and then wraps the results with quote_non_words, while unqprintable applies unquote and then unprintable. (Note that this is not MIME quoted-printable encoding.)

String 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.

elide($string) : $elided_string
elide($string, $length) : $elided_string
elide($string, $length, $word_boundary_strictness) : $elided_string

If the original string is shorter than $length, it is returned unchanged. At most $length characters are returned; if called with a single argument, $length defaults to $DefaultLength.

Up to $word_boundary_strictness 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, $word_boundary_strictness defaults to $DefaultStrictness.

$Elipses

The string of characters used to indicate the end of the excerpt. Initialized to '...'.

$DefaultLength

The default target excerpt length, used when the elide function is called with a single argument. Initialized to 60.

$DefaultStrictness

The default word-boundary flexibility, used when the elide function is called without the third argument. Initialized to 10.

Escape By-Name

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.

escape($escapes, $value) : $escaped_value
escape($escapes, @values) : @escaped_values

Returns an altered copy of the provided values by looking up the escapes string in a registry of string-modification functions.

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.

Valid escape specifications are:

one of the keys defined in %Escapes

The coresponding specification will be looked up and used.

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.

a reference to a function

The provided function will be called on with each value in turn.

a reference to an array

Each item in the array will be expanded as provided above.

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.

String::Escape::names() : @defined_escapes

Returns a list of defined escape specification strings.

String::Escape::add( $escape_name, \&escape_function );

Add a new escape specification and corresponding function.

%Escapes : $name, $operation, ...

By default, the %Escapes hash is initialized to contain the following mappings:

quote, unquote, or quote_non_words
printable, unprintable, qprintable, or unqprintable,
elide

Run the above-described functions of the same names.

uppercase, lowercase, or initialcase

Alters the case of letters in the string to upper or lower case, or for initialcase, sets the first letter to upper case and all others to lower.

none

Return an unchanged copy of the original value.

EXAMPLES

print printable( "\tNow is the time\nfor all good folks\n" );

\tNow is the time\nfor all good folks\n

print escape('qprintable', "\tNow is the time\nfor all good folks\n" );

"\tNow is the time\nfor all good folks\n"

print escape('uppercase qprintable', "\tNow is the time\nfor all good folks\n" );

"\tNOW IS THE TIME\nFOR ALL GOOD FOLKS\n"

print join '--', escape('printable', "\tNow is the time\n", "for all good folks\n" );

\tNow is the time\n--for all good folks\n

$string = 'foo bar baz this that the other';

print elide( $string, 100 );

foo bar baz this that the other

print elide( $string, 12 );

foo bar...

print elide( $string, 12, 0 );

foo bar b...

PREREQUISITES AND INSTALLATION

This package should run on any standard Perl 5 installation.

To install this package, download and unpack the distribution archive from http://www.evoscript.com/dist/ or your favorite CPAN mirror, and execute the standard "perl Makefile.PL", "make test", "make install" sequence.

STATUS AND SUPPORT

This release of String::Escape is intended for public review and feedback. It has been tested in several environments and no major problems have been discovered, but it should be considered "beta" pending that feedback.

  Name            DSLI  Description
  --------------  ----  ---------------------------------------------
  String::
  ::Escape        bdpf  Escape by-name registry and useful functions

Further information and support for this module is available at <www.evoscript.com>.

Please report bugs or other problems to <bugs@evoscript.com>.

The following changes are in progress or under consideration:

Use word-boundary test in elide's regular expression rather than \s|\Z.
Compare with TOMC's String::Edit package.

AUTHORS AND COPYRIGHT

Copyright 1997, 1998 Evolution Online Systems, Inc. <www.evolution.com>

You may use this software for free under the terms of the Artistic License.

Contributors: M. Simon Cavalletto <simonm@evolution.com>, Jeremy G. Bishop <jeremy@evolution.com>