NAME

Net::IP::Identifier - Identify IPs that fall within collections of network blocks

VERSION

version 0.054

SYNOPSIS

use Net::IP::Identifier;
      or
use Net::IP::Identifier ( qw( Microsoft Google ) );

DESCRIPTION

Net::IP::Identifier represents...

Methods

run

This module is a modulino, meaning it may be used as a module or as a script. The run method is called when there is no caller and it is used as a script. run parses the command line arguments, calls new() to create the object. If a filename is specified, that file is read and

new( [ options ] );

Creates a new Net::IP::Identifier object. The following options are available, and are also available as accessors:

parents => boolean

A format modifier. See identify below.

cidr => boolean

A format modifier. See identify below.

joiner => string

The string to use when 'join'ing pieces. The default is to use ':' on IPv4 addresses and '.' on IPv6 addresses.

entities ( [ @modules ] )

Returns the list of Plugin objects currently in use.

If @modules is defined, they should be the names of the Plugin objects to 'require':

$identifier->entities( qw(
    Net::IP::Identifier::Plugin::Microsoft
    Net::IP::Identifier::Plugin::Google
    ...
) );

If no plugin modules are loaded, and @modules is not defined, the import list (defined at 'use' time) is loaded. If there is no import list, all available modules found in Net::IP::Identifier::Plugins are 'required' and matched against. Loading a reference to an empty array:

$identifier->entities( [] );

also loads all available plugins.

modules may be passed as a reference to an array:

$identifier->entities ( \@modules );

Plugins can also be loaded selectively at 'use' time (see SYNOPSIS).

identify( IP )

Try to identify IP with an entity. IP may be a Net::IP::Identifier::Net object or any of the formats acceptable to Net::IP::Identifier::Net.

If the IP cannot be identified with an entity, undef is returned.

If the IP belongs to an included identity (see PLUGINS), the return value is modified by the format flags.

When all modifiers false, the return value is the name of the entity (e.g: 'Yahoo').

When cidr is true, the Net::IP::Identifier::Net object of the matching netblock is appended to the result.

When parents is true, any parent (and grandparent, etc) entities are prepended to the result.

Flags may be used concurrently.

In scalar context, a string is return where the pieces are joined using joiner. In array context, the array of pieces is returned.

tree_overlaps

During construction of the binary tree, there may be netblocks that overlap with existing netblocks. The return value from tree-descend()> containing more than a single node indicates an such an overlap, and those return values are stored to the tree_overlaps array reference.

When used as a modulino, the overlaps command line argument causes these overlaps to generate warning messages.

PLUGINS

Net::IP::Identifier uses the Module::Pluggable module to support plugins. See entities for details on controlling which Plugins are loaded.

Plugins uploaded to CPAN should be well known entities, or entities with wide netblocks. Let's not congest CPAN with a multitude of class C netblocks.

Entities with child netblocks can name them in a children subroutine (see Microsoft and Yahoo for examples). If you want to add a netblock as a child, you'll need to arrange with the parent's CPAN owner to add it. This relationship is independant of the network hierarchy, and is currently ignored by Net::IP::Identifier.

Plugins must satisfy the Net::IP::Identifier_Role (see Role::Tiny).

Make sure to test your plugin by running Identifier with the overlaps flag. overlaps causes overlapping netblocks to be reported. Overlaps are not necessarily an error and there may be overlaps caused by modules other than your new Plugin.

Note: there is no checking of overlapping or conflicting netblocks, so double check your information.

SEE ALSO

Net::IP

Net::IP::Identifier::Net

Net::IP::Identifier::Plugins::Google (and other plugins in this directory)

Role::Tiny

Module::Pluggable

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.