NAME

News::Newsrc - manage newsrc files

SYNOPSIS

  use News::Newsrc;
  $newsrc   = new News::Newsrc;
  $newsrc   = new News::Newsrc $file;
  $newsrc   = new News::Newsrc $file, create => 1;
  $ok       = $newsrc->load;
  $ok       = $newsrc->load             ( $file);
              $newsrc->import_rc        ( @lines);
              $newsrc->import_rc        (\@lines);
              $newsrc->save;
              $newsrc->save_as          ($file);
  @lines    = $newsrc->export_rc;
  $ok       = $newsrc-> add_group       ($group,             %options);
  $ok       = $newsrc->move_group       ($group,             %options);
  $ok       = $newsrc-> del_group       ($group);
              $newsrc->  subscribe      ($group,             %options);
              $newsrc->unsubscribe      ($group,             %options);
              $newsrc->mark             ($group,  $article , %options);
              $newsrc->mark_list        ($group, \@articles, %options);
              $newsrc->mark_range       ($group, $from, $to, %options);
              $newsrc->unmark           ($group,  $article , %options);
              $newsrc->unmark_list      ($group, \@articles, %options);
              $newsrc->unmark_range     ($group, $from, $to, %options);
       ... if $newsrc->exists           ($group);
       ... if $newsrc->subscribed       ($group);
       ... if $newsrc->marked           ($group, $article);
  $n        = $newsrc->  num_groups;
  @groups   = $newsrc->      groups;
  @groups   = $newsrc->  sub_groups;
  @groups   = $newsrc->unsub_groups;
  @articles = $newsrc->  marked_articles($group,             %options);
  @articles = $newsrc->unmarked_articles($group, $from, $to, %options);
  $articles = $newsrc->get_articles     ($group,             %options);
  $ok       = $newsrc->set_articles     ($group, $articles,  %options);

REQUIRES

Perl 5.6.0, Set::IntSpan 1.17

EXPORTS

Nothing

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
• changing the order of 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.

Lines containing only whitespace are ignored. Whitespace within a line is ignored.

Group

The group is the name of the newsgroup. A group name may not contain colons (:) or exclamation 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.

NEWSGROUP ORDER

"News::Newsrc" preserves the order of newsgroups in a newsrc file: if a file is loaded and then saved, the newsgroup order will be unchanged.

Methods that add or move newsgroups affect the newsgroup order. By default, these methods put newsgroups at the end of the newsrc file. Other locations may be specified by passing an %options hash with a "where" key to the method. Recognized locations are:

"where" => 'first'

Put the newsgroup first.

"where" => 'last'

Put the newsgroup last.

"where" => 'alpha'

Put the newsgroup in alphabetical order.

If the other newsgroups are not sorted alphabetically, put the group at an arbitrary location.

"where" => [ "before" => $group ]

Put the group immediately before $group.

If $group does not exist, put the group last.

"where" => [ "after" => $group ]

Put the group immediately after $group.

If $group does not exist, put the group last.

"where" => [ "number" => $n ]

Put the group at position $n in the group list. Indices are zero-based. Negative indices count backwards from the end of the list.

METHODS

$newsrc = "new" "News::Newsrc"

$newsrc = "new" "News::Newsrc" $file, %options

Creates and returns a "News::Newsrc" object.

If $file is specified, "new" loads the newsgroups in $file into the object. Subsequent calls to "save" will write to $file.

If $file exists and the load fails, "new" "die"s.

If $file doesn't exist and the "create => 1" option is supplied in %options, then "new" doesn't load any newsgroups.

If $file doesn't exist and the "create => 1" option is not supplied in %options, then "new" dies.

$ok = $newsrc->"load"

$ok = $newsrc->"load"($file)

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

If $file can't be opened, "load" discards existing data from $newsrc and returns null.

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

$newsrc->"import_rc"(@lines)

$newsrc->"import_rc"([@lines])

Imports the newsgroups in @lines into $newsrc. Any existing data in $newsrc is discarded.

Each line in @lines describes a single newsgroup, and must have the format described in "NEWSRC FILES". If @lines contains invalid lines, "import_rc" will "die". When this happens, the state of $newsrc is undefined.

"import_rc" accepts either an array or an array reference.

$newsrc->"save"

Writes the contents of $newsrc 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" will "die" if there is an error writing the file.

$newsrc->"save_as"($file)

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

"save_as" will "die" if there is an error writing the file.

@lines = $newsrc->"export_rc"

