NAME

IRC::Server::Tree::Network - An enhanced IRC::Server::Tree

SYNOPSIS

  ## Model a network
  my $net = IRC::Server::Tree::Network->new;

  ## Add a couple top-level peers
  $net->add_peer_to_self('hubA');
  $net->add_peer_to_self('leafA');

  ## Add some peers to hubA
  $net->add_peer_to_name('hubA', 'leafB');
  $net->add_peer_to_name('hubA', 'leafC');

  ## [ 'leafB', 'leafC' ] :
  my $split = $net->split_peer('hubA');

See below for complete details.

DESCRIPTION

An IRC::Server::Tree::Network provides simpler methods for interacting with an IRC::Server::Tree. It also handles "trace" route memoization and uniqueness-checking.

new

  my $net = IRC::Server::Tree::Network->new;

  ## With named opts:
  my $net = IRC::Server::Tree::Network->new(
    tree    => $my_tree,

    ## Turn off route preservation:
    memoize => 0,
  );

  ## With an existing Tree and no other opts:
  my $net = IRC::Server::Tree::Network->new(
    IRC::Server::Tree->new( $previous_tree )
  );

The constructor initializes a new Network.

memoize

Setting 'memoize' to a false value at construction time will disable route preservation, saving some memory at the expense of more frequent tree searches.

tree

If an existing Tree is passed in, a list of unique node names in the Tree is compiled and validated.

Routes are not stored until a "trace" is called.

add_peer_to_self

  $net->add_peer_to_self( $peer_name );

Adds a node identified by the specified peer name to the top level of our tree; i.e., a directly-linked peer.

The identifier must be unique. IRC networks may not have duplicate entries in the tree.

You can optionally specify an existing tree of nodes to add under the new node as an ARRAY:

  $net->add_peer_to_self( $peer_name, $array_ref );

...but it will trigger a tree-walk to reset seen peers.

add_peer_to_name

  $net->add_peer_to_name( $parent_name, $new_peer_name );

Add a node identified by the specified $new_peer_name to the specified $parent_name.

Returns empty list and warns if the specified parent is not found.

Specifying an existing ARRAY of nodes works the same as "add_peer_to_self".

have_peer

  if ( $net->have_peer( $peer_name ) ) {
    . . .
  }

Returns a boolean value indicating whether or not the specified name is already seen in the tree. (This relies on our tracked entries, rather than finding a path for each call.)

hop_count

  my $count = $net->hop_count( $peer_name );

Returns the number of hops to the destination node; i.e., a directly-linked peer is 1 hop away:

  hubA
    leafA     - 1 hop
    hubB      - 1 hop
      leafB   - 2 hops

Returns empty list if the peer was not found.

reset_tree

  $net->reset_tree;

Clears all currently-known routes and re-validates the tree.

You shouldn't normally need to call this yourself unless you are in the process of breaking things severely (such as manipulating the stored "tree").

split_peer

  my $split_names = $net->split_peer( $peer_name );

Splits a node from the tree.

Returns an ARRAY containing the names of every node beneath the one that was split, not including the originally specified peer.

Returns empty list if the peer was not found.

Returns empty arrayref if the node was split but no nodes were underneath the split node.

split_peer_nodes

  my $split_peer_nodes = $net->split_peer_nodes( $peer_name );

Splits a node from the tree just like "split_peer", except returns the array-of-arrays forming the tree underneath the split peer.

This can be fed back to Network add_peer methods such as "add_peer_to_self" and "add_peer_to_name":

  my $split_nodes = $net->split_peer_nodes( 'hubA' );
  $net->add_peer_to_self( 'NewHub' );
  $net->add_peer_to_name( 'NewHub', $split_nodes );

trace

  my $trace_names = $net->trace( $peer_name );

A successful trace returns the same value as "trace" in IRC::Server::Tree; see the documentation for IRC::Server::Tree for details.

Returns empty list if the peer was not found.

This proxy method memoizes routes for future lookups. They are cleared when "split_peer" is called.

tree

The tree() method returns the IRC::Server::Tree object belonging to this Network.

  my $as_hash = $net->tree->as_hash;

See the IRC::Server::Tree documentation for details.

Note that calling methods on the Tree object that manipulate the tree (adding and deleting nodes) will break future lookups via Network. Don't do that; if you need to manipulate the Tree directly, fetch it, change it, and create a new Network:

  my $tree = $net->tree;

  ## ... call methods on the IRC::Server::Tree ...
  $tree->del_node_by_name('SomeNode');

  my $new_net = IRC::Server::Tree::Network->new(
    $tree
  );

... or if you must, at least call reset_tree to reset our state and validate the tree:

  $net->tree->del_node_by_name('SomeNode');
  $net->reset_tree;

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>