/ 
IRC-Indexer-0.06
River stage zero No dependents
/ IRC::Indexer::POD::ServerSpec

NAME

IRC::Indexer::POD::ServerSpec - Export format for a single server

DESCRIPTION

This document describes the format of IRC::Indexer exports from a single trawler; this is the hash returned by IRC::Indexer::Report::Server after a trawler run has completed.

See IRC::Indexer::POD::NetworkSpec for details on the format of network-wide information exports as provided by IRC::Indexer::Report::Network.

Current as of IRC::Indexer 0.01

FORMAT

JSON is the preferred format for network transmission; it is light and support is fairly universal.

IRC::Indexer also provides support for YAML and pure-perl serialization formats. This layout definition applies to any IRC::Indexer::Output format.

The export is a hash. This is called "associative array" in some languages; this document will use the term "ARRAY" to refer to a list and "HASH" to refer to an associative key=>value mapping. In Perl these data structures deserialize to an array reference and a hash reference respectively.

The term undef will be used to refer to what some languages call null.

HASH KEYS

Status
Failure
StartedAt
ConnectedAt
FinishedAt
ConnectedTo
ServerName
NetName
IRCD
MOTD
GlobalUsers
OperCount
ChanCount
HashChans
ListChans
ListLinks

Internals

Status  => STRING describing status  (or undef)
Failure => STRING describing failure (or undef)

All times are in epoch seconds.

StartedAt   => TIME of object construction
ConnectedAt => TIME of socket creation (or undef)
FinishedAt  => TIME the trawl run completed (or undef)

In Perl, you can use these to create a DateTime object, for example:

my $dt = DateTime->new(from_epoch => $secs);
print $dt->mdy;

Informational

ConnectedTo => STRING server address we connected to
ServerName  => STRING server name announced by the server
NetName     => STRING network name announced by the server
               (or undef if no NETWORK= specified by server)
GlobalUsers => INT total number of global users
OperCount   => INT total number of global operators
               (optional, undef if not announced in LUSERS)
IRCD        => STRING IRCD version if available

MOTD

MOTD => [ ARRAY of MOTD lines ]

MOTD is saved as an array of lines as they are received, without newlines.

Channels

ChanCount => INT (public channels only)
ListChans => ARRAY (of arrays)
HashChans => HASH

HashChans

HashChans->{$channel} = {
  Users => INT
  Topic => STRING
}

HashChans is a hash, keyed on channel name, containing the number of users and the topic under the keys Users and Topic respectively.

If no topic is set, Topic should be the empty string, NOT undef.

ListChans

ListChans = [
  [ CHANNEL, USERS, TOPIC ],
  [ CHANNEL, USERS, TOPIC ],
],

ListChans is an array whose members are arrays containing three elements: channel name, channel users, channel topic.

IRC::Indexer generates ListChans if $trawler->info->channels() is called; it is not guaranteed to be available.

ListChans is provided as a convenience to frontends, so they do not need to execute possibly expensive sort routines themselves. If provided in exported output, ListChans must be sorted by user count, highest first.

The channel data should otherwise match HashChans.

ListLinks => ARRAY

Array containing the raw data from LINKS, if available.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

http://www.cobaltirc.org