Newsrc(3pm)

📦

version 1.11 · 2 versions

1.11 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
1.11 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

News::Newsrc — bestie, it manages your newsrc files 💖 (this is the Newsrc(3pm) page, Perl module edition, and she's a whole icon)

🌸 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 — that's the whole guest list, no gatekeeping beyond that 🫶

💅 EXPORTS 💅

Nothing. Literally nothing. She gives you nothing on a silver platter, you have to say News::Newsrc-> like a grown-up. Periodt.

👑 DESCRIPTION 👑

News::Newsrc manages newsrc files, of the style

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

and no cap, that colon-vs-exclamation thing is the entire personality of a newsrc file. 💀

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

Like… she does everything. Main character energy, honestly. 🔥

🦋 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. She's not gonna shuffle your vibes behind your back, bestie. 🫶

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. (yeah, she said arbitrary, she's doing her best 😭)
"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.

ok but the "if $group does not exist, put the group last" thing is the module's way of saying whatever, close enough and honestly? relatable. 🙈

✨ METHODS ✨

`new`

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

Okay bestie, this is the constructor — the birth of your News::Newsrc object. ✨ It creates and returns one.

If you pass $file, new loads the newsgroups from that file into the object. After that, every save call writes right back to $file. 💾

If $file exists but the load fails, new dies — no cap.

If $file doesn't exist and you slid the create => 1 option into %options, then new doesn't load any newsgroups. (There's nothing to load, bestie.) 🫶

But if $file doesn't exist and you did not pass create => 1, then new dies. Periodt.

`load`

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

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

If $file can't be opened, load discards existing data from $newsrc and returns null. (So it still wipes the slate, even on a fail. Iconic? Maybe not.)

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

`import_rc`

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

`save`

$newsrc->"save"

Writes the contents of $newsrc back to the file from which it was loaded. 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.

`save_as`

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

`export_rc`

@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. 🦋

`add_group`

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

`move_group`

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

`del_group`

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

`subscribe`

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

`unsubscribe`

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

`mark`

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

`mark_list`

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

`mark_range`

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

`unmark`

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

`unmark_list`

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

`unmark_range`

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

`exists`

$newsrc->"exists"($group)

Returns true iff $group exists in $newsrc. ✅

`subscribed`

$newsrc->"subscribed"($group)

Returns true iff $group exists and is subscribed. 💖

`marked`

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

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

`num_groups`

$n = $newsrc->"num_groups"

Returns the number of groups in $newsrc. 🔢

`groups`

@groups = $newsrc->"groups"

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

`sub_groups`

@groups = $newsrc->"sub_groups"

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

`unsub_groups`

@groups = $newsrc->"unsub_groups"

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

`marked_articles`

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

`unmarked_articles`

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

`get_articles`

$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'))

`set_articles`

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

Error Handling

"Don't test for errors that you can't handle."

load returns null if it can't open the newsrc file, and dies if the newsrc file contains invalid data. This isn't as schizophrenic as it seems. 😌

There are several ways a program could handle an open failure on the newsrc file. It could prompt the user to reenter the file name. It could assume that the user doesn't have a newsrc file yet. If it doesn't want to handle the error, it could go ahead and die. 💀

On the other hand, it is very difficult for a program to do anything sensible if the newsrc file opens successfully and then turns out to contain invalid data. Was there a disk error? Is the file corrupt? Did the user accidentally specify his kill file instead of his newsrc file? And what are you going to do about it? 😭

Rather than try to handle an error like this, it's probably better to die and let the user sort things out. By the same rational, save and save_as die on failure. 🫶

Programs that must retain control can use eval{...} to protect calls that may die. For example, Perl/Tk runs all callbacks inside an eval{...}. If a callback dies, Perl/Tk regains control and displays $@ in a dialog box. The user can then decide whether to continue or quit from the program. 🎀

`"import_rc"`/`"export_rc"`

I was going to call these methods "import" and "export", but "import" turns out not to be a good name for a method, because "use" also calls "import", and expects different semantics. 🤔

I added the "_rc" suffix to "import" to avoid this conflict. It's reasonably short and somewhat mnemonic (the module manages newsrc files). I added the same suffix to "export" for symmetry. ✨

`use integer`

Up until version 1.09, "News::Newsrc" specified "use integer". As of 2012, users are reporting newsgroups with article numbers above 0x7fffffff, which break the underlying "Set::IntSpan" module on 32-bit processors. 💀

Version 1.10 removes the "use integer" from "News::Newsrc". This extends the usable range of "Set::IntSpan" to (typically) 9e15, which ought to be enough, even for usenet. 🌈

If you want "use integer" back, either for performance, or because you are somehow dependent on its semantics, write

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

See "Set::IntSpan" for more information. 👑

💖 ACKNOWLEDGMENTS 💖

Shoutout to the whole squad who made this happen — these are the real ones, the day-ones, the people who put in the work so you don't have to. Besties, this is your moment 🫶✨

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> — the actual main character who wrote this whole thing. Respect 💅

🔍 SEE ALSO 🔍

perl(1)
Set::IntSpan

📜 COPYRIGHT 📜

And that's the whole page, bestie!! 💖 You just read the manual for perl v5.36.0, dated 2022-11-19, from the Newsrc(3pm) page — and honestly? You ate. Go forth and sort_newsrc your little heart out 🦋🌸✨

📦 where this page comes from

debian bookworm: libnews-newsrc-perl 1.11-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libnews-newsrc-perl 1.11-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libnews-newsrc-perl 1.11-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libnews-newsrc-perl 1.11-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libnews-newsrc-perl 1.11-3 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Newsrc(3pm)

✨ NAME ✨

🌸 SYNOPSIS 🌸

🧚 REQUIRES 🧚

💅 EXPORTS 💅

👑 DESCRIPTION 👑

🦋 NEWSRC FILES 🦋

🎀 Group

🎀 Subscription mark

🎀 Article list

🌈 NEWSGROUP ORDER 🌈

✨ METHODS ✨

new

load

import_rc

save

save_as

export_rc

add_group

move_group

del_group

subscribe

unsubscribe

mark

mark_list

mark_range

unmark

unmark_list

unmark_range

exists

subscribed

marked

num_groups

groups

sub_groups

unsub_groups

marked_articles

unmarked_articles

get_articles

set_articles

💀 DIAGNOSTICS 💀

📝 NOTES 📝

Error Handling

"import_rc"/"export_rc"

use integer

💖 ACKNOWLEDGMENTS 💖

👑 AUTHOR 👑

🔍 SEE ALSO 🔍

📜 COPYRIGHT 📜

`new`

`load`

`import_rc`

`save`

`save_as`

`export_rc`

`add_group`

`move_group`

`del_group`

`subscribe`

`unsubscribe`

`mark`

`mark_list`

`mark_range`

`unmark`

`unmark_list`

`unmark_range`

`exists`

`subscribed`

`marked`

`num_groups`

`groups`

`sub_groups`

`unsub_groups`

`marked_articles`

`unmarked_articles`

`get_articles`

`set_articles`

`"import_rc"`/`"export_rc"`

`use integer`