NAME

Net::IP::Identifier_Role - The role that Net::IP::Identifier plugins must satisfy

VERSION

version 0.111

SYNOPSIS

package Net::IP::Identifier::Plugin::My_Entity;

use Role::Tiny::With;
with Net::IP::Identifier_Role; # each Entity must satisfy this role

use Net::IP::Identifier::Net;

sub new {  # constructor
   my ($class, %opts) = @_;

   my $self = {};
   bless $self, (ref $class || $class);

   $self->ips( ... );  # set the array of Net::IP::Identifier::Net objects for this entity
   return $self;
}

sub name {
   return 'My_Entity';
}

1;

DESCRIPTION

Each entity included as a Net::IP::Identifier::Plugin module must satisfy the Net::IP::Identifier_Role, as per the SYNOPSYS above. The module must provide a method named ips which returns an array (or ref to an array in scalar context) of the Net::IP::Identifier::Net objects representing the IPs and network blocks that make up the entity.

Net::IP::Identifier_Role adds the identify method used to check whether an IP belongs to an entity, and an ips method for creating the array of IPs and netowrk blocks representing the entity, converting strings to Net::IP::Identifier::Net objects (and vice versa) as necessary.

Required Methods

This role requires two methods: a new constructor and a name. Typically, an entity consuming this role will set its collection of ips in its new constructor.

new( [ options ] );

Net::IP::Identifier will not pass any options, but they might be useful for stand-alone construction.

name

Must return a string representing the name of the entity. It's probably a good idea to keep this short, with no spaces.

Provided Methods

ips ( [ @new ] )

This method is provided by the Net::IP::Identifier_Role, but you may override it if you need different functionality. It must return an array of Net::IP::Identifier::Net objects that represent the entity.

The IPs are actually stored as a hash, where the key is the string representation and the values are the Net::IP::Identifier::Net objects. When called in scalar context, ips returns the reference to the hash.

If @new is defined, each element must be either a Net::IP or Net::IP::Identifier::Net object, or a form acceptable to Net::IP::Identifier::Net(or Net::IP)->new. The current hash of IPs is replaced by the @new list.

identify($ip, [ $replacement ] )

Match $ip against all of the Net::IP::Identifier::Net objects in the entity. $ip must be in the same form as described above in ips.

If no match is found, returns undef.

If a match is found, the entity object (which stringifies to the entity's name) is returned, unless $replacement is defined, it which case it is returned.

cidrs

A convenience method to return just the keys of the ips hash. In scalar context, returns the reference to the hash (same as ips).

cidr_id

This accessor/method sets or clears a flag that modifies the return value of the identify method. When clear, the return value of identify is the entity object (which stringifies to the entities name method). When set, the returned object is instead the Net::IP::Identifier::Net object (which stringifies to the print method).

refresh

A stub.

If there is a programatic method to fetch a new list of IPs and netblocks, and entity can override the refresh method.

This method should be called judiciously as it may be fairly network intensive. Also, many entities may not provide such a method. See Net::IP::Identifier::Google for an example.

SEE ALSO

Net::IP::Identifier

AUTHOR

Reid Augustin <reid@hellosix.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Reid Augustin.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.