ipadmin 0.3.0 → 0.4.0

data/lib/methods.rb

@@ -1,68 +1,63 @@
-=begin rdoc
- Copyright (c) 2006 Dustin Spinhirne -  
- Licensed under the same terms as Ruby, No Warranty is provided.
-=end
-
-
-
 module IPAdmin
 
 #==============================================================================#
 # compare()
 #==============================================================================#
 
-# Compare CIDR or NetStruct objects, and determine if one
+# Compare (2) CIDR addresses, and determine if one
 # is the supernet of the other.
 #
 # - Arguments:
-#   * Two CIDR or NetStruct objects
+#   * (2) CIDR addresses or IPAdmin::CIDR objects
 #
 # - Returns:
-#   * if one object is a subnet of another, then return an array in order of
-#     [supernet,subnet]
+#   * if one is a subnet of another, then return original array in order of [supernet,subnet]
 #   * if both are equal, return 1
 #   * if neither is a supernet of the other, return nil
 #
-# Example:
+# Examples:
 #   supernet,subnet = IPAdmin.compare(cidr1,cidr2)
+#   supernet,subnet = IPAdmin.compare('192.168.1.0/24','192.168.1.32/27')
 #
 
-def compare(obj1,obj2)
+def compare(cidr1,cidr2)
     ret_val = nil
-
-    # validate arguments
-    if ( !obj1.kind_of?(IPAdmin::CIDR) &&
-         !obj1.kind_of?(IPAdmin::NetStruct) )
-        raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
-                             "as first argument, but #{obj1.class} provided."
+    orig1 = cidr1
+    orig2 = cidr2
+    
+    # if args are not CIDR objects, then attempt to create
+    # cidr objects from them
+    if ( !cidr1.kind_of?(IPAdmin::CIDR) )
+        begin
+            cidr1 = IPAdmin::CIDR.new(:CIDR => cidr1)
+        rescue Exception => error
+            raise ArgumentError, "First provided argument raised the following " +
+                                 "errors: #{error}"
+        end
     end
 
-    if ( !obj2.kind_of?(IPAdmin::CIDR) &&
-         !obj2.kind_of?(IPAdmin::NetStruct) )
-         raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
-                              "as second argument, but #{obj2.class} provided."
+    if ( !cidr2.kind_of?(IPAdmin::CIDR))
+        begin
+            cidr2 = IPAdmin::CIDR.new(:CIDR => cidr2)
+        rescue Exception => error
+            raise ArgumentError, "Second provided argument raised the following " +
+                                 "errors: #{error}"
+        end
     end
 
     # make sure both are same version
-    if (obj1.version != obj2.version )
-        raise ArgumentError, "Provided objects are of different IP versions."
+    if (cidr1.version != cidr2.version )
+        raise ArgumentError, "Provided CIDR addresses are of different IP versions."
     end
 
 
     # get network/netmask of each
-    objects = [obj1,obj2]
+    objects = [cidr1,cidr2]
     networks = []
     netmasks = []
     for obj in objects
-        if ( obj.kind_of?(IPAdmin::CIDR) )
-            networks.push(obj.packed_network)
-            netmasks.push(obj.packed_netmask)
-
-        elsif ( obj.kind_of?(IPAdmin::NetStruct) )
-            networks.push(obj.network)
-            netmasks.push(obj.netmask)
-
-        end
+        networks.push(obj.packed_network)
+        netmasks.push(obj.packed_netmask)
     end
 
     # return 1's if objects are equal otherwise
@@ -73,11 +68,11 @@ def compare(obj1,obj2)
         ret_val = 1
     elsif (netmasks[0] < netmasks[1])
         if ( (netmasks[0] & networks[0]) == (netmasks[0] & networks[1]) )
-            ret_val = [obj1,obj2]
+            ret_val = [orig1,orig2]
         end
     elsif (netmasks[1] < netmasks[0])
         if ( (netmasks[1] & networks[0]) == (netmasks[1] & networks[1]) )
-            ret_val = [obj2,obj1]
+            ret_val = [orig2,orig1]
         end
     end
 
@@ -90,69 +85,26 @@ module_function :compare
 #======================================#
 
 
-#==============================================================================#
-# create_net_struct()
-#==============================================================================#
-
-# Create a NetStruct object from an CIDR or NetStruct object.
-# This type of Struct is used internally for various tasks, and is not likely
-# to be useful to anyone.
-#
-# - Arguments:
-#   * CIDR or NetStruct object
-#
-# - Returns:
-#   * NetStruct object
-#
-# Example:
-#   net_struct = IPAdmin.create_net_struct(object)
-#
-    def create_net_struct(object)
-
-        if ( object.kind_of?(IPAdmin::CIDR) )
-            network = object.packed_ip
-            netmask = object.packed_netmask
-
-        elsif ( object.kind_of?(IPAdmin::NetStruct) )
-            network = object.network
-            netmask = object.netmask
-        else
-            raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct "+
-                                 "object, but #{object.class} provided."
-        end
-
-        version = object.version
-        net_struct = NetStruct.new(network,netmask,version,object,[])
-
-        return(net_struct)
-    end
-module_function :create_net_struct
-
-#======================================#
-#
-#======================================#
-
-
 #==============================================================================#
 # merge()
 #==============================================================================#
 
-# Given a list of CIDR or NetStruct objects 
-# merge (supernet) them in the most efficient way possible. Supernetting 
-# will only occur when the newly created supernet will not result in the 
+# Given a list of CIDR addresses or IPAdmin::CIDR objects of the same version,
+# merge (summarize) them in the most efficient way possible. Summarization 
+# will only occur when the newly created supernets will not result in the 
 # 'creation' of additional space. For example the following blocks 
