netaddr 1.0.0 → 1.1.0

data/Errors

@@ -1,13 +1,7 @@
 =Error Classes
 
- Exception -
-            |
-             --StandardError -
-                              |
-                               --BoundaryError => CIDR or EUI is out of bounds for a valid address
-                              |
-                               --ValidationError => CIDR or EUI is not a valid address
-                              |
-                               --VersionError => CIDR or EUI is of improper version for requested operation
-                              |
-            |
+ +-Exception
+   +-StandardError
+     +-BoundaryError => CIDR or EUI is out of bounds for a valid address
+     +-ValidationError => CIDR or EUI failed validation checks
+     +-VersionError => CIDR or EUI is of improper version for requested operation

data/README

@@ -1,19 +1,19 @@
 =Introduction
 
- NetAddr arose through my need as a network engineer for a 
- back-end module that could easily handle such advanced tasks 
- as automating the subnetting/supernetting
- of IP space, performing calculations on IP CIDR blocks, and other
- various items. At that time there were no modules that could
- do any of the things that I needed, so I set out to create my own. 
- Since it proved to be fairly useful to me, I decided to share the
- code with the Ruby community. 
+NetAddr arose through my need as a network engineer for a 
+back-end module that could easily handle such advanced tasks 
+as automating the subnetting/supernetting
+of IP space, performing calculations on IP CIDR blocks, and other
+various items. At that time there were no modules that could
+do any of the things that I needed, so I set out to create my own. 
+Since it has proven to be fairly useful to me, I have decided to share the
+code with the Ruby community. 
  
- I have added things that I find immediately useful for me. I am
- open to suggestions if there is something that I could add to make
- your life easier. Comments are also welcome (positive ones in particular).  
+I have added things that I find immediately useful for me. I am
+open to suggestions if there is something that I could add to make
+your life easier. 
  
- Dustin Spinhirne
+Dustin Spinhirne
 
 
 =Example Script

data/lib/cidr.rb

@@ -1,5 +1,5 @@
 =begin rdoc
- Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
+ Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
  
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end
@@ -14,10 +14,10 @@ module NetAddr
 #This class accepts a CIDR address, via the CIDR.create method,
 #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.
 #CIDR.create then creates either a CIDRv4 or CIDRv6 object. An optional tag hash may be 
-#provided with each CIDR as a way of adding custom labels to the object.
+#provided with each CIDR as a way of adding custom labels.
 # 
 #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 
+#CIDR. 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.
@@ -83,6 +83,10 @@ private_class_method :new
 # cidr4_2 = NetAddr::CIDR.create(0x0a010001,
 #                                :PackedNetmask => 0xffffff00
 #                                :Version => 4)
+# cidr4_3 = NetAddr::CIDRv4.new('192.168.1.1',
+#                               :WildcardMask => ['0.7.0.255', :inversed])
+# cidr4_4 = NetAddr::CIDRv4.new('192.168.5.0',
+#                               :WildcardMask => ['255.248.255.0'])
 # cidr6 = NetAddr::CIDR.create('fec0::/64')
 # cidr6 = NetAddr::CIDR.create('fec0::/64',
 #                              :Tag => {'interface' => 'g0/1'})
@@ -94,13 +98,16 @@ private_class_method :new
 #     :PackedNetmask -- Integer representation of an IP Netmask (optional)
 #     :Version -- IP version - Integer (optional)
 #     :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#     :WildcardMask -- 2 element Array. First element contains a special bit mask used for
+#                      advanced IP pattern matching. The second element should be :inversed if this
+#                      bit mask is in inverse format. (optional)
 #
     def CIDR.create(addr, options=nil)
-        known_args = [:PackedNetmask, :Version, :Tag]
+        known_args = [:PackedNetmask, :Version, :Tag, :WildcardMask]
         cidr = nil
         packed_ip = nil
         version = nil
-        
+
         # validate addr arg
         if (addr.kind_of?(String))
             cidr = addr
@@ -109,7 +116,7 @@ private_class_method :new
         else
             raise ArgumentError, "String or Integer expected for argument 'addr' but #{addr.class} provided."
         end
-        
+
         # validate options
         if (options)     
             raise ArgumentError, "Hash expected for argument 'options' but " +
@@ -123,7 +130,7 @@ private_class_method :new
                 end
             end
         end
-        
+
         # attempt to determine version if not provided
         if (!version)
             if (packed_ip) 
@@ -132,15 +139,15 @@ private_class_method :new
                 else
                     version = 6
                 end
-            else           
+            else
                 if (cidr =~ /\./ && cidr !~ /:/)
                     version = 4
                 elsif (cidr =~ /:/)
                     version = 6
                 end
-            end          
+            end
         end
-      
+
         # create CIDRvX object
         if (version == 4)
             return(NetAddr::CIDRv4.new(addr, options))
