/ 
Net-CIDR-Lookup-0.51
River stage zero No dependents
/ Net::CIDR::Lookup

NAME

Net::CIDR::Lookup

DESCRIPTION

This class implements a lookup table indexed by IPv4 networks or hosts.

  • Addresses are accepted in numeric form (integer with separate netbits argument), as strings in CIDR notation or as IP address ranges

  • Overlapping or adjacent networks are automatically coalesced if their associated values are equal.

  • The table is implemented as a binary tree so lookup and insertion take O(log n) time.

Since V0.5, errors are signalled by an exception so method calls should generally by wrapped in an eval.

SYNOPSIS

use Net::CIDR::Lookup;

$cidr = Net::CIDR::Lookup->new;
$cidr->add("192.168.42.0/24",1);     # Add first network, value 1
$cidr->add_num(167772448,27,2);      # 10.0.1.32/27 => 2
$cidr->add("192.168.43.0/24",1);     # Automatic coalescing to a /23
$cidr->add("192.168.41.0/24",2);     # Stays separate due to different value
$cidr->add("192.168.42.128/25",2);   # Error: overlaps with different value

$val = $h->lookup("192.168.41.123"); # => 2

$h = $cidr->to_hash;                 # Convert tree to a hash
print "$k => $v\n" while(($k,$v) = each %$h);

# Output (order may vary):
# 192.168.42.0/23 => 1
# 10.0.1.32/27 => 2
# 192.168.41.0/24 => 2

$cidr->walk(sub {
    my ($addr, $bits, $val) = @_;
    print join('.', unpack 'C*', pack 'N', $addr), "/$bits => $val\n"
  }
);

# Output (fixed order):
# 10.0.1.32/27 => 2
# 192.168.41.0/24 => 2
# 192.168.42.0/23 => 1

$cidr->clear;                                 # Remove all entries
$cidr->add_range('1.2.3.11 - 1.2.4.234', 42); # Add a range of addresses,
                                              # automatically split into CIDR blocks
$h = $cidr->to_hash;
print "$k => $v\n" while(($k,$v) = each %$h);

# Output (order may vary):
# 1.2.4.128/26 => 42
# 1.2.3.32/27 => 42
# 1.2.3.64/26 => 42
# 1.2.4.234/32 => 42
# 1.2.4.0/25 => 42
# 1.2.3.12/30 => 42
# 1.2.3.128/25 => 42
# 1.2.3.16/28 => 42
# 1.2.4.224/29 => 42
# 1.2.4.232/31 => 42
# 1.2.3.11/32 => 42
# 1.2.4.192/27 => 42

VERSION HISTORY

See Net::CIDR::Lookup::Changes

METHODS

new

Arguments: none

Return Value: new object

add

Arguments: $cidr, $value

Return Value: none

Adds VALUE to the tree under the key CIDR. CIDR must be a string containing an IPv4 address followed by a slash and a number of network bits. Bits to the right of this mask will be ignored.

add_range

Arguments: $range, $value

Return Value: none

Adds VALUE to the tree for each address included in RANGE which must be a hyphenated range of IP addresses in dotted-quad format (e.g. "192.168.0.150-192.168.10.1") and with the first address being numerically smaller the second. This range will be split up into as many CIDR blocks as necessary (algorithm adapted from a script by Dr. Liviu Daia).

add_num

Arguments: $address, $bits, $value

Return Value: none

Like add() but accepts address and bits as separate integer arguments instead of a string.

add_num_range

Arguments: $start, $end, $value

Return Value: none

Like add_range() but accepts addresses as separate integer arguments instead of a range string.

lookup

Arguments: $address

Return Value: value assoiated with this address or undef

Looks up an address and returns the value associated with the network containing it. So far there is no way to tell which network that is though.

lookup_num

Arguments: $address

Return Value: value assoiated with this address or undef

Like lookup() but accepts the address in integer form.

to_hash

Arguments: none

Return Value: $hashref

Returns a hash representation of the tree with keys being CIDR-style network addresses.

walk

Arguments: $coderef to call for each tree entry. Callback arguments are:

$address

The network address in integer form

$bits

The current CIDR block's number of network bits

$value

The value associated with this block

Return Value: none

clear

Arguments: none

Return Value: none

Remove all entries from the tree.

BUGS

  • I didn't need deletions yet and deleting parts of a CIDR block is a bit more complicated than anything this class does so far, so it's not implemented.

  • Storing an undef value does not work and yields an error. This would be relatively easy to fix at the cost of some memory so that's more a design decision.

AUTHORS, COPYRIGHTS & LICENSE

Matthias Bethke <matthias@towiski.de> while working for 1&1 Internet AG

Licensed unter the Artistic License 2.0

SEE ALSO

This module's methods are based loosely on those of Net::CIDR::Lite