Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text::Quote(3)	      User Contributed Perl Documentation	Text::Quote(3)

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!

SEE ALSO
       perl.

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2002 by Yves Orton <yves@cpan.org>.

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

perl v5.32.1			  2014-06-28			Text::Quote(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | OVERIDE METHODS | INTENTION | TODO | EXPORTS | REPOSITORY | AUTHOR | CAVEAT | SEE ALSO | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::Quote&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help