@@ -149,7 +156,7 @@ private_class_method :new
         else
             raise ArgumentError, "IP version omitted or could not be detected."
         end
-        
+
     end
 
 #==============================================================================#
@@ -247,6 +254,8 @@ private_class_method :new
 #* -1 if the current CIDR is contained by (is subnet of) the provided CIDR
 #* nil if the two CIDR addresses are unrelated
 #
+# cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr4_2 = NetAddr::CIDR.create('192.168.1.0/26')
 # comp1 = cidr4.cmp(cidr4_2)
 # comp2 = cidr4.cmp('192.168.1.0/26')
 #
@@ -263,8 +272,8 @@ private_class_method :new
             rescue Exception => error
                 raise ArgumentError, "Provided argument raised the following " +
                                      "errors: #{error}"
-                end
             end
+        end
 
         if (cidr.version != @version)
             raise VersionError, "Attempted to compare a version #{cidr.version} CIDR " +
@@ -485,7 +494,8 @@ end
 #Return true if the current CIDR and the provided CIDR are equal 
 #(base address and netmask are equal).
 #
-# cidr4.eql?('192.168.1.1/24')
+# cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
+# cidr4.eql?('192.168.1.0/24')
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
@@ -523,8 +533,8 @@ end
 #Given a list of subnets of the current CIDR, return a new list with any
 #holes (missing subnets) filled in.
 #
+# cidr4 = NetAddr::CIDR.create('192.168.1.0/24')
 # subnets = cidr4.fill_in(['192.168.1.0/27','192.168.1.64/26','192.168.1.128/25'])
-# subnets = cidr4.fill_in(:List => ['192.168.1.0/27','192.168.1.64/26'], :Objectify => true)
 #
 #===Arguments:
 #* Array of CIDR addresses, or Array of NetAddr::CIDR objects
@@ -622,29 +632,6 @@ end
         end
     end
 
-#==============================================================================#
-# hostmask_ext()
-#==============================================================================#
-
-#===Synopsis
-#Provide IPv4 Hostmask in extended format (y.y.y.y).
-#
-# puts cidr4.hostmask_ext(
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* String
-#
-    def hostmask_ext()
-        if (@version == 4)
-            return(NetAddr.unpack_ip_addr(@hostmask, :Version => @version))
-        else
-            return(nil) 
-        end
-    end
-
 #==============================================================================#
 # ip()
 #==============================================================================#
@@ -754,9 +741,7 @@ end
 #==============================================================================#
 
 #===Synopsis
-#Provide last IP address in this CIDR object. The broadcast() method is 
-#aliased to this method, and thus works for IPv6 despite the fact that the 
-#IPv6 protocol does not support IP broadcasting
+#Provide last IP address in this CIDR object. 
 #
 # puts cidr4.last() 
 #
@@ -799,9 +784,47 @@ end
         end
 
         return(ip)
+    end   
+
+#==============================================================================#
+# matches?()
+#==============================================================================#
+
+#===Synopsis
+#Given an IP address (or if a CIDR, then the original IP of that CIDR), determine
+#if it falls within the range of addresses resulting from the combination of the 
+#IP and Wildcard Mask of this CIDR.
+#
+# cidr4 = NetAddr.CIDRv4.new('10.0.0.0', :WildcardMask => ['0.7.0.255', :inversed])
+# cidr4.matches?('10.0.0.22') -> true
+# cidr4.matches?('10.8.0.1') -> false
+# cidr4.matches?('10.1.0.1') -> true
+# cidr4.matches?('10.0.1.22') -> false
+#
+#===Arguments:
+#* IP address as a String or a CIDR object
+#
+#===Returns:
+#* True or False
+#
+    def matches?(ip)
+        packed = nil
+        if (!ip.kind_of?(NetAddr::CIDR))
+            begin
+                packed = NetAddr.pack_ip_addr(ip, :Version => @version)
+            rescue NetAddr::ValidationError
+                raise NetAddr::ValidationError, "Provided IP must be a valid IPv#{@version} address."
+            end
+        else
+            raise NetAddr::ValidationError, "Provided CIDR must be of type #{self.class}" if (ip.class != self.class)
+            packed = ip.packed_ip
+        end
+
+        mask = ~@wildcard_mask & @all_f
+
+        return(true) if (@ip & mask == packed & mask)
+        return(false)
     end
-    
-    alias :broadcast :last
 
 #==============================================================================#
 # multicast_mac()
@@ -881,29 +904,6 @@ end
         return("/#{bits}")
     end
 
-#==============================================================================#
-# netmask_ext()
-#==============================================================================#
-
-#===Synopsis
-#Provide IPv4 netmask in extended format (y.y.y.y).
-#
-# puts cidr4.netmask_ext()
-#
-#===Arguments:
-#* none
-#
-#===Returns:
-#* String
-#
-    def netmask_ext()    
-        if (@version == 4)
-            return(NetAddr.unpack_ip_addr(@netmask))
-        else
-            return(nil)
-        end
-    end
-
 #==============================================================================#
 # network()
 #==============================================================================#