-# (192.168.0.0/24, 192.168.1.0/24, and 192.168.2.0/24) would merge into 
+# (192.168.0.0/24, 192.168.1.0/24, and 192.168.2.0/24) would be summarized into 
 # 192.168.0.0/23 and 192.168.2.0/24 rather than into 192.168.0.0/22 
 #
 # - Arguments:
-#   * Hash with the following fields:
-#       - :List -- Array of CIDR or NetStruct objects
-#       - :NetStruct -- if true, return IPAdmin::NetStruct objects (optional)
+#   * Array of CIDR addresses or IPAdmin::CIDR objects, or a Hash with 
+#     the following fields:
+#       - :List -- Array of CIDR addresses or IPAdmin::CIDR objects
 #       - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * Array of CIDR or NetStruct objects
+#   * Array of CIDR address Strings or IPAdmin::CIDR objects
 #
 # - Notes:
 #   * I have designed this with enough flexibility that you can pass in CIDR 
@@ -160,211 +112,155 @@ module_function :create_net_struct
 #     10.1.0.0/26, 10.1.0.64/26) and they will be merged properly (ie 192.168.1.0/25,
 #     and 10.1.0.0/25 would be returned).
 #
-# Example:
-#   supernets = IPAdmin.merge(:List => list)
+# Examples:
+#   supernets = IPAdmin.merge(['192.168.1.0/27','192.168.1.32/27'])
+#   supernets = IPAdmin.merge(:List => ['192.168.1.0/27','192.168.1.32/27'], :Short => true)
 #
 def merge(options)
     version = nil
+    all_f = nil
     short = false
     objectify = false
 
     # validate options
-    if ( !options.kind_of?(Hash) )
-        raise ArgumentError, "Hash expected but #{options.class} provided."
-    end
-
-    if (!options.has_key?(:List))
-        raise ArgumentError, "Missing argument: List."
-    end
+    if ( options.kind_of?(Hash) )
+        if (!options.has_key?(:List))
+            raise ArgumentError, "Missing argument: List."
+        end
     
-    if (options.has_key?(:Short) && options[:Short] == true)
-        short = true
-    end
+        if (options.has_key?(:Short) && options[:Short] == true)
+            short = true
+        end
     
-    if (options.has_key?(:Objectify) && options[:Objectify] == true)
-        objectify = true
-    end
-
-    list = options[:List]
-    ret_struct = 1 if (options.has_key?(:NetStruct))
+        if (options.has_key?(:Objectify) && options[:Objectify] == true)
+            objectify = true
+        end
 
-    # make sure list is an array
-    if ( !list.kind_of?(Array) )
-        raise ArgumentError, "Expected Array for option :List, " +
-                             "but #{list.class} provided."
+        # make sure :List is an array
+        if ( !options[:List].kind_of?(Array) )
+            raise ArgumentError, "Expected Array for option :List, " +
+                                 "but #{list.class} provided."
+        end
+        list = options[:List]
+        
+    elsif ( options.kind_of?(Array) )
+        list = options
+    
+    else
+        raise ArgumentError, "Array or Hash expected but #{options.class} provided."
     end
-
+    
     # make sure all are valid types of the same IP version
+    supernet_list = []
     list.each do |obj|
-        if (!obj.kind_of?(IPAdmin::CIDR) && !obj.kind_of?(IPAdmin::NetStruct) )
-            raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
-                                 "object but #{obj.class} provided."
+        if (!obj.kind_of?(IPAdmin::CIDR))
+            begin
+                obj = IPAdmin::CIDR.new(:CIDR => obj)
+            rescue Exception => error
+                raise ArgumentError, "An array element of :List raised the following " +
+                                     "errors: #{error}"
+            end
         end
 
         version = obj.version if (!version)
+        all_f = obj.all_f if (!all_f)
         if (!obj.version == version)
             raise "Provided objects must be of the same IP version."
         end 
+        supernet_list.push(obj)
     end
 
-    # make all_f    
-    if (version == 4)
-        all_f = 2**32 - 1
-    else
-        all_f = 2**128 - 1
-    end
-
-    # make sure that our list is in order, and contains no duplicates
-    list = IPAdmin.sort(list)
-    index = 0
-    (list.length).times do
-        if ((index > 0)&&(IPAdmin.compare(list[index],list[index-1]) == 1))
-            list.delete_at(index)
-        else
-            index += 1
-        end
-    end
-
-    # create supernet_list from list
-    supernet_list = []
-    list.each do |obj|
-        if (obj.kind_of?(IPAdmin::CIDR))
-            supernet_list.push(IPAdmin.create_net_struct(obj))
-
-        elsif ( obj.kind_of?(IPAdmin::NetStruct) )
-            if (obj.subnets && obj.subnets.length > 0)
-                # get all child subnets of this branch entry
-                children = merge(:List => obj.subnets, :NetStruct => 1)
-
-                # if any child subnets are equal to the parent subnet
-                # then copy the grandchild subnets and delete the child
-                children.each do |child|
-                    if ( (obj.network == child.network) &&
-                         (obj.netmask == child.netmask) )
-                        if (child.subnets && child.subnets.length > 0)
-                            grandchildren = child.subnets
-                            children.concat(grandchildren)
-                        end
-                        children.delete(child)
-                        children =  IPAdmin.sort(children)
-                        break
-                    end
-                end
-
-                obj.subnets.clear
-                obj.subnets.concat(children)
-            end
-
-            supernet_list.push(obj)
-        end
-    end
-
-    # merge subnets of this new branch by removing them from 'supernet_list',
-    # and categorizing them into hash of arrays (key=netmask) 
+    # merge subnets by removing them from 'supernet_list',
+    # and categorizing them into hash of arrays ({packed_netmask => [packed_network,packed_network,etc...] ) 
     # within each categorization we merge contiguous subnets
     # and then remove them from that category & put them back into
