12.6.6 Group Info

Gnus stores all permanent info on groups in a group info list. This list is from three to six elements (or more) long and exhaustively describes the group.

Here are two example group infos; one is a very simple group while the second is a more complex one:

("no.group" 5 ((1 . 54324)))

("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55))
                ((tick (15 . 19)) (replied 3 6 (19 . 3)))
                (nnml "")
                ((auto-expire . t) (to-address . "ding@gnus.org")))

The first element is the group name—as Gnus knows the group, anyway. The second element is the subscription level, which normally is a small integer. (It can also be the rank, which is a cons cell where the car is the level and the cdr is the score.) The third element is a list of ranges of read articles. The fourth element is a list of lists of article marks of various kinds. The fifth element is the select method (or virtual server, if you like). The sixth element is a list of group parameters, which is what this section is about.

Any of the last three elements may be missing if they are not required. In fact, the vast majority of groups will normally only have the first three elements, which saves quite a lot of cons cells.

Here’s a BNF definition of the group info format:

info          = "(" group space ralevel space read
                [ "" / [ space marks-list [ "" / [ space method [ "" /
                space parameters ] ] ] ] ] ")"
group         = quote <string> quote
ralevel       = rank / level
level         = <integer in the range of 1 to inf>
rank          = "(" level "." score ")"
score         = <integer in the range of 1 to inf>
read          = range
marks-lists   = nil / "(" *marks ")"
marks         = "(" <string> range ")"
method        = "(" <string> *elisp-forms ")"
parameters    = "(" *elisp-forms ")"

Actually that ‘marks’ rule is a fib. A ‘marks’ is a ‘<string>’ consed on to a ‘range’, but that’s a bitch to say in pseudo-BNF.

If you have a Gnus info and want to access the elements, Gnus offers a series of macros for getting/setting these elements.

gnus-info-group ¶

gnus-info-set-group

Get/set the group name.

gnus-info-rank ¶

gnus-info-set-rank

Get/set the group rank (see Group Score).

gnus-info-level ¶

gnus-info-set-level

Get/set the group level.

gnus-info-score ¶

gnus-info-set-score

Get/set the group score (see Group Score).

gnus-info-read ¶

gnus-info-set-read

Get/set the ranges of read articles.

gnus-info-marks ¶

gnus-info-set-marks

Get/set the lists of ranges of marked articles.

gnus-info-method ¶

gnus-info-set-method

Get/set the group select method.

gnus-info-params ¶

gnus-info-set-params

Get/set the group parameters.

All the getter functions take one parameter—the info list. The setter functions take two parameters—the info list and the new value.

The last three elements in the group info aren’t mandatory, so it may be necessary to extend the group info before setting the element. If this is necessary, you can just pass on a non-nil third parameter to the three final setter functions to have this happen automatically.