home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _37f7f1bc38012902d07e60a0bdce4f84 < prev    next >
Text File  |  2000-03-23  |  25KB  |  542 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>News::Newsrc - manage newsrc files</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> News::Newsrc - manage newsrc files</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#requires">REQUIRES</A></LI>
  25.     <LI><A HREF="#exports">EXPORTS</A></LI>
  26.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  27.     <LI><A HREF="#newsrc files">NEWSRC FILES</A></LI>
  28.     <LI><A HREF="#newsgroup order">NEWSGROUP ORDER</A></LI>
  29.     <LI><A HREF="#methods">METHODS</A></LI>
  30.     <LI><A HREF="#diagnostics">DIAGNOSTICS</A></LI>
  31.     <LI><A HREF="#notes">NOTES</A></LI>
  32.     <UL>
  33.  
  34.         <LI><A HREF="#error handling">Error Handling</A></LI>
  35.         <LI><A HREF="#import_rc/export_rc"><CODE>import_rc</CODE>/<CODE>export_rc</CODE></A></LI>
  36.     </UL>
  37.  
  38.     <LI><A HREF="#author">AUTHOR</A></LI>
  39.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  40.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  41. </UL>
  42. <!-- INDEX END -->
  43.  
  44. <HR>
  45. <P>
  46. <H1><A NAME="name">NAME</A></H1>
  47. <P>News::Newsrc - manage newsrc files</P>
  48. <P>
  49. <HR>
  50. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  51. <UL>
  52. <LI>Linux</LI>
  53. <LI>Solaris</LI>
  54. <LI>Windows</LI>
  55. </UL>
  56. <HR>
  57. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  58. <PRE>
  59.   use News::Newsrc;
  60. </PRE>
  61. <PRE>
  62.  
  63.   $newsrc   = new News::Newsrc;</PRE>
  64. <PRE>
  65.  
  66.   $ok       = $newsrc->load;
  67.   $ok       = $newsrc->load             ($file);
  68.               $newsrc->import_rc        ( @lines);
  69.               $newsrc->import_rc        (\@lines);</PRE>
  70. <PRE>
  71.  
  72.               $newsrc->save;
  73.               $newsrc->save_as          ($file);
  74.   @lines    = $newsrc->export_rc;</PRE>
  75. <PRE>
  76.  
  77.   $ok       = $newsrc-> add_group       ($group,             %options);
  78.   $ok       = $newsrc->move_group       ($group,             %options);
  79.   $ok       = $newsrc-> del_group       ($group);</PRE>
  80. <PRE>
  81.  
  82.               $newsrc->  subscribe      ($group,             %options);
  83.               $newsrc->unsubscribe      ($group,             %options);</PRE>
  84. <PRE>
  85.  
  86.               $newsrc->mark             ($group,  $article , %options);
  87.               $newsrc->mark_list        ($group, \@articles, %options);
  88.               $newsrc->mark_range       ($group, $from, $to, %options);</PRE>
  89. <PRE>
  90.  
  91.               $newsrc->unmark           ($group,  $article , %options);
  92.               $newsrc->unmark_list      ($group, \@articles, %options);
  93.               $newsrc->unmark_range     ($group, $from, $to, %options);</PRE>
  94. <PRE>
  95.  
  96.        ... if $newsrc->exists           ($group);
  97.        ... if $newsrc->subscribed       ($group);
  98.        ... if $newsrc->marked           ($group, $article);</PRE>
  99. <PRE>
  100.  
  101.   $n        = $newsrc->  num_groups;
  102.   @groups   = $newsrc->      groups;
  103.   @groups   = $newsrc->  sub_groups;
  104.   @groups   = $newsrc->unsub_groups;</PRE>
  105. <PRE>
  106.  
  107.   @articles = $newsrc->  marked_articles($group,             %options);
  108.   @articles = $newsrc->unmarked_articles($group, $from, $to, %options);</PRE>
  109. <PRE>
  110.  
  111.   $articles = $newsrc->get_articles     ($group,             %options);
  112.   $ok       = $newsrc->set_articles     ($group, $articles,  %options);</PRE>
  113. <P>
  114. <HR>
  115. <H1><A NAME="requires">REQUIRES</A></H1>
  116. <P>Perl 5.004, Set::IntSpan 1.07</P>
  117. <P>
  118. <HR>
  119. <H1><A NAME="exports">EXPORTS</A></H1>
  120. <P>Nothing</P>
  121. <P>
  122. <HR>
  123. <H1><A NAME="description">DESCRIPTION</A></H1>
  124. <P><CODE>News::Newsrc</CODE> manages newsrc files, of the style</P>
  125. <PRE>
  126.     alt.foo: 1-21,28,31-34
  127.     alt.bar! 3,5,9-2900,2902</PRE>
  128. <P>Methods are provided for</P>
  129. <UL>
  130. <LI>
  131. reading and writing newsrc files
  132. <P></P>
  133. <LI>
  134. adding and removing newsgroups
  135. <P></P>
  136. <LI>
  137. changing the order of newsgroups
  138. <P></P>
  139. <LI>
  140. subscribing and unsubscribing from newsgroups
  141. <P></P>
  142. <LI>
  143. testing whether groups exist and are subscribed
  144. <P></P>
  145. <LI>
  146. marking and unmarking articles
  147. <P></P>
  148. <LI>
  149. testing whether articles are marked
  150. <P></P>
  151. <LI>
  152. returning lists of newsgroups
  153. <P></P>
  154. <LI>
  155. returning lists of articles
  156. <P></P></UL>
  157. <P>
  158. <HR>
  159. <H1><A NAME="newsrc files">NEWSRC FILES</A></H1>
  160. <P>A newsrc file is an ASCII file that lists newsgroups and article numbers.
  161. Each line of a newsrc file describes a single newsgroup.
  162. Each line is divided into three fields: 
  163. a <EM>group</EM>, a <EM>subscription mark</EM> and an <EM>article list</EM>.</P>
  164. <P>Lines containing only whitespace are ignored.
  165. Whitespace within a line is ignored.</P>
  166. <DL>
  167. <DT><STRONG><A NAME="item_Group">Group</A></STRONG><BR>
  168. <DD>
  169. The <EM>group</EM> is the name of the newsgroup.
  170. A group name may not contain colons (:) or exclamation points (!).
  171. <P>Group names must be unique within a newsrc file.
  172. The group name is required.</P>
  173. <P></P>
  174. <DT><STRONG><A NAME="item_Subscription_mark">Subscription mark</A></STRONG><BR>
  175. <DD>
  176. The <EM>subscription mark</EM> is either a colon (:), for subscribed groups,
  177. or an exclamation point (!), for unsubscribed groups.
  178. The subscription mark is required.
  179. <P></P>
  180. <DT><STRONG><A NAME="item_Article_list">Article list</A></STRONG><BR>
  181. <DD>
  182. The <EM>article list</EM> is a comma-separated list of positive integers.
  183. The integers must be listed in increasing order.
  184. Runs of consecutive integers may be abbreviated a-b, 
  185. where a is the first integer in the run and b is the last.
  186. The article list may be empty.
  187. <P></P></DL>
  188. <P>
  189. <HR>
  190. <H1><A NAME="newsgroup order">NEWSGROUP ORDER</A></H1>
  191. <P><CODE>News::Newsrc</CODE> preserves the order of newsgroups in a newsrc file:
  192. if a file is loaded and then saved, 
  193. the newsgroup order will be unchanged.</P>
  194. <P>Methods that add or move newsgroups affect the newsgroup order.
  195. By default, 
  196. these methods put newsgroups at the end of the newsrc file.
  197. Other locations may be specified by passing an <EM>%options</EM> hash
  198. with a <CODE>where</CODE> key to the method.
  199. Recognized locations are:</P>
  200. <DL>
  201. <DT><STRONG><A NAME="item_where_%3D%3E_%27first%27"><CODE>where</CODE> => <CODE>'first'</CODE></A></STRONG><BR>
  202. <DD>
  203. Put the newsgroup first.
  204. <P></P>
  205. <DT><STRONG><A NAME="item_where_%3D%3E_%27last%27"><CODE>where</CODE> => <CODE>'last'</CODE></A></STRONG><BR>
  206. <DD>
  207. Put the newsgroup last.
  208. <P></P>
  209. <DT><STRONG><A NAME="item_where_%3D%3E_%27alpha%27"><CODE>where</CODE> => <CODE>'alpha'</CODE></A></STRONG><BR>
  210. <DD>
  211. Put the newsgroup in alphabetical order.
  212. <P>If the other newsgroups are not sorted alphabetically,
  213. put the group at an arbitrary location.</P>
  214. <P></P>
  215. <DT><STRONG><A NAME="item_where_%3D%3E_%5B_before_%3D%3E_%24group_%5D"><CODE>where</CODE> => [ <CODE>before</CODE> => <EM>$group</EM> ]</A></STRONG><BR>
  216. <DD>
  217. Put the group immediately before <EM>$group</EM>.
  218. <P>If <EM>$group</EM> does not exist, 
  219. put the group last.</P>
  220. <P></P>
  221. <DT><STRONG><A NAME="item_where_%3D%3E_%5B_after_%3D%3E_%24group_%5D"><CODE>where</CODE> => [ <CODE>after</CODE> => <EM>$group</EM> ]</A></STRONG><BR>
  222. <DD>
  223. Put the group immediately after <EM>$group</EM>.
  224. <P>If <EM>$group</EM> does not exist, 
  225. put the group last.</P>
  226. <P></P>
  227. <DT><STRONG><A NAME="item_where_%3D%3E_%5B_number_%3D%3E_%24n_%5D"><CODE>where</CODE> => [ <CODE>number</CODE> => <EM>$n</EM> ]</A></STRONG><BR>
  228. <DD>
  229. Put the group at position <EM>$n</EM> in the group list.
  230. Indices are zero-based.
  231. Negative indices count backwards from the end of the list.
  232. <P></P></DL>
  233. <P>
  234. <HR>
  235. <H1><A NAME="methods">METHODS</A></H1>
  236. <DL>
  237. <DT><STRONG><A NAME="item_%24newsrc_%3D_new_News%3A%3ANewsrc"><EM>$newsrc</EM> = <CODE>new</CODE> <CODE>News::Newsrc</CODE></A></STRONG><BR>
  238. <DD>
  239. Creates and returns a <CODE>News::Newsrc</CODE> object.
  240. The object contains no newsgroups.
  241. <P></P>
  242. <DT><STRONG><A NAME="item_load"><EM>$ok</EM> = <EM>$newsrc</EM>-><CODE>load</CODE></A></STRONG><BR>
  243. <DD>
  244. <DT><STRONG><EM>$ok</EM> = <EM>$newsrc</EM>-><CODE>load</CODE>(<EM>$file</EM>)</STRONG><BR>
  245. <DD>
  246. Loads the newsgroups in <EM>$file</EM> into <EM>$newsrc</EM>.
  247. If <EM>$file</EM> is omitted, reads <EM>$ENV{HOME}/.newsrc</EM>.
  248. Any existing data in <EM>$newsrc</EM> is discarded.
  249. Returns true on success.
  250. <P>If <EM>$file</EM> can't be opened,
  251. <A HREF="#item_load"><CODE>load</CODE></A> discards existing data from <EM>$newsrc</EM> and returns null.</P>
  252. <P>If <EM>$file</EM> contains invalid lines, <A HREF="#item_load"><CODE>load</CODE></A> will <A HREF="../../../lib/Pod/perlfunc.html#item_die"><CODE>die</CODE></A>.
  253. When this happens, the state of <EM>$newsrc</EM> is undefined.</P>
  254. <P></P>
  255. <DT><STRONG><A NAME="item_import_rc"><EM>$newsrc</EM>-><CODE>import_rc</CODE>(<EM>@lines</EM>)</A></STRONG><BR>
  256. <DD>
  257. <DT><STRONG><EM>$newsrc</EM>-><CODE>import_rc</CODE>([<EM>@lines</EM>])</STRONG><BR>
  258. <DD>
  259. Imports the newsgroups in <EM>@lines</EM> into <EM>$newsrc</EM>.
  260. Any existing data in <EM>$newsrc</EM> is discarded.
  261. <P>Each line in <EM>@lines</EM> describes a single newsgroup,
  262. and must have the format described in <A HREF="#newsrc files">NEWSRC FILES</A>.
  263. If <EM>@lines</EM> contains invalid lines, <A HREF="#item_import_rc"><CODE>import_rc</CODE></A> will <A HREF="../../../lib/Pod/perlfunc.html#item_die"><CODE>die</CODE></A>.
  264. When this happens, the state of <EM>$newsrc</EM> is undefined.</P>
  265. <P><A HREF="#item_import_rc"><CODE>import_rc</CODE></A> accepts either an array or an array reference.</P>
  266. <P></P>
  267. <DT><STRONG><A NAME="item_save"><EM>$newsrc</EM>-><CODE>save</CODE></A></STRONG><BR>
  268. <DD>
  269. Writes the contents of <EM>$newsrc</EM> back to the file 
  270. from which it was <A HREF="#item_load"><CODE>load</CODE></A>ed. 
  271. If <A HREF="#item_load"><CODE>load</CODE></A> has not been called, writes to <EM>$ENV{HOME}/.newsrc</EM>.
  272. In either case, if the destination <EM>file</EM> exists, 
  273. it is renamed to <EM>file</EM><CODE>.bak</CODE>.
  274. <P><A HREF="#item_save"><CODE>save</CODE></A> will <A HREF="../../../lib/Pod/perlfunc.html#item_die"><CODE>die</CODE></A> if there is an error writing the file.</P>
  275. <P></P>
  276. <DT><STRONG><A NAME="item_save_as"><EM>$newsrc</EM>-><CODE>save_as</CODE>(<EM>$file</EM>)</A></STRONG><BR>
  277. <DD>
  278. Writes the contents of <EM>$newsrc</EM> to <EM>$file</EM>. 
  279. If <EM>$file</EM> exists, it is renamed to <EM>$file</EM><CODE>.bak</CODE>.
  280. Subsequent calls to <A HREF="#item_save"><CODE>save</CODE></A> will write to <EM>$file</EM>.
  281. <P><A HREF="#item_save_as"><CODE>save_as</CODE></A> will <A HREF="../../../lib/Pod/perlfunc.html#item_die"><CODE>die</CODE></A> if there is an error writing the file.</P>
  282. <P></P>
  283. <DT><STRONG><A NAME="item_export_rc"><EM>@lines</EM> = <EM>$newsrc</EM>-><CODE>export_rc</CODE></A></STRONG><BR>
  284. <DD>
  285. Returns the contents of <EM>$newsrc</EM> as a list of lines.
  286. Each line describes a single newsgroup,
  287. and has the format described in <A HREF="#newsrc files">NEWSRC FILES</A>.
  288. <P>In scalar context, returns an array reference.</P>
  289. <P></P>
  290. <DT><STRONG><A NAME="item_add_group"><EM>$ok</EM> = <EM>$newsrc</EM>-><CODE>add_group</CODE>(<EM>$group</EM>, <EM>%options</EM>)</A></STRONG><BR>
  291. <DD>
  292. Adds <EM>$group</EM> to the list of newsgroups in <EM>$newsrc</EM>.
  293. <EM>$group</EM> is initially subscribed.
  294. The article list for <EM>$group</EM> is initially empty.
  295. <P>By default, 
  296. <EM>$group</EM> is added to the end of the list of newsgroups.
  297. Other locations may be specified in <EM>%options</EM>;
  298. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  299. <P>By default,
  300. <A HREF="#item_add_group"><CODE>add_group</CODE></A> does nothing if <EM>$group</EM> already exists.
  301. If the <CODE>replace</CODE> => <CODE>1</CODE> option is provided, 
  302. then <A HREF="#item_add_group"><CODE>add_group</CODE></A> will delete <EM>$group</EM> if it exists,
  303. and then add it.</P>
  304. <P><A HREF="#item_add_group"><CODE>add_group</CODE></A> returns true iff <EM>$group</EM> was added.</P>
  305. <P></P>
  306. <DT><STRONG><A NAME="item_move_group"><EM>$ok</EM> = <EM>$newsrc</EM>-><CODE>move_group</CODE>(<EM>$group</EM>, <EM>%options</EM>)</A></STRONG><BR>
  307. <DD>
  308. Changes the position of <EM>$group</EM> in <EM>$newsrc</EM>
  309. according to <EM>%options</EM>.
  310. See <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.
  311. <P>If <EM>$group</EM> does not exist,
  312. <A HREF="#item_move_group"><CODE>move_group</CODE></A> does nothing and returns false.
  313. Otherwise, it returns true.</P>
  314. <P></P>
  315. <DT><STRONG><A NAME="item_del_group"><EM>$ok</EM> = <EM>$newsrc</EM>-><CODE>del_group</CODE>(<EM>$group</EM>)</A></STRONG><BR>
  316. <DD>
  317. If <EM>$group</EM> exists in <EM>$newsrc</EM>,
  318. <A HREF="#item_del_group"><CODE>del_group</CODE></A> removes it and returns true.
  319. The article list for <EM>$group</EM> is lost.
  320. <P>If <EM>$group</EM> does not exist in <EM>$newsrc</EM>,
  321. <A HREF="#item_del_group"><CODE>del_group</CODE></A> does nothing and returns false.</P>
  322. <P></P>
  323. <DT><STRONG><A NAME="item_subscribe"><EM>$newsrc</EM>-><CODE>subscribe</CODE>(<EM>$group</EM>, <EM>%options</EM>)</A></STRONG><BR>
  324. <DD>
  325. Subscribes to <EM>$group</EM>.
  326. <P><EM>$group</EM> will be created if it does not exist.
  327. Its location may be specified in <EM>%options</EM>;
  328. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  329. <P></P>
  330. <DT><STRONG><A NAME="item_unsubscribe"><EM>$newsrc</EM>-><CODE>unsubscribe</CODE>(<EM>$group</EM>, <EM>%options</EM>)</A></STRONG><BR>
  331. <DD>
  332. Unsubscribes from <EM>$group</EM>.
  333. <P><EM>$group</EM> will be created if it does not exist.
  334. Its location may be specified in <EM>%options</EM>;
  335. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  336. <P></P>
  337. <DT><STRONG><A NAME="item_mark"><EM>$newsrc</EM>-><CODE>mark</CODE>(<EM>$group</EM>, <EM>$article</EM>, <EM>%options</EM>)</A></STRONG><BR>
  338. <DD>
  339. Adds <EM>$article</EM> to the article list for <EM>$group</EM>.
  340. <P><EM>$group</EM> will be created if it does not exist.
  341. Its location may be specified in <EM>%options</EM>;
  342. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  343. <P></P>
  344. <DT><STRONG><A NAME="item_mark_list"><EM>$newsrc</EM>-><CODE>mark_list</CODE>(<EM>$group</EM>, <EM>\@articles</EM>, <EM>%options</EM>)</A></STRONG><BR>
  345. <DD>
  346. Adds <EM>@articles</EM> to the article list for <EM>$group</EM>.
  347. <P><EM>$group</EM> will be created if it does not exist.
  348. Its location may be specified in <EM>%options</EM>;
  349. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  350. <P></P>
  351. <DT><STRONG><A NAME="item_mark_range"><EM>$newsrc</EM>-><CODE>mark_range</CODE>(<EM>$group</EM>, <EM>$from</EM>, <EM>$to</EM>, <EM>%options</EM>)</A></STRONG><BR>
  352. <DD>
  353. Adds all the articles from <EM>$from</EM> to <EM>$to</EM>, inclusive, 
  354. to the article list for <EM>$group</EM>.
  355. <P><EM>$group</EM> will be created if it does not exist.
  356. Its location may be specified in <EM>%options</EM>;
  357. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  358. <P></P>
  359. <DT><STRONG><A NAME="item_unmark"><EM>$newsrc</EM>-><CODE>unmark</CODE>(<EM>$group</EM>, <EM>$article</EM>, <EM>%options</EM>)</A></STRONG><BR>
  360. <DD>
  361. Removes <EM>$article</EM> from the article list for <EM>$group</EM>.
  362. <P><EM>$group</EM> will be created if it does not exist.
  363. Its location may be specified in <EM>%options</EM>;
  364. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  365. <P></P>
  366. <DT><STRONG><A NAME="item_unmark_list"><EM>$newsrc</EM>-><CODE>unmark_list</CODE>(<EM>$group</EM>, <EM>\@articles</EM>, <EM>%options</EM>)</A></STRONG><BR>
  367. <DD>
  368. Removes <EM>@articles</EM> from the article list for <EM>$group</EM>.
  369. <P><EM>$group</EM> will be created if it does not exist.
  370. Its location may be specified in <EM>%options</EM>;
  371. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  372. <P></P>
  373. <DT><STRONG><A NAME="item_unmark_range"><EM>$newsrc</EM>-><CODE>unmark_range</CODE>(<EM>$group</EM>, <EM>$from</EM>, <EM>$to</EM>, <EM>%options</EM>)</A></STRONG><BR>
  374. <DD>
  375. Removes all the articles from <EM>$from</EM> to <EM>$to</EM>, inclusive, 
  376. from the article list for <EM>$group</EM>.
  377. <P><EM>$group</EM> will be created if it does not exist.
  378. Its location may be specified in <EM>%options</EM>;
  379. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  380. <P></P>
  381. <DT><STRONG><A NAME="item_exists"><EM>$newsrc</EM>-><CODE>exists</CODE>(<EM>$group</EM>)</A></STRONG><BR>
  382. <DD>
  383. Returns true iff <EM>$group</EM> exists in <EM>$newsrc</EM>.
  384. <P></P>
  385. <DT><STRONG><A NAME="item_subscribed"><EM>$newsrc</EM>-><CODE>subscribed</CODE>(<EM>$group</EM>)</A></STRONG><BR>
  386. <DD>
  387. Returns true iff <EM>$group</EM> exists and is subscribed.
  388. <P></P>
  389. <DT><STRONG><A NAME="item_marked"><EM>$newsrc</EM>-><CODE>marked</CODE>(<EM>$group</EM>, <EM>$article</EM>)</A></STRONG><BR>
  390. <DD>
  391. Returns true iff <EM>$group</EM> exists and its article list contains <EM>$article</EM>.
  392. <P></P>
  393. <DT><STRONG><A NAME="item_num_groups"><EM>$n</EM> = <EM>$newsrc</EM>-><CODE>num_groups</CODE></A></STRONG><BR>
  394. <DD>
  395. Returns the number of groups in <EM>$newsrc</EM>.
  396. <P></P>
  397. <DT><STRONG><A NAME="item_groups"><EM>@groups</EM> = <EM>$newsrc</EM>-><CODE>groups</CODE></A></STRONG><BR>
  398. <DD>
  399. Returns the list of groups in <EM>$newsrc</EM>,
  400. in newsrc order.
  401. In scalar context, returns an array reference.
  402. <P></P>
  403. <DT><STRONG><A NAME="item_sub_groups"><EM>@groups</EM> = <EM>$newsrc</EM>-><CODE>sub_groups</CODE></A></STRONG><BR>
  404. <DD>
  405. Returns the list of subscribed groups in <EM>$newsrc</EM>,
  406. in newsrc order.
  407. In scalar context, returns an array reference.
  408. <P></P>
  409. <DT><STRONG><A NAME="item_unsub_groups"><EM>@groups</EM> = <EM>$newsrc</EM>-><CODE>unsub_groups</CODE></A></STRONG><BR>
  410. <DD>
  411. Returns the list of unsubscribed groups in <EM>$newsrc</EM>,
  412. in newsrc order.
  413. In scalar context, returns an array reference.
  414. <P></P>
  415. <DT><STRONG><A NAME="item_marked_articles"><EM>@articles</EM> = <EM>$newsrc</EM>-><CODE>marked_articles</CODE>(<EM>$group</EM>)</A></STRONG><BR>
  416. <DD>
  417. Returns the list of articles in the article list for <EM>$group</EM>.
  418. In scalar context, returns an array reference.
  419. <P><EM>$group</EM> will be created if it does not exist.
  420. Its location may be specified in <EM>%options</EM>;
  421. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  422. <P></P>
  423. <DT><STRONG><A NAME="item_unmarked_articles"><EM>@articles</EM> = <EM>$newsrc</EM>-><CODE>unmarked_articles</CODE>(<EM>$group</EM>, <EM>$from</EM>, <EM>$to</EM>, <EM>%options</EM>)</A></STRONG><BR>
  424. <DD>
  425. Returns the list of articles from <EM>$from</EM> to <EM>$to</EM>, inclusive,
  426. that do <STRONG>not</STRONG> appear in the article list for <EM>$group</EM>.
  427. In scalar context, returns an array reference.
  428. <P><EM>$group</EM> will be created if it does not exist.
  429. Its location may be specified in <EM>%options</EM>;
  430. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  431. <P></P>
  432. <DT><STRONG><A NAME="item_get_articles"><EM>$articles</EM> = <EM>$newsrc</EM>-><CODE>get_articles</CODE>(<EM>$group</EM>, <EM>%options</EM>)</A></STRONG><BR>
  433. <DD>
  434. Returns the article list for <EM>$group</EM> as a string,
  435. in the format described in <A HREF="#newsrc files">NEWSRC FILES</A>.
  436. <P><EM>$group</EM> will be created if it does not exist.
  437. Its location may be specified in <EM>%options</EM>;
  438. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  439. <P>If you plan to do any nontrivial processing on the article list, 
  440. consider converting it to a <CODE>Set::IntSpan</CODE> object:</P>
  441. <PRE>
  442.   $articles = Set::IntSpan->new($newsrc->get_articles('alt.foo'))</PRE>
  443. <P></P>
  444. <DT><STRONG><A NAME="item_set_articles"><EM>$ok</EM> = <EM>$newsrc</EM>-><CODE>set_articles</CODE>(<EM>$group</EM>, <EM>$articles</EM>, <EM>%options</EM>)</A></STRONG><BR>
  445. <DD>
  446. Sets the article list for $group.
  447. Any existing article list is lost.
  448. <P><EM>$articles</EM> is a string, 
  449. as described in <A HREF="#newsrc files">NEWSRC FILES</A>.</P>
  450. <P><EM>$group</EM> will be created if it does not exist.
  451. Its location may be specified in <EM>%options</EM>;
  452. see <A HREF="#newsgroup order">NEWSGROUP ORDER</A> for details.</P>
  453. <P>If <EM>$articles</EM> does not have the format described in <A HREF="#newsrc files">NEWSRC FILES</A>,
  454. <A HREF="#item_set_articles"><CODE>set_articles</CODE></A> does nothing and returns false.
  455. Otherwise, it returns true.</P>
  456. <P></P></DL>
  457. <P>
  458. <HR>
  459. <H1><A NAME="diagnostics">DIAGNOSTICS</A></H1>
  460. <DL>
  461. <DT><STRONG><A NAME="item_Bad_newsrc_line">Bad newsrc line</A></STRONG><BR>
  462. <DD>
  463. A line in the newsrc file does not have the format described in 
  464. <A HREF="#newsrc files">NEWSRC FILES</A>.
  465. <P></P>
  466. <DT><STRONG><A NAME="item_Bad_article_list">Bad article list</A></STRONG><BR>
  467. <DD>
  468. The article list for a newsgroup does not have the format described in
  469. <A HREF="#newsrc files">NEWSRC FILES</A>.
  470. <P></P>
  471. <DT><STRONG><A NAME="item_News%3A%3ANewsrc%3A%3Asave_as%3A_Can%27t_rename_%2">News::Newsrc::save_as: Can't rename $file, $file.bak: $!</A></STRONG><BR>
  472. <DD>
  473. <DT><STRONG><A NAME="item_News%3A%3ANewsrc%3A%3Asave_as%3A_Can%27t_open_%24f">News::Newsrc::save_as: Can't open $file: $!</A></STRONG><BR>
  474. <DD>
  475. <DT><STRONG><A NAME="item_News%3A%3ANewsrc%3A%3Aformat%3A_Can%27t_write_%24f">News::Newsrc::format: Can't write $file: $!</A></STRONG><BR>
  476. <DD>
  477. </DL>
  478. <P>
  479. <HR>
  480. <H1><A NAME="notes">NOTES</A></H1>
  481. <P>
  482. <H2><A NAME="error handling">Error Handling</A></H2>
  483. <P>``Don't test for errors that you can't handle.''</P>
  484. <P><A HREF="#item_load"><CODE>load</CODE></A> returns null if it can't open the newsrc file, 
  485. and dies if the newsrc file contains invalid data.
  486. This isn't as schizophrenic as it seems.</P>
  487. <P>There are several ways a program could handle an open failure on the newsrc file.
  488. It could prompt the user to reenter the file name.
  489. It could assume that the user doesn't have a newsrc file yet.
  490. If it doesn't want to handle the error, it could go ahead and die.</P>
  491. <P>On the other hand, 
  492. it is very difficult for a program to do anything sensible 
  493. if the newsrc file opens successfully 
  494. and then turns out to contain invalid data.
  495. Was there a disk error?  
  496. Is the file corrupt?
  497. Did the user accidentally specify his kill file instead of his newsrc file?
  498. And what are you going to do about it?</P>
  499. <P>Rather than try to handle an error like this,
  500. it's probably better to die and let the user sort things out.
  501. By the same rational,
  502. <A HREF="#item_save"><CODE>save</CODE></A> and <A HREF="#item_save_as"><CODE>save_as</CODE></A> die on failure.</P>
  503. <P>Programs that must retain control can use eval{...} 
  504. to protect calls that may die.
  505. For example, Perl/Tk runs all callbacks inside an eval{...}.
  506. If a callback dies,
  507. Perl/Tk regains control and displays $@ in a dialog box.
  508. The user can then decide whether to continue or quit from the program.</P>
  509. <P>
  510. <H2><A NAME="import_rc/export_rc"><A HREF="#item_import_rc"><CODE>import_rc</CODE></A>/<A HREF="#item_export_rc"><CODE>export_rc</CODE></A></A></H2>
  511. <P>I was going to call these methods <A HREF="../../../lib/Pod/perlfunc.html#item_import"><CODE>import</CODE></A> and <CODE>export</CODE>,
  512. but <A HREF="../../../lib/Pod/perlfunc.html#item_import"><CODE>import</CODE></A> turns out not to be a good name for a method, 
  513. because <A HREF="../../../lib/Pod/perlfunc.html#item_use"><CODE>use</CODE></A> also calls <A HREF="../../../lib/Pod/perlfunc.html#item_import"><CODE>import</CODE></A>, 
  514. and expects different semantics.</P>
  515. <P>I added the <CODE>_rc</CODE> suffix to <A HREF="../../../lib/Pod/perlfunc.html#item_import"><CODE>import</CODE></A> to avoid this conflict.
  516. It's reasonably short and somewhat mnemonic 
  517. (the module manages news<EM>rc</EM> files).
  518. I added the same suffix to <CODE>export</CODE> for symmetry.</P>
  519. <P>
  520. <HR>
  521. <H1><A NAME="author">AUTHOR</A></H1>
  522. <P>Steven McDougall, <A HREF="mailto:swmcd@world.std.com">swmcd@world.std.com</A></P>
  523. <P>
  524. <HR>
  525. <H1><A NAME="see also">SEE ALSO</A></H1>
  526. <P>perl(1), Set::IntSpan</P>
  527. <P>
  528. <HR>
  529. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  530. <P>Copyright 1996-1998 by Steven McDougall. This module is free
  531. software; you can redistribute it and/or modify it under the same
  532. terms as Perl itself.</P>
  533. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  534. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  535. <STRONG><P CLASS=block> News::Newsrc - manage newsrc files</P></STRONG>
  536. </TD></TR>
  537. </TABLE>
  538.  
  539. </BODY>
  540.  
  541. </HTML>
  542.