MIME::Field::ParamVal (3)

Leading comments

Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/MIME::Field::ParamVal.3pm".)

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 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