ipadmin 0.2.1 → 0.2.2

data/README

@@ -1,5 +1,5 @@
 
- Copyright (c) 2006 Dustin Spinhirne
+ Copyright (c) 2006 Dustin Spinhirne - http://www.spinhirne.com
  Licensed under the same terms as Ruby, No Warranty is provided.
 
 
@@ -8,6 +8,64 @@
  
  Dustin Spinhirne
  
+
+=CIDR
+
+ A class & series of methods for creating and manipulating CIDR network
+ addresses. Both IPv4 and IPv6 are supported.
+ 
+ This class accepts a CIDR address in (x.x.x.x/yy or xxxx::/yy) format for
+ IPv4 and IPv6, or (x.x.x.x/y.y.y.y) for IPv4. An optional tag hash may be 
+ provided with each CIDR as a way of adding custom labels to the object.
+ 
+ Upon initialization, the IP version is auto-detected and assigned to the 
+ object. The original IP/Netmask passed within the CIDR is stored and then 
+ used to determine the confines of the CIDR block. Various properties of the
+ CIDR block are accessible via several different methods. There are also
+ methods for modifying the CIDR or creating new derivative CIDR's.
+ 
+ An example CIDR object is as follows:
+    IPAdmin::CIDR.new(:CIDR => '192.168.1.20/24')
+ 
+ This would create a CIDR object (192.168.1.0/24) with the following properties:
+    version = 4
+    base network = 192.168.1.0
+    ip address = 192.168.1.20
+    netmask = /24 (255.255.255.0)
+    size = 256 IP addresses
+    broadcast = 192.168.1.255
+    
+ You can see how the CIDR object is based around the entire IP space
+ defined by the provided IP/Netmask pair, and not necessarily the individual
+ IP address itself.
+
+
+=Tree
+
+ A class & series of methods for creating and manipulating IP-based
+ heirarchical trees. Both IPv4 and IPv6 are supported.
+
+ Tree's are useful for creating mini 'routing tables' of CIDR address space.
+ Using a tree, you can quickly determine the 'route' of another CIDR via
+ the standard longest-match algorithm.
+ 
+ Tree's are not dynamic, in that if you modify any of the CIDR objects
+ contained within, the Tree will not automatically adjust itself accordingly.
+ For example if you have a tree like the following:
+ 
+    192.168.0.0/24
+        192.168.0.0/26
+    192.168.1.0/24
+    
+ You decide to resize 192.168.0.0/24 to 192.168.0.0/23. The tree will now
+ be incorrect:
+ 
+    192.168.0.0/23
+        192.168.0.0/26
+    192.168.1.0/24
+ 
+ You would need to remove and re-add the CIDR 192.168.0.0/23 in order for the
+ tree to rebuild itself properly.
  
  
  
@@ -42,8 +100,16 @@
  cidr4.tag['test'] = 'modified cidr4 tag'
  puts "updated cidr4 tag '#{cidr4.tag['test']}'"
  puts "cidr4 version #{cidr4.version}"
+ puts "cidr6 version #{cidr6.version}"
  print "\n"
   
+ 
+ # arpa
+ puts "arpa"
+ puts "arpa for #{cidr4.desc()} is #{cidr4.arpa}"
+ puts "arpa for #{cidr6.desc(:Short => true)} is #{cidr6.arpa}"
+ print "\n"
+ 
  # bits
  puts "bits"
  puts "cidr4 netmask in bits #{cidr4.bits()}"
@@ -53,7 +119,7 @@
  # contains?
  puts "contains"
  puts "#{cidr4.desc} contains #{cidr4_2.desc}" if ( cidr4.contains?(cidr4_2) )
- puts "#{cidr6.desc} contains #{cidr6_2.desc}" if ( cidr6.contains?(cidr6_2) )
+ puts "#{cidr6.desc} contains #{cidr6_2.desc(:Short => true)}" if ( cidr6.contains?(cidr6_2) )
  print "\n"
 
  # desc
@@ -151,6 +217,7 @@
  # remainder
  puts "remainder"
  cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
+ puts "The remainder of #{cidr4.desc} after subtracting #{cidr4_2.desc} is:"
  cidr4.remainder(:Exclude => cidr4_2).each {|x| puts x}
  print "\n" 
   
@@ -304,6 +371,7 @@
  #=====================================#
  #
  #=====================================#
+ 
 
  #============================================================================#
  # IPAdmin Methods
@@ -313,15 +381,16 @@
  
  # validate ip
  puts "validate ip"
- puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv4_addr('192.168.1.0') )
- puts "fec0::0 is valid" if ( IPAdmin.validate_ipv6_addr('fec0::0') )
+ puts "192.168.1.0 is valid" if ( IPAdmin.validate_ip_addr(:IP => '192.168.1.0') )
+ puts "fec0::0 is valid" if ( IPAdmin.validate_ip_addr(:IP => 'fec0::0') )
+ puts "::ffff:10.1.0.1 is valid" if ( IPAdmin.validate_ip_addr(:IP => '::ffff:10.1.0.1') )
  print "\n"
 
  # validate netmask
  puts "validate netmask"