@@ -1097,7 +1097,7 @@ end
 #
 # cidr4 = NetAddr::CIDR.create('192.168.1.1/24')
 # puts cidr4.nth(1)
-# puts cidr4.nth(:Index => 1, :Objectify => true
+# puts cidr4.nth(1, :Objectify => true
 #
 #===Arguments:
 #* Index number as an Integer
@@ -1225,6 +1225,25 @@ end
         return(@network)
     end
 
+#==============================================================================#
+# packed_wildcard_mask()
+#==============================================================================#
+
+#===Synopsis
+#Provide an Integer representation of the IPv4 Wildcard Mask.
+#
+# puts cidr4.packed_wildcard_mask()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* Integer
+#
+    def packed_wildcard_mask()
+        return(@wildcard_mask)
+    end
+
 #==============================================================================#
 # range()
 #==============================================================================#
@@ -1323,7 +1342,7 @@ end
 #and 192.168.0.128/25 will be returned as the remainders.
 #
 # cidr4.remainder('192.168.1.32/27').each {|x| puts x}
-# cidr4.remainder(:Exclude => '192.168.1.32/27', :Objectify => true).each {|x| puts x.desc}
+# cidr4.remainder('192.168.1.32/27', :Objectify => true).each {|x| puts x.desc}
 #
 #===Arguments:
 #* CIDR address or NetAddr::CIDR object
@@ -1485,7 +1504,7 @@ end
 #==============================================================================#
 
 #===Synopsis
-#Provide number of IP addresses within this object.
+#Provide number of IP addresses within this CIDR.
 #
 # puts cidr4.size()
 #
@@ -1504,7 +1523,7 @@ end
 #==============================================================================#
 
 #===Synopsis
-#Subnet this object. There are 2 ways to subnet:
+#Subnet this CIDR. There are 2 ways to subnet:
 #   * By providing the netmask (in bits) of the new subnets in :Bits.
 #   * By providing the number of IP addresses needed in the new subnets in :IPCount
 #
@@ -1647,6 +1666,52 @@ end
     end
 
 
+#==============================================================================#
+# wildcard_mask()
+#==============================================================================#
+
+#===Synopsis
+#Set or return the wildcard mask. Wildcard masks are typically used for matching
+#entries in an access-list.
+#
+# cidr4.wildcard_mask() -> reads the current wildcard mask
+# cidr4.wildcard_mask('0.0.0.255', :inversed) -> sets wildcard mask using a reversed mask
+# cidr4.wildcard_mask('255.255.255.0') -> sets wildcard mask using a standard mask
+#
+#===Arguments:
+#* wildcard mask as a String or Integer
+#* the label :inversed if the mask is bit-flipped. (optional)
+#
+#===Returns:
+#* nil
+#
+    def wildcard_mask(mask=nil, inversed=nil)
+        if (mask)
+            if (mask.kind_of?(Integer)) 
+                packed = mask
+            else
+                packed = nil
+                begin
+                    packed = NetAddr.pack_ip_addr(mask, :Version => @version)
+                rescue NetAddr::ValidationError
+                    raise NetAddr::ValidationError, "Wildcard Mask must be a valid IPv#{@version} address."
+                end
+            end
+            packed = packed ^ @all_f if (inversed != :inversed)
+            @wildcard_mask = packed
+            ret_val = nil
+        else
+            if (inversed != :inversed)
+                ret_val = NetAddr.unpack_ip_addr(@wildcard_mask ^ @all_f, :Version => @version)
+            else
+                ret_val = NetAddr.unpack_ip_addr(@wildcard_mask, :Version => @version)
+            end
+        end
+
+        return(ret_val)
+    end
+
+
 # PRIVATE INSTANCE METHODS
 private
 
@@ -1700,6 +1765,8 @@ end # end class CIDR
 
 
 
+
+
 # IPv4 CIDR address - Inherits all methods from NetAddr::CIDR. 
 # Addresses of this class are composed of a 32-bit address space.
 class CIDRv4 < CIDR
@@ -1720,15 +1787,24 @@ public_class_method :new
 # cidr4 = NetAddr::CIDRv4.new('192.168.1.1 255.255.255.0')
 # cidr4_2 = NetAddr::CIDRv4.new(0x0a010001,
 #                               :PackedNetmask => 0xffffff00)
