NAME

       MIME::Field::ParamVal - subclass of Mail::Field, for structured MIME fields

SYNOPSIS

           # Create an object for a content-type field:
           $field = new Mail::Field 'Content-type';

           # Set some attributes:
           $field->param('_'        => 'text/html');
           $field->param('charset'  => 'us-ascii');
           $field->param('boundary' => '---ABC---');

           # Same:
           $field->set('_'        => 'text/html',
                       'charset'  => 'us-ascii',
                       'boundary' => '---ABC---');

           # Get an attribute, or undefined if not present:
           print "no id!"  if defined($field->param('id'));

           # Same, but use empty string for missing values:
           print "no id!"  if ($field->paramstr('id') eq '');

           # Output as string:
           print $field->stringify, "\n";

DESCRIPTION

       This is an abstract superclass of most MIME fields.  It handles fields with a general
       syntax like this:

           Content-Type: Message/Partial;
               number=2; total=3;
               id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

       Comments are supported between items, like this:

           Content-Type: Message/Partial; (a comment)
               number=2  (another comment) ; (yet another comment) total=3;
               id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

PUBLIC INTERFACE

       set [\%PARAMHASH | KEY=>VAL,...,KEY=>VAL]
           Instance method.  Set this field.  The paramhash should contain parameter names in all
           lowercase, with the special "_" parameter name signifying the "default" (unnamed)
           parameter for the field:

              # Set up to be...
              #
              #     Content-type: Message/Partial; number=2; total=3; id="ocj=pbe0M2"
              #
              $conttype->set('_'       => 'Message/Partial',
                             'number'  => 2,
                             'total'   => 3,
                             'id'      => "ocj=pbe0M2");

           Note that a single argument is taken to be a reference to a paramhash, while multiple
           args are taken to be the elements of the paramhash themselves.

           Supplying undef for a hashref, or an empty set of values, effectively clears the
           object.

           The self object is returned.

       parse_params STRING
           Class/instance utility method.  Extract parameter info from a structured field, and
           return it as a hash reference.  For example, here is a field with parameters:

               Content-Type: Message/Partial;
                   number=2; total=3;
                   id="oc=jpbe0M2Yt4s@thumper.bellcore.com"

           Here is how you'd extract them:

               $params = $class->parse_params('content-type');
               if ($$params{'_'} eq 'message/partial') {
                   $number = $$params{'number'};
                   $total  = $$params{'total'};
                   $id     = $$params{'id'};
               }

           Like field names, parameter names are coerced to lowercase.  The special '_' parameter
           means the default parameter for the field.

           NOTE: This has been provided as a public method to support backwards compatibility,
           but you probably shouldn't use it.

       parse STRING
           Class/instance method.  Parse the string into the instance.  Any previous information
           is wiped.  The self object is returned.

           May also be used as a constructor.

       param PARAMNAME,[VALUE]
           Instance method.  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.

       paramstr PARAMNAME,[VALUE]
           Instance method.  Like param(): return the given parameter, or empty if it isn't
           there.  With argument, set the parameter to that VALUE.  The PARAMNAME is case-
           insensitive.  A "_" refers to the "default" parameter.

       stringify
           Instance method.  Convert the field to a string, and return it.

       tag Instance method, abstract.  Return the tag for this field.

SEE ALSO

       Mail::Field