- puts "255.255.255.0 is valid" if (IPAdmin.validate_ipv4_netmask('255.255.255.0') )
- puts "/24 is valid" if ( IPAdmin.validate_ipv4_netmask(24) )
- puts "/64 is valid" if ( IPAdmin.validate_ipv6_netmask(64) )
+ puts "255.255.255.0 is valid" if (IPAdmin.validate_ip_netmask(:Netmask => '255.255.255.0') )
+ puts "/24 is valid" if ( IPAdmin.validate_ip_netmask(:Netmask => '/24') )
+ puts "/64 is valid" if ( IPAdmin.validate_ip_netmask(:Netmask => 64, :Version => 6) )
 
  cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
  cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/25')
@@ -351,12 +420,6 @@
   puts "  #{x}"
  end
  print "\n"
-
- # arpa
- puts "arpa"
- puts "arpa for #{cidr4_1.desc()} is #{IPAdmin.arpa(cidr4_1)}"
- puts "arpa for #{cidr6_1.desc()} is #{IPAdmin.arpa(cidr6_1)}"
- print "\n"
  
  # shorten
  puts "shorten"
@@ -370,3 +433,4 @@
  #=====================================#
  #
  #=====================================#
+

data/lib/cidr.rb

@@ -0,0 +1,1459 @@
+=begin rdoc
+ Copyright (c) 2006 Dustin Spinhirne -  
+ Licensed under the same terms as Ruby, No Warranty is provided.
+=end
+
+
+module IPAdmin
+class CIDR
+
+# instance variables
+# @all_f
+# @hostmask
+# @ip
+# @max_bits 
+# @netmask
+# @network
+# @tag
+# @version
+
+#==============================================================================#
+# attr_reader/attr_writer
+#==============================================================================#
+
+    # IP version 4 or 6.
+    attr_reader :version
+
+    # Hash of custom tags. Should be in the format tag => value.
+    attr_reader :tag
+
+    # Hash of custom tags. Should be in the format tag => value.
+    #
+    # Example:
+    #   cidr4.tag['test'] = 'modified cidr4 tag'
+    #   puts cidr4.tag['test']   --> modified cidr4 tag
+    #
+    def tag=(new_tag)
+        if (!new_tag.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{new_tag.class} provided."
+        end
+        @tag = new_tag
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# initialize()
+#==============================================================================#
+
+# - Arguments:
+#   * Hash with the following fields:
+#       - :CIDR -- IP address in CIDR notation - String (optional)
+#       - :Netmask -- IP Netmask - String or Integer (optional)
+#       - :PackedIP -- Integer representation of an IP address (optional)
+#       - :PackedNetmask -- Integer representation of an IP Netmask (optional)
+#       - :Version -- IP version - Integer (optional)
+#       - :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#
+# - Notes:
+#   * At a minimum, either :CIDR or PackedIP must be provided.
+#   * Netmask defaults to /32 or /128 if not provided.
+#   * :PackedIP takes precedence over :CIDR
+#   * :PackedNetmask always takes precedence over any other provided netmasks.
+#   * Netmask within :CIDR takes precedence over :Netmask.
+#   * Version will be auto-detected if not specified
+#
+# Example:
+#   cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.1/24')
+#   cidr4_2 = IPAdmin::CIDR.new(:PackedIP => 0x0a010001,
+#                               :PackedNetmask => 0xffffff00
+#                               :Version => 4)
+#   cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::/64',
+#                             :Tag => {'interface' => 'g0/1'})
+#   cidr6_2 = IPAdmin::CIDR.new(:CIDR => '::ffff:192.168.1.1/96')
+#
+    def initialize(options)
+        if (!options.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
+        end
+
+
+        if (options.has_key?(:PackedIP))
+            packed_ip = options[:PackedIP]
+            raise ArgumentError, "Expected Integer, but #{packed_ip.class} " +
+                                 "provided for option :PackedIP." if (!packed_ip.kind_of?(Integer))
+        elsif (options.has_key?(:CIDR))
+            cidr =  options[:CIDR]
+            raise ArgumentError, "Expected String, but #{cidr.class} " +
+                                 "provided for option :CIDR." if (!cidr.kind_of?(String))      
+        else
+            raise ArgumentError, "Missing argument: CIDR or PackedIP."
+        end        
+        
+        
+        if (options.has_key?(:PackedNetmask))
+            packed_netmask = options[:PackedNetmask]
+            raise ArgumentError, "Expected Integer, but #{packed_netmask.class} " +
+                                 "provided for option :PackedNetmask." if (!packed_netmask.kind_of?(Integer))
+
+        elsif (options.has_key?(:Netmask))
+            netmask = options[:Netmask]
+            raise ArgumentError, "Expected String or Integer, but #{netmask.class} " +
+                                 "provided for option :Netmask." if (!netmask.kind_of?(String) && !netmask.kind_of?(Integer))
+        end      
+        
+        
+        if (options.has_key?(:Version))
+            @version = options[:Version]
+            if (@version != 4 && @version != 6)
+                raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+            end
+        end
+        
+        if (options.has_key?(:Tag))
+            @tag = options[:Tag]
+            if (!@tag.kind_of? Hash)
+                raise ArgumentError, "Expected Hash, but #{@tag.class} provided for option :Tag."
+            end
+        end
+        
+        
+        if (packed_ip)
+            if (packed_ip < 2**32)
+                @version = 4 if (!@version)
+                @netmask = 2**32-1 if (!netmask && !packed_netmask)
+            else
+                @version = 6 if (!@version)
+                @netmask = 2**128-1 if (!netmask && !packed_netmask)
+            end
+            
+            # validate & store packed_ip
+            IPAdmin.validate_ip_addr(:IP => packed_ip, :Version => @version)
+            @ip = packed_ip
+        
+        else            
+            # determine version if not set
+            if (!@version)
+                if (cidr =~ /\./ && cidr !~ /:/)
+                    @version = 4
+                elsif (cidr =~ /:/)
+                    @version = 6
+                end
+            end        
+
+            # get ip/netmask
+            if (cidr =~ /\//) # if netmask part of cidr
+                ip,netmask = cidr.split(/\//)
+                raise ArgumentError, ":CIDR is improperly formatted." if (!ip || !netmask)
+            elsif (@version == 4)
+                ip = cidr
+                @netmask = 2**32-1 if (!netmask && !packed_netmask)
+            elsif (@version == 6)
+                ip = cidr
+                @netmask = 2**128-1 if (!netmask && !packed_netmask)
+            end
+
+            # validate & pack ip
+            IPAdmin.validate_ip_addr(:IP => ip, :Version => @version)                
+            @ip = IPAdmin.pack_ip_addr(:IP => ip, :Version => @version)            
+            
+        end
+
+                
+        # validate & store netmask || packed_netmask if needed
+        if (!@netmask)
+            if (packed_netmask)
+                IPAdmin.validate_ip_netmask(:Netmask => packed_netmask, :Packed => true, :Version => @version)
+                @netmask = packed_netmask
+            else
+                IPAdmin.validate_ip_netmask(:Netmask => netmask, :Version => @version)
+                @netmask = IPAdmin.pack_ip_netmask(:Netmask => netmask, :Version => @version)
+            end
+        end
+        
+        # set vars based on version
+        if (@version == 4)
+            @max_bits = 32
+            @all_f = 2**@max_bits - 1
+        else
+            @max_bits = 128
+            @all_f = 2**@max_bits - 1
+        end
+        
+        # get @network & @hostmask
+        @network = (@ip & @netmask)
+        @hostmask = @netmask ^ @all_f
+
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# arpa()
+#==============================================================================#
+
+# Depending on the IP version of the current CIDR, 
+# return either an in-addr.arpa. or ip6.arpa. string. The netmask will be used
+# to determine the length of the returned string.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * String
+#
+# Example:
+#   arpa = cidr4.arpa() --> '1.168.192.in-addr.arpa.'
+#
+    def arpa()
+
+        base = self.ip()
+        netmask = self.bits()
+
+        if (@version == 4)
+            net = base.split('.')
+
+            if (netmask)
+                while (netmask < 32)
+                    net.pop
+                    netmask = netmask + 8
+                end
+            end
+
+            arpa = net.reverse.join('.')
+            arpa << ".in-addr.arpa."
+
+        elsif (@version == 6)
+            fields = base.split(':')
+            net = []
+            fields.each do |field|
+                (field.split("")).each do |x|
+                    net.push(x)
+                end
+            end
+
+            if (netmask)
+                while (netmask < 128)
+                    net.pop
+                    netmask = netmask + 4
+                end
+            end
+
+            arpa = net.reverse.join('.')
+            arpa << ".ip6.arpa."
+
+        end
+
+        return(arpa)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# bits()
+#==============================================================================#
+
+# Provide number of bits in Netmask.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * Integer.
+#
+# Example:
+#   puts cidr4.bits()   --> 24
+#
+    def bits()
+        return(IPAdmin.unpack_ip_netmask(:Integer => @netmask))
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# contains?()
+#==============================================================================#
+
+# Determines if this CIDR contains (is supernet of)
+# the provided CIDR object.
+#
+# - Arguments:
+#   * CIDR object
+#
+# - Returns:
+#   * true or false
+#
+# Example:
+#   cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26')
+#   contains? = cidr4.contains(cidr4_2)   --> true
+#
+    def contains?(object)
+        is_contained = false
+
+        if (object.kind_of?(IPAdmin::CIDR))
+            network = object.packed_network 
+            netmask = object.packed_netmask
+
+        else 
+            raise ArgumentError, "Expected IPAdmin::CIDR " +
+                                 " object but #{object.class} provided."
+        end
+
+
+        if (object.version != @version)
+            raise ArgumentError, "Attempted to compare a version #{object.version} CIDR " +
+                                 "with a version #{@version} CIDR."
+        end
+
+        # if network == @network, then we have to go by netmask length
+        # else we can tell by or'ing network and @network by @hostmask
+        # and comparing the results
+        if (network == @network)
+            is_contained = true if (netmask > @netmask)
+
+        else
+            if ( (network | @hostmask) == (@network | @hostmask) )
+                is_contained = true
+            end
+        end
+
+        return(is_contained)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# desc()
+#==============================================================================#
+
+# Returns network/netmask in CIDR format.
+#
+# - Arguments:
+#   * Optional hash with the following fields:
+#       - :IP -- if true, return the original ip/netmask passed during initialization (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String
+#
+# Example:
+#   puts cidr4.desc()   --> 192.168.1.0/24
+#   puts cidr4.desc(:IP => true)   --> 192.168.1.1/24
+#
+    def desc(options=nil)
+        short = false
+        orig_ip = false
+
+        if (options)
+            if (!options.kind_of? Hash)
+                raise ArgumentError, "Expected Hash, but #{options.class} provided."
+            end
+            
+            if (options.has_key?(:Short))
+                short = true
+            end
+            
+            if (options.has_key?(:IP))
+                orig_ip = true
+            end
+        end
+        
+        if (!orig_ip)
+            ip = IPAdmin.unpack_ip_addr(:Integer => @network, :Version => @version)
+        else
+            ip = IPAdmin.unpack_ip_addr(:Integer => @ip, :Version => @version)
+        end
+        ip = IPAdmin.shorten(ip) if (short && @version == 6)
+        mask = IPAdmin.unpack_ip_netmask(:Integer => @netmask)
+
+        return("#{ip}/#{mask}")
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# enumerate()
+#==============================================================================#
+
+# Provide all IP addresses contained within the IP space of this CIDR.
+# (warning: this can be quite large for big blocks)
+#
+# - Arguments:
+#   * Optional Hash with the following fields:
+#       - :Bitstep -- enumerate in X sized steps 0 - Integer (optional)
+#       - :Limit -- limit returned list to X number of items - Integer (optional)
+#       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * Array of Strings or CIDR objects
+#
+# Example:
+#   ip_list = cidr4.enumerate(:Bitstep => 2, :Limit => 2)   --> ['192.168.1.0','192.168.1.1']
+#
+    def enumerate(options=nil)
+        bitstep = 1
+        objectify = false
+        limit = nil
+        short = false
+
+        if (options)
+            if (!options.kind_of? Hash)
+                raise ArgumentError, "Expected Hash, but #{options.class} provided."
+            end
+            
+            if( options.has_key?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+
+            if( options.has_key?(:Limit) )
+                limit = options[:Limit]
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+        end
+
+        list = []
+        my_ip = @network
+        change_mask = @hostmask | my_ip
+
+        until ( change_mask != (@hostmask | @network) ) 
+            if (!objectify)
+                my_ip_s = IPAdmin.unpack_ip_addr(:Integer => my_ip, :Version => @version)
+                my_ip_s = IPAdmin.shorten(my_ip_s) if (short && @version == 6)
+                list.push( my_ip_s )
+            else
+                list.push( IPAdmin::CIDR.new(:PackedIP => my_ip, :Version => @version) )
+            end
+            my_ip = my_ip + bitstep
+            change_mask = @hostmask | my_ip
+            if (limit)
+                limit = limit -1
+                break if (limit == 0)
+            end
+        end       
+        
+        return(list)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# hostmask_ext()
+#==============================================================================#
+
+# Provide IPv4 Hostmask in extended format (y.y.y.y).
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * String
+#
+# Example:
+#   puts cidr4.hostmask_ext()   --> 0.0.0.255
+#
+    def hostmask_ext()
+        if (@version == 4)
+            hostmask = IPAdmin.unpack_ip_addr(:Integer => @hostmask, :Version => @version)
+        else
+            raise "IPv6 does not support extended hostmask notation." 
+        end
+
+        return(hostmask)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# ip()
+#==============================================================================#
+
+# Provide original IP address passed during initialization.
+#
+# - Arguments:
+#   * Optional Hash with the following fields:
+#       - :Objectify -- if true, return IPAdmin::CIDR object (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String or CIDR object.
+#
+# Example:
+#   puts cidr4.ip()   --> 192.168.1.1
+#
+    def ip(options=nil)
+        objectify = false
+        short = false
+        
+        if (options)
+            if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+            
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+        end
+
+        
+        
+        if (!objectify)
+            ip = IPAdmin.unpack_ip_addr(:Integer => @ip, :Version => @version)
+            ip = IPAdmin.shorten(ip) if (short && @version == 6)
+        else
+            ip = IPAdmin::CIDR.new(:PackedIP => @ip, :Version => @version)
+        end
+
+        return(ip)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# last()
+#==============================================================================#
+
+# Provide last IP address in this CIDR object. 
+#
+# - Arguments:
+#   * Optional Hash with the following fields:
+#       - :Objectify -- if true, return IPAdmin::CIDR object (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String or CIDR object.
+#
+# - Notes:
+#   * The broadcast() method is liased to this method, and thus works for
+#     IPv6 despite the fact that the IPv6 protocol does not support IP
+#     broadcasting.
+#
+# Example:
+#   puts cidr4.last()   --> 192.168.1.255
+#
+    def last(options=nil)
+        objectify = false
+        short = false
+        
+        if (options)
+            if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+            
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+
+        end
+        
+        packed_ip = @network | @hostmask
+        if (!objectify)
+            ip = IPAdmin.unpack_ip_addr(:Integer => packed_ip, :Version => @version)
+            ip = IPAdmin.shorten(ip) if (short && !objectify && @version == 6)
+        else
+            ip = IPAdmin::CIDR.new(:PackedIP => packed_ip, :Version => @version)
+        end
+
+        return(ip)
+    end
+    
+    alias :broadcast :last
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# netmask()
+#==============================================================================#
+
+# Provide netmask in CIDR format.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * String
+#
+# Example:
+#   puts cidr4.netmask()   --> /24
+#
+    def netmask()
+        bits = IPAdmin.unpack_ip_netmask(:Integer => @netmask)
+        return("/#{bits}")
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# netmask_ext()
+#==============================================================================#
+
+# Provide IPv4 netmask in extended format (y.y.y.y).
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * String
+#
+# Example:
+#   puts cidr4.netmask_ext()   --> 255.255.255.0
+#
+    def netmask_ext()    
+        if (@version == 4)
+            netmask = IPAdmin.unpack_ip_addr(:Integer => @netmask)
+        else
+            raise "IPv6 does not support extended netmask notation. " +
+                  "Use netmask() method instead."
+        end
+
+        return(netmask)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# network()
+#==============================================================================#
+
+# Provide base network address.
+#
+# - Arguments:
+#   * Optional Hash with the following fields:
+#       - :Objectify -- if true, return IPAdmin::CIDR object (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String or CIDR object.
+#
+# Example:
+#   puts cidr4.network()   --> 192.168.1.0
+#
+    def network(options=nil)
+        objectify = false
+        short = false
+        
+        if (options)
+            if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+            
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+        end
+
+            
+        if (!objectify)
+            ip = IPAdmin.unpack_ip_addr(:Integer => @network, :Version => @version)
+            ip = IPAdmin.shorten(ip) if (short && @version == 6)
+        else
+            ip = IPAdmin::CIDR.new(:PackedIP => @network, :Version => @version)
+        end
+
+        return(ip)
+    end
+
+    alias :base :network
+    alias :first :network
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# next_ip()
+#==============================================================================#
+
+# Provide the next IP following the last available IP within this 
+# CIDR object. 
+#
+# - Arguments:
+#   * Optional Hash with the following fields:
+#       - :Bitstep -- step in X sized steps - Integer (optional)
+#       - :Objectify -- if true, return IPAdmin::CIDR object (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String or CIDR object.
+#
+# Example:
+#   puts cidr4.next_ip()   --> 192.168.2.0
+#
+    def next_ip(options=nil)
+        bitstep = 1
+        objectify = false
+        short = false
+        
+        if (options)
+            if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+            end
+            
+            if( options.has_key?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+        end
+        
+        next_ip = @network + @hostmask + bitstep
+        
+        if (next_ip > @all_f)
+            raise "Returned IP is out of bounds for IPv#{@version}."
+        end
+
+                
+        if (!objectify)
+            next_ip = IPAdmin.unpack_ip_addr(:Integer => next_ip, :Version => @version)
+            next_ip = IPAdmin.shorten(next_ip) if (short && @version == 6)
+        else
+            next_ip = IPAdmin::CIDR.new(:PackedIP => next_ip, :Version => @version)
+        end
+        
+        return(next_ip)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# next_subnet()
+#==============================================================================#
+
+# Provide the next subnet following this CIDR object. The next subnet will
+# be of the same size as the current CIDR object. 
+#
+# - Arguments:
+#   * Optional Hash with the following fields:
+#       - :Bitstep -- step in X sized steps. - Integer (optional)
+#       - :Objectify -- if true, return IPAdmin::CIDR object (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String or CIDR object.
+#
+# Example:
+#   puts cidr4.next_subnet()   --> 192.168.2.0/24
+#
+    def next_subnet(options=nil)
+        bitstep = 1
+        objectify = false
+        short = false
+        
+        if (options)
+            if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+            end
+            
+            if( options.has_key?(:Bitstep) )
+                bitstep = options[:Bitstep]
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+        end
+        
+        bitstep = bitstep * (2**(@max_bits - self.bits) )
+        next_sub = @network + bitstep
+        
+        if (next_sub > @all_f)
+            raise "Returned subnet is out of bounds for IPv#{@version}."
+        end
+
+        netmask =  self.bits       
+        if (!objectify)
+            next_sub = IPAdmin.unpack_ip_addr(:Integer => next_sub, :Version => @version)
+            next_sub = IPAdmin.shorten(next_sub) if (short && @version == 6)        
+            next_sub = next_sub << "/" << netmask.to_s
+        else
+            next_sub = IPAdmin::CIDR.new(:PackedIP => next_sub, :Netmask => netmask, :Version => @version)
+        end
+        
+        return(next_sub)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# nth()
+#==============================================================================#
+
+# Provide the nth IP within this object.
+#
+# - Arguments:
+#   * Hash with the following fields:
+#       - :Index -- index number of the IP address to return - Integer
+#       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * String or CIDR object.
+#
+# Example:
+#   puts cidr4.nth(:Index => 1)   --> 192.168.1.1
+#
+    def nth(options)
+        objectify = false
+        short = false
+
+        if (!options.kind_of?(Hash))
+            raise ArgumentError, "Expected Hash, but " +
+                                 "#{options.class} provided."
+        end
+        
+        if ( !options.has_key?(:Index) )
+            raise ArgumentError, "Missing argument: Index."
+        end
+        index = options[:Index]
+
+        if( options.has_key?(:Short) )
+            short = true
+        end
+        
+        if( options.has_key?(:Objectify) )
+                objectify = true
+        end
+
+        my_ip = @network + index
+        if ( (@hostmask | my_ip) == (@hostmask | @network) )
+            
+            if (!objectify)
+                my_ip = IPAdmin.unpack_ip_addr(:Integer => my_ip, :Version => @version)
+                my_ip = IPAdmin.shorten(my_ip) if (short && @version == 6)
+            else
+                my_ip = IPAdmin::CIDR.new(:PackedIP => my_ip, :Version => @version)
+            end
+
+        else
+            raise "Index of #{index} returns IP that is out of " +
+                  "bounds of CIDR network."
+        end
+
+        return(my_ip)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# packed_hostmask()
+#==============================================================================#
+
+# Provide an integer representation of the Hostmask of this object.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * Integer
+#
+# Example:
+#   puts cidr4.packed_hostmask().to_s(16)   --> 0xff
+#
+    def packed_hostmask()
+        return(@hostmask)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# packed_ip()
+#==============================================================================#
+
+# Provide an integer representation of the IP address of this object.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * Integer
+#
+# Example:
+#   puts cidr4.packed_ip().to_s(16)   --> 0xc0c80101
+#
+    def packed_ip()
+        return(@ip)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# packed_netmask()
+#==============================================================================#
+
+# Provide an integer representation of the Netmask of this object.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * Integer
+#
+# Example:
+#   puts cidr4.packed_netmask().to_s(16)   --> 0xffffff00
+#
+    def packed_netmask()
+        return(@netmask)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# packed_network()
+#==============================================================================#
+
+# Provide an integer representation of the Network address of this object.
+#
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Integer
+#
+# Example:
+#   packed = cidr4.packed_network().to_s(16)   --> 0xc0c80100
+#
+    def packed_network()
+        return(@network)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# range()
+#==============================================================================#
+
+# Given two Indexes, return all IP addresses within the CIDR that are
+# between them (inclusive).
+#
+# - Arguments:
+#   * Hash with the following fields:
+#       - :Bitstep -- enumerate in X sized steps - Integer (optional)
+#       - :Indexes -- index numbers of the addresses to use as boundaries - Array of (2) Integers
+#       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * Array Strings or CIDR objects
+#
+# Example:
+#   list = cidr4.range(:Indexes => [0,1]) --> ['192.168.1.0','192.168.1.1']
+#
+    def range(options)
+        objectify = false
+        short = false
+        bitstep = 1
+
+        if (!options.kind_of?(Hash))
+            raise Argumenterror, "Expected Hash, but #{options.class} provided."
+        end
+        
+        if ( !options.has_key?(:Indexes) )
+            raise ArgumentError, "Missing argument: Indexes."
+        end
+        indexes = options[:Indexes]
+        indexes.sort!
+        
+        if( (!indexes.kind_of?(Array)) || (indexes.length != 2))
+            raise ArgumentError, "Argument :Index should be an array of (2) index numbers."
+        end
+
+        if ( (indexes[0] < 0) || (indexes[0] > self.size) )
+            raise ArgumentError, "Index #{indexes[0]} is out of bounds for this CIDR."
+        end
+        
+        if (indexes[1] >= self.size)
+            raise ArgumentError, "Index #{indexes[1]} is out of bounds for this CIDR."
+        end
+        
+        if( options.has_key?(:Short) )
+            short = true
+        end
+        
+        if( options.has_key?(:Objectify) )
+            objectify = true
+        end
+        
+        if( options.has_key?(:Bitstep) )
+            bitstep = options[:Bitstep]
+        end
+
+        start_ip = @network + indexes[0]
+        end_ip = @network + indexes[1]
+        my_ip = start_ip
+        list = []
+        until (my_ip > end_ip)            
+            if (!objectify)
+                ip = IPAdmin.unpack_ip_addr(:Integer => my_ip, :Version => @version)
+                ip = IPAdmin.shorten(ip) if (short && @version == 6)
+            else
+                ip = IPAdmin::CIDR.new(:PackedIP => my_ip, :Version => @version)
+            end
+            
+            list.push(ip)
+            my_ip += bitstep
+        end
+
+        return(list)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# remainder()
+#==============================================================================#
+
+# Given a portion of the current CIDR, provide the remainder of
+# the CIDR. For example if the original CIDR is 192.168.0.0/24 and you
+# provide 192.168.0.64/26 as the portion to exclude, then 192.168.0.0/26,
+# 192.168.0.128/26, and 192.168.0.192/26 will be returned as the remainder.
+#
+# - Arguments:
+#   * Optional hash with the following fields:
+#       - :Exclude -- CIDR object to use in calculating the remainder.
+#       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#
+# - Returns:
+#   * Array of Strings or CIDR objects
+#
+#
+# Example:
+#   cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
+#   cidr4.remainder(:Exclude => cidr4_2).each {|x| puts}
+#
+    def remainder(options)
+        short = nil
+        objectify = nil
+        
+        if (!options.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
+        end
+            
+        if ( !options.has_key?(:Exclude) )
+            raise ArgumentError, "Missing argument: Exclude."
+        end
+        to_exclude = options[:Exclude]
+            
+        if ( !to_exclude.kind_of?(IPAdmin::CIDR) )
+            raise ArgumentError, "Expeced IPAdmin::CIDR, but #{exclude.class} " +
+                                 "for option: Exclude."
+        end
+        
+        if( options.has_key?(:Short) )
+            short = true
+        end
+        
+        if( options.has_key?(:Objectify) )
+            objectify = true
+        end
+        
+        # make sure 'to_exclude' is the same ip version
+        if ( to_exclude.version != @version )
+            raise "#{to_exclude.desc(:Short => true)} is of a different " +
+                  "IP version than #{self.desc(:Short => true)}."
+        end    
+
+        # make sure we contain 'to_exclude'
+        if ( self.contains?(to_exclude) != true )
+            raise "#{to_exclude.desc(:Short => true)} does not fit " +
+                  "within the bounds of #{self.desc(:Short => true)}."
+        end
+
+        # split this cidr in half & see which half 'to_exclude'
+        # belongs in. take that half & repeat the process. every time
+        # we repeat, store off the non-matching half
+        new_mask = self.bits + 1
+        lower_network = self.packed_network
+        upper_network = self.packed_network + 2**(@max_bits - new_mask)
+        
+        new_subnets = []
+        until(new_mask > to_exclude.bits)
+            if (to_exclude.packed_network < upper_network)
+                match = lower_network
+                non_match = upper_network
+            else
+                match = upper_network
+                non_match = lower_network
+            end
+
+            
+            if (!objectify)
+                non_match = IPAdmin.unpack_ip_addr(:Integer => non_match, :Version => @version)
+                non_match = IPAdmin.shorten(non_match) if (short && @version == 6)
+                new_subnets.unshift("#{non_match}/#{new_mask}")
+            else
+                new_subnets.unshift(IPAdmin::CIDR.new(:PackedIP => non_match, 
+                                                      :Netmask => new_mask, 
+                                                      :Version => @version))
+            end
+            
+            new_mask = new_mask + 1
+            lower_network = match
+            upper_network = match + 2**(@max_bits - new_mask)
+        end
+        
+        return(new_subnets)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# resize()
+#==============================================================================#
+
+# Resize the CIDR by changing the size of the Netmask. 
+# Return the resulting CIDR as a new object.
+#
+# - Arguments:
+#   * Hash with the following fields:
+#       - :Subnet -- Number of bits of new Netmask - Integer
+#
+# - Returns:
+#   * CIDR object
+#
+# Example:
+#   new_cidr = cidr4.resize(:Subnet => 23)
+#   puts new_cidr.desc   --> 192.168.1.0/23
+#
+    def resize(options)
+        if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+        end
+            
+        if ( !options.has_key?(:Subnet) )
+                raise Argumenterror, "Missing argument: Subnet."
+        end
+        bits = options[:Subnet]
+        
+        IPAdmin.validate_ip_netmask(:Netmask => bits, :Version => @version)
+        netmask = IPAdmin.pack_ip_netmask(:Netmask => bits, :Version => @version)
+        network = @network & netmask
+        
+        cidr = IPAdmin::CIDR.new(:PackedIP => network, :PackedNetmask => netmask, :Version => @version)
+        return(cidr)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# resize!()
+#==============================================================================#
+
+# Resize this object by changing the size of the Netmask. 
+#
+# - Arguments:
+#   * Hash with the following fields:
+#       - :Subnet -- Number of bits of new Netmask - Integer
+#
+# - Returns:
+#   * nil
+#
+# - Notes:
+#   * If CIDR is resized such that the original IP is no longer contained within,
+#     then that IP will be reset to the base network address.
+#
+# Example:
+#   cidr4.resize!(:Subnet => 23)
+#   puts cidr4.desc   --> 192.168.1.0/23
+#
+    def resize!(options)
+        if (!options.kind_of?(Hash))
+                raise Argumenterror, "Expected Hash, but " +
+                                     "#{options.class} provided."
+        end
+            
+        if ( !options.has_key?(:Subnet) )
+                raise Argumenterror, "Missing argument: Subnet."
+        end
+        bits = options[:Subnet]
+        
+        IPAdmin.validate_ip_netmask(:Netmask => bits, :Version => @version)
+        netmask = IPAdmin.pack_ip_netmask(:Netmask => bits, :Version => @version)
+        
+        @netmask = netmask
+        @network = @network & netmask
+        @hostmask = @netmask ^ @all_f
+        
+        # check @ip
+        if ((@ip & @netmask) != (@network))
+            @ip = @network
+        end
+        
+        return(nil)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# size()
+#==============================================================================#
+
+# Provide number of IP addresses within this object.
+#
+# - Arguments:
+#   * none
+#
+# - Returns:
+#   * Integer
+#
+# Example:
+#   puts cidr4.size()   --> 256
+#
+    def size()
+        return(@hostmask + 1)
+    end
+
+#======================================#
+#
+#======================================#
+
+
+#==============================================================================#
+# subnet()
+#==============================================================================#
+
+# Subnet this object. Object will be fully subnetted into X number of subnets
+# of specified size. If :MinCount is provided, then method will return at least 
+# that number of subnets (of size X) and the remainder of the new subnets
+# will be merged together as tightly as possible. If a size is not provided,
+# then the current object will be split in half.
+#
+# - Arguments:
+#   * Optional hash with the following fields:
+#       - :IPCount -- Minimum number of IP's that new subnets should contain - Integer (optional)
+#       - :MinCount -- Minimum number of X sized subnets to return - Integer (optional)
+#       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
+#       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
+#       - :Subnet --  Netmask (in bits) of new subnets - Integer (optional)
+#
+# - Returns:
+#   * Array of CIDR addresses or IPAdmin::CIDR objects
+#
+# - Notes:
+#   * :Subnet always takes precedence over :IPCount.
+#
+# Example:
+#   cidr_list = cidr4.subnet(:Subnet => 28, :MinCount => 3)
+#   cidr_list = cidr4.subnet(:IPCount => 19)
+#   puts cidr_list[0]   --> 192.168.1.0/27
+#
+    def subnet(options=nil)
+        my_network = self.packed_network
+        my_mask = self.bits
+        subnet_bits = my_mask + 1
+        min_count = nil 
+        objectify = false
+        short = false       
+        
+        if (options)
+            if (!options.kind_of? Hash)
+                raise ArgumentError, "Expected Hash, but #{options.class} provided."
+            end
+            
+            if ( options.has_key?(:IPCount) )
+                subnet_bits = IPAdmin.minimum_size(:IPCount => options[:IPCount],
+                                                   :Version => @version)
+            end
+            
+            if ( options.has_key?(:Subnet) )
+                subnet_bits = options[:Subnet]
+            end
+            
+            if ( options.has_key?(:MinCount) )
+                min_count = options[:MinCount]
+            end
+            
+            if( options.has_key?(:Short) )
+                short = true
+            end
+        
+            if( options.has_key?(:Objectify) )
+                objectify = true
+            end
+            
+        end
+
+        # get number of subnets possible with the requested subnet_bits
+        num_avail = 2**(subnet_bits - my_mask)        
+
+        # get the number of bits in the next supernet and
+        # make sure min_count is a power of 2
+        bits_needed = 1
+        min_count = num_avail if (!min_count)
+        until (2**bits_needed >= min_count)
+            bits_needed += 1
+        end
+        min_count = 2**bits_needed
+        next_supernet_bits = subnet_bits - bits_needed
+        
+
+        # make sure subnet isnt bigger than available bits
+        if (subnet_bits > @max_bits)
+            raise "Requested subnet (#{subnet_bits}) does not fit " +
+                  "within the bounds of IPv#{@version}."
+        end
+
+        # make sure subnet is larger than mymask
+        if (subnet_bits < my_mask)
+            raise "Requested subnet (#{subnet_bits}) is too large for " +
+                  "current CIDR space."
+        end
+
+        # make sure MinCount is smaller than available subnets
+        if (min_count > num_avail)
+            raise "Requested subnet count (#{min_count}) exceeds subnets " +
+                  "available for allocation (#{num_avail})."
+        end
+
+        # list all 'subnet_bits' sized subnets of this cidr block
+        # with a limit of min_count
+        bitstep = 2**(@max_bits - subnet_bits)
+        subnets = self.enumerate(:Bitstep => bitstep, :Limit => min_count)
+
+        # save our subnets
+        new_subnets = []
+        subnets.each do |subnet|
+            if (!objectify)
+                subnet = IPAdmin.shorten(subnet) if (short && @version == 6)
+                new_subnets.push("#{subnet}/#{subnet_bits}")
+            else            
+                new_subnets.push(IPAdmin::CIDR.new(:CIDR => "#{subnet}/#{subnet_bits}", :Version => @version))
+            end
+        end
+
+        # now go through the rest of the cidr space and make the rest
+        # of the subnets. we want these to be as tightly merged as possible
+        next_supernet_bitstep = (bitstep * min_count)
+        next_supernet_ip = my_network + next_supernet_bitstep
+        until (next_supernet_bits == my_mask)
+            if (!objectify)
+                next_network = IPAdmin.unpack_ip_addr(:Integer => next_supernet_ip, :Version => @version)
+                next_network = IPAdmin.shorten(next_network) if (short && @version == 6)
+                new_subnets.push("#{next_network}/#{next_supernet_bits}")
+            else
+                new_subnets.push(IPAdmin::CIDR.new(:PackedIP => next_supernet_ip,
+                                                   :Netmask =>next_supernet_bits,
+                                                   :Version => @version))
+            end
+            
+            next_supernet_bits -= 1
+            next_supernet_ip = next_supernet_ip + next_supernet_bitstep
+            next_supernet_bitstep = next_supernet_bitstep << 1
+        end
+
+        return(new_subnets)
+    end
+
+#======================================#
+#
+#======================================#
+
+end
+
+end # module IPAdmin
+__END__