NAME

Net::IP::Lite - Perl extension for manipulating IPv4/IPv6 addresses

SYNOPSIS

use Net::IP::Lite;

print ip2bin('127.0.0.1') . "\n";
print ip_validate('127.0.0.1') . "\n";

print ip_is_ipv4('127.0.0.1') . "\n";
print ip_is_ipv6('::1') . "\n";
print ip_is_ipv6ipv4('::ffff:7f00:1') . "\n";

print ip_transform('127.0.0.1', {
	convert_to => 'ipv6ipv4',
	short_ipv6 => 1 }
) . "\n";

print ip_equal('0x7f000001', '127.0.0.1') . "\n";
print ip_equal_v4('0x7f000001', '::ffff:127.0.0.1') . "\n";
print ip_equal_v6('0x7f000001', '::ffff:127.0.0.1') . "\n";

print ip_in_range('127.0.0.1', '127.0.0.1/8') . "\n";
print ip_in_range('127.0.0.1', [
	'127.0.0.1/8',
	'10.0.0.0 255.255.255.255'
]) . "\n";

my $ip = Net::IP::Lite->new('127.0.0.1') || die 'Invalid IP address';
print $ip->binary . "\n";
print $ip->address . "\n";

print $ip->is_ipv4('127.0.0.1') . "\n";
print $ip->is_ipv6('::1') . "\n";
print $ip->is_ipv6ipv4('::ffff:7f00:1') . "\n";

print $ip->transform({
	convert_to => 'ipv6ipv4',
	short_ipv6 => 1
}) . "\n";

print $ip->equal('0x7f000001', '127.0.0.1') . "\n";
print $ip->equal('0x7f000001', Net::IP::Lite->new('127.1')) . "\n";
print $ip->equal_v4('0x7f000001', '::ffff:127.0.0.1') . "\n";
print $ip->equal_v6('0x7f000001', '::ffff:127.0.0.1') . "\n";

print $ip->in_range('127.0.0.1', '127.0.0.1/8') . "\n";
print $ip->in_range('127.0.0.1', [
	'127.0.0.1/8',
	'10.0.0.0 255.0.0.0',
	Net::IP::Lite::Net->new('10.0.0.0/8')
]) . "\n";

my $net = Net::IP::Lite::Net->new('10.0.0.0/8') || die ...;
print $net->address() . "\n";
print $net->mask->address() . "\n";
print $net->contains('10.1.1.1') . "\n";

DESCRIPTION

This is another module to manipulate IPv4/IPv6 addresses. In contrast of NET::IP, it does not require Math::BigInt. Also, it supports some additional IPv4 formats like 0x7f000001, 2130706433, 017700000001, 0177.0.0.1, 0x7f.0.0.0x1.

The module provides the following capabilities:

validating IP addresses;
converting IP addresses in different format;
comparing IP addresses;
verifying whether an IP is an IPv4 or an IPv6 or an IPv4-embedded IPv6 address;
verifying whether an IP is in a range.

Most subroutines have two implementations, so you can use procedural or object-oriented approach.

SUPPORTED FORMATS

You can use any IPv4 and IPv6 formats:

127.0.0.1, 127.0.1, 127.1 (IPv4 with decimal octets);
0177.0.0.1, 0177.0.1, 0177.1 (IPv4 with octal octets);
0x7f.0x0.0x0.0x1, 0x7f.0x0.0x1, 0x7f.0x1 (IPv4 with hexadecimal octets);
0177.0.0.1, 0x7f.0.1, 0177.0x1 (IPv4 with mixed octets);
2130706433 (decimal IPv4);
0x7f000001 (hexadecimal IPv4);
017700000001 (octal IPv4);
0:0:0:0:0:0:0:1, ::, ::1 (IPv6);
0:0:0:0:0:ffff:127.0.0.1, ::ffff:127.0.0.1 (IPv4-embedded IPv6 address).

PROCEDURAL INTERFACE

ip2bin

Returns a string that contains binary representation of an IP address. Returns the empty string if an invalid IP address is specified.