Returns the contents of $newsrc as a list of lines. Each line describes a single newsgroup, and has the format described in "NEWSRC FILES".

In scalar context, returns an array reference.

$ok = $newsrc->"add_group"($group, %options)

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

By default, $group is added to the end of the list of newsgroups. Other locations may be specified in %options; see "NEWSGROUP ORDER" for details.

By default, "add_group" does nothing if $group already exists. If the "replace" => 1 option is provided, then "add_group" will delete $group if it exists, and then add it.

"add_group" returns true iff $group was added.

$ok = $newsrc->"move_group"($group, %options)

Changes the position of $group in $newsrc according to %options. See "NEWSGROUP ORDER" for details.

If $group does not exist, "move_group" does nothing and returns false. Otherwise, it returns true.

$ok = $newsrc->"del_group"($group)

If $group exists in $newsrc, "del_group" removes it and returns true. The article list for $group is lost.

If $group does not exist in $newsrc, "del_group" does nothing and returns false.

$newsrc->"subscribe"($group, %options)

Subscribes to $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"unsubscribe"($group, %options)

Unsubscribes from $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"mark"($group, $article, %options)

Adds $article to the article list for $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"mark_list"($group, \@articles, %options)

Adds @articles to the article list for $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"mark_range"($group, $from, $to, %options)

Adds all the articles from $from to $to, inclusive, to the article list for $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"unmark"($group, $article, %options)

Removes $article from the article list for $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"unmark_list"($group, \@articles, %options)

Removes @articles from the article list for $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"unmark_range"($group, $from, $to, %options)

Removes all the articles from $from to $to, inclusive, from the article list for $group.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$newsrc->"exists"($group)

Returns true iff $group exists in $newsrc.

$newsrc->"subscribed"($group)

Returns true iff $group exists and is subscribed.

$newsrc->"marked"($group, $article)

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

$n = $newsrc->"num_groups"

Returns the number of groups in $newsrc.

@groups = $newsrc->"groups"

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

@groups = $newsrc->"sub_groups"

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

@groups = $newsrc->"unsub_groups"

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

@articles = $newsrc->"marked_articles"($group)

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

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

@articles = $newsrc->"unmarked_articles"($group, $from, $to, %options)

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.

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

$articles = $newsrc->"get_articles"($group, %options)

Returns the article list for $group as a string, in the format described in "NEWSRC FILES".

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

If you plan to do any nontrivial processing on the article list, consider converting it to a "Set::IntSpan" object:

  $articles = Set::IntSpan->new($newsrc->get_articles('alt.foo'))
    

$ok = $newsrc->"set_articles"($group, $articles, %options)

Sets the article list for $group. Any existing article list is lost.

$articles is a string, as described in "NEWSRC FILES".

$group will be created if it does not exist. Its location may be specified in %options; see "NEWSGROUP ORDER" for details.

If $articles does not have the format described in "NEWSRC FILES", "set_articles" does nothing and returns false. Otherwise, it returns true.

DIAGNOSTICS

Bad newsrc line

A line in the newsrc file does not have the format described in "NEWSRC FILES".

Bad article list

The article list for a newsgroup does not have the format described in "NEWSRC FILES".

News::Newsrc::save_as: Can't rename $file, $file.bak: $!

News::Newsrc::save_as: Can't open $file: $!

News::Newsrc::format: Can't write $file: $!

NOTES

  BEGIN { $Set::IntSpan::integer = 1 }
  use News::Newsrc;

ACKNOWLEDGMENTS

• Neil Bowers <neilb@cre.canon.co.uk>
• Matthew Darwin <matthew@davin.ottawa.on.ca>
• Philip Hallstrom <philip.hallstrom@cendantsoft.com>
• M. Hedlund <hedlund@best.com>
• Bruce J. Keeler <bruce@gridpoint.com>
• Chris Leach <Chris.Leach@epa.ericsson.se>
• Abhijit Menon-Sen <ams@wiw.org>
• J.B. Nicholson-Owens <jbn@pop-a-wheelie.midwest.net>
• Lars Balker Rasmussen <gnort@daimi.aau.dk>
• Nicholas Redgrave <baron@bologrew.net>
• Mike Stok <mike@stok.co.uk>
• Bennett Todd <bet@onyx.interactive.net>
• Larry W. Virden <lvirden@cas.org>
• Chris Szurgot <szurgot@itribe.net>

AUTHOR

Steven McDougall, swmcd@world.std.com

SEE ALSO

perl(1), Set::IntSpan

COPYRIGHT

Copyright 1996-2013 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.