Initial Commit

2025-12-03 16:38:10 +01:00
parent c5e26bf594
commit b732d8d4b5
17680 changed files with 5977495 additions and 2 deletions
--- a/database/perl/vendor/lib/Mail/Internet.pod
+++ b/database/perl/vendor/lib/Mail/Internet.pod
@@ -0,0 +1,387 @@
+=encoding utf8
+
+=head1 NAME
+
+Mail::Internet - manipulate email messages
+
+=head1 SYNOPSIS
+
+  use Mail::Internet;
+  my $msg = Mail::Internet->new(\*STDIN);
+
+=head1 DESCRIPTION
+
+This package implements reading, creating, manipulating, and writing email
+messages.  Sometimes, the implementation tries to be too smart, but in
+the general case it works as expected.
+
+If you start writing a B<new application>, you should use the L<Mail::Box>
+distribution, which has more features and handles messages much better
+according to the RFCs.  See L<http://perl.overmeer.net/mailbox/>.
+You may also chose L<MIME::Entity>, to get at least some multipart
+support in your application.
+
+=head1 METHODS
+
+=head2 Constructors
+
+=over 4
+
+=item $obj-E<gt>B<dup>()
+
+Duplicate the message as a whole.  Both header and body will be
+deep-copied: a new L<Mail::Internet|Mail::Internet> object is returned.
+
+=item $obj-E<gt>B<extract>(\@lines)
+
+Extract header and body from an ARRAY of message lines.  Requires an
+object already created with L<new()|Mail::Internet/"Constructors">, which contents will get overwritten.
+
+=item $obj-E<gt>B<new>( [$arg], [%options] )
+
+=item Mail::Internet-E<gt>B<new>( [$arg], [%options] )
+
+$arg is optional and may be either a file descriptor (reference to a GLOB)
+or a reference to an array. If given the new object will be
+initialized with headers and body either from the array of read from 
+the file descriptor.
+
+The L<Mail::Header::new()|Mail::Header/"Constructors"> %options C<Modify>, C<MailFrom> and C<FoldLength>
+may also be given.
+
+ -Option--Default
+  Body    []
+  Header  undef
+
+=over 2
+
+=item Body => ARRAY-of-LINES
+
+The value of this option should be a reference to an array which contains
+the lines for the body of the message. Each line should be terminated with
+C<\n> (LF). If Body is given then C<Mail::Internet> will not attempt to
+read the body from C<$arg> (even if it is specified).
+
+=item Header => Mail::Header
+
+The value of this option should be a L<Mail::Header|Mail::Header> object. If given then
+C<Mail::Internet> will not attempt to read a mail header from C<$arg>, if
+it was specified.
+
+=back
+
+=item $obj-E<gt>B<read>($fh)
+
+Read a message from the $fh into an already existing message
+object.  Better use L<new()|Mail::Internet/"Constructors"> with the $fh as first argument.
+
+=back
+
+=head2 Accessors
+
+=over 4
+
+=item $obj-E<gt>B<body>( [$body] )
+
+Returns the body of the message. This is a reference to an array.
+Each entry in the array represents a single line in the message.
+
+If I<$body> is given, it can be a reference to an array or an array, then
+the body will be replaced. If a reference is passed, it is used directly
+and not copied, so any subsequent changes to the array will change the
+contents of the body.
+
+=item $obj-E<gt>B<head>()
+
+Returns the C<Mail::Header> object which holds the headers for the current
+message
+
+=back
+
+=head2 Processing the message as a whole
+
+=over 4
+
+=item $obj-E<gt>B<as_mbox_string>( [$already_escaped] )
+
+Returns the message as a string in mbox format.  C<$already_escaped>, if
+given and true, indicates that L<escape_from()|Mail::Internet/"High-level functionality"> has already been called on
+this object.
+
+=item $obj-E<gt>B<as_string>()
+
+Returns the message as a single string.
+
+=item $obj-E<gt>B<print>( [$fh] )
+
+Print the header, body or whole message to file descriptor I<$fh>.
+I<$fd> should be a reference to a GLOB. If I<$fh> is not given the
+output will be sent to STDOUT.
+
+example: 
+
+    $mail->print( \*STDOUT );  # Print message to STDOUT
+
+=item $obj-E<gt>B<print_body>( [$fh] )
+
+Print only the body to the $fh (default STDOUT).
+
+=item $obj-E<gt>B<print_header>( [$fh] )
+
+Print only the header to the $fh (default STDOUT).
+
+=back
+
+=head2 Processing the header
+
+Most of these methods are simply wrappers around methods provided
+by L<Mail::Header|Mail::Header>.
+
+=over 4
+
+=item $obj-E<gt>B<add>(PAIRS)
+
+The PAIRS are field-name and field-content.  For each PAIR,
+L<Mail::Header::add()|Mail::Header/"Processing"> is called.  All fields are added after
+existing fields.  The last addition is returned.
+
+=item $obj-E<gt>B<combine>( $tag, [$with] )
+
+See L<Mail::Header::combine()|Mail::Header/"Processing">.
+
+=item $obj-E<gt>B<delete>( $tag, [$tags] )
+
+Delete all fields with the name $tag.  L<Mail::Header::delete()|Mail::Header/"Processing"> is doing the
+work.
+
+=item $obj-E<gt>B<fold>( [$length] )
+
+See L<Mail::Header::fold()|Mail::Header/"Processing">.
+
+=item $obj-E<gt>B<fold_length>( [$tag], [$length] )
+
+See L<Mail::Header::fold_length()|Mail::Header/"Accessors">.
+
+=item $obj-E<gt>B<get>( $tag, [$tags] )
+
+In LIST context, all fields with the name $tag are returned.  In SCALAR
+context, only the first field which matches the earliest $tag is returned.
+L<Mail::Header::get()|Mail::Header/"Processing"> is called to collect the data.
+
+=item $obj-E<gt>B<header>(\@lines)
+
+See L<Mail::Header::header()|Mail::Header/""Fake" constructors">.
+
+=item $obj-E<gt>B<replace>(PAIRS)
+
+The PAIRS are field-name and field-content.  For each PAIR,
+L<Mail::Header::replace()|Mail::Header/"Processing"> is called with index 0. If a $field is already
+in the header, it will be removed first.  Do not specified the same
+field-name twice.
+
+=back
+
+=head2 Processing the body
+
+=over 4
+
+=item $obj-E<gt>B<remove_sig>( [$nlines] )
+
+Attempts to remove a user's signature from the body of a message. It does this 
+by looking for a line equal to C<'-- '> within the last C<$nlines> of the
+message. If found then that line and all lines after it will be removed. If
+C<$nlines> is not given a default value of 10 will be used. This would be of
+most use in auto-reply scripts.
+
+=item $obj-E<gt>B<sign>(%options)
+
+Add your signature to the body.  L<remove_sig()|Mail::Internet/"Processing the body"> will strip existing
+signatures first.
+
+ -Option   --Default
+  File       undef
+  Signature  []
+
+=over 2
+
+=item File => FILEHANDLE
+
+Take from the FILEHANDLE all lines starting from the first C<< -- >>.
+
+=item Signature => STRING|ARRAY-of-LINES
+
+=back
+
+=item $obj-E<gt>B<tidy_body>()
+
+Removes all leading and trailing lines from the body that only contain
+white spaces.
+
+=back
+
+=head2 High-level functionality
+
+=over 4
+
+=item $obj-E<gt>B<escape_from>()
+
+It can cause problems with some applications if a message contains a line
+starting with C<`From '>, in particular when attempting to split a folder.
+This method inserts a leading C<`>'> on any line that matches the regular
+expression C</^>*From/>
+
+=item $obj-E<gt>B<nntppost>( [%options] )
+
+Post an article via NNTP.  Requires Net::NNTP to be installed.
+
+ -Option--Default
+  Debug   <false>
+  Host    <required>
+  Port    119
+
+=over 2
+
+=item Debug => BOOLEAN
+
+Debug value to pass to Net::NNTP, see L<Net::NNTP>
+
+=item Host => HOSTNAME|Net::NNTP object
+
+Name of NNTP server to connect to, or a Net::NNTP object to use.
+
+=item Port => INTEGER
+
+Port number to connect to on remote host
+
+=back
+
+=item $obj-E<gt>B<reply>(%options)
+
+Create a new object with header initialised for a reply to the current 
+object. And the body will be a copy of the current message indented.
+
+The C<.mailhdr> file in your home directory (if exists) will be read
+first, to provide defaults.
+
+ -Option  --Default
+  Exclude   []
+  Indent    '>'
+  Keep      []
+  ReplyAll  false
+
+=over 2
+
+=item Exclude => ARRAY-of-FIELDS
+
+Remove the listed FIELDS from the produced message.
+
+=item Indent => STRING
+
+Use as indentation string.  The string may contain C<%%> to get a single C<%>,
+C<%f> to get the first from name, C<%F> is the first character of C<%f>,
+C<%l> is the last name, C<%L> its first character, C<%n> the whole from
+string, and C<%I> the first character of each of the names in the from string.
+
+=item Keep => ARRAY-of-FIELDS
+
+Copy the listed FIELDS from the original message.
+
+=item ReplyAll => BOOLEAN
+
+Automatically include all To and Cc addresses of the original mail,
+excluding those mentioned in the Bcc list.
+
+=back
+
+=item $obj-E<gt>B<send>( [$type, [$args...]] )
+
+Send a Mail::Internet message using L<Mail::Mailer|Mail::Mailer>.  $type and $args are
+passed on to L<Mail::Mailer::new()|Mail::Mailer/"Constructors">.
+
+=item $obj-E<gt>B<smtpsend>( [%options] )
+
+Send a Mail::Internet message using direct SMTP to the given
+ADDRESSES, each can be either a string or a reference to a list of email
+addresses. If none of C<To>, <Cc> or C<Bcc> are given then the addresses
+are extracted from the message being sent.
+
+The return value will be a list of email addresses that the message was sent
+to. If the message was not sent the list will be empty.
+
+Requires Net::SMTP and Net::Domain to be installed.
+
+ -Option  --Default
+  Bcc       undef
+  Cc        undef
+  Debug     <false>
+  Hello     localhost.localdomain
+  Host      $ENV{SMTPHOSTS}
+  MailFrom  Mail::Util::mailaddress()
+  Port      25
+  To        undef
+
+=over 2
+
+=item Bcc => ADDRESSES
+
+=item Cc => ADDRESSES
+
+=item Debug => BOOLEAN
+
+Debug value to pass to Net::SMTP, see <Net::SMTP>
+
+=item Hello => STRING
+
+Send a HELO (or EHLO) command to the server with the given name.
+
+=item Host => HOSTNAME
+
+Name of the SMTP server to connect to, or a Net::SMTP object to use
+
+If C<Host> is not given then the SMTP host is found by attempting
+connections first to hosts specified in C<$ENV{SMTPHOSTS}>, a colon
+separated list, then C<mailhost> and C<localhost>.
+
+=item MailFrom => ADDRESS
+
+The e-mail address which is used as sender.  By default,
+L<Mail::Util::mailaddress()|Mail::Util/"FUNCTIONS"> provides the address of the sender.
+
+=item Port => INTEGER
+
+Port number to connect to on remote host
+
+=item To => ADDRESSES
+
+=back
+
+=item $obj-E<gt>B<unescape_from>(())
+
+Remove the escaping added by L<escape_from()|Mail::Internet/"High-level functionality">.
+
+=back
+
+=head1 SEE ALSO
+
+This module is part of the MailTools distribution,
+F<http://perl.overmeer.net/mailtools/>.
+
+=head1 AUTHORS
+
+The MailTools bundle was developed by Graham Barr.  Later, Mark
+Overmeer took over maintenance without commitment to further development.
+
+Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
+Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
+Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
+For other contributors see ChangeLog.
+
+=head1 LICENSE
+
+Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
+2001-2017 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
+
+This program is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+See F<http://www.perl.com/perl/misc/Artistic.html>
+