view release on metacpan or  search on metacpan

lib/MIME/Head.pm  view on Meta::CPAN

}
#------------------------------

=item from_file EXPR,OPTIONS

I<Class or instance method>.
For convenience, you can use this to parse a header object in from EXPR,
which may actually be any expression that can be sent to open() so as to
return a readable filehandle.  The "file" will be opened, read, and then
closed:

    ### Create a new header by parsing in a file:
    my $head = MIME::Head->from_file("/tmp/test.hdr");

Since this method can function as either a class constructor I<or>
an instance initializer, the above is exactly equivalent to:

    ### Create a new header by parsing in a file:
    my $head = MIME::Head->new->from_file("/tmp/test.hdr");

On success, the object will be returned; on failure, the undefined value.

The OPTIONS are the same as in new(), and are passed into new()
if this is invoked as a class method.

B<Note:> This is really just a convenience front-end onto C<read()>,
provided mostly for backwards-compatibility with MIME-parser 1.0.

=cut

sub from_file {
    my ($self, $file, @opts) = @_; ### at this point, $self is inst. or class!
    my $class = ref($self) ? ref($self) : $self;

    ### Parse:
    my $fh = IO::File->new($file, '<') or return error("open $file: $!");
    $fh->binmode() or return error("binmode $file: $!");  # we expect to have \r\n at line ends, and want to keep 'em.
    $self = $class->new($fh, @opts);      ### now, $self is instance or undef
    $fh->close or return error("close $file: $!");
    $self;
}

#------------------------------

=item read FILEHANDLE

I<Instance (or class) method.>
This initializes a header object by reading it in from a FILEHANDLE,
until the terminating blank line is encountered.
A syntax error or end-of-stream will also halt processing.

Supply this routine with a reference to a filehandle glob; e.g., C<\*STDIN>:

    ### Create a new header by parsing in STDIN:
    $head->read(\*STDIN);

On success, the self object will be returned; on failure, a false value.

B<Note:> in the MIME world, it is perfectly legal for a header to be
empty, consisting of nothing but the terminating blank line.  Thus,
we can't just use the formula that "no tags equals error".

B<Warning:> as of the time of this writing, Mail::Header::read did not flag
either syntax errors or unexpected end-of-file conditions (an EOF
before the terminating blank line).  MIME::ParserBase takes this
into account.

=cut

sub read {
    my $self = shift;      ### either instance or class!
    ref($self) or $self = $self->new;    ### if used as class method, make new
    $self->SUPER::read(@_);
}



#------------------------------

=back

=head2 Getting/setting fields

The following are methods related to retrieving and modifying the header
fields.  Some are inherited from Mail::Header, but I've kept the
documentation around for convenience.

=over 4

=cut

#------------------------------


#------------------------------

=item add TAG,TEXT,[INDEX]

I<Instance method, inherited.>
Add a new occurrence of the field named TAG, given by TEXT:

    ### Add the trace information:
    $head->add('Received',
               'from eryq.pr.mcs.net by gonzo.net with smtp');

Normally, the new occurrence will be I<appended> to the existing
occurrences.  However, if the optional INDEX argument is 0, then the
new occurrence will be I<prepended>.  If you want to be I<explicit>
about appending, specify an INDEX of -1.

B<Warning>: this method always adds new occurrences; it doesn't overwrite
any existing occurrences... so if you just want to I<change> the value
of a field (creating it if necessary), then you probably B<don't> want to use
this method: consider using C<replace()> instead.

=cut

### Inherited.

#------------------------------
#