Book HomeJava and XSLTSearch this book

17.3. The News::Newsrc Module

Most Unix-based newsreaders parse and extract your newsgroup information from a .newsrc file. This file contains an entry for each newsgroup, with the name of the group and a comma-separated list of article numbers from 1 to the current article. The first entry in the list shows articles that have been read; the remaining entries list unread articles. Each entry also has a colon (:) following the name if you are subscribed to that newsgroup, or an exclamation point (!) if you are currently unsubscribed.

To read a newsgroup, your newsreader needs to be connected to an NNTP server. The newsreader then checks the .newsrc entry for that newsgroup to determine which articles you haven't read, and displays the first unread article. You can then read the articles sequentially or select which articles you want to read. When you "catch-up" a newsgroup by marking all the articles as "read", or when you exit from the newsreader program, your .newsrc file is updated to reflect your activity during that session.

The News::Newsrc module provides methods for managing your .newsrc file. Some of the functions it provides include letting you add, remove, or reorder newsgroups; subscribe to or unsubscribe from newsgroups; and mark articles as read or unmark them. Unless you tell it to rearrange the order of the newsgroups in .newsrc, News::Newsrc leaves the order unchanged.

17.3.1. News::Newsrc Reference

new

$newsrc = new News::Newsrc

Constructor. Creates a new News::Newsrc object that contains no newsgroups.

add_group

$newsrc->add_group(groupname[, options])

Adds newsgroup to .newsrc, as a subscribed group. Defaults to adding at the end. The arguments are:

groupname
Name of the newsgroup to add.

options
Hash with one entry, indicating where to put the newsgroup. Key is where, and possible values are:

after => group
Put immediately after newsgroup group, or last if group is not there.

alpha
Put in alphabetical order.

before => group
Put immediately before newsgroup group.

first
Put as first newsgroup.

last
Put as last newsgroup.

number => n
Put at position n, where the first position is 0. If position is negative, count from the end of the list backwards n positions.

del_group

$newsrc->del_group(groupname)

Removes specified newsgroup groupname from .newsrc.

exists

$newsrc->exists(groupname)

Returns true if newsgroup groupname is in .newsrc.

groups

$newsrc->groups(  )

Returns list of newsgroups in .newsrc. In scalar context, returns an array reference.

load

$newsrc->load([filename])

Loads newsgroups in filename into $newsrc, replacing any newsgroups that are already there. Defaults to $HOME/.newsrc.

mark

$newsrc->mark(groupname, article_number[, options])

Adds an article to the list for a specified newsgroup. Arguments are:

groupname
Newsgroup to add an article to.

article_number
Article number of the article to add.

options
Hash. See description under add_group.

marked

$newsrc->marked(groupname, article_number)

Returns true if the newsgroup exists and contains the specified article. Arguments are:

groupname
Group to report on

article_number
Number of the article to verify

marked_articles

$newsrc->marked_articles(groupname)

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

mark_list

$newsrc->mark_list(groupname, \@article_list[, options])

Adds articles to the list for a specified group. Arguments are:

groupname
Group to add articles to.

\@article_list
Reference to list of articles to add.

options
Hash. See description under add_group.

mark_range

$newsrc->mark_range(groupname, n, m[, options])

Adds articles in the specified range to the list. Arguments are:

groupname
Newsgroup to add articles to.

n
Number of the first article in the range.

m
Number of the last article in the range.

options
Hash. See description under add_group.

save

$newsrc->save(  )

Saves changes to .newsrc file.

save_as

$newsrc->save_as(filename)

Saves changes to specified file filename, rather than to .newsrc file.

sub_groups

$newsrc->sub_groups(  )

Returns list of subscribed groups in .newsrc.

subscribe

$newsrc->subscribe(groupname)

Subscribes to newsgroup groupname. If the group is not in .newsrc, it is added; its location may be given in options, as specified for add_group.

subscribed

$newsrc->subscribed(groupname)

Returns true if the group groupname exists and is subscribed to.

unmark

$newsrc->unmark(groupname, article_number[, options])

Removes specified article from the group list. Arguments are:

groupname
Newsgroup to remove articles from.

article_number
Article to remove.

options
Hash. See description under add_group.

unmarked_articles

$newsrc->unmarked_articles(groupname, n, m[, options])

Returns the list of articles from n to m, inclusive, that are not in the article list for the newsgroup. Arguments are:

groupname
Group to return articles from.

n
Number of the first article in the range.

m
Number of the last article in the range.

options
Hash. See description under add_group.

unmark_list

$newsrc->unmark_list(groupname, \@article_list[, options)

Removes specified list of articles from the group list. Arguments are:

groupname
Group to remove articles from.

\@article_list
Reference to list of articles to remove.

options
Hash. See description under add_group.

unmark_range

$newsrc->unmark_range(groupname, n, m[, options])

Removes a range of articles from n to mfrom .newsrc. Arguments are:

groupname
Group to remove articles from.

n
Number of the first article in the range.

m
Number of the last article in the range.

options
Hash. See description under add_group.

unsub_groups

$newsrc->unsub_groups(  )

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

unsubscribe

$newsrc->unsubscribe(groupname[, options])

Unsubscribes from newsgroup in .newsrc. If the group is not in .newsrc, it is added. Arguments are:

groupname
Group to unsubscribe from.

options
Hash. See description under add_group.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.