NAME

Net::RGTP - Reverse Gossip client

SYNOPSIS

use Net::RGTP;

my $rgtp = Net::RGTP->new(Host=>'gossip.example.com')
  or die "Cannot connect to RGTP server!";

$rgtp->login('spqr1@cam.ac.uk', 'DEADBEEFCAFEF00D');

for my $itemid (keys %{$rgtp->items}) {
  my $item = $rgtp->item($itemid);

  print $itemid, ' ', $item->{'subject'}, ' has ',
    scalar(@{$item->{'posts'}}),
    " posts.\n";
}

DESCRIPTION

Net::RGTP is a class implementing the RGTP bulletin board protocol, as used in the Cambridge University GROGGS system. At present it provides read-only access only.

Future versions of this package will include posting, editing and registration capabilities.

OVERVIEW

RGTP stands for Reverse Gossip Transfer Protocol. An RGTP board, such as GROGGS, consists essentially of a set of "items", each denoted by an eight-character itemid such as "A1240111". An item consists of a sequence of posts on a given subject, identified by a subject string attached to the item. When an item has reached a certain size, attempting to post to it will instead generate a new item, known as a "continuation" or "child" item, with a new itemid and subject string. RGTP keeps track of which items are children of which parent items, thus allowing long chains of discussion to be built.

The first character of itemids was "A" in 1986, the first year of GROGGS's existence, and has been incremented through the alphabet every year since.

Every user is identified to RGTP by their email address. They are usually identified to the other users by a string known as their "grogname". (These are usually fanciful, and regular contests are held as to the best ones.)

Every action which causes a state change on an RGTP server is given a monotonically increasing sequence number. Most actions are also given timestamps. These are in seconds since midnight UTC, 1 January 1970.

CONSTRUCTOR

new ([ OPTIONS ])

This is the constructor for a new Net::RGTP object. OPTIONS are passed in a hash-like fashion, using key and value pairs. Possible options are:

Host - the name of the RGTP server to connect to. If this is omitted, it will default to rgtp-serv.groggs.group.cam.ac.uk.

Port - the port number to connect to. If this is omitted, it will default to 1471, the IANA standard number for RGTP.

Debug - set this to 1 if you want the traffic between the server and client to be printed to stderr. This does not print the contents of files (e.g. the index, or items) as they transfer.

METHODS

login (USERID [, SECRET])

Logs in to the RGTP server. SECRET is the shared-secret which is sent out by mail. It should be undef only if you are expecting not to have to go through authentication (for example, many RGTP servers have an account called "guest" which needs no authentication step).

access_level

Returns the current access level. 0 means only the message of the day may be read. 1 means the index and any item may be read, but nothing may be written. 2 means that items may be posted to. 3 means that the contents of the items, including posts made by other users, may be edited.

latest_seq

Returns the highest sequence number which has been seen in the index of this server. This may be undef if we have not downloaded the index (or if the server is entirely empty).

motd

Returns a hashref containing only the key posts, which maps to an arrayref containing only one element, a hashref which contains three keys:

seq: the sequence number of the message of the day;

text: the text of the message of the day; and

timestamp: the time the message of the day was last set.

The reason for the baroque formatting is that it matches the format of the response of the item method.

Returns undef if there is no message of the day.

item(ITEMID)

Returns a hashref which may if applicable contain the keys:

parent, which is the itemid of the given item's parent;

child, which is the itemid of the given item's child;

subject, which is the subject line of the given item;

reply, which is the sequence number of the most recent reply to the given item; and

edit, which is the sequence number of the most recent edit. (That is, an edit by an editor, not an ordinary reply.)

The hashref will always contain a key posts. This maps to an arrayref of hashrefs, each representing a post to this item. Each hashref may if applicable contain the keys:

seq, which is the sequence number of this post;

timestamp, which is the timestamp of this post;

grogname, which is the grogname of the poster; and

poster, which is the user ID of the poster (that is, their email address).

There will also always be a key text, which contains the text of the post.

item returns undef if the item does not exist.

As a special case, item("motd") is equivalent to calling the motd method.

items

Returns a hashref describing every item on the current server.

The keys of the hashref are the itemids of the several items, except for the key "motd", which describes the message of the day. Each key maps to a hash describing the item. The keys of this hash are:

subject: the subject line of the item. This may be truncated by the RGTP server; you may find the exact subject line using the item method.

posts: a count of posts.

timestamp: the timestamp of the most recent change to this item.

seq: the sequence number of the most recent change to this item.

parent: the itemid of the parent of this item. Exists only for items which have a parent.

child: the itemid of the child of this item. Exists only for items which have a child.

This method may take a long time to execute on popular RGTP servers the first time it is called. This is because it has to download the entire index. Subsequent calls will use cached data and will be faster. See also the state method.

state([STATE])

This method exists because the items method is slow on first use. (Over my home connection, for the main GROGGS server, it takes about forty seconds). When called with no arguments, state returns a scalar describing the state of items's cache. When called with this scalar as argument, it re-fills the cache with this data. This scalar can be seralised so that the advantages of caching can be gained between sessions.

UNIMPLEMENTED

The following aspects of RGTP have not been implemented. This will be addressed in a later revision:

Posting

Anything to do with posting items.

Registration

Creating new user accounts.

Editing

Using superuser powers to modify other people's comments.

AUTHOR

Thomas Thurman <marnanel@marnanel.org>

CREDITS

Firinel Thurman - for being there to bounce ideas off, and, well, everything.

John Stark - for inventing GROGGS.

Ian Jackson - for inventing RGTP.

Tony Finch - whose RGTP to Atom converter made the idea of this module click for me.

SEE ALSO

The RGTP protocol, at http://www.groggs.group.cam.ac.uk/protocol.txt .

The GROGGS home page, at http://www.groggs.group.cam.ac.uk/ .

Yarrow, a CGI RGTP client, at http://rgtp.thurman.org.uk/gossip/groggs/browse .

GREED, an Emacs RGTP client, at http://www.chiark.greenend.org.uk/~owend/free/GREED.html .

COPYRIGHT

Copyright (c) 2005 Thomas Thurman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Net::RGTP

perl -MCPAN -e shell
install Net::RGTP