+# cidr4_3 = NetAddr::CIDRv4.new('192.168.1.1',
+#                               :WildcardMask => ['0.7.0.255', :inversed])
+# cidr4_4 = NetAddr::CIDRv4.new('192.168.5.0',
+#                               :WildcardMask => ['255.248.255.0'])
+# cidr4_5 = NetAddr::CIDRv4.new('192.168.1.1',
+#                               :WildcardMask => 0x000700ff)
 #
 #===Arguments:
 #* CIDR address as a String, or a packed IP address as an Integer
 #* Optional Hash with the following keys:
 #     :PackedNetmask -- Integer representation of an IP Netmask (optional)
 #     :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#     :WildcardMask -- 2 element Array. First element contains a special bit mask used for
+#                      advanced IP pattern matching. The second element should be :inversed if this
+#                      bit mask is in inverse format. (optional)
 #
     def initialize(addr, options=nil)
-        known_args = [:PackedNetmask, :Tag]
+        known_args = [:PackedNetmask, :Tag, :WildcardMask]
         @tag = {}
         @version = 4
         @max_bits = 32
@@ -1753,17 +1829,43 @@ public_class_method :new
                 packed_netmask = options[:PackedNetmask]
                 raise ArgumentError, "Expected Integer, but #{packed_netmask.class} " +
                                      "provided for option :PackedNetmask." if (!packed_netmask.kind_of?(Integer))
-            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 (options.has_key?(:WildcardMask))
+                if (!options[:WildcardMask].kind_of?(Array))
+                    raise ArgumentError, "Expected Array, but #{options[:WildcardMask].class} provided for option :WildcardMask."
+                end
+                wildcardmask = options[:WildcardMask][0]
+                inversed = false
+                inversed = true if (options[:WildcardMask][1] && options[:WildcardMask][1] == :inversed)
+
+                if (wildcardmask.kind_of?(Integer))
+                   begin
+                        @wildcard_mask = wildcardmask
+                        NetAddr.validate_ip_addr(@wildcard_mask, :Version => @version)
+                    rescue NetAddr::ValidationError
+                        raise NetAddr::ValidationError, ":WildcardMask must be a valid IPv#{@version} address."
+                    end 
+                else
+                    begin
+                        @wildcard_mask = NetAddr.pack_ip_addr(wildcardmask, :Version => @version)
+                    rescue NetAddr::ValidationError
+                        raise NetAddr::ValidationError, ":WildcardMask must be a valid IPv#{@version} address."
+                    end
+                end
+
+                @wildcard_mask = @wildcard_mask ^ @all_f if (inversed)
+            end
         end
-        
-        
+
+
         if (packed_ip)
             # validate & store packed_ip
             NetAddr.validate_ip_addr(packed_ip, :Version => @version)
@@ -1806,11 +1908,58 @@ public_class_method :new
         # set @network & @hostmask
         @network = (@ip & @netmask)
         @hostmask = @netmask ^ @all_f
+        @wildcard_mask = @hostmask if (!@wildcard_mask)
 
     end
 
-end
 
+#==============================================================================#
+# broadcast()
+#==============================================================================#
+
+# Alias for last
+alias :broadcast :last
+
+#==============================================================================#
+# hostmask_ext()
+#==============================================================================#
+
+#===Synopsis
+#Provide IPv4 Hostmask in extended format (y.y.y.y).
+#
+# puts cidr4.hostmask_ext(
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def hostmask_ext()
+        return(NetAddr.unpack_ip_addr(@hostmask, :Version => @version))
+    end
+
+#==============================================================================#
+# netmask_ext()
+#==============================================================================#
+
+#===Synopsis
+#Provide IPv4 netmask in extended format (y.y.y.y).
+#
+# puts cidr4.netmask_ext()
+#
+#===Arguments:
+#* none
+#
+#===Returns:
+#* String
+#
+    def netmask_ext()    
+        return(NetAddr.unpack_ip_addr(@netmask))
+    end
+
+end # end class CIDRv4
+ 
 
 # IPv6 CIDR address - Inherits all methods from NetAddr::CIDR. 
 # Addresses of this class are composed of a 128-bit address space.
@@ -1832,15 +1981,20 @@ public_class_method :new
 # cidr6 = NetAddr::CIDRv6.new('fec0::/64',
 #                             :Tag => {'interface' => 'g0/1'})
 # cidr6_2 = NetAddr::CIDRv6.new('::ffff:192.168.1.1/96')
+# cidr6_3 = NetAddr::CIDRv6.new('fec0::',
+#                               :WildcardMask => '0000:ffff::ffff')
 #
 #===Arguments:
 #* CIDR address as a String, or a packed IP address as an Integer
 #* Optional Hash with the following keys:
 #     :PackedNetmask -- Integer representation of an IP Netmask (optional)
 #     :Tag -- Custom descriptor tag - Hash, tag => value. (optional)
+#     :WildcardMask -- 2 element Array. First element contains a special bit mask used for
+#                      advanced IP pattern matching. The second element should be :inversed if this
+#                      bit mask is in inverse format. (optional)
 #
     def initialize(addr, options=nil)