-    # 'supernet_list'. we do this until our list stops getting any shorter
+    # 'supernet_list'. we do this until supernet_list stops getting any shorter
     categories = {}
     supernet_list_length = 0
     until (supernet_list_length == supernet_list.length)
         supernet_list_length = supernet_list.length
 
         # categorize
-        supernet_list.each do |entry|
-            netmask = entry.netmask
+        supernet_list.each do |cidr|
+            netmask = cidr.packed_netmask
+            network = cidr.packed_network
             if (categories.has_key?(netmask) )
-                (categories[netmask]).push(entry)
+                categories[netmask].push(network)
             else
-                categories[netmask] = [entry]
+                categories[netmask] = [network]
             end
         end
         supernet_list.clear
 
-        categories.each_key do |netmask|
-            entries = categories[netmask]
+        ordered_cats = categories.keys.sort        
+        ordered_cats.each do |netmask|
+            nets = categories[netmask].sort
             bitstep = (all_f + 1) - netmask
-
-            # this entire process depends on the list being in order
-            until (entries.length == 0)
+            
+            until (nets.length == 0)
+                # take the first network & create its supernet. this
+                # supernet will have x number of subnets, so we'll look
+                # & see if we have those subnets. if so, keep supernet & delete subnets.
                 to_merge = []
                 multiplier = 1
-                first = entries[0]
+                network1 = nets[0]
                 num_required = 2**multiplier
                 supermask = (netmask << multiplier) & all_f
-                supernet = supermask & first.network
-                if (first.network == supernet)
-                    # take first entry and use it to form a base
-                    # supernet address. this supernet should have
-                    # x number of subnets in it, so we look for
-                    # those subnets & if found store them
-                    expected = first.network
-                    entries.each do |entry|
-                        if ( (entry.network == expected) && (first.network == supernet) )
-                            to_merge.push(entry)
+                supernet = supermask & network1
+                if (network1 == supernet)
+                    # we have the first half of the new supernet                   
+                    expected = network1
+                    nets.each do |network|
+                        if (network == expected)
+                            to_merge.push(network)
                             expected = expected + bitstep
-                            if ( (to_merge.length == num_required) &&
-                                 (entries.length > num_required ) )
+                            if ( (to_merge.length == num_required) && (nets.length > num_required) )
+                                # we have all of our subnets for this round, but still have
+                                # more to look at
                                 multiplier += 1
                                 num_required = 2**multiplier
                                 supermask = (netmask << multiplier) & all_f
-                                supernet = supermask & first.network
+                                supernet = supermask & network1
                             end
                         else
-                            # if entry is a duplicate, then kill it
-                            if (IPAdmin.compare(entry,to_merge.last) == 1)
-                                entries.delete(entry)
-                            end
                             break 
                         end
                     end
                 else
-                   to_merge.push(first)
+                   # we have the second half of the new supernet only
+                   to_merge.push(network1)
                 end
 
-                # make sure we actually have all of our subnets
-                # create our new supernet
+                
                 if (to_merge.length != num_required)
+                    # we dont have all of our subnets, so backstep 1 bit                    
                     multiplier -= 1
                     supermask = (netmask << multiplier) & all_f
-                    supernet = supermask & first.network
+                    supernet = supermask & network1
                 end
-                net_struct = NetStruct.new(supernet,supermask,version,nil,[])
-
-                # now that we have the child members of our new supernet
-                # take any grandchild subnets that they may have and 
-                # add them to the new supernet. then kill the children
-                (2**multiplier).times do
-                    to_kill = to_merge.shift
-                    net_struct.subnets.concat(to_kill.subnets) if (to_kill.subnets)
-                    entries.delete(to_kill)
-                end
-                supernet_list.push(net_struct)
+                
+                # save new supernet
+                supernet_list.push(IPAdmin::CIDR.new(:PackedIP => supernet,
+                                                     :PackedNetmask => supermask,
+                                                     :Version => version))
+                
+                # delete the subnets of the new supernet
+                (2**multiplier).times {nets.delete(to_merge.shift)}               
             end
         end
         categories.clear
         supernet_list = IPAdmin.sort(supernet_list)
     end
 
-    # if '!ret_struct', return CIDR's
-    if (!ret_struct)
-        supernets = []
-        supernet_list.each do |entry|
-            if (!objectify)
-                network = IPAdmin.unpack_ip_addr(:Integer => entry.network, :Version => version)
-                network = IPAdmin.shorten(network) if (short && version == 6)
-                netmask = IPAdmin.unpack_ip_netmask(:Integer => entry.netmask, :Version => version)
-                supernets.push("#{network}/#{netmask}")
-            else
-                supernets.push(IPAdmin::CIDR.new(:PackedIP => entry.network, 
-                                                 :PackedNetmask => entry.netmask, 
-                                                 :Version => version))
-            end
-        end
+    # decide what to return
+    if (!objectify)
+            supernets = []
+            supernet_list.each {|entry| supernets.push(entry.desc(:Short => short))}
+            return(supernets)
     else
-        supernets = supernet_list
+            return(supernet_list)
     end
 
-    return(supernets)
 end
 module_function :merge
 