$ip = ip2bin('127.0.0.1'); # '01111111000000000000000000000001'
$ip = ip2bin('::1');       # '0' x 127 . '1'
$ip = ip2bin('::1:');      # ''

ip_validate

Returns TRUE if the specified IP address is a valid, or FALSE otherwise.

$ok = ip_validate('127.0.0.1');     # TRUE
$ok = ip_validate('::1');           # TRUE
$ok = ip_validate('127.0.0.');      # FALSE
$ok = ip_validate('127.256');       # FALSE
$ok = ip_validate('::1:127.0.0.1'); # FALSE

ip_is_ipv4

Returns TRUE if the specified IP address is an IPv4 address, or FALSE otherwise.

$ok = ip_is_ipv4('127.0.0.1');        # TRUE
$ok = ip_is_ipv4('::1');              # FALSE
$ok = ip_is_ipv4('0::0:');            # FALSE
$ok = ip_is_ipv4('::ffff:127.0.0.1'); # FALSE

ip_is_ipv6

Returns TRUE if the specified IP address is an IPv6 address, or FALSE otherwise.

$ok = ip_is_ipv6('::1');              # TRUE
$ok = ip_is_ipv6('::ffff:127.0.0.1'); # TRUE
$ok = ip_is_ipv6('0::0:');            # FALSE
$ok = ip_is_ipv6('0::0:ffff1');       # FALSE
$ok = ip_is_ipv6('127.0.0.1');        # FALSE

ip_is_ipv6ipv4

Returns TRUE if the specified IP address is an IPv4-embedded IPv6 address, or FALSE otherwise.

$ok = ip_is_ipv6ipv4('::ffff:127.0.0.1'); # TRUE
$ok = ip_is_ipv6ipv4('::ffff:7f00:1');    # TRUE
$ok = ip_is_ipv6ipv4('::fff1:7f00:1');    # FALSE
$ok = ip_is_ipv6ipv4('127.0.0.1');        # FALSE

ip_transform

Converts an IP address string to another IP address string (or number).

$ip = ip_transform($ip, $opts);

Where $opts is a hash that can have the following keys:

short_ipv6 => 1 (return abbreviated IPv6 address);
short_ipv4 => 1 (return abbreviated IPv4 address);
lead_zeros => 1 (add leading zeros to IPv6 address or hexadecimal IPv4 address);
reverse => 1 (return reversed IP address);
convert_to => 'ipv6' (transform IPv4 to IPv6 address);
convert_to => 'ipv4' (transform IPv6-embedded address to IPv4);
convert_to => 'ipv6ipv4' (transform IP address to format ::ffff:xx.xx.xx.xx);
format_ipv4 => 'X' (transform IPv4 address to hexadecimal number);
format_ipv4 => 'D' (transform IPv4 address to decimal number);
format_ipv4 => 'O' (transform IPv4 address to octal number);
format_ipv4 => 'x' (transform IPv4 address to hexadecimal octet format);
format_ipv4 => 'o' (transform IPv4 address to octal number).

$ip = ip_transform('127.0.1');          # 127.0.0.1
$ip = ip_transform('::1');              # 0:0:0:0:0:0:0:1
$ip = ip_transform('::ffff:127.0.0.1'); # 0:0:0:0:0:ffff:7f00:1

$ip = ip_transform('127.0.0.1', {
	short_ipv4 => 1
}); # 127.1

$ip = ip_transform('0:0::1', {
	short_ipv6 => 1
}); # ::1

$ip = ip_transform('0:0::1', {
	lead_zeros => 1
}); # 0000:0000:0000:0000:0000:0000:0000:0001

$ip = ip_transform('0:0::1', {
	short_ipv6 => 1,
	lead_zeros => 1
}); # ::0001

$ip = ip_transform('0:0::1', {
	reverse => 1
}); # 1:0:0:0:0:0:0:0

$ip = ip_transform('::ffff:127.0.0.1', {
	reverse => 1,
	short_ipv6 => 1
}); # 1:7f00:ffff::

