.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "MIME::Field::ParamVal 3pm"
.TH MIME::Field::ParamVal 3pm 2024-04-27 "perl v5.38.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
MIME::Field::ParamVal \- subclass of Mail::Field, for structured MIME fields
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    # Create an object for a content\-type field:
\&    $field = new Mail::Field \*(AqContent\-type\*(Aq;
\&
\&    # Set some attributes:
\&    $field\->param(\*(Aq_\*(Aq        => \*(Aqtext/html\*(Aq);
\&    $field\->param(\*(Aqcharset\*(Aq  => \*(Aqus\-ascii\*(Aq);
\&    $field\->param(\*(Aqboundary\*(Aq => \*(Aq\-\-\-ABC\-\-\-\*(Aq);
\&
\&    # Same:
\&    $field\->set(\*(Aq_\*(Aq        => \*(Aqtext/html\*(Aq,
\&                \*(Aqcharset\*(Aq  => \*(Aqus\-ascii\*(Aq,
\&                \*(Aqboundary\*(Aq => \*(Aq\-\-\-ABC\-\-\-\*(Aq);
\&
\&    # Get an attribute, or undefined if not present:
\&    print "no id!"  if defined($field\->param(\*(Aqid\*(Aq));
\&
\&    # Same, but use empty string for missing values:
\&    print "no id!"  if ($field\->paramstr(\*(Aqid\*(Aq) eq \*(Aq\*(Aq);
\&
\&    # Output as string:
\&    print $field\->stringify, "\en";
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This is an abstract superclass of most MIME fields.  It handles
fields with a general syntax like this:
.PP
.Vb 3
\&    Content\-Type: Message/Partial;
\&        number=2; total=3;
\&        id="oc=jpbe0M2Yt4s@thumper.bellcore.com"
.Ve
.PP
Comments are supported \fIbetween\fR items, like this:
.PP
.Vb 3
\&    Content\-Type: Message/Partial; (a comment)
\&        number=2  (another comment) ; (yet another comment) total=3;
\&        id="oc=jpbe0M2Yt4s@thumper.bellcore.com"
.Ve
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.IP "set [\e%PARAMHASH | KEY=>VAL,...,KEY=>VAL]" 4
.IX Item "set [%PARAMHASH | KEY=>VAL,...,KEY=>VAL]"
\&\fIInstance method.\fR  Set this field.
The paramhash should contain parameter names
in \fIall lowercase\fR, with the special \f(CW"_"\fR parameter name
signifying the "default" (unnamed) parameter for the field:
.Sp
.Vb 8
\&   # Set up to be...
\&   #
\&   #     Content\-type: Message/Partial; number=2; total=3; id="ocj=pbe0M2"
\&   #
\&   $conttype\->set(\*(Aq_\*(Aq       => \*(AqMessage/Partial\*(Aq,
\&                  \*(Aqnumber\*(Aq  => 2,
\&                  \*(Aqtotal\*(Aq   => 3,
\&                  \*(Aqid\*(Aq      => "ocj=pbe0M2");
.Ve
.Sp
Note that a single argument is taken to be a \fIreference\fR to
a paramhash, while multiple args are taken to be the elements
of the paramhash themselves.
.Sp
Supplying undef for a hashref, or an empty set of values, effectively
clears the object.
.Sp
The self object is returned.
.IP "parse_params STRING" 4
.IX Item "parse_params STRING"
\&\fIClass/instance utility method.\fR
Extract parameter info from a structured field, and return
it as a hash reference.  For example, here is a field with parameters:
.Sp
.Vb 3
\&    Content\-Type: Message/Partial;
\&        number=2; total=3;
\&        id="oc=jpbe0M2Yt4s@thumper.bellcore.com"
.Ve
.Sp
Here is how you'd extract them:
.Sp
.Vb 6
\&    $params = $class\->parse_params(\*(Aqcontent\-type\*(Aq);
\&    if ($$params{\*(Aq_\*(Aq} eq \*(Aqmessage/partial\*(Aq) {
\&        $number = $$params{\*(Aqnumber\*(Aq};
\&        $total  = $$params{\*(Aqtotal\*(Aq};
\&        $id     = $$params{\*(Aqid\*(Aq};
\&    }
.Ve
.Sp
Like field names, parameter names are coerced to lowercase.
The special '_' parameter means the default parameter for the
field.
.Sp
\&\fBNOTE:\fR This has been provided as a public method to support backwards
compatibility, but you probably shouldn't use it.
.IP "parse STRING" 4
.IX Item "parse STRING"
\&\fIClass/instance method.\fR
Parse the string into the instance.  Any previous information is wiped.
The self object is returned.
.Sp
May also be used as a constructor.
.IP "param PARAMNAME,[VALUE]" 4
.IX Item "param PARAMNAME,[VALUE]"
\&\fIInstance method.\fR
Return the given parameter, or undef if it isn't there.
With argument, set the parameter to that VALUE.
The PARAMNAME is case-insensitive.  A "_" refers to the "default" parameter.
.IP "paramstr PARAMNAME,[VALUE]" 4
.IX Item "paramstr PARAMNAME,[VALUE]"
\&\fIInstance method.\fR
Like \fBparam()\fR: return the given parameter, or \fIempty\fR if it isn't there.
With argument, set the parameter to that VALUE.
The PARAMNAME is case-insensitive.  A "_" refers to the "default" parameter.
.IP stringify 4
.IX Item "stringify"
\&\fIInstance method.\fR
Convert the field to a string, and return it.
.IP tag 4
.IX Item "tag"
\&\fIInstance method, abstract.\fR
Return the tag for this field.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::Field