NetAddr::IP - Manages IPv4 (your traditional IP) addresses and subnets

     * * * * THIS MODULE REQUIRES PERL 5.6.0 OR NEWER. * * * *

This  module  is  designed as  a  help  for  managing (ranges  of)  IP
addresses. It includes efficient implementations for most common tasks
done  to subnets or  ranges of  IP addresses,  namely verifying  if an
address is within a subnet, comparing, looping, splitting subnets into
longer prefixes, compacting addresses to the shortest prefixes, etc.

The general idea, is that you should be able to do 

  use NetAddr::IP;

  my $ip = new NetAddr::IP $something_vaguely_resembling_a_subnet;

and as long  as $something_vaguely_resembling_a_subnet holds something
that describes  a subnet unambiguously,  you should receive  an object
representing such  subnet. Currently this includes  various flavors of
CIDR notation, traditional notation in one, two, three and four dotted
octets, hexadecimal, range and subnet notations.

Overloading is also  used to ease printing and  doing simple aritmetic
and comparisons on  the IP addresses. For instance,  you can do things
like:

  use NetAddr::IP;

  for (my $ip = new NetAddr::IP '10.0.0.1/28';
       $ip < $ip->broadcast;
       $ip ++) 
  {
    print "$ip\n";
  }

This will print out something like...

10.0.0.1/28
10.0.0.2/28
10.0.0.3/28
10.0.0.4/28
10.0.0.5/28
(and so on...)

...which  is  quite  useful   for  generating  config  files  and  the
such. This works even for huge ranges of IP addresses.

This module is entirely written in  Perl, so you do not need access to
a compiler to use it.  It  has been extensively tested in a variety of
platforms.  An extensive  test suite  is provided  with the  module to
verify correct results.

The lastest version of this module should be preferred. You can obtain
it  on http://www.cpan.org/authors/id/L/LU/LUISMUNOZ/  or  one of  the
many CPAN  mirrors. Please find a  mirror near you to  help spread the
load.

Note that version  3 and above is not  completely backwards compatible
with version 2.  Version 2 was a somewhat unstable  work that grew too
fast. If you're  upgrading from 2.xx, please review  your code as some
methods no longer exist or have changed.

**********************************************************************
* VERSIONS EARLIER THAN 3.00 WON'T BE SUPPORTED AT ALL. PLEASE DON'T *
* EVEN ASK. I have very limited time and this module has grown quite *
* popular. Please help me help you by staying up to date with it. If *
* you find a bug, upgrade  to the  latest version  on CPAN  prior to *
* contacting me.                                                     *
**********************************************************************

To install, follow the standard CPAN recipe of:

$ perl Makefile.PL
$ make
$ make test

If all tests pass, then do

$ make install

The  test suite includes  a lot  of cases.  Note that  currently, some
tests require Test::More. Eventually all tests will require it, so you
should really consider installing it if your Perl did not include this
module.

Tests related to address compaction could be too resource-intensive in
some environments. If  this is your case, you can  skip those tests by
setting an environment variable  before make'ing test.  In a bash-like
shell, you could use the following example:

$ LIGHTERIPTESTS=yes; export LIGHTERIPTESTS

The  module's  documentation  can   be  accessed  through  POD.  After
installing the module, you can do

$ perldoc NetAddr::IP

to access  the documentation. There is  also a tutorial  in HTML. Look
for  the file  tutorial.htm  within  the package  bundle,  which is  a
tutorial I submitted to perlmonks.org recently.

Bug  reports  are  welcome. Please  do  not  forget  to tell  me  what
version/platform are you running this code on. Providing a small piece
of  code that  shows the  bug helps  me a  lot in  sorting it  out and
possibly in writting more tests for the distribution.

Also, this code is intended to be strict and -w safe, so please report
cases where warnings are generated so that I can fix them.

Report your bugs to me (luismunoz@cpan.org).

This software is (c) Luis E. Munoz.  It can be used under the terms of
the perl artistic license provided  that proper credit for the work of
the  author is  preserved in  the form  of this  copyright  notice and
license for this module.

$Id: README,v 1.2 2002/10/31 04:30:22 lem Exp $