@@ -378,10 +274,10 @@ module_function :merge
 #==============================================================================#
 
 # Given the number of IP addresses required in a subnet, return the minimum
-# netmask required for that subnet.
+# netmask (in bits) required for that subnet.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Integer or Hash with the following fields:
 #       - :IPCount -- the number of IP addresses required - Integer
 #       - :Version -- IP version - Integer(optional)
 #
@@ -391,23 +287,26 @@ module_function :merge
 # - Notes:
 #   * Version is assumed to be 4 unless specified otherwise.
 #
-# Example:
-#   netmask = IPAdmin.minumum_size(:IPCount => 14) -> 28
+# Examples:
+#   netmask = IPAdmin.minumum_size(14)
+#   netmask = IPAdmin.minumum_size(:IPCount => 65536, :Version => 6)
 #
 def minimum_size(options)
     version = 4
 
-    if ( !options.kind_of?(Hash) )
-        raise ArgumentError, "Hash expected but #{options.class} provided."
-    end
-
-    if ( !options.has_key?(:IPCount) )
-        raise ArgumentError, "Missing argument: List."
-    end
-    ipcount = options[:IPCount]
+    if ( options.kind_of?(Hash) )
+        if ( !options.has_key?(:IPCount) )
+            raise ArgumentError, "Missing argument: List."
+        end
+        ipcount = options[:IPCount]
     
-    if (options.has_key?(:Version))
-        version = options[:Version]
+        if (options.has_key?(:Version))
+            version = options[:Version]
+        end
+    elsif ( options.kind_of?(Integer) )
+        ipcount = options
+    else
+        raise ArgumentError, "Integer or Hash expected but #{options.class} provided."
     end
     
     if (version == 4)
@@ -442,11 +341,10 @@ module_function :minimum_size
 # pack_ip_addr()
 #==============================================================================#
 
-# Convert IP addresses into an integer. No attempt at
-# validation is performed.
+# Convert IP addresses into an integer.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * IP address as a String, or a Hash with the following fields:
 #       - :IP -- IP address - String
 #       - :Version -- IP version - Integer
 #
@@ -456,32 +354,39 @@ module_function :minimum_size
 # - Notes:
 #   * Will attempt to auto-detect IP version if not provided
 #
-# Example:
-#   pack_ip_addr(IP => '192.168.1.1')
-#   pack_ip_addr(IP => 'ffff::1')
-#   pack_ip_addr(IP => '::192.168.1.1')
+# Examples:
+#   pack_ip_addr('192.168.1.1')
+#   pack_ip_addr(IP => 'ffff::1', :Version => 6)
+#   pack_ip_addr(::192.168.1.1')
 #
 def pack_ip_addr(options)
+    to_validate = {}
     
-    if (!options.kind_of?(Hash))
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
-    
-    if (!options.has_key?(:IP))
-        raise ArgumentError, "Missing argument: IP."
-    end
-    ip = options[:IP]
-    
-    if (options.has_key?(:Version))
-        version = options[:Version]
-        if (version != 4 && version != 6)
-            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+    if (options.kind_of?(Hash))
+        if (!options.has_key?(:IP))
+            raise ArgumentError, "Missing argument: IP."
         end
-    end
+        ip = options[:IP]
+
+        if (options.has_key?(:Version))
+            version = options[:Version]
+            to_validate[:Version] = version
+            if (version != 4 && version != 6)
+                raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+            end
+        end
+    elsif
+        ip = options
+    else
+        raise ArgumentError, "String or Hash expected, but #{options.class} provided."
+    end 
+    to_validate[:IP] = ip
     
-        
     if ( ip.kind_of?(String) )
         
+        # validate
+        IPAdmin.validate_ip_addr(to_validate)
+        
         # determine version if not provided
         if (!version)
             if ( ip =~ /\./ && ip !~ /:/ )
@@ -550,7 +455,7 @@ def pack_ip_addr(options)
         end
 
     else
-        raise ArgumentError, "Argument :IP should be a String, but is a #{ip.class}."    
+        raise ArgumentError, "IP address should be a String, but is a #{ip.class}."    
     end
 
     return(packed_ip)
@@ -566,12 +471,12 @@ module_function :pack_ip_addr
 # pack_ip_netmask()
 #==============================================================================#
 
-# Convert IP netmask into an integer.  No validation is performed. Netmask
-# may be in either CIDR (/yy) or extended (y.y.y.y) format. CIDR formatted
-# netmasks may either be a String or an Integer.
+# Convert IP netmask into an integer.Netmask may be in either CIDR (/yy) or
+# extended (y.y.y.y) format. CIDR formatted netmasks may either
+# be a String or an Integer.
 #
 # - Arguments
-#   * Hash with the following fields:
+#   * Netmask as a String, or a Integer, or a Hash with the following fields:
 #       - :Netmask -- Netmask - String or Integer
 #       - :Version -- IP version - Integer (optional)
 #
@@ -581,38 +486,45 @@ module_function :pack_ip_addr
 # - Notes:
 #   * Version defaults to 4
 #
-# Example:
-#   packed = IPAdmin.pack_ip_netmask(Netmask => '255.255.255.0')
-#   packed = IPAdmin.pack_ip_netmask(Netmask => '24')
-#   packed = IPAdmin.pack_ip_netmask(Netmask => 24)
-#   packed = IPAdmin.pack_ip_netmask(Netmask => '/24')
+# Examples:
+#   packed = IPAdmin.pack_ip_netmask('255.255.255.0')
+#   packed = IPAdmin.pack_ip_netmask('24')
+#   packed = IPAdmin.pack_ip_netmask(24)
+#   packed = IPAdmin.pack_ip_netmask('/24')
 #   packed = IPAdmin.pack_ip_netmask(Netmask => '64', :Version => 6)
 #
 def pack_ip_netmask(options)
