- NAME
- SYNOPSIS
- DESCRIPTION

- effective_type - Access the effective MIME type
- get - Access header tags.
- set - Set a header tag.
- delete - Remove a header tag.
- size - Access the total size.
- preamble - Set or get the preamble.
- epilogue - Set or get the epilogue.
- mime_type - Set or get the MIME type.
- is_multipart - See if you have a multi-part part.
- parts - Access sub parts.
- multipart_boundary - Set or get the multi-part boundary.
- header_as_string - Access the whole header.
- split_field - Retrieve the emails split up into an array.
- suggest_encoding - Get a suggestion for encoding.
- recommended_filename - Figure out the file name.
- body_as_string - Get the body as a string.
- body_in - Find the body.
- body_data - Get the in memory body.
- body_handle - Get an IO handle to the body.
- body_path - Get the location of the file the body is in.

- COPYRIGHT
- VERSION

# NAME

GT::Mail::Parts - Data storage class for MIME parts

# SYNOPSIS

        use GT::Mail;

        my $mail = new GT::Mail;

        my $top_part = $mail->parse('/path/to/email');

        # Access the emails as an array
        my @to   = $top_part->split_field('to');
        my @from = $top_part->split_field('from');

        # Access to the header fields
        my $mailer  = $top_part->get('X-Mailer');
        my $subject = $top_part->get('Subject');

        # Access to this parts sub part
        if ($top_part->is_multipart) {
            my @parts = $top_parts->parts;
            for my $part (@parts) {

                # Access parts of the header
                print "Filename: ", $part->recommended_filename, "\n";
                print "Part is multi-part\n" if $part->is_multipart;

                # Get the body as a string
                my $body = $part->body_as_string;
            }
        }

        # Change who it is to
        $top_part->set('to', 'scott@gossamer-threads.com');

        # Remove the bcc line
        $top_part->delete('bcc');

# DESCRIPTION

GT::Mail::Parts is a class to provide methods to change and access a MIME messages. The object for this class is meant to be istansiated from the GT::Mail manpage.

## effective_type - Access the effective MIME type

        my $type = $obj->effective_type;

        if ($type eq 'application/octet-stream') {
            ...
        }

This method returns the effective MIME Type of this objects part.

## get - Access header tags.

        my $subj = $obj->get('Subject');

        # or if there is more than one
        my @recv = $obj->get('Received');

Used to access any of the tags in the header of the MIME part. If the tag requested is not present returns false. The first argument to this method is the name of he tag you want to extract. This is case insensitive.

## set - Set a header tag.

        # Change who the email is to
        $obj->set('to', 'scott@gossamer-threads.com');

        # Change the second Received tag
        $obj->set('Received', 'from unknown', 1);

Set any of the tags in the header. If the tag does not exist this will create it. This method takes three arguments. The first is the name of the tag to change or add, this is case insensitive. The second argument is the value for the tag. The third zero based optional argument is the position. The position will default to zero if it is not specified.

## delete - Remove a header tag.

        # Delete who the message is from
        $obj->delete('from');

This method deletes the tag specified by the first argument from this MIME part.

## size - Access the total size.

        my $size = $obj->size;

This method returns the total size of this part. This includes the header and the body.

## preamble - Set or get the preamble.

        # Retrieve the preamble
        my $pre = $obj->preamble;

        # Set the preamble
        $obj->preamble('This is a multi-part message in MIME format.');

This is a set get method for the preamble. The preamble is the part after the head but before the first MIME boundary. This method makes no since if this is not a multi-part part.

## epilogue - Set or get the epilogue.

        # Retrieve the epilogue
        my $ep = $obj->epilogue;

        # Set the epilogue
        $obj->epilogue('This is my cool epilogue');

This is a set get method for the epilogue. The epilogue is the part of the MIME part after the MIME boundary and before the next head. This method makes no since if this is not a multi-part part.

## mime_type - Set or get the MIME type.

        my ($type, $subtype) = split('/', $obj->mime_type);

This method returns the MIME type of this part. You can pass in an argument to change the MIME type as well. So you could do

        $obj->mime_type('text/plain');

This is probably not such a good idea unless you are constructing the email from scratch.

## is_multipart - See if you have a multi-part part.

        if ($obj->is_multipart) {
            # do some multi-part stuff
        }

Returns true is this part is a multi-part MIME part.

## parts - Access sub parts.

        my @parts = $obj->parts;

Returns the parts object this part contains. Returns false if this part does no have any sub parts. The parts objects that returns are from this same class. Any parts that are milti-part should contain parts.

## multipart_boundary - Set or get the multi-part boundary.

        my $boundary = $obj->multipart_boundary;

This returns the multi-part boundary for this part. Setting this is never needed and may be removed in the future. This method only makes since if you are working with a multi-part pert.

## header_as_string - Access the whole header.

        my $head = $obj->header_as_string;

This method creates and returns the header for this part. The returned header should be fully rfc822 compliant. Avoid calling this method more than once, as it will build the header from an internal data structure each time.

## split_field - Retrieve the emails split up into an array.

        my @to  = $obj->split_field; # Defaults to 'to'
        my @bcc = $obj->split_field('bcc');

This is mostly a utility method. It takes an option argument as to the field you want the email address from (default is to), it then splits the emails on '\s*,\s*' that is not inside quotes. Returns an array of the split up string.

## suggest_encoding - Get a suggestion for encoding.

        my $encode = $obj->suggest_encoding;

Returns a suggested encoding for the body of this message. This is useful to decide what encoding you should use for the body when building an email. This is used in the GT::Mail::Parse manpage to decide how to encode the message body.

## recommended_filename - Figure out the file name.

        my $file = $obj->recommended_filename;
        if ($file) {
            ...
        }

This method tries to figure out the file name of this part. This does not make much since if this part is not an attachment of some kind. Returns an empty string on failure.

## body_as_string - Get the body as a string.

This method returns the entire body of the MIME message as a string. You should not use this method if the body could be large.

## body_in - Find the body.

        my $in = $obj->body_in;
        my $body;

        if ($in eq 'MEMORY') {
            $body = $obj->body_data;
        }
        elsif ($in eq 'HANDLE') {
            $body = $obj->body_handle;
        }
        elsif ($in eq 'FILE') {
            $body = $obj->body_path;
        }

This method returns the location of the body. The location can be one of three things:

MEMORY

  The body is in a string.

HANDLE

  The body is in an IO handle.

FILE

  The body is in a file.

You would use this to decide what method to use to access the body. If the MIME message was parsed into GT::Mail::Parts using the GT::Mail::Parser manpage the body will always be in a FILE.

## body_data - Get the in memory body.

This method returns the body if it is stored in memory. Returns undefined if the body is not in memory.

## body_handle - Get an IO handle to the body.

This method returns a handle to the body if the body is stored in a handle for this part. Returns undefined if not.

## body_path - Get the location of the file the body is in.

This method returns the file path to the file the body is located in if the body for this part is stored in a file. Returns undefined if not.

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

$Revision: 1.84 $