SYNOPSIS

  use Message::MIME::Type;

  my $type = Message::MIME::Type->parse_web_mime_type
      ('text/CSS; charset="US-ASCII"');
  
  is $type->type, 'text';
  is $type->subtype, 'css';
  is_deeply $type->attrs, ['charset'];
  is $type->param ('charset'), 'US-ASCII';
  
  $type->param (charset => 'utf-8');
  is $type->param ('charset'), 'utf-8';
  
  is $type->as_valid_mime_type, 'text/css; charset=us-ascii';
  is $type->as_valid_mime_type_with_no_params, 'text/css';

DESCRIPTION

An Message::MIME::Type object represents a MIME type (aka Internet Media Type), with or without parameters.

METHODS

$t = Message::MIME::Type->new_from_type_and_subtype ($type, $subtype)

Returns a new object whoes type is $type (string) and subtype is $subtype (string). $type and $subtype are ASCII case-insensitive.

$t = Message::MIME::Type->parse_web_mime_type ($string, [$onerror], [$levels])

Parses $string as a MIME type string and returns result object, if parsing ends successfully, or undef.

The $string is assumed as a "valid MIME type" defined in Web Applications 1.0 specification. If $string does not begin with a "valid MIME type with no parameters", the method returns undef. Otherwise, the method tries to parse the $string as a "valid MIME type" as far as possible.

If a code reference is specified as the second argument, $onerror, it is invoked whenever a parse error or warning is raised.

The third argument, $levels, can be specified to control error levels raised by the parser.

Although RFC 2616, which is referenced by Web Applications 1.0 specification, does not define how to parse MIME types, the parser does its best to do The Right Thing.

Strictly speaking, MIME and related specifications do no prohibit duplication of attributes (e.g. charset=a; charset=b). However, it is apparently useless in the real world and the Message::MIME::Type module does not support such unusual parameters. The parser reports a warning if there are more than one parameters with same attribute.

It is inappropriate to use this method to parse MIME types in mail or news messages; they have different syntax from HTTP messages.

$type = $t->type ([$type])

On getting, it returns the type part of the MIME type, in lowercase. The type part does not contain subtype.

On setting, it updates the type part of the MIME type. Note that the type is ASCII case-insensitive and therefore normalized by the setter.

$subtype = $t->subtype ([$subtype])

On getting, it returns the subtype part of the MIME type, in lowercase.

On setting, it updates the subtype part of the MIME type. Note that the subtype is ASCII case-insensitive and therefore normalized by the setter.

[$a1, $a2, ...] = $t->attrs

Retunrs a snapshot list (array reference) of attributes (i.e. names of parameters), in lowercase, ordered by alphabetical order.

$s = $t->param ($attr, [$value])

If there is only an argument, $attr, then the method returns the value of the parameter whoes attribute matches to $attr. Note that attribute is ASCII case-insensitive. If there is no such parameter, then undef is returned.

If there are two arguments, the method sets the value of the parameter whoes attribute matches to $attr to $value. If the parameter already exists, the previous value is discarded.

Note that the object does not distinguish whether the value is represented as a token or a quoted-string in the lexical form. Therefore, the method never returnes enclosing " characters nor \ in quoted-pair.

BOOL = $t->is_styling_lang

Returns whether the type represents a styling language, such as CSS.

BOOL = $t->is_text_based

Returns whether the type represents a text-based format.

BOOL = $t->is_composed_type

Returns whether the type is a composed type, i.e. message or multipart.

BOOL = $t->is_xml_mime_type

Returns whether the type is an XML MIME type according to Web Applications 1.0's definition.

$s = $t->as_valid_mime_type_with_no_params

Serializes the object in type and subtype pair separated by a / character, if possible, or returns undef. If it returns a non-undef value, it is always a "valid MIME type with no parameters" as per Web Applications 1.0 specification. In addition, it is always in lowercase.

$s = $t->as_valid_mime_type

Serializes the object in the form where type and subtype are separated by a / character and then followed by parameters, if possible, or returns undef. If it returns a non-undef value, it is always a "valid MIME type" as per Web Applications 1.0 specification. In addition, type, subtype, and attributes are in lowercase.

$t->validate ($onerror, no_required_params => BOOL)

Performs conformance checking of the object. It reports errors or wanrings such as "unregistered type error" or "private subtype warning" to the code reference, $onerror.

If the no_required_params parameter is set to true, it does not report errors on required parameters.

HISTORY

Part of this module is originally contained in Whatpm::IMTChecker module. Whatpm::IMTChecker is obsolete and removed from the manakai package in favor of this Message::MIME::Type module.

SEE ALSO

Message::MIME::Type::Definitions.

RFC 2048 "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" <http://tools.ietf.org/html/rfc2046>.

RFC 2616 "Hypertext Transfer Protocol -- HTTP/1.1" <http://tools.ietf.org/html/rfc2616>.

RFC 3023 "XML Media Types" <http://tools.ietf.org/html/rfc3023>.

RFC 4288 "Media Type Specifications and Registration Procedures" <http://tools.ietf.org/html/rfc4288>.

Web Applications 1.0 <http://www.whatwg.org/specs/web-apps/current-work/complete.html>.

MIME Media Types <http://www.iana.org/assignments/media-types/>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

Copyright 2007-2010 Wakaba <wakaba@suikawiki.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.