$ip = ip_transform('127.0.0.1', {
	convert_to => 'ipv6'
}); # 0:0:0:0:0:ffff:7f00:1

$ip = ip_transform('::ffff:127.0.0.1', {
	convert_to => 'ipv6'
}); # 0:0:0:0:0:ffff:7f00:1

$ip = ip_transform('::ffff:7f00:1', {
	convert_to => 'ipv4'
}); # 127.0.0.1

$ip = ip_transform('::ffff:127.0.0.1', {
	convert_to => 'ipv4'
}); # 127.0.0.1

$ip = ip_transform('::ffff:7f00:1', {
	convert_to => 'ipv6ipv4'
}); # 0:0:0:0:0:ffff:127.0.0.1

$ip = ip_transform('::ffff:127.0.0.1', {
	convert_to => 'ipv6ipv4'
}); # 0:0:0:0:0:ffff:127.0.0.1

$ip = ip_transform('127.0.0.1', {
	convert_to => 'ipv6ipv4'
}); # 0:0:0:0:0:ffff:127.0.0.1

$ip = ip_transform('0.0.0.1', {
	format_ipv4 => 'X'
}); # 0x1

$ip = ip_transform('0.0.0.1', {
	format_ipv4 => 'X',
	lead_zeros => 1
}); # 0x00000001

$ip = ip_transform('127.0.0.1', {
	format_ipv4 => 'D'
}); # 2130706433

$ip = ip_transform('127.0.0.1', {
	format_ipv4 => 'O'
});
# 017700000001

$ip = ip_transform('127.0.0.1', {
	format_ipv4 => 'x'
}); # 0x7f.0x0.0x0.0x1

$ip = ip_transform('127.0.0.1', {
	format_ipv4 => 'x',
short_ipv4 => 1
}); # 0x7f.0x1

$ip = ip_transform('127.0.0.1', {
	format_ipv4 => 'x',
	lead_zeros => 1 });
# 0x7f.0x00.0x00.0x01'

$ip = ip_transform('127.0.0.1', {
	format_ipv4 => 'o'
}); # 0177.0.0.01

ip_equal

Compares two IP addresses.

$eq = ip_equal('127.0.0.1', '0x7f000001');       # TRUE
$eq = ip_equal('::', '0:0:0:0:0:0:0:0');         # TRUE
$eq = ip_equal('::ffff:127.0.0.1', '127.0.0.1'); # FALSE

ip_equal_v4

Compares two IP addresses as IPv4 addresses.

$eq = ip_equal_v4('127.0.0.1', '0x7f000001');       # TRUE
$eq = ip_equal_v4('::ffff:127.0.0.1', '127.0.0.1'); # TRUE
$eq = ip_equal_v4('::', '127.0.0.1');               # dies

ip_equal_v6

Compares two IP addresses as IPv6 addresses.

$eq = ip_equal_v6('127.0.0.1', '0x7f000001');       # TRUE
$eq = ip_equal_v6('::1', '0:0::1');                 # TRUE
$eq = ip_equal_v6('::ffff:127.0.0.1', '127.0.0.1'); # TRUE
$eq = ip_equal_v6('::', '127.0.0.1');               # FALSE

ip_in_range

Verifies whether the specified IP address in a range.

$in_range = ip_in_range('127.0.0.1', $range);

Where range can be specified in the following ways:

an IP address and a mask ('192.168.0.1 255.255.255.0');
an IP address with a prefix ('ffff:ffff:1::/48');
an IP address without mask ('129.168.0.1' (equivalent to '192.168.0.1/32'));
as an array ([ '129.168.0.0/16', '172.16.0.0/12', '10.0.0.0 255.0.0.0', '::ffff/96' ]);

$in = ip_in_range('192.168.0.1', '192.168.0 255.255.255.0');   # TRUE
$in = ip_in_range('10.10.10.19', [ '127.1', '10.0/8' ]);       # TRUE
$in = ip_in_range('10.10.10.19', '10.10.10.8/29');             # FALSE
$in = ip_in_range('a0:a0:a0:a0:1::1', 'a0:a0:a0:a0::/64');     # TRUE
$in = ip_in_range('::ffff:10.10.10.10', '::ffff:0:0/96');      # TRUE
$in = ip_in_range('1:2:3::8000:40', '1:2:3::8000:20/123');     # FALSE

