.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Newsrc 3pm"
.TH Newsrc 3pm "2007-12-10" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
News::Newsrc \- manage newsrc files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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        (\e@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, \e@articles, %options);
\&              $newsrc\->mark_range       ($group, $from, $to, %options);
\&
\&              $newsrc\->unmark           ($group,  $article , %options);
\&              $newsrc\->unmark_list      ($group, \e@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);
.Ve
.SH "REQUIRES"
.IX Header "REQUIRES"
Perl 5.6.0, Set::IntSpan 1.07
.SH "EXPORTS"
.IX Header "EXPORTS"
Nothing
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`News::Newsrc\*(C'\fR manages newsrc files, of the style
.PP
.Vb 2
\&    alt.foo: 1\-21,28,31\-34
\&    alt.bar! 3,5,9\-2900,2902
.Ve
.PP
Methods are provided for
.IP "\(bu" 4
reading and writing newsrc files
.IP "\(bu" 4
adding and removing newsgroups
.IP "\(bu" 4
changing the order of newsgroups
.IP "\(bu" 4
subscribing and unsubscribing from newsgroups
.IP "\(bu" 4
testing whether groups exist and are subscribed
.IP "\(bu" 4
marking and unmarking articles
.IP "\(bu" 4
testing whether articles are marked
.IP "\(bu" 4
returning lists of newsgroups
.IP "\(bu" 4
returning lists of articles
.SH "NEWSRC FILES"
.IX Header "NEWSRC FILES"
A newsrc file is an \s-1ASCII\s0 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 \fIgroup\fR, a \fIsubscription mark\fR and an \fIarticle list\fR.
.PP
Lines containing only whitespace are ignored.
Whitespace within a line is ignored.
.IP "Group" 4
.IX Item "Group"
The \fIgroup\fR is the name of the newsgroup.
A group name may not contain colons (:) or exclamation points (!).
.Sp
Group names must be unique within a newsrc file.
The group name is required.
.IP "Subscription mark" 4
.IX Item "Subscription mark"
The \fIsubscription mark\fR is either a colon (:), for subscribed groups,
or an exclamation point (!), for unsubscribed groups.
The subscription mark is required.
.IP "Article list" 4
.IX Item "Article list"
The \fIarticle list\fR 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.
.SH "NEWSGROUP ORDER"
.IX Header "NEWSGROUP ORDER"
\&\f(CW\*(C`News::Newsrc\*(C'\fR preserves the order of newsgroups in a newsrc file:
if a file is loaded and then saved,
the newsgroup order will be unchanged.
.PP
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 \fI\f(CI%options\fI\fR hash
with a \f(CW\*(C`where\*(C'\fR key to the method.
Recognized locations are:
.ie n .IP """where""\fR => \f(CW\*(Aqfirst\*(Aq" 4
.el .IP "\f(CWwhere\fR => \f(CW\*(Aqfirst\*(Aq\fR" 4
.IX Item "where => first"
Put the newsgroup first.
.ie n .IP """where""\fR => \f(CW\*(Aqlast\*(Aq" 4
.el .IP "\f(CWwhere\fR => \f(CW\*(Aqlast\*(Aq\fR" 4
.IX Item "where => last"
Put the newsgroup last.
.ie n .IP """where""\fR => \f(CW\*(Aqalpha\*(Aq" 4
.el .IP "\f(CWwhere\fR => \f(CW\*(Aqalpha\*(Aq\fR" 4
.IX Item "where => alpha"
Put the newsgroup in alphabetical order.
.Sp
If the other newsgroups are not sorted alphabetically,
put the group at an arbitrary location.
.ie n .IP """where""\fR => [ \f(CW""before""\fR => \fI\f(CI$group\fI ]" 4
.el .IP "\f(CWwhere\fR => [ \f(CWbefore\fR => \fI\f(CI$group\fI\fR ]" 4
.IX Item "where => [ before => $group ]"
Put the group immediately before \fI\f(CI$group\fI\fR.
.Sp
If \fI\f(CI$group\fI\fR does not exist,
put the group last.
.ie n .IP """where""\fR => [ \f(CW""after""\fR => \fI\f(CI$group\fI ]" 4
.el .IP "\f(CWwhere\fR => [ \f(CWafter\fR => \fI\f(CI$group\fI\fR ]" 4
.IX Item "where => [ after => $group ]"
Put the group immediately after \fI\f(CI$group\fI\fR.
.Sp
If \fI\f(CI$group\fI\fR does not exist,
put the group last.
.ie n .IP """where""\fR => [ \f(CW""number""\fR => \fI\f(CI$n\fI ]" 4
.el .IP "\f(CWwhere\fR => [ \f(CWnumber\fR => \fI\f(CI$n\fI\fR ]" 4
.IX Item "where => [ number => $n ]"
Put the group at position \fI\f(CI$n\fI\fR in the group list.
Indices are zero-based.
Negative indices count backwards from the end of the list.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "\fI\fI$newsrc\fI\fR = ""new""\fR \f(CW""News::Newsrc""" 4
.el .IP "\fI\f(CI$newsrc\fI\fR = \f(CWnew\fR \f(CWNews::Newsrc\fR" 4
.IX Item "$newsrc = new News::Newsrc"
.PD 0
.ie n .IP "\fI\fI$newsrc\fI\fR = ""new""\fR \f(CW""News::Newsrc""\fR \fI\f(CI$file\fI\fR, \fI\f(CI%options\fI" 4
.el .IP "\fI\f(CI$newsrc\fI\fR = \f(CWnew\fR \f(CWNews::Newsrc\fR \fI\f(CI$file\fI\fR, \fI\f(CI%options\fI\fR" 4
.IX Item "$newsrc = new News::Newsrc $file, %options"
.PD
Creates and returns a \f(CW\*(C`News::Newsrc\*(C'\fR object.
.Sp
If \fI\f(CI$file\fI\fR is specified,
\&\f(CW\*(C`new\*(C'\fR loads the newsgroups in \fI\f(CI$file\fI\fR into the object.
Subsequent calls to \f(CW\*(C`save\*(C'\fR will write to \fI\f(CI$file\fI\fR.
.Sp
If \fI\f(CI$file\fI\fR exists and the load fails, \f(CW\*(C`new\*(C'\fR \f(CW\*(C`die\*(C'\fRs.
.Sp
If \fI\f(CI$file\fI\fR doesn't exist and the \f(CW\*(C`create => 1\*(C'\fR option is supplied in \fI\f(CI%options\fI\fR,
then \f(CW\*(C`new\*(C'\fR doesn't load any newsgroups.
.Sp
If \fI\f(CI$file\fI\fR doesn't exist and the \f(CW\*(C`create => 1\*(C'\fR option is not supplied in \fI\f(CI%options\fI\fR,
then \f(CW\*(C`new\*(C'\fR dies.
.ie n .IP "\fI\fI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->""load""" 4
.el .IP "\fI\f(CI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWload\fR" 4
.IX Item "$ok = $newsrc->load"
.PD 0
.ie n .IP "\fI\fI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->""load""\fR(\fI\f(CI$file\fI)" 4
.el .IP "\fI\f(CI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWload\fR(\fI\f(CI$file\fI\fR)" 4
.IX Item "$ok = $newsrc->load($file)"
.PD
Loads the newsgroups in \fI\f(CI$file\fI\fR into \fI\f(CI$newsrc\fI\fR.
If \fI\f(CI$file\fI\fR is omitted, reads \fI\f(CI$ENV\fI{\s-1HOME\s0}/.newsrc\fR.
Any existing data in \fI\f(CI$newsrc\fI\fR is discarded.
Returns true on success.
.Sp
If \fI\f(CI$file\fI\fR can't be opened,
\&\f(CW\*(C`load\*(C'\fR discards existing data from \fI\f(CI$newsrc\fI\fR and returns null.
.Sp
If \fI\f(CI$file\fI\fR contains invalid lines, \f(CW\*(C`load\*(C'\fR will \f(CW\*(C`die\*(C'\fR.
When this happens, the state of \fI\f(CI$newsrc\fI\fR is undefined.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""import_rc""\fR(\fI\f(CI@lines\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWimport_rc\fR(\fI\f(CI@lines\fI\fR)" 4
.IX Item "$newsrc->import_rc(@lines)"
.PD 0
.ie n .IP "\fI\fI$newsrc\fI\fR\->""import_rc""\fR([\fI\f(CI@lines\fI])" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWimport_rc\fR([\fI\f(CI@lines\fI\fR])" 4
.IX Item "$newsrc->import_rc([@lines])"
.PD
Imports the newsgroups in \fI\f(CI@lines\fI\fR into \fI\f(CI$newsrc\fI\fR.
Any existing data in \fI\f(CI$newsrc\fI\fR is discarded.
.Sp
Each line in \fI\f(CI@lines\fI\fR describes a single newsgroup,
and must have the format described in \*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R".
If \fI\f(CI@lines\fI\fR contains invalid lines, \f(CW\*(C`import_rc\*(C'\fR will \f(CW\*(C`die\*(C'\fR.
When this happens, the state of \fI\f(CI$newsrc\fI\fR is undefined.
.Sp
\&\f(CW\*(C`import_rc\*(C'\fR accepts either an array or an array reference.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""save""" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWsave\fR" 4
.IX Item "$newsrc->save"
Writes the contents of \fI\f(CI$newsrc\fI\fR back to the file
from which it was \f(CW\*(C`load\*(C'\fRed.
If \f(CW\*(C`load\*(C'\fR has not been called, writes to \fI\f(CI$ENV\fI{\s-1HOME\s0}/.newsrc\fR.
In either case, if the destination \fIfile\fR exists,
it is renamed to \fIfile\fR\f(CW\*(C`.bak\*(C'\fR.
.Sp
\&\f(CW\*(C`save\*(C'\fR will \f(CW\*(C`die\*(C'\fR if there is an error writing the file.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""save_as""\fR(\fI\f(CI$file\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWsave_as\fR(\fI\f(CI$file\fI\fR)" 4
.IX Item "$newsrc->save_as($file)"
Writes the contents of \fI\f(CI$newsrc\fI\fR to \fI\f(CI$file\fI\fR.
If \fI\f(CI$file\fI\fR exists, it is renamed to \fI\f(CI$file\fI\fR\f(CW\*(C`.bak\*(C'\fR.
Subsequent calls to \f(CW\*(C`save\*(C'\fR will write to \fI\f(CI$file\fI\fR.
.Sp
\&\f(CW\*(C`save_as\*(C'\fR will \f(CW\*(C`die\*(C'\fR if there is an error writing the file.
.ie n .IP "\fI\fI@lines\fI\fR = \fI\f(CI$newsrc\fI\fR\->""export_rc""" 4
.el .IP "\fI\f(CI@lines\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWexport_rc\fR" 4
.IX Item "@lines = $newsrc->export_rc"
Returns the contents of \fI\f(CI$newsrc\fI\fR as a list of lines.
Each line describes a single newsgroup,
and has the format described in \*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R".
.Sp
In scalar context, returns an array reference.
.ie n .IP "\fI\fI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->""add_group""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWadd_group\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$ok = $newsrc->add_group($group, %options)"
Adds \fI\f(CI$group\fI\fR to the list of newsgroups in \fI\f(CI$newsrc\fI\fR.
\&\fI\f(CI$group\fI\fR is initially subscribed.
The article list for \fI\f(CI$group\fI\fR is initially empty.
.Sp
By default,
\&\fI\f(CI$group\fI\fR is added to the end of the list of newsgroups.
Other locations may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.Sp
By default,
\&\f(CW\*(C`add_group\*(C'\fR does nothing if \fI\f(CI$group\fI\fR already exists.
If the \f(CW\*(C`replace\*(C'\fR => \f(CW1\fR option is provided,
then \f(CW\*(C`add_group\*(C'\fR will delete \fI\f(CI$group\fI\fR if it exists,
and then add it.
.Sp
\&\f(CW\*(C`add_group\*(C'\fR returns true iff \fI\f(CI$group\fI\fR was added.
.ie n .IP "\fI\fI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->""move_group""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWmove_group\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$ok = $newsrc->move_group($group, %options)"
Changes the position of \fI\f(CI$group\fI\fR in \fI\f(CI$newsrc\fI\fR
according to \fI\f(CI%options\fI\fR.
See \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.Sp
If \fI\f(CI$group\fI\fR does not exist,
\&\f(CW\*(C`move_group\*(C'\fR does nothing and returns false.
Otherwise, it returns true.
.ie n .IP "\fI\fI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->""del_group""\fR(\fI\f(CI$group\fI)" 4
.el .IP "\fI\f(CI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWdel_group\fR(\fI\f(CI$group\fI\fR)" 4
.IX Item "$ok = $newsrc->del_group($group)"
If \fI\f(CI$group\fI\fR exists in \fI\f(CI$newsrc\fI\fR,
\&\f(CW\*(C`del_group\*(C'\fR removes it and returns true.
The article list for \fI\f(CI$group\fI\fR is lost.
.Sp
If \fI\f(CI$group\fI\fR does not exist in \fI\f(CI$newsrc\fI\fR,
\&\f(CW\*(C`del_group\*(C'\fR does nothing and returns false.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""subscribe""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWsubscribe\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->subscribe($group, %options)"
Subscribes to \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""unsubscribe""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWunsubscribe\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->unsubscribe($group, %options)"
Unsubscribes from \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""mark""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$article\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWmark\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$article\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->mark($group, $article, %options)"
Adds \fI\f(CI$article\fI\fR to the article list for \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""mark_list""\fR(\fI\f(CI$group\fI\fR, \fI\e@articles\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWmark_list\fR(\fI\f(CI$group\fI\fR, \fI\e@articles\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->mark_list($group, @articles, %options)"
Adds \fI\f(CI@articles\fI\fR to the article list for \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""mark_range""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$from\fI\fR, \fI\f(CI$to\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWmark_range\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$from\fI\fR, \fI\f(CI$to\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->mark_range($group, $from, $to, %options)"
Adds all the articles from \fI\f(CI$from\fI\fR to \fI\f(CI$to\fI\fR, inclusive,
to the article list for \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""unmark""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$article\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWunmark\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$article\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->unmark($group, $article, %options)"
Removes \fI\f(CI$article\fI\fR from the article list for \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""unmark_list""\fR(\fI\f(CI$group\fI\fR, \fI\e@articles\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWunmark_list\fR(\fI\f(CI$group\fI\fR, \fI\e@articles\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->unmark_list($group, @articles, %options)"
Removes \fI\f(CI@articles\fI\fR from the article list for \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""unmark_range""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$from\fI\fR, \fI\f(CI$to\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWunmark_range\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$from\fI\fR, \fI\f(CI$to\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$newsrc->unmark_range($group, $from, $to, %options)"
Removes all the articles from \fI\f(CI$from\fI\fR to \fI\f(CI$to\fI\fR, inclusive,
from the article list for \fI\f(CI$group\fI\fR.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""exists""\fR(\fI\f(CI$group\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWexists\fR(\fI\f(CI$group\fI\fR)" 4
.IX Item "$newsrc->exists($group)"
Returns true iff \fI\f(CI$group\fI\fR exists in \fI\f(CI$newsrc\fI\fR.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""subscribed""\fR(\fI\f(CI$group\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWsubscribed\fR(\fI\f(CI$group\fI\fR)" 4
.IX Item "$newsrc->subscribed($group)"
Returns true iff \fI\f(CI$group\fI\fR exists and is subscribed.
.ie n .IP "\fI\fI$newsrc\fI\fR\->""marked""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$article\fI)" 4
.el .IP "\fI\f(CI$newsrc\fI\fR\->\f(CWmarked\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$article\fI\fR)" 4
.IX Item "$newsrc->marked($group, $article)"
Returns true iff \fI\f(CI$group\fI\fR exists and its article list contains \fI\f(CI$article\fI\fR.
.ie n .IP "\fI\fI$n\fI\fR = \fI\f(CI$newsrc\fI\fR\->""num_groups""" 4
.el .IP "\fI\f(CI$n\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWnum_groups\fR" 4
.IX Item "$n = $newsrc->num_groups"
Returns the number of groups in \fI\f(CI$newsrc\fI\fR.
.ie n .IP "\fI\fI@groups\fI\fR = \fI\f(CI$newsrc\fI\fR\->""groups""" 4
.el .IP "\fI\f(CI@groups\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWgroups\fR" 4
.IX Item "@groups = $newsrc->groups"
Returns the list of groups in \fI\f(CI$newsrc\fI\fR,
in newsrc order.
In scalar context, returns an array reference.
.ie n .IP "\fI\fI@groups\fI\fR = \fI\f(CI$newsrc\fI\fR\->""sub_groups""" 4
.el .IP "\fI\f(CI@groups\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWsub_groups\fR" 4
.IX Item "@groups = $newsrc->sub_groups"
Returns the list of subscribed groups in \fI\f(CI$newsrc\fI\fR,
in newsrc order.
In scalar context, returns an array reference.
.ie n .IP "\fI\fI@groups\fI\fR = \fI\f(CI$newsrc\fI\fR\->""unsub_groups""" 4
.el .IP "\fI\f(CI@groups\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWunsub_groups\fR" 4
.IX Item "@groups = $newsrc->unsub_groups"
Returns the list of unsubscribed groups in \fI\f(CI$newsrc\fI\fR,
in newsrc order.
In scalar context, returns an array reference.
.ie n .IP "\fI\fI@articles\fI\fR = \fI\f(CI$newsrc\fI\fR\->""marked_articles""\fR(\fI\f(CI$group\fI)" 4
.el .IP "\fI\f(CI@articles\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWmarked_articles\fR(\fI\f(CI$group\fI\fR)" 4
.IX Item "@articles = $newsrc->marked_articles($group)"
Returns the list of articles in the article list for \fI\f(CI$group\fI\fR.
In scalar context, returns an array reference.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI@articles\fI\fR = \fI\f(CI$newsrc\fI\fR\->""unmarked_articles""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$from\fI\fR, \fI\f(CI$to\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI@articles\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWunmarked_articles\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$from\fI\fR, \fI\f(CI$to\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "@articles = $newsrc->unmarked_articles($group, $from, $to, %options)"
Returns the list of articles from \fI\f(CI$from\fI\fR to \fI\f(CI$to\fI\fR, inclusive,
that do \fBnot\fR appear in the article list for \fI\f(CI$group\fI\fR.
In scalar context, returns an array reference.
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.ie n .IP "\fI\fI$articles\fI\fR = \fI\f(CI$newsrc\fI\fR\->""get_articles""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$articles\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWget_articles\fR(\fI\f(CI$group\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$articles = $newsrc->get_articles($group, %options)"
Returns the article list for \fI\f(CI$group\fI\fR as a string,
in the format described in \*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R".
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.Sp
If you plan to do any nontrivial processing on the article list,
consider converting it to a \f(CW\*(C`Set::IntSpan\*(C'\fR object:
.Sp
.Vb 1
\&  $articles = Set::IntSpan\->new($newsrc\->get_articles(\*(Aqalt.foo\*(Aq))
.Ve
.ie n .IP "\fI\fI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->""set_articles""\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$articles\fI\fR, \fI\f(CI%options\fI)" 4
.el .IP "\fI\f(CI$ok\fI\fR = \fI\f(CI$newsrc\fI\fR\->\f(CWset_articles\fR(\fI\f(CI$group\fI\fR, \fI\f(CI$articles\fI\fR, \fI\f(CI%options\fI\fR)" 4
.IX Item "$ok = $newsrc->set_articles($group, $articles, %options)"
Sets the article list for \f(CW$group\fR.
Any existing article list is lost.
.Sp
\&\fI\f(CI$articles\fI\fR is a string,
as described in \*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R".
.Sp
\&\fI\f(CI$group\fI\fR will be created if it does not exist.
Its location may be specified in \fI\f(CI%options\fI\fR;
see \*(L"\s-1NEWSGROUP\s0 \s-1ORDER\s0\*(R" for details.
.Sp
If \fI\f(CI$articles\fI\fR does not have the format described in \*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R",
\&\f(CW\*(C`set_articles\*(C'\fR does nothing and returns false.
Otherwise, it returns true.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "Bad newsrc line" 4
.IX Item "Bad newsrc line"
A line in the newsrc file does not have the format described in
\&\*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R".
.IP "Bad article list" 4
.IX Item "Bad article list"
The article list for a newsgroup does not have the format described in
\&\*(L"\s-1NEWSRC\s0 \s-1FILES\s0\*(R".
.ie n .IP "News::Newsrc::save_as: Can't rename $file\fR, \f(CW$file.bak: $!" 4
.el .IP "News::Newsrc::save_as: Can't rename \f(CW$file\fR, \f(CW$file\fR.bak: $!" 4
.IX Item "News::Newsrc::save_as: Can't rename $file, $file.bak: $!"
.PD 0
.ie n .IP "News::Newsrc::save_as: Can't open $file: $!" 4
.el .IP "News::Newsrc::save_as: Can't open \f(CW$file:\fR $!" 4
.IX Item "News::Newsrc::save_as: Can't open $file: $!"
.ie n .IP "News::Newsrc::format: Can't write $file: $!" 4
.el .IP "News::Newsrc::format: Can't write \f(CW$file:\fR $!" 4
.IX Item "News::Newsrc::format: Can't write $file: $!"
.PD
.SH "NOTES"
.IX Header "NOTES"
.Sh "Error Handling"
.IX Subsection "Error Handling"
\&\*(L"Don't test for errors that you can't handle.\*(R"
.PP
\&\f(CW\*(C`load\*(C'\fR 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.
.PP
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.
.PP
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?
.PP
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,
\&\f(CW\*(C`save\*(C'\fR and \f(CW\*(C`save_as\*(C'\fR die on failure.
.PP
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.
.ie n .Sh """import_rc""\fP/\f(CW""export_rc"""
.el .Sh "\f(CWimport_rc\fP/\f(CWexport_rc\fP"
.IX Subsection "import_rc/export_rc"
I was going to call these methods \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`export\*(C'\fR,
but \f(CW\*(C`import\*(C'\fR turns out not to be a good name for a method,
because \f(CW\*(C`use\*(C'\fR also calls \f(CW\*(C`import\*(C'\fR,
and expects different semantics.
.PP
I added the \f(CW\*(C`_rc\*(C'\fR suffix to \f(CW\*(C`import\*(C'\fR to avoid this conflict.
It's reasonably short and somewhat mnemonic
(the module manages news\fIrc\fR files).
I added the same suffix to \f(CW\*(C`export\*(C'\fR for symmetry.
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
.IP "\(bu" 4
Neil Bowers <neilb@cre.canon.co.uk>
.IP "\(bu" 4
Matthew Darwin <matthew@davin.ottawa.on.ca>
.IP "\(bu" 4
Philip Hallstrom <philip.hallstrom@cendantsoft.com>
.IP "\(bu" 4
M. Hedlund <hedlund@best.com>
.IP "\(bu" 4
Bruce J. Keeler <bruce@gridpoint.com>
.IP "\(bu" 4
Chris Leach <Chris.Leach@epa.ericsson.se>
.IP "\(bu" 4
Abhijit Menon-Sen <ams@wiw.org>
.IP "\(bu" 4
J.B. Nicholson-Owens <jbn@pop\-a\-wheelie.midwest.net>
.IP "\(bu" 4
Lars Balker Rasmussen <gnort@daimi.aau.dk>
.IP "\(bu" 4
Mike Stok <mike@stok.co.uk>
.IP "\(bu" 4
Bennett Todd <bet@onyx.interactive.net>
.IP "\(bu" 4
Larry W. Virden <lvirden@cas.org>
.IP "\(bu" 4
Chris Szurgot <szurgot@itribe.net>
.SH "AUTHOR"
.IX Header "AUTHOR"
Steven McDougall, swmcd@world.std.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), Set::IntSpan
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1996\-2007 by Steven McDougall. This module is free
software; you can redistribute it and/or modify it under the same
terms as Perl itself.