-        known_args = [:PackedNetmask, :Tag]
+        known_args = [:PackedNetmask, :Tag, :WildcardMask]
         @tag = {}
         @version = 6
         @max_bits = 128
@@ -1873,18 +2027,44 @@ public_class_method :new
                     raise ArgumentError, "Expected Hash, but #{@tag.class} provided for option :Tag."
                 end
             end
+
+            if (options.has_key?(:WildcardMask))
+                if (!options[:WildcardMask].kind_of?(Array))
+                    raise ArgumentError, "Expected Array, but #{options[:WildcardMask].class} provided for option :WildcardMask."
+                end
+                wildcardmask = options[:WildcardMask][0]
+                inversed = false
+                inversed = true if (options[:WildcardMask][1] && options[:WildcardMask][1] == :inversed)
+
+                if (wildcardmask.kind_of?(Integer))
+                   begin
+                        @wildcard_mask = wildcardmask
+                        NetAddr.validate_ip_addr(@wildcard_mask, :Version => @version)
+                    rescue NetAddr::ValidationError
+                        raise NetAddr::ValidationError, ":WildcardMask must be a valid IPv#{@version} address."
+                    end 
+                else
+                    begin
+                        @wildcard_mask = NetAddr.pack_ip_addr(wildcardmask, :Version => @version)
+                    rescue NetAddr::ValidationError
+                        raise NetAddr::ValidationError, ":WildcardMask must be a valid IPv#{@version} address."
+                    end
+                end
+
+                @wildcard_mask = @wildcard_mask ^ @all_f if (inversed)
+            end
         end
-        
-        
-        if (packed_ip) 
+
+
+        if (packed_ip)
             # validate & store packed_ip
             NetAddr.validate_ip_addr(packed_ip, :Version => @version)
             @ip = packed_ip
-        
-        else           
+
+        else
             # if ipv6 and extended netmask was provided, then raise exception
-            raise ArgumentError, "Garbage provided at end of IPv6 address." if (cidr =~ /.+\s+.+/ )    
-            
+            raise ArgumentError, "Garbage provided at end of IPv6 address." if (cidr =~ /.+\s+.+/ )
+
             # get ip and netmask
             if (cidr =~ /\//) 
                 ip,netmask = cidr.split(/\//)
@@ -1894,16 +2074,16 @@ public_class_method :new
             else
                 ip = cidr
             end
-            
-            # pack ip                
-            @ip = NetAddr.pack_ip_addr(ip, :Version => @version)           
+
+            # pack ip
+            @ip = NetAddr.pack_ip_addr(ip, :Version => @version)
         end
 
         # if no netmask or packed_netmask, then set
         # else validate. packed_netmask takes precedence over netmask
         if (!netmask && !packed_netmask)
             @netmask = @all_f
-        else            
+        else
             if (packed_netmask)
                 NetAddr.validate_ip_netmask(packed_netmask, :Packed => true, :Version => @version)
                 @netmask = packed_netmask
@@ -1912,14 +2092,15 @@ public_class_method :new
                 @netmask = NetAddr.pack_ip_netmask(netmask, :Version => @version)
             end
         end
-        
+
         # set @network & @hostmask
         @network = (@ip & @netmask)
         @hostmask = @netmask ^ @all_f
+        @wildcard_mask = @hostmask if (!@wildcard_mask)
 
     end
 
-end
+end # end class CIDRv6
 
 end # module NetAddr
 __END__

data/lib/eui.rb

@@ -1,5 +1,5 @@
 =begin rdoc
- Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com)
+ Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com)
   
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end

data/lib/methods.rb

@@ -1,5 +1,5 @@
 =begin rdoc
- Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com)
+ Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com)
   
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end
@@ -14,11 +14,11 @@ module NetAddr
 #Given a list of CIDR addresses or NetAddr::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 
+#'creation' of new IP space. For example the following blocks 
 #(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 
 #
-#I have designed this with enough flexibility that you can pass in CIDR 
+#I have designed this with enough flexibility so that you can pass in CIDR 
 #addresses that arent even related (ex. 192.168.1.0/26, 192.168.1.64/27, 192.168.1.96/27
 #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).
@@ -52,13 +52,13 @@ def merge(list,options=nil)
         raise ArgumentError, "Hash expected for argument 'options' but #{options.class} provided." if (!options.kind_of?(Hash) )
         NetAddr.validate_args(options.keys,known_args)
     
-        if (options.has_key?(:Short) && options[:Short] == true)
-            short = true
-        end
-    
         if (options.has_key?(:Objectify) && options[:Objectify] == true)
             objectify = true
-        end        
+        end
+        
+        if (options.has_key?(:Short) && options[:Short] == true)
+            short = true 
+        end
     end
     
     # make sure all are valid types of the same IP version
@@ -181,7 +181,7 @@ module_function :merge
 
 #===Synopsis
 #Given the number of IP addresses required in a subnet, return the minimum