-    if (!options.kind_of?(Hash))
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
+    all_f = 2**32-1
     
-    if (!options.has_key?(:Netmask))
-        raise ArgumentError, "Missing argument: Netmask."
-    end
-    netmask = options[:Netmask]
+    if (options.kind_of?(Hash))
+        if (!options.has_key?(:Netmask))
+            raise ArgumentError, "Missing argument: Netmask."
+        end
+        netmask = options[:Netmask]
+        to_validate = {:Netmask => netmask}
     
-    if (options.has_key?(:Version))
-        version = options[:Version]
-        if (version != 4 && version != 6)
-            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
-        elsif (version == 6)
-            all_f = 2**128-1
-        else
-            all_f = 2**32-1
+        if (options.has_key?(:Version))
+            version = options[:Version]
+            if (version != 4 && version != 6)
+                raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+            elsif (version == 6)
+                all_f = 2**128-1
+            else
+                all_f = 2**32-1
+            end
+            to_validate[:Version] = version
         end
+    
+    elsif (options.kind_of?(String) || options.kind_of?(Integer))
+        netmask = options
+        to_validate = {:Netmask => netmask}
     else
-        all_f = 2**32-1
+        raise ArgumentError, "String, Integer, or Hash expected, but #{options.class} provided."
     end
     
-    
     if (netmask.kind_of?(String))
+        IPAdmin.validate_ip_netmask(to_validate)
+        
         if(netmask =~ /\./)
             packed_netmask = IPAdmin.pack_ip_addr(:IP => netmask)
 
@@ -625,11 +537,14 @@ def pack_ip_netmask(options)
             netmask = netmask.to_i
             packed_netmask = all_f ^ (all_f >> netmask)
         end
+        
     elsif (netmask.kind_of?(Integer))
+        to_validate[:Packed] = true
+        IPAdmin.validate_ip_netmask(to_validate)
         packed_netmask = all_f ^ (all_f >> netmask)
     
     else
-        raise ArgumentError, "Argument :Netmask should be a String or Integer, but is a #{netmask.class}."
+        raise ArgumentError, "Netmask should be a String or Integer, but is a #{netmask.class}."
     
     end
     
@@ -646,36 +561,41 @@ module_function :pack_ip_netmask
 # range()
 #==============================================================================#
 
-# Given two IPAdmin::CIDR objects of the same version, return all IP
-# addresses between them (non-inclusive).
+# Given two CIDR addresses or IPAdmin::CIDR objects of the same version,
+# return all IP addresses between them.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Array of (2)CIDR addresses or IPAdmin::CIDR objects, or a Hash
+#     with the following fields:
 #       - :Bitstep -- enumerate in X sized steps - Integer (optional)
-#       - :Boundaries -- array of (2) CIDR objects
+#       - :Boundaries -- array of (2) CIDR addresses or IPAdmin::CIDR objects
+#       - :Inclusive -- if true, include boundaries in returned data
 #       - :Limit -- limit returned list to X number of items - Integer (optional)
 #       - :Objectify -- if true, return CIDR objects (optional)
 #       - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
 #
 # - Returns:
-#   * Array of Strings or CIDR objects
+#   * Array of CIDR address Strings or IPAdmin::CIDR objects
 #
 # - Notes:
 #   * IPAdmin.range will use the original IP address passed during the initialization
-#     of the CIDR objects. This IP can be found using the CIDR.ip() method.
+#     of the IPAdmin::CIDR objects, or the base address of any CIDR addresses passed.
+#   * The default behavior is to be non-inclusive (dont include boundaries as part of returned data) 
 #
-# Example:
-#   list = IPAdmin.range(:Boundaries => [cidr1,cidr2])
+# Examples:
+#   list = IPAdmin.range(:Boundaries => [cidr1,cidr2], :Limit => 10)
+#   list = IPAdmin.range(['192.168.1.0','192.168.1.10']
 #
 def range(options)
     list = []
     bitstep = 1
     objectify = false
     short = false
+    inclusive = false
     limit = nil
 
     # check options
-    if (options)
+    if (options.kind_of?(Hash))
         if ( !options.has_key?(:Boundaries) ) 
             raise ArgumentError, "Missing argument: Boundaries."
         end
@@ -698,16 +618,39 @@ def range(options)
         if( options.has_key?(:Short) && options[:Short] == true )
             short = true
         end
+        
+        if( options.has_key?(:Inclusive) && options[:Inclusive] == true )
+            inclusive = true
+        end
 
         if( options.has_key?(:Limit) )
             limit = options[:Limit]
         end
+    
+    elsif(options.kind_of?(Array))
+        (cidr1,cidr2) = options
+    else
+        raise ArgumentError, "Array or Hash expected but #{options.class} provided."
+    end
+
+    # if cidr1/cidr2 are not CIDR objects, then attempt to create
+    # cidr objects from them
+    if ( !cidr1.kind_of?(IPAdmin::CIDR) )
+        begin
+            cidr1 = IPAdmin::CIDR.new(:CIDR => cidr1)
+        rescue Exception => error
+            raise ArgumentError, "First argument of :Boundaries raised the following " +
+                                 "errors: #{error}"
+        end
     end
 