EXPORTS

Net::IP::Lite exports the following functions:

ip2bin
ip_validate
ip_is_ipv4
ip_is_ipv6
ip_is_ipv6ipv4
ip_transform
ip_equal
ip_equal_v4
ip_equal_v6
ip_in_range

OBJECT-ORIENTED INTERFACE

When you use the object oriented approach, binary representation of IP address is calculated once (when you create Net::SimpleIO object). Thus, if you are going to use an IP address (or a range) more than once, you can use once created object to reduce redundant IP-to-binary conversions.

Net::IP::Lite object

constructor

$ip = Net::IP::Lite->new('10.77.0.77') || die 'Invalid IP address';
$ip = Net::IP::Lite->new('::1') || die ...

address

Returns the original IP address that was specified as the constructor argument.

$ip = Net::IP::Lite->new('10.77.77');
print $ip->address(); # 10.77.77

binary

Returns a string that contains binary representation of the specified IP address.

$ip = Net::IP::Lite->new('10.77.77');
print $ip->binary(); # 00001010010011010000000001001101

is_ipv4

Returns TRUE if the IP address is a IPv4 address, or FALSE otherwise.

$ip = Net::IP::Lite->new('10.77.77');
$ipv4 = $ip->is_ipv4(); # TRUE

$ip = Net::IP::Lite->new('::1');
$ipv4 = $ip->is_ipv4(); # FALSE

is_ipv6

Returns TRUE if the IP address is a IPv6 address, or FALSE otherwise.

$ip = Net::IP::Lite->new('::1');
$ipv6 = $ip->is_ipv6(); # TRUE

$ip = Net::IP::Lite->new('127.1');
$ipv6 = $ip->is_ipv6(); # FALSE

is_ipv6ipv4

Returns TRUE if the IP address is a IPv4-Embedded IPv6 address, or FALSE otherwise.

$ip = Net::IP::Lite->new('::ffff:127.0.0.1');
$emb = $ip->is_ipv6ipv4(); # TRUE

$ip = Net::IP::Lite->new('::ffff:7f00:1');
$emb = $ip->is_ipv6ipv4(); # TRUE

$ip = Net::IP::Lite->new('::1');
$emb = $ip->is_ipv6ipv4(); # FALSE

$ip = Net::IP::Lite->new('127.1');
$emb = $ip->is_ipv6ipv4(); # FALSE

transform

Converts the IP address to an IP address string (or number).

$ip = Net::IP::Lite->new('0:0:0:0:0:0:0:1');
print $ip->transform({ short_ipv6 => 1 }); # ::1

See "ip_transform" for all possible values of $opts.

equal

Compares two IP addresses.

$ip = Net::IP::Lite->new('0:0:0:0:0:0:0:1');
$eq = $ip->equal('::1'); # TRUE
$eq = $ip->equal('::2'); # FALSE

$ip1 = Net::IP::Lite->new('0:0:0:0:0:0:0:1');
$ip2 = Net::IP::Lite->new('::1');
$eq = $ip->equal($ip2); # TRUE

equal_v4

Compares two IP addresses as IPv4 addresses.

$ip = Net::IP::Lite->new('::ffff:127.0.0.1');
$eq = $ip->equal_v4('127.0.0.1'); # TRUE

$ip1 = Net::IP::Lite->new('::ffff:7f00:1');
$ip2 = Net::IP::Lite->new('127.0.0.1');
$eq = $ip->equal_v4($ip2); # TRUE

$ip = Net::IP::Lite->new('::7f00:1');
$eq = $ip->equal_v4('127.0.0.1'); # dies

equal_v6

Compares two IP addresses as IPv6 addresses.

$ip = Net::IP::Lite->new('::ffff:127.0.0.1');
$eq = $ip->equal_v6('127.0.0.1'); # TRUE

