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