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.

News::Newsrc Reference

$newsrc = new News::Newsrc 

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

$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 . If position is negative, count from the end of the list backwards n positions.

$newsrc->del_group(groupname) 

Removes specified newsgroup groupname from newsrc.

$newsrc->exists(groupname) 

Returns true if newsgroup groupname is in newsrc.

$newsrc->groups( ) 

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

$newsrc->load([filename]) 

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

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

$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

$newsrc->marked_articles(groupname) 

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

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

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

$newsrc->save( ) 

Saves changes to newsrc file.

$newsrc->save_as(filename) 

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

$newsrc->sub_groups( ) 

Returns list of subscribed groups in newsrc.

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

$newsrc->subscribed(groupname) 

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

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

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

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

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

$newsrc->unsub_groups( ) 

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

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