News::Article - Object for handling Usenet articles in mail or news form.
See below for functions available.
An object for representing a Usenet article (or a mail
message). Primarily written for use with mail2news and/or moderation
programs. (Not really intended for transit use.)
Article exports nothing.
- new ()
-
- new ( SOURCE [,MAXSIZE [,MAXHEADS]] )
-
Use this to create a new Article object. Makes an empty article if no
parameters are specified, otherwise reads in an article from
SOURCE
as for read.
- clone ()
-
Create a new Article as an exact clone of the current one.
Returns a ref to the new object.
- envelope ( [SENDER] )
-
If
SENDER is specified, sets the envelope sender to the specified
value (which will then subsequently be used if the article is mailed).
Returns the (new or current) envelope sender in any case.
- rawheaders ()
-
Returns a list (or a reference to an array if in scalar context) of
the original header lines of the article, as read from the input
source. Terminating newlines are not included. (Continued headers are
returned as single strings with embedded newlines.)
- header_names ()
-
Returns a list of the names of all headers currently present
in the article.
- headers ([FIRST [,NEXT [,LAST]]])
-
Returns a list of all header strings with no terminating
newlines. Continued headers will have embedded newlines.
FIRST, NEXT and LAST are optional references to arrays of header
names. The order of the returned headers is as follows:
- headers specified by FIRST (one value only per name)
- headers in the order originally read in (if any)
- headers specified by NEXT (one value only per name)
- any remaining headers not named in LAST, sorted by name
- headers named in LAST (all values)
LAST overrides the original order of headers, but NEXT does not.
Headers named in LAST will also be grouped together by header name.
- headers_first (HDR...)
-
Set default ordering for headers().
- headers_next (HDR...)
-
Set default ordering for headers().
- headers_last (HDR...)
-
Set default ordering for headers().
- set_headers ( NAME, VALUE [, NAME, VALUE [...]] )
-
For each header name supplied, replace any current occurences of the
header with the specified value(s). Each value may be a single scalar,
or a reference to an array of values. Returns undef without completing
the assignments if any attempt is made to supply multiple values for a
unique header. Undef or empty values cause the header to be deleted.
(If an array is supplied, it is not copied. This is probably a mistake
and should not be relied on.)
- add_headers ( NAME, VALUE [, NAME, VALUE [...]] )
-
Add new header values without affecting existing ones. Each value is
either a single scalar, or a reference to an array of values. Returns
undef without completing if any attempt is made to supply duplicate
values for a unique header. (If an array reference is supplied, the
array is copied.)
- drop_headers ( NAME [, NAME [...]] )
-
Delete all values of the specified header(s).
- header ( NAME )
-
Returns a list of values for the specified header. Returns a null list
if the header does not exist. In scalar context, returns the first
value found or undef.
- rename_header ( SRC, DEST [, ACTION] )
-
Transform the name of a header without touching the value. Fails
if the source header does not exist. Returns undef on failure,
true on success.
Optional ACTION (may be ``drop'', ``clobber'', ``add'', or ``fail''
(default)), specifies what to do if both source and destination exist:
ACTION PREVIOUS DEST
drop unchanged (SRC dropped)
clobber dropped (SRC replaces DEST)
add preserved (SRC added to DEST)
fail unchanged (operation fails)
- body ()
-
Return the body of the article as a list of lines (no newlines),
or a reference to an array in scalar context (the array may be
modified in this case).
- lines ()
-
Returns the number of lines in the article body.
- bytes ()
-
Returns the total size of the article body, not counting newlines.
- set_body ( BODY )
-
Replace the current article body with the specified text. Expects a
list, each item of which is either one line, or multiple lines
separated by newlines. (Trailing newlines on the values are ignored.)
- add_body ( BODY )
-
Append the specified text to the current article body. Expects a
list, each item of which is either one line, or multiple lines
separated by newlines, or a reference to an array of lines. (Trailing
newlines on the values are ignored.)
- trim_blank_lines ()
-
Remove any trailing blank lines from the article body. Returns the
number of lines removed.
- read_headers ( SOURCE, MAXSIZE )
-
Read article headers (terminated by an empty line) from the specified
source (see
read for defintion of allowed sources).
Gives up (returning undef) if more than MAXSIZE bytes are read. Returns
the amount read.
- read_body ( SOURCE, MAXSIZE )
-
Read an article body from the specified source (see
read). Stops at
end of file; fails (returning undef) if MAXSIZE is reached prior to
that point. Returns the number of bytes read (may be 0 if the body is
null).
Trailing blank lines are NOT removed (an incompatible, but regrettably
necessary, change from previous versions); see trim_blank_lines if you
need to do that.
- read ( SOURCE [,MAXSIZE [,MAXHEADS]] )
-
Reads in an article from
SOURCE.
SOURCE may be any of the following:
- a CODE ref, which is called to return lines or chunks of data
- an ARRAY ref, assumed to contain a list of lines with optional
line terminators
- a SCALAR ref, assumed to contain text with embedded newlines
- a scalar, assumed to be a filename, which is opened and read
- anything else is assumed to be a glob, reference to a glob,
or reference to a filehandle, and is read from accordingly
When reading in articles, MAXHEADS is the maximum header size to
read (default 8k), and MAXSIZE is the maximum article body size
(default 256k). If MAXSIZE is explicitly specified as 0, then no
attempt at reading the body is made. Returns the total number of bytes
read, or undef if either limit is reached or no headers were found.
- write ( FILE )
-
Write the entire article to the specified filehandle reference.
- write_unique_file ( DIR [,MODE] )
-
Write the article to a (hopefully) uniquely-named file in the
specified directory. The file is written under a temporary name (with
a leading period) and relinked when complete. Returns 1 if successful,
otherwise undef.
MODE is the access mode to use for the created file (default 644);
this will be modified in turn by the current umask.
The implementation is careful to avoid losing the file or clobbering
existing files even in the case of a name collision, but relies on
POSIX link() semantics and may fail on lesser operating systems
(or buggy NFS implementations).
- write_original ( FILE )
-
Write the original headers followed by the article body to the
specified filehandle reference.
- sendmail ( [COMMAND] )
-
Get or set the command and options that will be used to mail the
article. Defaults to a system dependent value such as
/usr/sbin/sendmail -oi -oem
- mail ( [RECIPIENTS...] )
-
Mails the article to the specified list of recipients, or to the
addressed recipients in the header (To, Cc, Bcc) if none are supplied.
Attempts to set the envelope sender to the stored envelope sender, if
set, so unset that before mailing if you do not want this behavior.
- post ( [CONN] )
-
Post the article. Avoids inews due to undesirable header munging and
unwarranted complaints to stderr. Takes an optional parameter which is
a Net::NNTP reference. If supplied, posts the article to it;
otherwise opens a new reader connection and posts to that.
Throws an exception containing the error message on failure.
- ihave ( [CONN] )
-
Inject the article. Takes an optional parameter which is a Net::NNTP
reference. If supplied, posts the article to it; otherwise opens a
new transport connection and posts to that. All required headers must
already be present, including Path and Message-ID.
Throws an exception containing the error message on failure.
- add_message_id ( [PREFIX [, DOMAIN] ] )
-
If the current article lacks a message-id, then create one.
- add_date ( [TIME] )
-
If the current article lacks a date, then add one (in local time).
If TIME is specified (numerical Unix time), it is used instead of the
current time.
- sign_pgpmoose ( GROUP, PASSPHRASE [, KEYID] )
-
Signs the article according to the PGPMoose spec. We require that pgp be
on the path to do this. Takes a ``group'' which can be either a newsgroup
or an address, a PGP password, and an optional key id and returns a null
list on success, the PGP error output as a list on failure.
If the key id is omitted, we will assume that if the group is an e-mail
address, the key id is that address surrounded by <>, and otherwise the
key id will be the group with a space on either side. This is so that one
can help PGP distinguish between the keys for (say) mod.config and
mod.config.status. The PGP key id should be something like:
Moderator of group.name <request-address@some.host>
The article to be signed must already have all of the headers needed by
PGPMoose (Newsgroups, From, Subject) or this will fail. Message-ID is
added if necessary.
- verify_pgpmoose ( GROUP )
-
Verifies an article signature according to the PGPMoose spec. We
require that pgp be on the path to do this. Takes a ``group'' which can
be either a newsgroup or an address, and an optional key id.
Looks for a X-Auth header matching the specified group or address, and
if found, checks the validity of the signature. If successful, returns
the signer identity (from the PGP output), otherwise returns false.
- sign_control ( KEYID, PASSPHRASE [, HEADER [...] ] )
-
Signs the article in the manner used for control messages. This is
derived from signcontrol, written by David Lawrence, but with fewer sanity
checks since we assume people know what they're doing. Caveat programmer.
We take a key id, a PGP password, and an optional list of extra
headers to add to the signature. By default, Subject, Control,
Message-ID, Date, From, and Sender are signed. Any signed header that
isn't present in the article will be signed with an empty value. Date
and Message-ID are automatically added if needed.
This module is not fully transparent. In particular:
These factors make it undesirable to use this module in news transit
applications.
This code may be used and/or distributed under the same terms as Perl
itself.