$ip1 = Net::IP::Lite->new('::ffff:7f00:1');
$ip2 = Net::IP::Lite->new('127.0.0.1');
$eq = $ip->equal_v6($ip2); # TRUE

in_range

Verifies whether the IP in a range.

$ip = Net::IP::Lite->new('10.10.10.10');
$in = $ip->in_range('10.10.10.8/29'); # TRUE
$in = $ip->in_range([ '192.168.0 255.255.255.0', '10.0/8' ]); # TRUE

Net::IP::Lite::Net object

constructor

The Net::IP::Lite::Net class is a descendant of Net::IP::Lite.

$net = Net::IP::Lite::Net->new('10.0/8') || die ...;
$net = Net::IP::Lite::Net->new('10.0.0.8 255.255.255.248') || die ...;
$net = Net::IP::Lite::Net->new('1::/16') || die ...;
$net = Net::IP::Lite::Net->new('1:: ffff::') || die ...;

Please note: Net::IP::Lite::Net allows you to create an network (without possible hosts).

For example:

$net = Net::IP::Lite::Net->new('10.10.10.8/28');

You can use the <"contains" method to check whether there are any possible hosts or not.

All Net:IP::Lite methods return the same values as if you created Net::IP::Lite object without a mask.

$net = Net::IP::Lite::Net->new('1:: ffff::') || die ...;
print $net->address; # 1::

mask

Returns Net::IP::Lite instance for the network mask;

$net = Net::IP::Lite::Net->new('1:: ffff::') || die ...;
print $net->mask->address(); # ffff::

$net = Net::IP::Lite::Net->new('1::/32') || die ...;
print $net->mask->address(); # ffff:ffff:0:0:0:0:0:0

$net = Net::IP::Lite::Net->new('10.0/8') || die ...;
print $net->mask->binary(); # 11111111000000000000000000000000

network

Returns the original network definition that was specified as the constructor argument.

my $net = Net::IP::Lite::Net->new('1::/32') || die ...;
print $net->network(); # 1::/32

contains

Verifies whether an IP in the net.

$net = Net::IP::Lite::Net->new('1:: ffff::') || die ...;
$in = $net->contains('1:ff::1'); # TRUE

Also you can pass an Net::IP::Lite object:

$ip = Net::IP::Lite::Net->new('1::1') || die ...;
$net = Net::IP::Lite::Net->new('1::/32') || die ...;
my $in = $net->contains($ip); # TRUE

This method also can be used to check whether there are possible hosts in the network or not:

$net = Net::IP::Lite::Net->new('10.10.10.8/28');
$ok = $net->contains($net); # FALSE

$net = Net::IP::Lite::Net->new('10.10.10.8/29');
$ok = $net->contains($net); # TRUE

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::IP::Lite

You can also look for information at:

Code Repository at GitHub

http://github.com/alexey-komarov/Net-IP-Lite
GitHub Issue Tracker

http://github.com/alexey-komarov/Net-IP-Lite/issues
RT, CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-IP-Lite

AUTHOR

Alexey A. Komarov <alexkom@cpan.org>

COPYRIGHT

2013 Alexey A. Komarov

LICENSE

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

To install Net::IP::Lite, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::IP::Lite

CPAN shell

perl -MCPAN -e shell
install Net::IP::Lite

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

SUPPORTED FORMATS

PROCEDURAL INTERFACE

ip2bin

ip_validate

ip_is_ipv4

ip_is_ipv6

ip_is_ipv6ipv4

ip_transform

ip_equal

ip_equal_v4

ip_equal_v6

ip_in_range

EXPORTS

OBJECT-ORIENTED INTERFACE

Net::IP::Lite object

constructor

address

binary

is_ipv4

is_ipv6

is_ipv6ipv4

transform

equal

equal_v4

equal_v6

in_range

Net::IP::Lite::Net object

constructor

mask

network

contains

SEE ALSO

SUPPORT

AUTHOR

COPYRIGHT

LICENSE

Module Install Instructions