Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Newsrc(3)	      User Contributed Perl Documentation	     Newsrc(3)

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

       o   reading and writing newsrc files

       o   adding and removing newsgroups

       o   changing the	order of newsgroups

       o   subscribing and unsubscribing from newsgroups

       o   testing whether groups exist	and are	subscribed

       o   marking and unmarking articles

       o   testing whether articles are	marked

       o   returning lists of newsgroups

       o   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
   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
       o   Neil	Bowers <neilb@cre.canon.co.uk>

       o   Matthew Darwin <matthew@davin.ottawa.on.ca>

       o   Philip Hallstrom <philip.hallstrom@cendantsoft.com>

       o   M. Hedlund <hedlund@best.com>

       o   Bruce J. Keeler <bruce@gridpoint.com>

       o   Chris Leach <Chris.Leach@epa.ericsson.se>

       o   Abhijit Menon-Sen <ams@wiw.org>

       o   J.B.	Nicholson-Owens	<jbn@pop-a-wheelie.midwest.net>

       o   Lars	Balker Rasmussen <gnort@daimi.aau.dk>

       o   Nicholas Redgrave <baron@bologrew.net>

       o   Mike	Stok <mike@stok.co.uk>

       o   Bennett Todd	<bet@onyx.interactive.net>

       o   Larry W. Virden <lvirden@cas.org>

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

perl v5.32.1			  2013-04-15			     Newsrc(3)

NAME | SYNOPSIS | REQUIRES | EXPORTS | DESCRIPTION | NEWSRC FILES | NEWSGROUP ORDER | METHODS | DIAGNOSTICS | NOTES | ACKNOWLEDGMENTS | AUTHOR | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=News::Newsrc&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help