.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Quoted 3pm"
.TH Quoted 3pm "2014-04-05" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Quoted \- Extract the structure of a quoted mail message
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Text::Quoted;
\&    Text::Quoted::set_quote_characters( qr/[:]/ ); # customize recognized quote characters
\&    my $structure = extract($text);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Text::Quoted\*(C'\fR examines the structure of some text which may contain
multiple different levels of quoting, and turns the text into a nested
data structure.
.PP
The structure is an array reference containing hash references for each
paragraph belonging to the same author. Each level of quoting recursively
adds another list reference. So for instance, this:
.PP
.Vb 3
\&    > foo
\&    > # Bar
\&    > baz
\&
\&    quux
.Ve
.PP
turns into:
.PP
.Vb 8
\&    [
\&      [
\&        { text => \*(Aqfoo\*(Aq, quoter => \*(Aq>\*(Aq, raw => \*(Aq> foo\*(Aq },
\&        [ 
\&            { text => \*(AqBar\*(Aq, quoter => \*(Aq> #\*(Aq, raw => \*(Aq> # Bar\*(Aq } 
\&        ],
\&        { text => \*(Aqbaz\*(Aq, quoter => \*(Aq>\*(Aq, raw => \*(Aq> baz\*(Aq }
\&      ],
\&
\&      { empty => 1 },
\&      { text => \*(Aqquux\*(Aq, quoter => \*(Aq\*(Aq, raw => \*(Aqquux\*(Aq }
\&    ];
.Ve
.PP
This also tells you about what's in the hash references: \f(CW\*(C`raw\*(C'\fR is the
paragraph of text as it appeared in the original input; \f(CW\*(C`text\*(C'\fR is what
it looked like when we stripped off the quotation characters, and \f(CW\*(C`quoter\*(C'\fR
is the quotation string.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "extract"
.IX Subsection "extract"
Takes a single string argument which is the text to extract quote structure
from.  Returns a nested datastructure as described above.
.PP
Exported by default.
.SS "set_quote_characters"
.IX Subsection "set_quote_characters"
Takes a regex (\f(CW\*(C`qr//\*(C'\fR) matching characters that should indicate a quoted line.
By default, a very liberal set is used:
.PP
.Vb 1
\&    set_quote_characters(qr/[!#%=|:]/);
.Ve
.PP
The character \f(CW\*(C`>\*(C'\fR is always recognized as a quoting character.
.PP
If \f(CW\*(C`undef\*(C'\fR is provided instead of a regex, only \f(CW\*(C`>\*(C'\fR will remain as a
quote character.
.PP
Not exported by default, but exportable.
.SS "combine_hunks"
.IX Subsection "combine_hunks"
.Vb 1
\&  my $text = combine_hunks( $arrayref_of_hunks );
.Ve
.PP
Takes the output of \f(CW\*(C`extract\*(C'\fR and turns it back into text.
.PP
Not exported by default, but exportable.
.SH "CREDITS"
.IX Header "CREDITS"
Most of the heavy lifting is done by a modified version of Damian Conway's
\&\f(CW\*(C`Text::Autoformat\*(C'\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2002\-2003 Kasei Limited
Copyright (C) 2003\-2004 Simon Cozens
Copyright (C) 2004\-2013 Best Practical Solutions, \s-1LLC\s0
.PP
This software is distributed \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied
warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.