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.

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. (The letter for 2005 is "U".)

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.

USERID is the user identity to use on the RGTP server, typically an email address. If left blank it will default to "guest".

SECRET is the shared-secret which is sent out by mail. It must either be a hex string with an even number of digits, or undef. It should be undef only if you are expecting not to have to go through authentication (for example, on many RGTP servers the account called "guest" needs no authentication step).

This method returns the current access level, in the format returned by the access_level method. The method returns undef on failure, and sets $@ to an appropriate message.

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.

quick_item(ITEMID)

Similar to the item method, but the hashref returned does not contain the key posts. Use this method if you only need to know, for example, the item's most recent sequence number or its subject line. It executes many times faster than the item method, because the content of the item does not need to be transferred.

This implements the RGTP function "STAT". The method is not called stat because that is a perl builtin.

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.

post(WHERE, WHAT, [OPTS])

Adds some content to the RGTP board.

WHAT is a block of text wrapped at 80 columns. I recommend the use of Text::ASCIITable::Wrap to format arbitrary text in this way.

WHERE can be one of three things:

The string new. In this case WHAT is posted as a new item on the server.

A valid and existing itemid. In this case WHAT is appended as a reply to the given item.

The string continue. This only works when the continuation flag is set (see CONTINUATIONS below). WHAT is posted as the first entry in a continuation item.

OPTIONS are passed in a hash-like fashion, using key and value pairs. Possible options are:

Seq. The sequence number of the last known reply to this item. Ignored when WHAT is new or continue. If this is undefined, the sequence number will not be checked. See COLLISIONS below.

Grogname. The grogname to use when posting. If this is undefined, no grogname will be used. Grognames which are too long may cause the method to return an error.

Title. The title to use for the new item. Required when WHAT is new or continue, and ignored at all other times.

On success, in list context, this method returns a list consisting of the itemid followed by the sequence number of the post. In scalar context, it returns only the itemid.

The method returns undef on failure, and sets $@ to an appropriate message. It also causes the functions item_is_full and item_is_grown to return values which represent the reason it failed.

item_is_full

Returns true iff the most recent call to post failed because the target item had gone into a continuation. This is known as the "continuation flag": see CONTINUATIONS below.

item_has_grown

Returns true iff the most recent call to post failed because of a collision in the target item. See COLLISIONS below.

CONTINUATIONS

Items have a maximum size. Thus after a certain amount of posting to any given item, it will cease to be possible to post any more content. When this happens, post will return undef, and set the "continuation flag", which may be inspected using the item_is_full method.

When the flag is set, and only when the flag is set, it is possible to call post again with the WHERE parameter set to "continue". This creates a continuation item following on from the item you were originally trying to post to.

COLLISIONS

Because RGTP is not threaded, most users want to check, when they reply to an item, that it has not been replied to already while they were composing their reply. The lack of a built-in way to do this is a fundamental flaw in RGTP; most clients get around the problem by doing a STAT (equivalent to our quick_item method) immediately before posting, and comparing the sequence number given to one taken before the reply was composed. Net::RGTP provides an easy way to accomplish this: setting the Seq option to the post command. If this check fails, post will return undef and item_has_grown will subsequently return true.

However, any such mechanism introduces a race condition into the protocol. The chance of a race occurring is slight, and the problems caused thereby are small, but programmers should be aware of it.

The only case when RGTP does tell us when an item has been updated is when an item has gone into a continuation. In this case post and item_has_grown will behave as if Seq had been specified, even if it was not.

UNIMPLEMENTED

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

Edit log

Viewing the log of editors' changes to the board.

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