NAME

Text::Quote - Quotes strings as required for perl to eval them back correctly

SYNOPSIS

        use Text::Quote;

        my @quotes=map{$quoter->quote($_,indent=>6,col_width=>60)}('
                "The time has come"
                        the     walrus said,
                "to speak of many things..."
        ',"\0\1\2\3\4\5\6\a\b\t\n\13\f\r\16\17\20\21\22\23\24\25\26\27\30\31\32\e\34\35\36\37",
        ("\6\a\b\t\n\13\f\r\32\e\34" x 5),2/3,10,'00');
        for my $i (1..@quotes) {
                print "\$var$i=".$quotes[$i-1].";\n";
        }

Would produce:

        $var1=qq'"The time has come"\n\tthe\twalrus said,\n\t"to speak of man'.
              qq'y things..."';
        $var2="\0\1\2\3\4\5\6\a\b\t\n\13\f\r\16\17\20\21\22\23\24\25\26\27".
              "\30\31\32\e\34\35\36\37";
        $var3=("\6\a\b\t\n\13\f\r\32\e\34" x 5);
        $var4=0.666666666666667;
        $var5=10;
        $var6='00';

DESCRIPTION

Text::Quote is intended as a utility class for other classes that need to be able to produce valid perl quoted strings. It posses routines to determine the ideal quote character to correctly quote hash keys, to correctly quote and encode binary strings.

This code was inspired by an analysis of Data::Dump by Gisle Aas. In some cases it was much more than inspired. :-)

METHODS

quote(STR,OPTS)

Quotes a string. Will encode or compress or otherwise change the strings representation as the options specify. If an option is omitted the class default is used if it exists then an internal procedure default is used.

Normal behaviour is as follows

Numbers: Not quoted
Short Repeated Substr: Converted into a repeat statement "($str x $repeat)"
Simple Strings: Single quoted, or double quoted if multiline or containing small numbers of other control characters (tabs excluded).
Binary Strings: Converted into hex using pack() or if larger into Base64 using decode64()
Large Strings: Converted to a call to decompress64().

The output and OPTS will passed on to quote_columns() for formatting if it is multiline. No indentation of the first line is done.

See init() for options.

quote_simple(STR,OPTS)

Quotes a string. Does not attempt to encode it, otherwise the same quote()

quote_key(STR,OPTS)

Quotes a string as though it was a hash key. In otherwords will only quote it if it contains whitespace, funky characters or reserved words.

See init() for options.

quote_regexp(STR)

Quotes a regexp or string as though it was a regexp, includes the qr operator. Will automatically select the appropriate quoting char.

quote_columns(STR,QB,QE,OPTS)

Takes a preescaped string and chops it into lines with a specific maximum length each line is independantly quoted and concatenated together, this allows the column to be set at a precise indent and maximum width. It also handles slicing the string at awkward points, such as in an escape sequence that might invalidate the quote. Note the first line is not indented by default.

STR is the string to quote. QB is the begin quote pattern. QE is end quote pattern. OPTS can be

        col_width    (defaults 76) Width of text excl. quote symbols and cat char
        leading      (defaults 0)  Width of first line offset.
        indent       (defaults 0)  Width of overall indentation
        indent_first (defaults 0)  Whether the first line is indented.

decompress64(STR)

Takes a compressed string in quoted 64 representation and decompresses it.

decode64(STR)

Takes a string encoded in base 64 and decodes it.

best_quotes(STR,OPTS)

Selects the optimal quoting character and quoting type for a given string.

Returns a list

  $qq          - Either 'q' or 'qq'
  $qbegin      - The beginning quote character
  $qend        - The ending quote character
  $needs_type  - Whether $qq is needed to make the quotes valid.

OPTS may include the normal options as well as

  chars : a list of chars (or pairs) to be allowed for quoting.

OVERIDE METHODS

These methods are defined by Text::Quote for when it runs as a stand alone. Normally they would be overriden by child classes, or alternatively used by the child class.

init()

Takes a list of options and uses them to initialize the quoting object. Defaults are provided if an option is not specified.

  esc_chars     : a hash of chars needing to be escaped and their escaped equivelent
  esc_class     : a regex class that matches the chars needing to be escaped
  quote_chars   : chars to be used as alternate quote chars
  key_quote_hash    : hash of words that must be quoted if used as a hash key
  repeat_len    : Length of pattern to look for in the string
  encode_high   : Set to 1 to cause high bits chars to be escaped. Dafaults to 0

Set the following to 0 to disable

  repeat_at     : Length of string at which Text::Quote should see if there is a repeated pattern.
  encode_at     : Length at which binary data should be quoted in Base64
  compress_at   : Length at which the string should be compressed using Compress::Zlib

These options are set using quote_prop()

new()

Creates a hash based object and calls init(@_) afterwards

quote_prop()

As this class is intended to be subclassed all of its parameters are kept and accessed through a single accessor.

This hash is normally stored as $obj->{Text::Quote} however should the default class type not be a hash this method may be overriden to provide access to the the Text::Quote proprty hash. Or even to redirect various properties elsewhere.

Called with no parameters it returns a reference to the property hash. Called with a string as the only parameter it returns the value of that named property. Called with a string as the first parameter and a value it will set the property to equal the value and return the new value. Called with a reference as the only parameter the passed value is substituted for the property hash.

_self_obj()

This is a utility method to enable Text::Quote and its descendants the ability to act as both CLASS and OBJECT methods. Creates an object to act as a class object.

If called as an object method returns the object

If called as a class method returns a singleton, which is the result of calling class->new(); The singleton is inserted into the calling classes package under the global scalar $class::SINGLETON and is reused thereafter. The object is kept in a closure for maximum privacy of the object data.

INTENTION

I wrote this module to enable me to avoid having to put code for how to neatly output perl quoted strings in a reasonable way in the same module as Data::BFDump. I've documented it and packaged in the mind that others may find it useful, and or help me improve it. I was thinking for example that there are a number of modules with one form of quoting or another, be it SQL statements or excel CSV quoting. There are lots of modules (and ways) of reading these formats but no one clear location for finding ones that output them. Perhaps they could live here? Feedback welcome.

TODO

Better synopsis. Better Description. More tests.

EXPORTS

None.

REPOSITORY

<https://github.com/neilbowers/Text-Quote>

AUTHOR

Yves Orton, <demerphq@hotmail.com>

Parts by Gisle Aas

Additional testing and encouragement Dan Brook

CAVEAT

This module is currently in BETA condition. It should not be used in a production enviornment, and is released with no warranty of any kind whatsoever.

Corrections, suggestions, bugreports and tests are welcome!

COPYRIGHT AND LICENSE

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