/ 
News-Newsrc-1.00
River stage zero No dependents
/ News::Newsrc

NAME

News::Newsrc - manage newsrc files

SYNOPSIS

    use News::Newsrc;

    $newsrc = new News::Newsrc;
    
    $newsrc->load();
    $newsrc->load($file);
    
    $newsrc->save();
    $newsrc->save_as($file);

    $newsrc->add_group($group);
    $newsrc->del_group($group);
	
    $newsrc->subscribe  ($group);
    $newsrc->unsubscribe($group);

    $newsrc->mark        ($group,  $article);
    $newsrc->mark_list   ($group, \@articles);
    $newsrc->mark_range  ($group, $from, $to);
    
    $newsrc->unmark      ($group,  $article);
    $newsrc->unmark_list ($group, \@articles);
    $newsrc->unmark_range($group, $from, $to);

    ... if $newsrc->exists    ($group);
    ... if $newsrc->subscribed($group);
    ... if $newsrc->marked    ($group, $article);

    @groups = $newsrc->groups();
    $groups = $newsrc->groups();

    @groups = $newsrc->sub_groups();
    $groups = $newsrc->sub_groups();

    @groups = $newsrc->unsub_groups();
    $groups = $newsrc->unsub_groups();
	
    @articles = $newsrc->marked_articles($group);
    $articles = $newsrc->marked_articles($group);

    @articles = $newsrc->unmarked_articles($group, $from, $to);
    $articles = $newsrc->unmarked_articles($group, $from, $to);

EXPORTS

None

REQUIRES

Perl 5.001

Set::IntSpan

DESCRIPTION

News::Newsrc manages newsrc files, of the style

alt.foo: 1-21,28,31-34
alt.bar! 3,5,9-2900,2902

Methods are provided for

  • reading and writing newsrc files

  • adding and removing newsgroups

  • subscribing and unsubscribing from newsgroups

  • testing whether groups exist and are subscribed

  • marking and unmarking articles

  • testing whether articles are marked

  • returning lists of newsgroups

  • returning lists of articles

NEWSRC FILES

A newsrc file is an ASCII file that lists newsgroups and article numbers. Each line of a newsrc file describes a single newsgroup. Each line is divided into three fields: a group, a subscription mark and an article list. Whitespace within a line is ignored.

Group

The group is the name of the newsgroup. A group name may not contain colons (:) or exclaimation points (!). Group names must be unique within a newsrc file. The group name is required.

Subscription mark

The subscription mark is either a colon (:), for subscribed groups, or an exclamation point (!), for unsubscribed groups. The subscription mark is required.

Article list

The article list is a comma-separated list of positive integers. The integers must be listed in increasing order. Runs of consecutive integers may be abbreviated a-b, where a is the first integer in the run and b is the last. The article list may be empty.

METHODS

new News::Newsrc

Creates and returns a News::Newsrc object. The object contains no newsgroups.

load()
load($file)

Loads the newsgroups in $file into a newsrc object. If $file is omitted, reads $ENV{HOME}/.newsrc. Any existing data in the object is discarded. Returns non-zero on success.

If $file can't be opened, load() discards existing data from the newsrc object and returns the undefined value.

If $file contains invalid lines, load() will die(). When this happens, the state of the newsrc object is undefined.

save()

Writes the contents of a newsrc object back to the file from which it was load()ed. If load() has not been called, writes to $ENV{HOME}/.newsrc. In either case, if the destination file exists, it is renamed to file.bak

save_as($file)

Writes the contents of a newsrc object to $file. If $file exists, it is renamed to $file.bak. Subsequent calls to save() will write to $file.

add_group($group)

Adds $group to the list of newsgroups in a newsrc object. $group is initially subscribed. The article list for $group is initially empty.

del_group($group)

Removes $group from the list of groups in a newsrc object. The article list for $group is lost.

subscribe($group)

Subscribes to $group. $group will be created if it does not exist.

unsubscribe($group)

Unscribes from $group. $group will be created if it does not exist.

mark($group, $article)

Adds $article to the article list for $group. $group will be created if it does not exist.

mark_list($group, \@articles)

Adds @articles to the article list for $group. $group will be created if it does not exist.

mark_range($group, $from, $to)

Adds all the articles from $from to $to, inclusive, to the article list for $group. $group will be created if it does not exist.

unmark($group, $article)

Removes $article from the article list for $group. $group will be created if it does not exist.

unmark_list($group, \@articles)

Removes @articles from the article list for $group. $group will be created if it does not exist.

unmark_range($group, $from, $to)

Removes all the articles from $from to $to, inclusive, from the article list for $group. $group will be created if it does not exist.

exists($group)

Returns true if $group exists in the newsrc object.

subscribed($group)

Returns true if $group exists and is subscribed.

marked($group, $article)

Returns true if $group exists and its article list contains $article.

groups()

Returns the list of groups in a newsrc object. In scalar context, returns an array reference.

sub_groups()

Returns the list of subscribed groups in a newsrc object. In scalar context, returns an array reference.

unsub_groups()

Returns the list of unsubscribed groups in a newsrc object. In scalar context, returns an array reference.

marked($group)

Returns the list of articles in the article list for $group. In scalar context, returns an array reference.

unmarked($group, $from, $to)

Returns the list of articles from $from to $to, inclusive, that do not appear in the article list for $group. In scalar context, returns an array reference.

DIAGNOSTICS

load() returns the undefined value if it can't open the newsrc file.

load will die() if the newsrc file contains invalid lines.

save() and save_as() will die() if they can't backup or write the newsrc file.

TESTING

To test News::Newsrc, run it as a stand-alone Perl program:

%perl Newsrc.pm
OK
%

Normal output is "OK"; anything else indicates a problem.

Add -v flags for verbose output; the more flags, the more output.

The test routines create temporary files named ".newsrc", "newsrc", ".newsrc.bak" and "newsrc.bak" in the current working directory; these files must not already exist.

AUTHOR

Steven McDougall <swm@cric.com>

COPYRIGHT

Copyright (c) 1996 Steven McDougall. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.