NAME

News::Article::Ref - reference functions for news articles

SYNOPSIS

  use News::Article::Ref;

  my $date = "Wed, 06 Mar 2002 11:23:10 -0600";
  my $gooddate = News::Article::Ref->valid_date($date);

  my $messageid = '<godwin-20020306172310$31f9@news.killfile.org>';
  my $goodmid = News::Article::Ref->valid_messageid($messageid);

Further functions are below.

DESCRIPTION

News::Article::Ref is a module for determining if a news article is technically suited for Usenet - ie, it checks to see if it follows all of Usenet's technical rules, as set down in the RFCs. This is useful for moderation 'bots and other news processing.

The current specifications are based on a combination of RFC1036 and RFC1036bis. This probably isn't the best idea, but it works for now.

News::Article::Ref exports nothing.

USAGE

Validation Methods

The following methods validate the information already in a header - ie, they check to see if it's valid with current Usenet specifications. This may be more or less restrictive than any given news server will require, but it's a good general rule to follow the rules regardless.

valid_header ( HEADER, CONTENTS )

Verifies that the CONTENTS of HEADER are valid. Checks From, Subject, Newsgroups, Message-ID, Path, Date, Followup-to, Expires, Reply-To, Sender, References, Control, Distribution, Summary, Approved, Lines, Organization, and Supersedes; all other headers are assumed to be unnecessary but okay.

Note that many of these functions are available below.

valid_headers ( HEADERS )

Takes an array of headers HEADERS, and verifies that together they make up a valid set of headers for a news article. This means, in general, that each header is valid, and that enough headers are there to be posted. Takes advantage of valid_headers(). Returns 1 if valid, 0 otherwise.

valid_body ( BODY )

Verifies that BODY is a valid message body for the article. Currently just checks to make sure that there *is* a body; this may change later. Returns 1 if valid, 0 otherwise.

valid_article ( ARTICLE )

Takes a whole ARTICLE as input, and does both verify_headers() and verify_body() on it. Returns 1 if the article is valid, 0 otherwise.

valid_messageid ( ID )

Determines whether ID is a valid Message-ID, which is of the general form '<unique.string4159@site.com.invalid>'. Returns 1 if yes, 0 otherwise.

valid_date ( DATE )

Determines whether DATE is a valid Date header, which is of the general form 'Wed, 06 Mar 2002 11:23:10 -0600'. Returns 1 if yes, 0 otherwise.

valid_from ( ADDRESS )

Verifies that the email address is "valid" - not that it delivers, but that it follows the proper form. ADDRESS can take one of three forms:

  tskirvin@killfile.org
  Tim Skirvin <tskirvin@killfile.org>
  tskirvin@killfile.org (Tim Skirvin)

Returns 1 if valid, 0 otherwise.

valid_path ( PATH )

Determines if PATH is valid for the Path: header. Takes the form 'news.meat.net!news.killfile.org!local-form'. Returns 1 if valid, 0 otherwise.

valid_groupname ( GROUPNAME )

Determines if the given GROUPNAME is a valid newsgroup name - letters and numbers only, with '.' as a separator. Returns 1 if valid, 0 otherwise.

valid_newsgroups ( NEWSGROUPS )

Determines of NEWSGROUPS is a valid Newsgroups: header - each group name must be separated by only a comma, and new groups can be repeated. Returns 1 if valid, 0 otherwise.

valid_subject ( SUBJECT )

Determines if SUBJECT is a valid subject header. This isn't too tough - it just has to be not blank. Returns 1 if valid, 0 otherwise.

valid_control ( LINE )

Determines if LINE is a valid Control: header. This is fairly tricky, because there are many types of control headers:

  cancel MESSAGEID
  ihave  MESSAGEID [HOST]
  sendme MESSAGEID [HOST]
  newgroup GROUPNAME [moderated|unmoderated]
  rmgroup GROUPNAME
  sendsys 
  version
  checkgroups

Returns 1 if valid, 0 otherwise.

Create-New-Entry Methods

The following methods can be used to create new data suitable for using in article headers.

create_messageid ( [ PREFIX [, DOMAIN ]] )

Creates a valid message-ID based on PREFIX, DOMAIN, and the current time. Based on add_message_id() from News::Article.

create_date ( [TIME] )

Creates a valid Date: header from TIME (seconds since the epoch), or the current time if not offered. Based on add_date() from News::Article.

TODO

Put some clean_* functions somewhere - ie clean_date(), which would make a canonical date header for the article based on whatever it's offered. This wouldn't necessarily go in this module, though.

Include some debugging information, so that the user can determine *how* there were problems. This will involve some major re-writes.

Choose which RFC to follow.

AUTHOR

Tim Skirvin <tskirvin@killfile.org>

COPYRIGHT

This code may be distributed under the same terms as Perl itself.