Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Article(3)	      User Contributed Perl Documentation	    Article(3)

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

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.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 1574:
	   You forgot a	'=back'	before '=head1'

perl v5.24.1			  2002-08-11			    Article(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | CAVEATS | AUTHOR | COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=News::Article&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help