-    # check our objects
-    if (!cidr1.kind_of?(IPAdmin::CIDR) && !cidr2.kind_of?(IPAdmin::CIDR))
-        raise ArgumentError, "One or more values provided under :Boundaries "+
-                             "is not a valid IPAdmin::CIDR object."
+    if ( !cidr2.kind_of?(IPAdmin::CIDR))
+        begin
+            cidr2 = IPAdmin::CIDR.new(:CIDR => cidr2)
+        rescue Exception => error
+            raise ArgumentError, "Second argument of :Boundaries raised the following " +
+                                 "errors: #{error}"
+        end
     end
 
     # check version, store & sort
@@ -720,8 +663,15 @@ def range(options)
     end
 
     # dump our range
-    my_ip = boundaries[0] + 1
-    until (my_ip >= boundaries[1]) 
+    if (!inclusive)
+        my_ip = boundaries[0] + 1
+        end_ip = boundaries[1]
+    else
+        my_ip = boundaries[0]
+        end_ip = boundaries[1] + 1
+    end
+    
+    until (my_ip >= end_ip) 
         if (!objectify)
             my_ip_s = IPAdmin.unpack_ip_addr(:Integer => my_ip, :Version => version)
             my_ips = IPAdmin.shorten(my_ips) if (short && version == 6)
@@ -754,13 +704,13 @@ module_function :range
 # The address should not contain a netmask.
 #
 # - Arguments:
-#   * String
+#   * IP address as a String
 #
 # - Returns:
 #   * String
 #
-# Example:
-#   short = IPAdmin.shorten('fec0:0000:0000:0000:0000:0000:0000:0001') --> 'fec0::1'
+# Examples:
+#   short = IPAdmin.shorten('fec0:0000:0000:0000:0000:0000:0000:0001')
 #
 def shorten(addr)
 
@@ -846,21 +796,22 @@ module_function :shorten
 # sort()
 #==============================================================================#
 
-# Given a list of IPAdmin::CIDR or NetStruct objects
+# Given a list of CIDR addresses or IPAdmin::CIDR objects, 
 # sort them from lowest to highest by Network/Netmask.
 #
 # - Arguments:
-#   * Array of CIDR or NetStruct objects
+#   * Array of CIDR addresses or IPAdmin::CIDR objects
 #
 # - Returns:
-#   * Array
+#   * Array of CIDR address Strings or IPAdmin::CIDR objects
 #
 # - Notes:
 #   * IPAdmin.sort will use the original IP address passed during the initialization
-#     of the CIDR objects. This IP can be found using the CIDR.ip() method.
+#     of any IPAdmin::CIDR objects, or the base address of any CIDR addresses passed.
 #
-# Example:
-#   sorted = IPAdmin.sort(list)
+# Examples:
+#   sorted = IPAdmin.sort([cidr1,cidr2])
+#   sorted = IPAdmin.sort(['192.168.1.32/27','192.168.1.0/27'])
 #
 def sort(list)
 
@@ -872,33 +823,35 @@ def sort(list)
 
     # make sure all are valid types of the same IP version
     version = nil
-    list.each do |obj|
-        unless (obj.kind_of?(IPAdmin::CIDR) || obj.kind_of?(IPAdmin::NetStruct) )
-            raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
-                                 "object but #{obj.class} provided."
+    cidr_hash = {}
+    list.each do |cidr|
+        if (!cidr.kind_of?(IPAdmin::CIDR))
+            begin
+                new_cidr = IPAdmin::CIDR.new(cidr)
+            rescue Exception => error
+                raise ArgumentError, "An element of the provided Array " +
+                                     "raised the following errors: #{error}"
+            end
+        else
+            new_cidr = cidr
         end
-
-        version = obj.version if (!version)
-        unless (obj.version == version)
-            raise "Provided objects must all be of the same IP version."
+        cidr_hash[new_cidr] = cidr
+        
+        version = new_cidr.version if (!version)
+        unless (new_cidr.version == version)
+            raise "Provided CIDR addresses must all be of the same IP version."
         end 
     end
 
-    # create unsorted_list from list
-    unsorted_list = []
-    list.each do |obj|
-        unsorted_list.push(IPAdmin.create_net_struct(obj))
-    end
-
     # sort by network. if networks are equal, sort by netmask.
     sorted_list = []
-    unsorted_list.each do |entry|
+    cidr_hash.each_key do |entry|
         index = 0
         sorted_list.each do
-            if(entry.network < (sorted_list[index]).network)
+            if(entry.packed_network < (sorted_list[index]).packed_network)
                 break
-            elsif (entry.network == (sorted_list[index]).network)
-                if (entry.netmask < (sorted_list[index]).netmask)
+            elsif (entry.packed_network == (sorted_list[index]).packed_network)
+                if (entry.packed_netmask < (sorted_list[index]).packed_netmask)
                     break
                 end
             end
@@ -906,15 +859,12 @@ def sort(list)
         end
         sorted_list.insert(index, entry)
     end
+    
+    # return original values passed
+    ret_list = []
+    sorted_list.each {|x| ret_list.push(cidr_hash[x])}
 
-    # replace sorted_list entries with their .object
-    index = 0
-    sorted_list.length.times do
-        sorted_list[index] = (sorted_list[index]).object
-        index += 1
-    end
-
-    return(sorted_list)
+    return(ret_list)
 end
 module_function :sort
 
@@ -927,11 +877,10 @@ module_function :sort
 # unpack_ip_addr()
 #==============================================================================#
 
-# Unack a packed IP address back into a printable string. No attempt at
-# validation is performed.
+# Unack a packed IP address back into a printable string.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Integer or a Hash with the following fields:
 #       - :Integer -- Integer representaion of an IP address
 #       - :Version -- IP version - Integer (optional)
 #       - :IPv4Mapped -- if true, unpack IPv6 as an IPv4 mapped address (optional)
