Provided by: libnews-article-perl_1.27-12_all bug

NAME

       News::Article - Object for handling Usenet articles in mail or news form.

SYNOPSIS

         use News::Article;

       See below for functions available.

DESCRIPTION

       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.)

USAGE

         use News::Article;

       Article exports nothing.

       Article objects must be created with the new method.

   Article Methods
       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 occurrences 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 definition 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.

CAVEATS

       This module is not fully transparent. In particular:

       -   Case of headers is smashed

       -   improper duplicate headers may be discarded

       -   Broken or dubious header names are not preserved

       These factors make it undesirable to use this module in news transit applications.

AUTHOR

       Written by Andrew Gierth <andrew@erlenstar.demon.co.uk>

       Thanks to Russ Allbery <rra@stanford.edu> for comments and suggestions.

COPYRIGHT

       Copyright 1997-2002 Andrew Gierth <andrew@erlenstar.demon.co.uk>

       This code may be used and/or distributed under the same terms as Perl itself.