-#netmask (in bits) required for that subnet. IP version is assumed to be 4 unless specified otherwise.
+#netmask (bits by default) required for that subnet. IP version is assumed to be 4 unless specified otherwise.
 #
 # Example:
 # netmask = NetAddr.minumum_size(14)
@@ -190,14 +190,16 @@ module_function :merge
 #===Arguments:
 #* IP count as an Integer
 #* Optional Hash with the following keys:
+#     :Extended -- If true, then return the netmask in extended format (y.y.y.y) for IPv4
 #     :Version -- IP version - Integer(optional)
 #
 #===Returns:
-#* Integer
+#* Integer or String
 #
 def minimum_size(ipcount, options=nil)
     version = 4
-    known_args = [:Version]
+    extended = false
+    known_args = [:Version, :Extended]
 
     # validate ipcount
     raise ArgumentError, "Integer expected for argument 'ipcount' but #{ipcount.class} provided." if (!ipcount.kind_of?(Integer))
@@ -211,10 +213,14 @@ def minimum_size(ipcount, options=nil)
         if (options.has_key?(:Version))
             version = options[:Version]
         end
+        
+        if (options.has_key?(:Extended) && options[:Extended] == true)
+            extended = true
+        end
     end
     
     if (version == 4)
-        max_bits = 32        
+        max_bits = 32
     else
         max_bits = 128
     end
@@ -232,6 +238,7 @@ def minimum_size(ipcount, options=nil)
     end
     subnet_bits = max_bits - bits_needed
     
+    return(NetAddr.unpack_ip_addr(NetAddr.pack_ip_netmask(subnet_bits))) if (extended && version == 4)
     return(subnet_bits)
 end
 module_function :minimum_size
@@ -440,8 +447,8 @@ module_function :pack_ip_netmask
 #Given two CIDR addresses or NetAddr::CIDR objects of the same version,
 #return all IP addresses between them. NetAddr.range will use the original IP 
 #address passed during the initialization of the NetAddr::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)
+#ip address of any CIDR addresses passed. The default behavior is to be 
+#non-inclusive (don't include boundaries as part of returned data)
 #
 # Example:
 # list = NetAddr.range(cidr1,cidr2, :Limit => 10)
@@ -503,7 +510,7 @@ def range(cidr1, cidr2, options=nil)
         end
         
         if( options.has_key?(:Short) && options[:Short] == true )
-            short = true
+            short = true 
         end
         
         if( options.has_key?(:Inclusive) && options[:Inclusive] == true )
@@ -652,7 +659,7 @@ module_function :shorten
 #===Synopsis
 #Given a list of CIDR addresses or NetAddr::CIDR objects, 
 #sort them from lowest to highest by Network/Netmask. NetAddr.sort will use the
-#original IP address passed during the initialization of any NetAddr::CIDR 
+#base address passed during the initialization of any NetAddr::CIDR 
 #objects, or the base address of any CIDR addresses passed
 #
 # Example:
@@ -1233,6 +1240,87 @@ def validate_ip_netmask(netmask, options=nil)
 end
 module_function :validate_ip_netmask
 
+#==============================================================================#
+# wildcard()
+#==============================================================================#
+
+#===Synopsis
+#Convert a wildcard IP into a valid CIDR address. Wildcards must always be at
+#the end of the address. Any data located after the first wildcard will be lost.
+#Shorthand notation is prohibited for IPv6 addresses. 
+#IPv6 encoded IPv4 addresses are not currently supported.
+#
+# Examples:
+# NetAddr.wildcard('192.168.*')
+# NetAddr.wildcard('192.168.1.*')
+# NetAddr.wildcard('fec0:*')
+# NetAddr.wildcard('fec0:1:*')
+#
+#===Arguments:
+#* Wildcard IP address as a String
+#
+#===Returns:
+#* CIDR object 
+#
+def wildcard(ip)
+    version = 4
+
+    # do operations per version of address
+    if (ip =~ /\./ && ip !~ /:/)
+        octets = []
+        mask = 0
+
+        ip.split('.').each do |x|
+            if (x =~ /\*/)
+                break
+            end
+            octets.push(x)
+        end
+        
+        octets.length.times do
+            mask = mask << 8
+            mask = mask | 0xff
+        end
+        
+        until (octets.length == 4)
+            octets.push('0')
+            mask = mask << 8
+        end
+        ip = octets.join('.')
+        
+    elsif (ip =~ /:/)
+        version = 6
+        fields = []
+        mask = 0
+
+        raise ArgumentError, "IPv6 encoded IPv4 addresses are unsupported." if (ip =~ /\./)
+        raise ArgumentError, "Shorthand IPv6 addresses are unsupported." if (ip =~ /::/)
+
+        ip.split(':').each do |x|
+            if (x =~ /\*/)
+                break
+            end
+            fields.push(x)
+        end
+
+        fields.length.times do
+            mask = mask << 16
+            mask = mask | 0xffff
+        end
+
+        until (fields.length == 8)
+            fields.push('0')
+            mask = mask << 16
+        end
+        ip = fields.join(':')
+    end
+        
+    # make & return cidr
+    cidr = NetAddr::CIDR.create(ip, :PackedNetmask => mask, :Version => version)
+    return(cidr)
+end
+module_function :wildcard
+
 #==============================================================================#
 # NetStruct
 #==============================================================================#
