NAME

Text::EscapeDelimiters - escape delimiter characters within strings

SYNOPSIS

        my $obj = new Text::EscapeDelimiters();

        #Convert a list of lists into a string using tab and newline as field and record delimiters
        #Escape any delimiters occurring in the strings first
        my $stringified = join("\n", map {
                join("\t", map {$obj->escape($_, ["\t", "\n"])} @$_)
        } @records);

        #Convert the string back, respecting the escapes
        @records = map {
                [ map {$obj->unescape($_)} $obj->split($_, "\t") ]
        } $obj->split($stringified, "\n");

        #Pick off the first 5 records
        my $delim_regex = $obj->regex("\n");
        my @first_five;
        for(1..5) {
                $stringified =~ /(.*?)$delim_regex/g;
                push @first_five, [ map {$obj->unescape($_)} $obj->split($1, "\t") ];
        }

DESCRIPTION

When joining strings with a delimiter (aka separator), you need to worry about escaping occurences of that delimiter in the values you are joining. When splitting on the delimiter, you need to respect the escape sequences so you don't split on escaped delimiters.

This module provides a solution to that problem allowing you to escape values before you join, split the values whilst respecting escaped delimiters, and finally unescape the data.

Escaping is achieved by placing an escape sequence in front of delimiter characters. The default escape sequence is a backslash but you can change this.

$obj = new Text::EscapeDelimiters(\%options)

Valid options are:

EscapeSequence

One or more characters that will be used as an escape sequence in front of delimiter characters. If not supplied, defaults to a backslash. An undef or empty string of this key can be used to specify a null escape sequence.

$escaped = $obj->escape($string, $delimiters)

Escapes one or more delimiter characters in a string ($delimiters can be a scalar or an an arrayref)

@list = $obj->split($escaped_and_joined, $delimiter)

Splits an escaped string on a delimiter (respecting escaped delimiters)

$regex = $obj->regex($delimiters)

Creates a regular expression that will match delimiters (but not escaped delimiters). $delimiters can be a scalar or an an arrayref.

$string = $obj->unescape($escaped)

Inverse of escape()

VERSION

See $Text::EscapeDelimiters::VERSION. Last edit: $Revision: 1.4 $ on $Date: 2005/03/20 23:10:53 $

BUGS

None known. This module has not yet been used heavily in production so it's not impossible a bug may have slipped through the unit tests. Bug reports are welcome, particularly with patches & test cases.

AUTHOR

John Alden <johna@cpan.org>

SEE ALSO

URI::Escape

Escapes/unescapes strings using URI encoding

Tie::Scalar::Escaped

Similar to URI::Escape, but provides a tie interface.

String::Escape

Routines for backslash escaping strings

Regex::Common::delimited

Provides regexes for extracting values between PAIRED delimiters (e.g. quotes).

Text::DelimMatch

Module for extracting values between PAIRED delimiters (e.g. quotes). Handles escaped delimiter characters etc.

COPYRIGHT AND LICENSE

Copyright 2005 by John Alden

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.