[NNTP] LISTGROUP

[Russ Allbery]

As promised, here's my proposed text for LISTGROUP that makes the command
a mandatory part of READER and adds a range argument.

This is presented for discussion to see if we can reach consensus that
this is a good idea.  I'm also copying this to news.software.nntp to get
more implementor eyes on it.  If this proposal goes into the draft, it
would mean that in order to claim NNTPv2 compliance, implementing
LISTGROUP with a range argument would be mandatory.

Please note that I think there's at least an even chance that the result
of this discussion will be to reject this idea as too late in the process
or too different from existing practice, but the idea achieved enough
support that I wanted to put together a whole proposal.

6.1.2  LISTGROUP

6.1.2.1  Usage

   Indicating capability: READER
   Syntax
      LISTGROUP [group [range]]
   Responses
      211 number low high group   Article numbers follow (multiline)
      411                         No such newsgroup
      412                         No newsgroup selected [1]
   Parameters
      group  = name of newsgroup
      range  = number(s) of articles
      number = estimated number of articles in the group
      low    = reported low water mark
      high   = reported high water mark
   [1] The 412 response can only occur if no group has been specified.

6.1.2.2  Description

   The LISTGROUP command is used to get a listing of some or all the
   article numbers in a particular newsgroup.  As a side effect, it also
   selects the group in the same way as the GROUP command (see Section
   6.1.1).

   The first optional argument is the name of the newsgroup to be selected
   (e.g.  "news.software.misc").  If no group is specified, the current
   selected newsgroup is used.

   The second optional argument, range, may be any of the following:
   o  an article number
   o  an article number followed by a dash to indicate all following
   o  an article number followed by a dash followed by another article
      number
   If no range is specified, the range 1- is assumed.  If the name of the
   newsgroup is not specified, the range may not be specified.

   On success, the list of article numbers is returned as a multi-line
   response following the 211 response code (the arguments on the initial
   response line are the same as for the GROUP command).  The list
   contains one number per line, is in numerical order, and lists
   precisely those articles that exist in the group at the moment of
   selection whose numbers are within the given range.  This list may be
   empty if no articles in the group have numbers within the given range.

   If the group specified is not available on the server, a 411 response
   MUST be returned.  If no group is specified and the current selected
   newsgroup is invalid, a 412 response MUST be returned.

   In all other aspects the LISTGROUP command behaves identically to the
   GROUP command.

6.1.2.3  Examples

   Example of LISTGROUP on an empty group:
      [C] LISTGROUP   example.empty.newsgroup
      [S] 211 0 0 0 example.empty.newsgroup list follows
      [S] .

   Example of LISTGROUP on a valid current selected newsgroup:
      [C] GROUP   misc.test
      [S] 211 2000 3000234 3002322 misc.test
      [C] LISTGROUP
      [S] 211 2000 3000234 3002322 misc.test list follows
      [S] 3000234
      [S] 3000237
      [S] 3000238
      [S] 3000239
      [S] 3002322
      [S] .

   Example of LISTGROUP with a range:
      [C] LISTGROUP misc.test 3000239-
      [S] 211 2000 3000234 3002322 misc.test list follows
      [S] 3000239
      [S] 3002322
      [S] .

   Example of LISTGROUP with an empty list:
      [C] LISTGROUP misc.test 3002400-3002420
      [S] 211 2000 3000234 3002322 misc.test list follows
      [S] .

   Example of LISTGROUP failing because no group has been selected:
      [Assumes current selected newsgroup is invalid.]
      [C] LISTGROUP
      [S] 412 no current group
      [C] GROUP   example.is.sob.bradner.or.barber
      [S] 411 no such group
      [C] LISTGROUP
      [S] 412 no current group

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>