@@ -1246,7 +1334,7 @@ module_function :validate_ip_netmask
 #   * parent - parent NetStruct in tree
 #   * children - Array of children NetStruct objects
 #
-NetStruct = Struct.new(:cidr, :parent, :children)
+NetStruct = Struct.new(:cidr, :parent, :children) #:nodoc:
 
 
 # PRIVATE METHODS

data/lib/net_addr.rb

@@ -1,5 +1,5 @@
 =begin rdoc
- Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com)
+ Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com)
   
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end

data/lib/tree.rb

@@ -1,5 +1,5 @@
 =begin rdoc
- Copyright (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
+ Copyleft (c) 2006 Dustin Spinhirne (www.spinhirne.com) 
  
  Licensed under the same terms as Ruby, No Warranty is provided.
 =end
@@ -695,7 +695,7 @@ class Tree
 #==============================================================================#
 
 #===Synopsis
-# Print the tree in a nicely formatted string.
+# Print the tree as a nicely formatted string.
 #
 # puts tree.show()
 #

data/tests/cidr_test.rb

@@ -19,6 +19,10 @@ class TestCIDR < Test::Unit::TestCase
         assert_nothing_raised(Exception){NetAddr::CIDR.create('fec0::1/64')}
         assert_nothing_raised(Exception){NetAddr::CIDR.create('fec0::1/64')}
         assert_nothing_raised(Exception){NetAddr::CIDR.create(0x0a0a0a0a, :PackedNetmask => 0xffffffff)}
+        assert_nothing_raised(Exception){NetAddr::CIDR.create('192.168.1.1', :WildcardMask => ['0.0.7.255', :inversed]) }
+        assert_nothing_raised(Exception){NetAddr::CIDR.create('192.168.1.1', :WildcardMask => [0x000007ff, :inversed]) }
+        assert_nothing_raised(Exception){NetAddr::CIDR.create('fec0::1', :WildcardMask => ['0000:ffff::ffff', :inversed])}
+        assert_nothing_raised(Exception){NetAddr::CIDR.create('fec0::1', :WildcardMask => [0xffff, :inversed])}
         
         assert_kind_of(NetAddr::CIDRv4, NetAddr::CIDR.create('192.168.1.1 255.255.0.0'))
         assert_kind_of(NetAddr::CIDRv4, NetAddr::CIDR.create('192.168.1.1/24 255.255.0.0'))
@@ -27,6 +31,8 @@ class TestCIDR < Test::Unit::TestCase
         assert_kind_of(NetAddr::CIDRv4, NetAddr::CIDR.create('10.10.10.10/32', :PackedNetmask => 0xffffff00))
         
         assert_raise(ArgumentError){ NetAddr::CIDR.create(:Version => 4) }
+        assert_raise(NetAddr::ValidationError){ NetAddr::CIDR.create('192.168.1.1', :WildcardMask => ['0000:ffff::ffff', :inversed]) }
+        assert_raise(NetAddr::ValidationError){ NetAddr::CIDR.create('fec0::1', :WildcardMask => ['0.0.7.255', :inversed]) }
     end
     
     def test_new
@@ -67,6 +73,26 @@ class TestCIDR < Test::Unit::TestCase
         assert_raise(NetAddr::ValidationError){ NetAddr::CIDRv4.new('192.168.1.0 a') }
     end
     
+    def test_matches?
+        cidr = NetAddr::CIDR.create('10.0.0.0/24')
+        assert(cidr.matches?('10.0.0.22'))
+        assert(!cidr.matches?('10.1.1.1'))
+        
+        cidr = NetAddr::CIDR.create('10.0.248.0')
+        cidr.wildcard_mask('255.248.255.0')
+        assert(cidr.matches?('10.1.248.0'))
+        assert(!cidr.matches?('10.8.248.0'))
+        
+        cidr = NetAddr::CIDR.create('10.0.248.0')
+        cidr.wildcard_mask('0.7.0.255', :inversed)
+        assert(cidr.matches?('10.1.248.0'))
+        assert(!cidr.matches?('10.8.248.0'))
+        
+        cidr = NetAddr::CIDR.create('fec0::1')
+        cidr.wildcard_mask('0000:ffff::ffff', :inversed)
+        assert(cidr.matches?('fec0:1::1'))
+        assert(!cidr.matches?('fec0:0:1::1'))
+    end
     
     def test_cmp
 
@@ -396,6 +422,29 @@ class TestCIDR < Test::Unit::TestCase
         subnet4 = cidr4.subnet(:IPCount => 31)
         assert_equal('192.168.1.0/27', subnet4[0])       
     end
+    
+    def test_wildcard_mask
+        cidr = NetAddr::CIDR.create('10.1.0.0/24')
+        assert_equal('0.0.0.255', cidr.wildcard_mask(nil,:inversed))
+        assert_equal('255.255.255.0', cidr.wildcard_mask)
+        
+        cidr.wildcard_mask('0.7.0.255', :inversed)
+        assert_equal('0.7.0.255', cidr.wildcard_mask(nil,:inversed))
+        assert_equal('255.248.255.0', cidr.wildcard_mask())
+        cidr.wildcard_mask('255.248.255.0')
+        assert_equal('0.7.0.255', cidr.wildcard_mask(nil,:inversed))
+        assert_equal('255.248.255.0', cidr.wildcard_mask())
+        cidr.wildcard_mask('0.0.0.0')
+        assert_equal('0.0.0.0', cidr.wildcard_mask)
+        assert_raise(NetAddr::ValidationError){ cidr.wildcard_mask('0000:ffff::ffff') }
+        
+        cidr = NetAddr::CIDR.create('fec0::1/64')
+        assert_equal('0000:0000:0000:0000:ffff:ffff:ffff:ffff', cidr.wildcard_mask(nil,:inversed))
+        cidr.wildcard_mask('0000:ffff::ffff', :inversed)
+        assert_equal('0000:ffff:0000:0000:0000:0000:0000:ffff', cidr.wildcard_mask(nil,:inversed))
+        assert_raise(NetAddr::ValidationError){ cidr.wildcard_mask('0.7.0.255', :inversed) }
+        
+    end
 
     
 end

data/tests/methods_test.rb

@@ -65,6 +65,10 @@ class TestMethods < Test::Unit::TestCase
         assert_raise(ArgumentError) {NetAddr.minimum_size(200, :test => true)}
         assert_equal(24, NetAddr.minimum_size(200))
         assert_equal(96, NetAddr.minimum_size(2**32-1, :Version => 6))
+        assert_equal('255.255.255.0', NetAddr.minimum_size(200, :Extended => true))
+        assert_equal('255.255.255.224', NetAddr.minimum_size(17, :Extended => true))
+        assert_equal(24, NetAddr.minimum_size(200, :Extended => false))
+        assert_equal(96, NetAddr.minimum_size(2**32-1, :Version => 6, :Extended => true))
         
         assert_raise(ArgumentError){ NetAddr.minimum_size({}) }
     end
@@ -296,6 +300,29 @@ class TestMethods < Test::Unit::TestCase
     end 
     
     
+    def test_wildcard
+        cidr = NetAddr.wildcard('192.168.*')
+        assert_equal(NetAddr::CIDRv4, cidr.class )
+        assert_equal(16, cidr.bits)
+        assert_equal('192.168.0.0', cidr.network)
+        
+        cidr = NetAddr.wildcard('192.*.1.0')
+        assert_equal(8, cidr.bits)
+        assert_equal('192.0.0.0', cidr.network)
+        
+        cidr = NetAddr.wildcard('fec0:*')
+        assert_equal(NetAddr::CIDRv6, cidr.class )
+        assert_equal(16, cidr.bits)
+        assert_equal('fec0:0000:0000:0000:0000:0000:0000:0000', cidr.network)
+        
+        cidr = NetAddr.wildcard('fec0:1:*')
+        assert_equal(32, cidr.bits)
+        assert_equal('fec0:0001:0000:0000:0000:0000:0000:0000', cidr.network)
+        
+        assert_raise(ArgumentError){NetAddr.wildcard('fec0::*')}
+        assert_raise(ArgumentError){NetAddr.wildcard('::ffff:192.168.*')}
+    end
+    
 end
 
 

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.0
 specification_version: 1
 name: netaddr
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
-date: 2006-08-17 00:00:00 -05:00
+  version: 1.1.0
+date: 2007-01-05 00:00:00 -06:00
 summary: A package for manipulating network addresses.
 require_paths: 
 - lib
@@ -25,20 +25,21 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Dustin Spinhirne
 files: 
+- lib/methods.rb
 - lib/cidr.rb
 - lib/eui.rb
-- lib/methods.rb
-- lib/tree.rb
 - lib/net_addr.rb
+- lib/tree.rb
 - README
 - Errors
 test_files: 
 - tests/cidr_test.rb
-- tests/eui_test.rb
 - tests/methods_test.rb
+- tests/eui_test.rb
 - tests/tree_test.rb
 rdoc_options: []