Quoting¶

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.

unquote($value) : $escaped

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

quote_non_words($value) : $escaped

As above, but only quotes empty, punctuated, and multiword values; simple values consisting of alphanumerics without special characters are not quoted.

singlequote($value) : $escaped

Add single quote characters to each end of the string.

unsinglequote($value) : $escaped

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

Backslash Escaping Functions¶

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

These functions recognize common whitespace sequences "\r", "\n", and "\t", as well as hex escapes "\x4F" and ocatal "\020".

When escaping, alphanumeric characters and most punctuation is passed through unchanged; only the return, newline, tab, backslash, dollar, at sign and unprintable control and high-bit characters are escaped.

backslash($value) : $escaped

Converts special characters to their backslash-escaped equivalents.

unbackslash($value) : $escaped

Converts backslash escape sequences in a string back to their original characters.

qqbackslash($value) : $escaped

Converts special characters to their backslash-escaped equivalents and then wraps the results with double quotes.

unqqbackslash($value) : $escaped

Strips surrounding double quotes then converts backslash escape sequences back to their original characters.

Here are a few examples:

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

•   print unbackslash( '\\tNow is the time\\nfor all good folks\\n' );
          Now is the time
    for all good folks
      

Legacy Backslash Functions¶

In addition to the four functions listed above, there is a corresponding set which use a slightly different set of escape sequences.

These functions do not support as many escape sequences and use a non-standard format for hex escapes. In general, the above "backslash()" functions are recommended, while these functions are retained for legacy compatibility purposes.

printable($value) : $escaped

Converts return, newline, tab, backslash and unprintable characters to their backslash-escaped equivalents.

unprintable($value) : $escaped

Converts backslash escape sequences in a string back to their original value.

qprintable($value) : $escaped

Converts special characters to their backslash-escaped equivalents and then wraps the results with double quotes.

(Note that this is not MIME quoted-printable encoding.)

unqprintable($value) : $escaped

Strips surrounding double quotes then converts backslash escape sequences back to their original value.

Other Backslash Functions¶

In addition to the functions listed above, there is also one function that mirrors the behavior of Perl's built-in "quotemeta()" function.

unquotemeta($value) : $escaped

Strips out backslashes before any character.

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

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

Return a single-quoted, shortened version of the string, with ellipsis.

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.

Here are a few examples:

•

  $string = 'foo bar baz this that the other';
  print elide( $string, 12 );
  # foo bar...
  print elide( $string, 12, 0 );
  # foo bar b...
  print elide( $string, 100 );
  # foo bar baz this that the other
    

escape()¶

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.

Space-separated compound specifications like 'quoted uppercase' are expanded to a list of functions to be applied in order.

Valid escape specifications are:

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.

By default, all of the public functions described below are available as named escape commands, as well as the following built-in functions:

• none: Return the string unchanged.
• uppercase: Calls the built-in uc function.
• lowercase: Calls the built-in lc function.
• initialcase: Calls the built-in lc and ucfirst functions.

Here are a few examples:

• "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
      

• You can add more escaping functions to the supported set by calling add().

  "String::Escape::add( 'html', \&HTML::Entities::encode_entities );"

  "print escape('html', "AT&T" );"

    AT&T
      

Space-separated Lists and Hashes¶

@words = string2list( $space_separated_phrases );

Converts a space separated string of words and quoted phrases to an array;

$space_sparated_string = list2string( @words );

Joins an array of strings into a space separated string of words and quoted phrases;

%hash = string2hash( $string );

Converts a space separated string of equal-sign-associated key=value pairs into a simple hash.

$string = hash2string( %hash );

Converts a simple hash into a space separated string of equal-sign-associated key=value pairs.

%hash = list2hash( @words );

Converts an array of equal-sign-associated key=value strings into a simple hash.

@words = hash2list( %hash );

Converts a hash to an array of equal-sign-associated key=value strings.

Here are a few examples:

• "print list2string('hello', 'I move next march');"

    hello "I move next march"
      

• "@list = string2list('one "second item" 3 "four\nlines\nof\ntext"');"

  "print $list[1];"

    second item
      

• "print hash2string( 'foo' => 'Animal Cities', 'bar' => 'Cheap' );"

    foo="Animal Cities" bar=Cheap
      

• "%hash = string2hash('key=value "undefined key" words="the cat in the hat"');"

  "print $hash{'words'};"

    the cat in the hat
      

  "print exists $hash{'undefined_key'} and ! defined $hash{'undefined_key'};"

    1