@@ -942,35 +891,44 @@ module_function :sort
 # - Notes:
 #   * IP version will attempt to be auto-detected if not provided
 #
-# Example:
+# Examples:
+#   unpacked = IPAdmin.unpack_ip_addr(3232235906)
 #   unpacked = IPAdmin.unpack_ip_addr(:Integer => packed)
 #
 def unpack_ip_addr(options)
     ipv4_mapped = false
+    to_validate = {}
     
-    if (!options.kind_of?(Hash))
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
+    if (options.kind_of?(Hash))
+        if (!options.has_key?(:Integer))
+            raise ArgumentError, "Missing argument: Integer."
+        end
+        packed_ip = options[:Integer]
+        
+        if (options.has_key?(:Version))
+            version = options[:Version]
+            to_validate[:Version] = version
+            if (version != 4 && version != 6)
+                raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+            end
+        end
     
-    if (!options.has_key?(:Integer))
-        raise ArgumentError, "Missing argument: Integer."
+        if (options.has_key?(:IPv4Mapped) && options[:IPv4Mapped] == true)
+            ipv4_mapped = true
+        end
+    elsif (options.kind_of?(Integer))
+        packed_ip = options
+    else
+        raise ArgumentError, "Integer or Hash expected, but #{options.class} provided."
     end
-    packed_ip = options[:Integer]
     
     if (!packed_ip.kind_of?(Integer))
-        raise ArgumentError, "Expected Integer, but #{options.class} provided for argument: 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
+        raise ArgumentError, "Packed IP should be an Integer, but was a #{options.class}."
     end
     
-    if (options.has_key?(:IPv4Mapped) && options[:IPv4Mapped] == true)
-        ipv4_mapped = true
-    end
+    # validate
+    to_validate[:IP] = packed_ip
+    IPAdmin.validate_ip_addr(to_validate)
     
     # set version if not set
     if (!version)
@@ -1030,38 +988,48 @@ module_function :unpack_ip_addr
 #==============================================================================#
 
 # Unack a packed IP netmask into a integer representing the number of
-# bits in the CIDR mask. No attempt at validation is performed.
+# bits in the CIDR mask.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Integer or a Hash with the following fields:
 #       - :Integer -- Integer representation of an IP Netmask
 #
 # - Returns:
 #   * Integer
 #
-# Example:
+# Examples:
+#   unpacked = IPAdmin.unpack_ip_netmask(0xfffffffe)
 #   unpacked = IPAdmin.unpack_ip_netmask(:Integer => packed)
 #
 def unpack_ip_netmask(options)
-    if (!options.kind_of?(Hash))
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
     
-    if (!options.has_key?(:Integer))
-        raise ArgumentError, "Missing argument: Integer."
-    end
-    packed_netmask = options[:Integer]
+    if (options.kind_of?(Hash))
+        if (!options.has_key?(:Integer))
+            raise ArgumentError, "Missing argument: Integer."
+        end
+        packed_netmask = options[:Integer]
+        
+        if (!packed_netmask.kind_of?(Integer))
+            raise ArgumentError, "Packed netmask should be an Integer, but is a #{packed_netmask.class}."
+        end
+        
+    elsif (options.kind_of?(Integer))
+        packed_netmask = options
+        
+    else
+        raise ArgumentError, "Integer or Hash expected, but #{options.class} provided."
+    end    
     
-    if (!packed_netmask.kind_of?(Integer))
-        raise ArgumentError, "Argument :Integer should be an Integer, but is a #{packed_netmask.class}."
-    end
     
     if (packed_netmask < 2**32)
         mask = 32
+        IPAdmin.validate_ip_netmask(:Netmask => packed_netmask, :Packed => true, :Version => 4)
     else
+        IPAdmin.validate_ip_netmask(:Netmask => packed_netmask, :Packed => true, :Version => 6)
         mask = 128
     end
     
+    
     mask.times do    
         if ( (packed_netmask & 1) == 1)
             break
@@ -1087,13 +1055,13 @@ module_function :unpack_ip_netmask
 # notation. The address should not contain a netmask.
 #
 # - Arguments:
-#   * String
+#   * IP address as a String
 #
 # - Returns:
 #   * String
 #
-# Example:
-#   long = IPAdmin.unshorten('fec0::1') --> 'fec0:0000:0000:0000:0000:0000:0000:0001'
+# Examples:
+#   long = IPAdmin.unshorten('fec0::1')
 #
 def unshorten(addr)
 
@@ -1128,24 +1096,27 @@ module_function :unshorten
 # Validate an EUI-48 or EUI-64 address. 
 #
 # - Arguments
-#   * Hash with the following fields:
+#   * EUI address as a String, or a Hash with the following fields:
 #       - :EUI -- Address to validate - String
 #
 # - Returns:
 #   * True
 #
-# - Example:
+# Examples:
+#   * IPAdmin.validate_eui('01-00-5e-12-34-56')
 #   * IPAdmin.validate_eui(:EUI => '01-00-5e-12-34-56')
 #
 def validate_eui(options)
-    if (!options.kind_of? Hash)
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
-        
-    if (!options.has_key?(:EUI))
-        raise ArgumentError, "Missing argument: EUI."
+    if (options.kind_of? Hash)
+        if (!options.has_key?(:EUI))
+            raise ArgumentError, "Missing argument: EUI."
+        end
+        eui = options[:EUI]
+    elsif (options.kind_of? String)
+        eui = options
+    else
+        raise ArgumentError, "String or Hash expected, but #{options.class} provided."
     end
