Newer
Older
NetAddr-IP / README
  1. NetAddr::IP - Manages IPv4 (your traditional IP) addresses and subnets
  2.  
  3. * * * * THIS MODULE REQUIRES PERL 5.6.0 OR NEWER. * * * *
  4.  
  5. This module is designed as a help for managing (ranges of) IP
  6. addresses. It includes efficient implementations for most common tasks
  7. done to subnets or ranges of IP addresses, namely verifying if an
  8. address is within a subnet, comparing, looping, splitting subnets into
  9. longer prefixes, compacting addresses to the shortest prefixes, etc.
  10.  
  11. The general idea, is that you should be able to do
  12.  
  13. use NetAddr::IP;
  14.  
  15. my $ip = new NetAddr::IP $something_vaguely_resembling_a_subnet;
  16.  
  17. and as long as $something_vaguely_resembling_a_subnet holds something
  18. that describes a subnet unambiguously, you should receive an object
  19. representing such subnet. Currently this includes various flavors of
  20. CIDR notation, traditional notation in one, two, three and four dotted
  21. octets, hexadecimal, range and subnet notations.
  22.  
  23. Overloading is also used to ease printing and doing simple aritmetic
  24. and comparisons on the IP addresses. For instance, you can do things
  25. like:
  26.  
  27. use NetAddr::IP;
  28.  
  29. for (my $ip = new NetAddr::IP '10.0.0.1/28';
  30. $ip < $ip->broadcast;
  31. $ip ++)
  32. {
  33. print "$ip\n";
  34. }
  35.  
  36. This will print out something like...
  37.  
  38. 10.0.0.1/28
  39. 10.0.0.2/28
  40. 10.0.0.3/28
  41. 10.0.0.4/28
  42. 10.0.0.5/28
  43. (and so on...)
  44.  
  45. ...which is quite useful for generating config files and the
  46. such. This works even for huge ranges of IP addresses.
  47.  
  48. This module is entirely written in perl, so you do not need access to
  49. a compiler to use it. It has been extensively tested in a variety of
  50. platforms. An extensive test suite is provided with the module to
  51. verify correct results.
  52.  
  53. The lastest version of this module should be preferred. You can obtain
  54. it on http://www.cpan.org/authors/id/L/LU/LUISMUNOZ/ or one of the
  55. many CPAN mirrors. Please find a mirror near you to help spread the
  56. load.
  57.  
  58. Note that version 3 and above is not completely backwards compatible
  59. with version 2. Version 2 was a somewhat unstable work that grew too
  60. fast. If you're upgrading from 2.xx, please review your code as some
  61. methods no longer exist or have changed.
  62.  
  63. To install, follow the standard CPAN recipe of:
  64.  
  65. $ perl Makefile.PL
  66. $ make
  67. $ make test
  68.  
  69. If all tests pass, then do
  70.  
  71. $ make install
  72.  
  73. Tests related to address compaction could be too resource-intensive in
  74. some environments. If this is your case, you can skip those tests by
  75. setting an environment variable before make'ing test. In a bash-like
  76. shell, you could use the following example:
  77.  
  78. $ LIGHTERIPTESTS=yes; export LIGHTERIPTESTS
  79.  
  80. The module's documentation can be accessed through POD. After
  81. installing the module, you can do
  82.  
  83. $ perldoc NetAddr::IP
  84.  
  85. to access the documentation.
  86.  
  87. Bug reports are welcome. Please do not forget to tell me what
  88. version/platform are you running this code on. Providing a small piece
  89. of code that shows the bug helps me a lot in sorting it out and
  90. possibly in writting more tests for the distribution.
  91.  
  92. Also, this code is intended to be strict and -w safe, so please report
  93. cases where warnings are generated so that I can fix them.
  94.  
  95. Report your bugs to me (luismunoz@cpan.org).
  96.  
  97. This software is (c) Luis E. Munoz. It can be used under the terms of
  98. the perl artistic license provided that proper credit for the work of
  99. the author is preserved in the form of this copyright notice and
  100. license for this module.