.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Courriel::Header::Disposition 3pm"
.TH Courriel::Header::Disposition 3pm "2021-08-22" "perl v5.32.1" "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"
Courriel::Header::Disposition \- The content disposition for an email part
.SH "VERSION"
.IX Header "VERSION"
version 0.49
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    my $disp = $part\->content_disposition();
\&    print $disp\->is_inline();
\&    print $disp\->is_attachment();
\&    print $disp\->filename();
\&
\&    my %attr = $disp\->attributes();
\&    while ( my ( $k, $v ) = each %attr ) {
\&        print "$k => $v\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class represents the contents of a \*(L"Content-Disposition\*(R" header attached
to an email part. Such headers indicate whether or not a part should be
considered an attachment or should be displayed to the user directly. This
header may also include information about the attachment's filename, creation
date, etc.
.PP
Here are some typical headers:
.PP
.Vb 1
\&  Content\-Disposition: inline
\&
\&  Content\-Disposition: multipart/alternative; boundary=abcdefghijk
\&
\&  Content\-Disposition: attachment; filename="Filename.jpg"
\&
\&  Content\-Disposition: attachment; filename="foo\-bar.jpg";
\&    creation\-date="Tue, 31 May 2011 09:41:13 \-0700"
.Ve
.SH "API"
.IX Header "API"
This class supports the following methods:
.SS "Courriel::Header::Disposition\->new_from_value( ... )"
.IX Subsection "Courriel::Header::Disposition->new_from_value( ... )"
This takes two parameters, \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`value\*(C'\fR. The \f(CW\*(C`name\*(C'\fR is optional, and
defaults to \*(L"Content-Disposition\*(R".
.PP
The \f(CW\*(C`value\*(C'\fR is parsed and split up into the disposition and attributes.
.SS "Courriel::Header::Disposition\->new( ... )"
.IX Subsection "Courriel::Header::Disposition->new( ... )"
This method creates a new object. It accepts the following parameters:
.IP "\(bu" 4
name
.Sp
This defaults to 'Content\-Type'.
.IP "\(bu" 4
value
.Sp
This is the full header value.
.IP "\(bu" 4
disposition
.Sp
This should usually either be \*(L"inline\*(R" or \*(L"attachment\*(R".
.Sp
In theory, the RFCs allow other values.
.IP "\(bu" 4
attributes
.Sp
A hash reference of attributes from the header, such as a filename, creation
date, size, etc. The keys are attribute names and the values can either be
strings or Courriel::HeaderAttribute objects. Values which are strings will
be inflated into objects by the constructor.
.Sp
This is optional, and can be an empty hash reference or omitted entirely.
.ie n .SS "$ct\->\fBname()\fP"
.el .SS "\f(CW$ct\fP\->\fBname()\fP"
.IX Subsection "$ct->name()"
The header name, usually \*(L"Content-Disposition\*(R".
.ie n .SS "$ct\->\fBvalue()\fP"
.el .SS "\f(CW$ct\fP\->\fBvalue()\fP"
.IX Subsection "$ct->value()"
The raw header value.
.ie n .SS "$disp\->\fBdisposition()\fP"
.el .SS "\f(CW$disp\fP\->\fBdisposition()\fP"
.IX Subsection "$disp->disposition()"
Returns the disposition value passed to the constructor.
.ie n .SS "$disp\->\fBis_inline()\fP"
.el .SS "\f(CW$disp\fP\->\fBis_inline()\fP"
.IX Subsection "$disp->is_inline()"
Returns true if the disposition is not equal to \*(L"attachment\*(R".
.ie n .SS "$disp\->\fBis_attachment()\fP"
.el .SS "\f(CW$disp\fP\->\fBis_attachment()\fP"
.IX Subsection "$disp->is_attachment()"
Returns true if the disposition is equal to \*(L"attachment\*(R".
.ie n .SS "$disp\->\fBfilename()\fP"
.el .SS "\f(CW$disp\fP\->\fBfilename()\fP"
.IX Subsection "$disp->filename()"
Returns the filename found in the attributes, or \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$disp\->\fBcreation_datetime()\fP, $disp\->\fBlast_modified_datetime()\fP, $disp\->\fBread_datetime()\fP"
.el .SS "\f(CW$disp\fP\->\fBcreation_datetime()\fP, \f(CW$disp\fP\->\fBlast_modified_datetime()\fP, \f(CW$disp\fP\->\fBread_datetime()\fP"
.IX Subsection "$disp->creation_datetime(), $disp->last_modified_datetime(), $disp->read_datetime()"
These methods look for a corresponding attribute (\*(L"creation-date\*(R", etc.) and
return a DateTime object representing that attribute's value, if it exists.
.ie n .SS "$disp\->\fBattributes()\fP"
.el .SS "\f(CW$disp\fP\->\fBattributes()\fP"
.IX Subsection "$disp->attributes()"
Returns a hash (not a reference) of the attributes passed to the constructor.
.PP
Attributes are Courriel::HeaderAttribute objects.
.PP
The keys of the hash are all lower case, though the original casing is
preserved in the \f(CW\*(C`name()\*(C'\fR returned by the Courriel::HeaderAttribute object.
.ie n .SS "$disp\->attribute($key)"
.el .SS "\f(CW$disp\fP\->attribute($key)"
.IX Subsection "$disp->attribute($key)"
Given a key, returns the named Courriel::HeaderAttribute object. Obviously,
this value can be \f(CW\*(C`undef\*(C'\fR if the attribute doesn't exist. Name lookup is
case-insensitive.
.ie n .SS "$disp\->attribute_value($key)"
.el .SS "\f(CW$disp\fP\->attribute_value($key)"
.IX Subsection "$disp->attribute_value($key)"
Given a key, returns the named attribute's value as a string. Obviously, this
value can be \f(CW\*(C`undef\*(C'\fR if the attribute doesn't exist. Name lookup is
case-insensitive.
.PP
The attribute is a Courriel::HeaderAttribute object.
.ie n .SS "$disp\->\fBas_header_value()\fP"
.el .SS "\f(CW$disp\fP\->\fBas_header_value()\fP"
.IX Subsection "$disp->as_header_value()"
Returns the object as a string suitable for a header value (but not folded).
.SH "EXTENDS"
.IX Header "EXTENDS"
This class extends Courriel::Header.
.SH "ROLES"
.IX Header "ROLES"
This class does the \f(CW\*(C`Courriel::Role::HeaderWithAttributes\*(C'\fR role.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/Courriel/issues>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Courriel can be found at <https://github.com/houseabsolute/Courriel>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2021 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.