-    eui = options[:EUI]
         
     if (eui.kind_of?(String))
         # check for invalid characters
@@ -1174,8 +1145,7 @@ def validate_eui(options)
         end
 
     else
-        raise ArgumentError, "Expected String, but #{eui.class} " +
-                             "provided for argument :EUI."
+        raise ArgumentError, "EUI address should be a String, but was a#{eui.class}."
     end
     return(true)
 end
@@ -1193,7 +1163,7 @@ module_function :validate_eui
 # Validate an IP address. The address should not contain a netmask.
 #
 # - Arguments
-#   * Hash with the following fields:
+#   * IP address as a String or Integer, or a Hash with the following fields:
 #       - :IP -- IP address to validate - String or Integer
 #       - :Version -- IP version - Integer (optional)
 #
@@ -1203,9 +1173,9 @@ module_function :validate_eui
 # - Notes:
 #   * IP version will attempt to be auto-detected if not provided
 #
-# Example:
-#   validate_ip_addr(IP => '192.168.1.1')
-#   validate_ip_addr(IP => 'ffff::1')
+# Examples:
+#   validate_ip_addr('192.168.1.1')
+#   validate_ip_addr(IP => 'ffff::1', :Version => 6)
 #   validate_ip_addr(IP => '::192.168.1.1')
 #   validate_ip_addr(IP => 0xFFFFFF)
 #   validate_ip_addr(IP => 2**128-1)
@@ -1213,20 +1183,22 @@ module_function :validate_eui
 #
 def validate_ip_addr(options)
     
-    if (!options.kind_of?(Hash))
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
-    
-    if (!options.has_key?(:IP))
-        raise ArgumentError, "Missing argument: IP."
-    end
-    ip = options[:IP]
+    if (options.kind_of?(Hash))
+        if (!options.has_key?(:IP))
+            raise ArgumentError, "Missing argument: IP."
+        end
+        ip = options[:IP]
     
-    if (options.has_key?(:Version))
-        version = options[:Version]
-        if (version != 4 && version != 6)
-            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+        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
+    elsif (options.kind_of?(String) || options.kind_of?(Integer))
+        ip = options
+    else
+        raise ArgumentError, "String or Hash expected, but #{options.class} provided."
     end
     
     if ( ip.kind_of?(String) )
@@ -1358,7 +1330,7 @@ module_function :validate_ip_addr
 # Validate IP Netmask.
 #
 # - Arguments:
-#   * Hash with the following fields:
+#   * Netmask as a String or Integer, or a Hash with the following fields:
 #       - :Netmask -- Netmask to validate - String or Integer
 #       - :Packed -- if true, the provided Netmask is a packed Integer
 #       - :Version -- IP version - Integer (optional)
@@ -1369,42 +1341,43 @@ module_function :validate_ip_addr
 # - Notes:
 #   * Version defaults to 4 if not specified.
 #
-# Example:
-#   IPAdmin.validate_ip_netmask(:Netmask => '/32')
-#   IPAdmin.validate_ip_netmask(:Netmask => 32)
+# Examples:
+#   IPAdmin.validate_ip_netmask('/32')
+#   IPAdmin.validate_ip_netmask(32)
 #   IPAdmin.validate_ip_netmask(:Netmask => 0xffffffff, :Packed => true)
 #
 def validate_ip_netmask(options)
     packed = false
+    version = 4
+    max_bits = 32
     
-    if (!options.kind_of?(Hash))
-        raise ArgumentError, "Expected Hash, but #{options.class} provided."
-    end
-    
-    if (!options.has_key?(:Netmask))
-        raise ArgumentError, "Missing argument: Netmask."
-    end
-    netmask = options[:Netmask]
+    if (options.kind_of?(Hash))
+        if (!options.has_key?(:Netmask))
+            raise ArgumentError, "Missing argument: Netmask."
+        end
+        netmask = options[:Netmask]
     
-    if (options.has_key?(:Packed) && options[:Packed] == true)
-        packed = true
-    end
+        if (options.has_key?(:Packed) && options[:Packed] == true)
+            packed = true
+        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}'."
-        elsif (version == 6)
-            max_bits = 128
-        else
-            max_bits = 32
+        if (options.has_key?(:Version))
+            version = options[:Version]
+            if (version != 4 && version != 6)
+                raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
+            elsif (version == 6)
+                max_bits = 128
+            else
+                max_bits = 32
+            end
         end
+    
+    elsif (options.kind_of?(String) || options.kind_of?(Integer))
+        netmask = options
     else
-        version = 4
-        max_bits = 32
+        raise ArgumentError, "String, Integer, or Hash expected, but #{options.class} provided."
     end
     
-
     if (netmask.kind_of?(String))
         if(netmask =~ /\./)
             all_f = 2**32-1
@@ -1490,13 +1463,11 @@ module_function :validate_ip_netmask
 # to anyone.
 #
 # Description of fields:
-#   * network - Integer representing an IP address
-#   * netmask - Integer representing IP netmask
-#   * version - Integer representing an IP version
-#   * object - holds an IPAdmin class object
-#   * subnets - an array of children NetStruct objects
+#   * cidr - IPAdmin::CIDR object
+#   * parent - parent NetStruct in tree
+#   * children - Array of children NetStruct objects
 #
-NetStruct = Struct.new(:network, :netmask, :version, :object, :subnets)
+NetStruct = Struct.new(:cidr, :parent, :children)
 
 #======================================#
 #