ipadmin 0.1.1 → 0.1.2

data/README

@@ -15,106 +15,140 @@
 =Examples:
  
  
+ #!/usr/bin/ruby
+
  require 'rubygems'
  require_gem 'ipadmin'
- 
- 
+
  #============================================================================#
  # IPAdmin::IPAddr
  #============================================================================#
  puts "IPAdmin::IPAddr"
- 
- begin
-     ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1/24')
-     ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1',
-                               :Netmask => '255.255.255.0',
-                               :Tag => {'test' => 'ip4 tag'})
-     ip6 = IPAdmin::IPAddr.new(:IPAddr => 'fec0::1/64')
-     rescue Exception
-     puts 'oops'
-     exit
- end
-  
+
+ # new
+ ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1/24')
+ ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1',
+                           :Netmask => '255.255.255.0',
+                           :Tag => {'test' => 'ip4 tag'})
+ ip6 = IPAdmin::IPAddr.new(:IPAddr => 'fec0::1/64')
+
+ # reader/writer
  puts ip4.tag['test']
  ip4.tag['test'] = 'modified ip4 tag'
  puts ip4.tag['test']
- 
- puts "base addr #{ip4.base()}"
- puts "base addr #{ip6.base()}"
 
- puts "bcast addr #{ip4.broadcast()}"
+ # base
+ puts "ip4 base addr #{ip4.base()}"
+ puts "ip6 base addr #{ip6.base()}"
 
- puts "description #{ip4.desc()}"
- puts "description #{ip6.desc()}"
+ # broadcast
+ puts "ip4 bcast addr #{ip4.broadcast()}"
 
- puts "extended hostmask #{ip4.hostmask_ext()}"
- puts "extended netmask #{ip4.netmask_ext()}"
+ # desc
+ puts "ip4 description #{ip4.desc()}"
+ puts "ip6 description #{ip6.desc()}"
 
- puts "ip addr #{ip4.ip()}"
- puts "ip addr #{ip6.ip()}"
+ # extended masks
+ puts "ip4 extended hostmask #{ip4.hostmask_ext()}"
+ puts "ip6 extended netmask #{ip4.netmask_ext()}"
 
- puts "netmask in bits #{ip4.netmask()}"
- puts "netmask in bits #{ip6.netmask()}"
+ # ip
+ puts "ip4 ip addr #{ip4.ip()}"
+ puts "ip6 ip addr #{ip6.ip()}"
+
+ # netmask
+ puts "ip4 netmask in CIDR format #{ip4.netmask()}"
+ puts "ip6 netmask in CIDR format #{ip6.netmask()}"
+ 
+ # bits
+ puts "ip4 netmask in bits #{ip4.bits()}"
+ puts "ip6 netmask in bits #{ip6.bits()}"
 
  print "\n\n\n"
  #=====================================#
- #     
+ #
  #=====================================#
 
-
  #============================================================================#
  # IPAdmin::CIDR
  #============================================================================#
  puts "IPAdmin::CIDR"
 
- begin
-    cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
-    cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0',
-                              :Netmask => '255.255.255.0',
-                              :Tag => {'test' => 'cidr4 tag'})
-    cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
-    rescue Exception
-    puts 'oops'
-    exit
- end
- 
+ # new
+ cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
+ cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0',
+                           :Netmask => '255.255.255.0',
+                           :Tag => {'test' => 'cidr4 tag'})
+ cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
+
+ # attr reader/writer
  puts cidr4.tag['test']
  cidr4.tag['test'] = 'modified cidr4 tag'
  puts cidr4.tag['test']
 
- puts "cidr4 contains ip4" if ( cidr4.contains(ip4) )
- puts "cidr6 contains ip6" if ( cidr6.contains(ip6) )
- 
- puts "description #{cidr4.desc()}"
- puts "description #{cidr6.desc()}"
- 
- puts "extended hostmask #{cidr4.hostmask_ext()}"
- puts "extended netmask #{cidr4.netmask_ext()}"
- 
- puts "netmask in bits #{cidr4.netmask()}"
- puts "netmask in bits #{cidr6.netmask()}"
- 
- puts "network address #{cidr4.network()}"
- puts "network address #{cidr6.network()}"
- 
- puts "1st ip is #{cidr4.nth(:Index => 1)}"
- puts "1st ip is #{(cidr6.nth(:Index => 1, :Objectify => 1)).desc}"
+ # contains
+ puts "#{cidr4.desc} contains #{ip4.desc}" if ( cidr4.contains(ip4) )
+ puts "#{cidr6.desc} contains #{ip6.desc}" if ( cidr6.contains(ip6) )
+
+ # desc
+ puts "cidr4 description #{cidr4.desc()}"
+ puts "cidr6 description #{cidr6.desc()}"
+
+ # extended masks
+ puts "cidr4 extended hostmask #{cidr4.hostmask_ext()}"
+ puts "cidr4 extended netmask #{cidr4.netmask_ext()}"
+
+ # netmask
+ puts "cidr4 netmask in CIDR format #{cidr4.netmask()}"
+ puts "cidr6 netmask in CIDR format #{cidr6.netmask()}"
  
+ # bits
+ puts "cidr4 netmask in bits #{cidr4.bits()}"
+ puts "cidr6 netmask in bits #{cidr6.bits()}"
+
+ # network
+ puts "cidr4 network address #{cidr4.network()}"
+ puts "cidr6 network address #{cidr6.network()}"
+
+ # nth
+ puts "cidr4 1st ip is #{cidr4.nth(:Index => 1)}"
+ puts "cidr6 1st ip is #{(cidr6.nth(:Index => 1, :Objectify => 1)).desc}"
+
+ # size
  puts "cidr4 size is #{cidr4.size()}"
  puts "cidr6 size is #{cidr6.size()}"
+
+ # enumerate
+ puts "first 4 cidr4 addresses (bitstep 32)"
+ list4 = cidr4.enumerate(:Limit => 4, :Bitstep => 32)
+ list4.each do |addr|
+     puts "  #{addr}"
+ end
  
- cidr4.enumerate(:Limit => 4, :Bitstep => 32) {|addr| puts addr}
- cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => 1) {|addr| puts  addr.desc()}
+ puts "first 4 cidr6 addresses (bitstep 32)"
+ list6 = cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => 1)
+ list6.each do |addr|
+     puts "  #{addr.desc}"
+ end
  
- cidr4.subnet(:Subnet => 28, :MinCount => 3) {|cidr| puts cidr.desc()}
- cidr6.subnet(:Subnet => 66, :MinCount => 4) {|cidr| puts cidr.desc()}
+ # subnet
+ puts "cidr4 subnetted into at least 3 /28 ranges"
+ sn4 = cidr4.subnet(:Subnet => 28, :MinCount => 3)
+ sn4.each do |cidr|
+     puts "  #{cidr.desc()}"
+ end
  
- print "\n\n\n" 
+ puts "cidr6 subnetted into at least 4 /66 ranges"
+ sn6 = cidr6.subnet(:Subnet => 66, :MinCount => 4)
+ sn6.each do |cidr|
+     puts "  #{cidr.desc()}"
+ end
+
+ print "\n\n\n"
  #=====================================#
- #     
+ #
  #=====================================#
 
-
  #============================================================================#
  # IPAdmin::CIDRTable
  #============================================================================#
@@ -127,20 +161,17 @@
  cidr4_5 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
  cidr4_6 = IPAdmin::CIDR.new(:CIDR => '192.168.1.128/26')
  cidr4_7 = IPAdmin::CIDR.new(:CIDR => '192.168.1.192/26')
-         
+
  cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::/10')
  cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fe80::/10')
  cidr6_3 = IPAdmin::CIDR.new(:CIDR => 'fec0::/64')
  cidr6_4 =IPAdmin::CIDR.new(:CIDR => 'fec0::/126')
- 
- begin
-    table4 = IPAdmin::CIDRTable.new(4)
-    table6 = IPAdmin::CIDRTable.new(6)
-    rescue Exception
-    puts 'oops'
-    exit
- end
-         
+
+ # new
+ table4 = IPAdmin::CIDRTable.new(4)
+ table6 = IPAdmin::CIDRTable.new(6)
+
+ # add_cidr
  table4.add_cidr(cidr4_1)
  table4.add_cidr(cidr4_2)
  table4.add_cidr(cidr4_3)
@@ -148,92 +179,105 @@
  table4.add_cidr(cidr4_5)
  table4.add_cidr(cidr4_6)
  table4.add_cidr(cidr4_7)
- 
+
  table6.add_cidr(cidr6_1)
  table6.add_cidr(cidr6_2)
  table6.add_cidr(cidr6_3)
  table6.add_cidr(cidr6_4)
 
- puts "ip4 belongs in #{table4.find_ip(ip4).desc}"
- puts "ip6 belongs in #{table6.find_ip(ip6).desc}"
- 
+ # find_ip
+ puts "#{ip4.desc} belongs in #{table4.find_ip(ip4).desc}"
+ puts "#{ip6.desc} belongs in #{table6.find_ip(ip6).desc}"
+
+ # find_space
  puts "all blocks that can hold a /27"
  list4 = table4.find_space(:Size => 27)
  list4.each do |cidr|
     puts "  #{cidr.desc()}"
  end
- 
+
  puts "first block that can hold a /64"
  list6 = table6.find_space(:Size => 64, :Limit => 1)
  list6.each do |cidr|
     puts "  #{cidr.desc()}"
  end
- 
- 
+
+ # dump
  puts 'dump table4...'
- dump4 = table4.dump 
+ dump4 = table4.dump
  dump4.each do |cidr|
     puts "  #{cidr.desc}"
  end
  puts 'dump table6...'
- dump6 = table6.dump 
+ dump6 = table6.dump
  dump6.each do |cidr|
      puts "  #{cidr.desc}"
  end
+ 
+ puts "remove 192.168.1.0/26 from table4"
+ table4.rem_cidr(cidr4_3)
+ dump4 = table4.dump
+ dump4.each do |cidr|
+    puts "  #{cidr.desc}"
+ end
 
  print "\n\n\n"
  #=====================================#
- #     
+ #
  #=====================================#
 
-
  #============================================================================#
- # IPAdmin Misc Methods
+ # IPAdmin Methods
  #============================================================================#
- puts "Misc Methods"
+ puts "IPAdmin Methods"
 
+ # validate ip
  puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv4_addr('192.168.1.0') )
  puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv6_addr('fec0::0') )
- 
+
+ # 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) )
- 
+
  cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
  cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/25')
  cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/10')
  cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
- 
+
+ # compare_cidr
  comp1 = IPAdmin.compare_cidr(cidr4_1,cidr4_2)
  comp2 = IPAdmin.compare_cidr(cidr6_1,cidr6_2)
  puts "#{(comp1[0]).desc} is the supernet of #{(comp1[1]).desc}"
  puts "#{(comp2[0]).desc} is the supernet of #{(comp2[1]).desc}"
- 
+
  cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
  cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.0.0/24')
  cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/128')
  cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::1/128')
- 
+
+ # merge_cidr
  puts "192.168.1.0/24 and 192.168.0.0/24 merge into #{IPAdmin.merge_cidr([cidr4_1,cidr4_2]).desc}"
  puts "fec0::0/128 and fec0::1/128 merge into #{IPAdmin.merge_cidr([cidr6_1,cidr6_2]).desc}"
 
  ip1 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.0')
  ip2 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.50')
 
-
+ # range
  list = IPAdmin.range(:Boundaries => [ip1,ip2], :Bitstep => 20 )
- puts "ip's between #{ip1.desc} and #{ip2.desc}"
+ puts "ip's between #{ip1.desc} and #{ip2.desc} (bitstep of 20)"
  list.each do |x|
   puts "  #{x}"
  end
 
+ # make_arpa
+ puts "arpa for #{cidr4_1.desc()} is #{IPAdmin.make_arpa(cidr4_1)}"
+ puts "arpa for #{cidr6_1.desc()} is #{IPAdmin.make_arpa(cidr6_1)}"
  
+ # v6_short
+ puts "shorthand notation for  #{cidr6_1.network()} is #{IPAdmin.v6_short(cidr6_1.network)}"
+
  print "\n\n\n"
  #=====================================#
- #     
+ #
  #=====================================#
- 
-
-
-
-

data/lib/ip_admin.rb

@@ -9,18 +9,23 @@ module IPAdmin
 # Compare cidr addresses of two IPAdmin::CIDR objects.
 # - Arguments:
 #   * Two IPAdmin::CIDR objects
-# 
+#
 # - Returns:
 #   * if one object is a subnet of another, then return an array in order of
 #     [supernet,subnet]
 #   * if both are equal, return 1
 #   * if neither is a subnet of the other, return nil
 #
+# Example:
+#   supernet,subnet = IPAdmin.compare_cidr(cidr1,cidr2)
+#   puts "#{supernet.desc} is the supernet of #{subnet.desc}"
+#
+
 def compare_cidr(cidr1,cidr2)
     
     # we only accept CIDR objects
     unless ( (cidr1.kind_of? IPAdmin::CIDR)&&(cidr2.kind_of? IPAdmin::CIDR) )
-        raise "Expected IPAdmin::CIDR, but #{options.class} provided."
+        raise ArgumentError, "Arguments shouldbe of type IPAdmin::CIDR."
     end
     
     # make sure both are same version
@@ -74,6 +79,84 @@ module_function :compare_cidr
 
 
 
+#============================================================================#
+# make_arpa()
+#============================================================================#
+
+# Given the address in the provided IPAdmin::IPAddr or IPAdmin::CIDR object, 
+# return either an in-addr.arpa. or ip6.arpa string. If an IPAdmin::CIDR 
+# object is provided, then its netmask will be used to determine the length
+# of the returned arpa string.
+# 
+# - Arguments:
+#   * IPAdmin::CIDR or IPAdmin::IPAddr object
+# 
+# - Returns:
+#   * IP/CIDR address in in-addr.arpa or ip6.arpa format
+#
+# Example:
+#   arpa = IPAdmin.make_arpa(cidr)
+#
+def make_arpa(object)
+
+    if (object.kind_of? IPAdmin::CIDR)
+        base = object.network()
+        netmask = object.bits()
+        
+    elsif (object.kind_of? IPAdmin::IPAddr)
+        base = object.ip()
+        
+    else
+        raise ArgumentError, "Expected IPAdmin::CIDR or IPAdmin::IPAddr object, " +
+                            "but #{object.class} provided."
+    end
+    
+    
+    if (object.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."
+
+    else
+        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 
+module_function :make_arpa
+
+#=====================================#
+#     
+#=====================================#
+
+
+
 #============================================================================#
 # merge_cidr()
 #============================================================================#
@@ -87,11 +170,14 @@ module_function :compare_cidr
 # - Returns:
 #   * IPAdmin::CIDR object
 #
+# Example:
+#   merged = IPAdmin.merge_cidr([cidr1,cidr2])
+#
 def merge_cidr(cidr_list)
     
     # make sure we have an array with at least 2 objects
     unless ( (cidr_list.kind_of? Array) && (cidr_list.length > 1) )
-        raise "Array of at least two IPAdmin::CIDR objects required."
+        raise ArgumentError, "Array of at least two IPAdmin::CIDR objects required."
     end
     
     
@@ -99,7 +185,7 @@ def merge_cidr(cidr_list)
     version = {}
     cidr_list.each do |cidr|
         unless (cidr.kind_of? IPAdmin::CIDR)
-            raise "Expected IPAdmin::CIDR, but #{options.class} provided."
+            raise ArgumentError, "Expected IPAdmin::CIDR, but #{cidr.class} provided."
         end
         version[cidr.version] = 1
     end
@@ -193,12 +279,15 @@ module_function :merge_cidr
 # 
 # - Returns:
 #   * packed IPv4 address or exception on error.
+#
+# Example:
+#   packed = IPAdmin.pack_ipv4_addr('192.168.1.1')
 # 
 def pack_ipv4_addr(ip)
  
     # is this a string?
     unless (ip.kind_of? String)
-        raise "Expected String, but #{ip.class} provided."
+        raise ArgumentError, "Expected String, but #{ip.class} provided."
     end
     
     # pack our ip
@@ -227,7 +316,7 @@ module_function :pack_ipv4_addr
 # pack_ipv4_netmask()
 #============================================================================#
 
-# Pack IPv4 netmask into a single byte field.  No attempt at validation
+# Pack IPv4 netmask into a single byte field.  Only very basic validation
 # is performed.
 # - Arguments:
 #   * IPv4 netmask in cidr or extended notation
@@ -235,6 +324,10 @@ module_function :pack_ipv4_addr
 # - Returns:
 #   * packed IPv4 netmask or exception on error.
 #
+# Example:
+#   packed = IPAdmin.pack_ipv4_netmask('255.255.255.0')
+#   packed = IPAdmin.pack_ipv4_netmask('24')
+#
 def pack_ipv4_netmask(netmask)
     
     all_f = 2**32-1
@@ -247,10 +340,21 @@ def pack_ipv4_netmask(netmask)
             packed_netmask = pack_ipv4_addr(netmask)
             packed_hostmask = packed_netmask ^ all_f    
             rescue Exception 
-            raise "#{netmask} is invalid."
+            raise "#{netmask} is not a valid IPv4 netmask."
         end
             
-    elsif (netmask !~ /\D/)
+    else    
+        # remove '/' if present
+        if (netmask =~ /^\// )
+            netmask[0] = " "
+            netmask.lstrip!
+        end
+        
+        # check if we have any non numeric characters
+        if (netmask =~ /\D/)
+            raise "#{netmask} is not a valid IPv4 netmask."
+        end
+        
         if (netmask.kind_of? String)
             netmask = netmask.to_i            
         end
@@ -258,9 +362,6 @@ def pack_ipv4_netmask(netmask)
         packed_hostmask = all_f >> netmask   
         packed_netmask = all_f ^ packed_hostmask
         
-    else
-        raise "#{netmask} is unrecognized."
-        
     end
     
     ret_vals = [packed_netmask,packed_hostmask]    
@@ -287,11 +388,14 @@ module_function :pack_ipv4_netmask
 # - Returns:
 #   * packed IPv6 address or exception on error.
 #
+# Example:
+#   packed = IPAdmin.pack_ipv4_netmask('fec0::0001')
+#
 def pack_ipv6_addr(ip)
     
     # is this a string?
     unless (ip.kind_of? String)
-        raise "Expected String, but #{ip.class} provided."
+        raise ArgumentError, "Expected String, but #{ip.class} provided."
     end       
      
         
@@ -351,7 +455,7 @@ module_function :pack_ipv6_addr
 # pack_ipv6_netmask()
 #============================================================================#
 
-# Pack IPv6 netmask into a single byte field. No attempt at validation
+# Pack IPv6 netmask into a single byte field. Only very basic validation
 # is performed.
 # - Arguments:
 #   * IPv6 netmask in cidr notation
@@ -359,10 +463,18 @@ module_function :pack_ipv6_addr
 # - Returns:
 #   * packed IPv6 netmask or exception on error.
 #
+# Example:
+#   packed = IPAdmin.pack_ipv4_netmask('64')
+#
 def pack_ipv6_netmask(netmask)
 
     all_f = 2**128-1    
     
+    # remove '/' if present
+    if (netmask =~ /^\// )
+        netmask[0] = " "
+        netmask.lstrip!
+    end
     
     if (netmask !~ /\D/)   
         # pack
@@ -374,7 +486,7 @@ def pack_ipv6_netmask(netmask)
         packed_netmask = all_f ^ packed_hostmask
         
     else
-        raise "#{netmask} is unrecognized."
+        raise "#{netmask} is not a valid IPv6 netmask."
         
     end
     
@@ -401,14 +513,17 @@ module_function :pack_ipv6_netmask
 # 
 # - Arguments:
 #   * Hash with the following fields
-#   - :Bitstep -- enumerate in X sized steps
-#   - :Boundaries -- array of (2) IPAdmin::IPAddr objects
-#   - :Limit -- limit returned list to X number of items
-#   - :Objectify -- return IPAdmin::IPAddr objects
+#       - :Bitstep -- enumerate in X sized steps
+#       - :Boundaries -- array of (2) IPAdmin::IPAddr objects
+#       - :Limit -- limit returned list to X number of items
+#       - :Objectify -- return IPAdmin::IPAddr objects
 # 
 # - Returns:
 #   * array of IP addresses or IPAdmin::IPAddr objects
 #
+# Example:
+#   list = IPAdmin.range(:Boundaries => [ip1,ip2])
+#
 def range(options)
     list = []
     bitstep = 1
@@ -537,6 +652,9 @@ module_function :range
 # - Returns:
 #   * IPv4 address.
 #
+# Example:
+#   unpacked = IPAdmin.unpack_ipv4_addr(packed)
+#
 def unpack_ipv4_addr(packed_ip)
     
     octets = []
@@ -571,6 +689,9 @@ module_function :unpack_ipv4_addr
 # - Returns:
 #   * IPv4 netmask as number of bits (cidr format).
 #
+# Example:
+#   unpacked = IPAdmin.unpack_ipv4_netmask(packed)
+#
 def unpack_ipv4_netmask(packed_mask)
     
     mask = 32
@@ -604,6 +725,9 @@ module_function :unpack_ipv4_netmask
 # - Returns:
 #   * IPv6 address.
 #
+# Example:
+#   unpacked = IPAdmin.unpack_ipv6_addr(packed)
+#
 def unpack_ipv6_addr(packed_ip)
     hex_fields = []
     (0..7).each do |x|
@@ -642,6 +766,9 @@ module_function :unpack_ipv6_addr
 # - Returns:
 #   * IPv6 netmask as number of bits (cidr format).
 #
+# Example:
+#   unpacked = IPAdmin.unpack_ipv6_netmask(packed)
+#
 def unpack_ipv6_netmask(packed_mask)
     
     mask = 128
@@ -663,22 +790,104 @@ module_function :unpack_ipv6_netmask
 
 
 
+#============================================================================#
+# v6_short()
+#============================================================================#
+
+# Take a standard IPv6 address, and format it in short-hand notation.
+# Address should not contain a netmask.
+# - Arguments:
+#   * IPv6 address
+# 
+# - Returns:
+#   * IPv6 short-hand address.
+# 
+# Example:
+#   short = IPAdmin.v6_short('fec0:0000:0000:0000:0000:0000:0000:0001')
+#
+def v6_short(addr)
+
+    # is this a string?
+    unless (addr.kind_of? String)
+        raise ArgumentError, "Expected String, but #{addr.class} provided."
+    end    
+
+    validate_ipv6_addr(addr)
+    
+    # make sure this isnt already shorthand
+    if (addr =~ /::/)
+        raise "#{addr} already appears to be in IPv6 shorthand notation."
+    end
+    
+    
+    # look for most 0 fields
+    found_zero = nil
+    pattern = ""
+    zero_fields = []
+    fields = addr.split(":")  
+    
+    (0..(fields.length-1)).each do |x|    
+        fields[x] = fields[x].to_i(16)
+        
+        if (fields[x] == 0)        
+            if (!found_zero)
+                found_zero = 1
+            end
+            pattern << ":0"            
+        else
+            if (found_zero)
+                found_zero = nil
+                pattern << ":"
+                zero_fields.push(pattern)
+                pattern = ""
+            end        
+        end
+                
+        fields[x] = fields[x].to_s(16)        
+    end    
+    
+
+    # pattern should be the longest set of 0's in a row
+    zero_fields.push(pattern) if (pattern != "")
+    pattern = ""
+    zero_fields.each do |x|
+        pattern = x if (x.length > pattern.length)          
+    end
+
+    
+
+    short = fields.join(":")
+    short.sub!(pattern,"::")
+    
+    return(short)
+end
+module_function :v6_short
+    
+#=====================================#
+#     
+#=====================================#
+
+
+
 #============================================================================#
 # validate_ipv4_addr()
 #============================================================================#
 
-# Validate IPv4 addresses.
+# Validate IPv4 addresses. Address should not contain a netmask.
 # - Arguments:
 #   * IPv4 address
 # 
 # - Returns:
 #   * 1 on valid IP or exception on error.
 # 
+# Example:
+#   IPAdmin.validate_ipv4_addr('192.168.1.1')
+#
 def validate_ipv4_addr(ip)
 
     # is this a string?
     unless (ip.kind_of? String)
-        raise "Expected String, but #{ip.class} provided."
+        raise ArgumentError, "Expected String, but #{ip.class} provided."
     end
     octets = ip.split( /\./ )
     
@@ -686,14 +895,14 @@ def validate_ipv4_addr(ip)
     
     # check validity of characters in the addr
     if ( (ip =~ /\.{2,}?/ ) || (ip =~ /[^0-9\.]/) )
-        raise "#{ip} is invalid."
+        raise "#{ip} is not a valid IPv4 address."
     end
     
     
     
     # do we have 4 octets?
     if (octets.length != 4)
-        raise "#{ip} is invalid."
+        raise "#{ip} is not a valid IPv4 address."
     end
 
     
@@ -702,14 +911,14 @@ def validate_ipv4_addr(ip)
     (0..3).each do |x|
         octets[x] = octets[x].to_i        
         unless ( (octets[x] >= 0) && (octets[x] < 256 ) )
-            raise "#{ip} is invalid." 
+            raise "#{ip} is not a valid IPv4 address." 
         end
     end
         
     
     # dont allow first octet to be 0
     if (octets[0] == 0)
-        raise "#{ip} is invalid." 
+        raise "#{ip} is not a valid IPv4 address." 
     end
     
     return(1)
@@ -734,6 +943,12 @@ module_function :validate_ipv4_addr
 # - Returns:
 #   * 1 on valid IP or exception on error.
 # 
+# Example:
+#   IPAdmin.validate_ipv4_netmask('255.255.255.0')
+#   IPAdmin.validate_ipv4_netmask('24')
+#   IPAdmin.validate_ipv4_netmask('/24')
+#   IPAdmin.validate_ipv4_netmask(24)
+#
 def validate_ipv4_netmask(netmask)
     
     all_f = (2**32)-1
@@ -747,7 +962,7 @@ def validate_ipv4_netmask(netmask)
             packed_mask = pack_ipv4_addr(netmask)
                 
             rescue Exception 
-            raise "#{netmask} is invalid."
+            raise "#{netmask} is not a valid IPv4 netmask."
         end
             
         # cycle through the bits of hostmask and compare
@@ -762,7 +977,7 @@ def validate_ipv4_netmask(netmask)
             if ( check != 0)
                 hostmask = hostmask >> 1
                 unless ( (packed_mask ^ hostmask) == all_f)
-                    raise "#{netmask} is invalid." 
+                    raise "#{netmask} is not a valid IPv4 netmask." 
                 end
                 break
             else
@@ -773,9 +988,15 @@ def validate_ipv4_netmask(netmask)
         
     else 
         
+        # remove '/' if present
+        if (netmask =~ /^\// )
+            netmask[0] = " "
+            netmask.lstrip!
+        end
+        
         # check if we have any non numeric characters
         if (netmask =~ /\D/)
-            raise "#{netmask} is invalid."
+            raise "#{netmask} is not a valid IPv4 netmask."
         end          
         
         
@@ -785,7 +1006,7 @@ def validate_ipv4_netmask(netmask)
         end
             
         if ( (netmask > 32) || (netmask == 0) )
-            raise "#{netmask} is invalid." 
+            raise "#{netmask} is not a valid IPv4 netmask." 
         end
         
     end
@@ -805,24 +1026,27 @@ module_function :validate_ipv4_netmask
 # validate_ipv6_addr()
 #============================================================================#
 
-# Validate IPv6 addresses.
+# Validate IPv6 addresses. Address should not contain a netmask.
 # - Arguments:
 #   * IPv6 address
 # 
 # - Returns:
 #   * 1 on valid IP or exception on error.
 # 
+# Example:
+#   IPAdmin.validate_ipv6_addr('fec0::')
+#
 def validate_ipv6_addr(ip)
     # is this a string?
     unless (ip.kind_of? String)
-        raise "Expected String, but #{ip.class} provided."
+        raise ArgumentError, "Expected String, but #{ip.class} provided."
     end
     
     
     
     # check validity of characters in the addr
     if ( (ip =~ /:{3,}?/ ) || (ip =~ /[^0-9a-fA-F:]/) )
-        raise "#{ip} is invalid."
+        raise "#{ip} is not a valid IPv6 address."
     end    
       
         
@@ -833,7 +1057,7 @@ def validate_ipv6_addr(ip)
     if (ip =~ /::/)
         shrthnd = ip.split( /::/ ) 
         unless ( (shrthnd.length > 0) && (shrthnd.length < 3) )
-            raise "#{ip} is invalid."
+            raise "#{ip} is not a valid IPv6 address."
         end
     end
         
@@ -848,7 +1072,7 @@ def validate_ipv6_addr(ip)
             elements.each {|x| hex_fields.push(x)}
         end
         if ( (hex_fields.length < 1) || (hex_fields.length > 7) )
-            raise "#{ip} is invalid."
+            raise "#{ip} is not a valid IPv6 address."
         end
         
      else
@@ -856,7 +1080,7 @@ def validate_ipv6_addr(ip)
         # have exactly 8 hex fields        
         hex_fields = ip.split( /:/ )
         if (hex_fields.length != 8)
-            raise "#{ip} is invalid."
+            raise "#{ip} is not a valid IPv6 address."
         end
         
     end
@@ -867,7 +1091,7 @@ def validate_ipv6_addr(ip)
     # hex field
     hex_fields.each do |x|
         if (x.length > 4)
-            raise "#{ip} is invalid."
+            raise "#{ip} is not a valid IPv6 address."
         end
     end
 
@@ -893,11 +1117,22 @@ module_function :validate_ipv6_addr
 # 
 # - Returns:
 #   * 1 on valid IP or exception on error.
+#
+# Example:
+#   IPAdmin.validate_ipv6_netmask('64')
+#   IPAdmin.validate_ipv6_netmask('/64')
+#   IPAdmin.validate_ipv6_netmask(64)
 # 
 def validate_ipv6_netmask(netmask)
 
+    # remove '/' if present
+    if (netmask =~ /^\// )
+        netmask[0] = " "
+        netmask.lstrip!
+    end
+    
     if (netmask =~ /\D/)
-        raise "#{netmask} is invalid."
+        raise "#{netmask} is not a valid IPv6 netmask."
         
     else
         # are we between 1 and 128 inclusive    
@@ -906,7 +1141,7 @@ def validate_ipv6_netmask(netmask)
         end
                     
         if ( (netmask > 128) || (netmask == 0) )
-            raise "#{netmask} is invalid." 
+            raise "#{netmask} is not a valid IPv6 netmask." 
         end
         
     end
@@ -942,17 +1177,20 @@ class CIDR
 #============================================================================#
 # attr_reader/attr_writer
 #============================================================================#
-
-    # @network - packed cidr network
-    # @netmask - packet cidr netmask
-    # @hostmask - inverse packed netmask    
     
     # ip version 4 or 6
     attr_reader :version
     
     # hash of custom tags. should be in the format tag => value
     attr_reader :tag
-    attr_writer :tag
+    
+    # attr_writer - hash of custom tags. should be in the format tag => value
+    def tag=(new_tag)
+        unless (new_tag.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{new_tag.class} provided."
+        end
+        @tag = new_tag
+    end
 
 #=====================================#
 #        
@@ -966,14 +1204,21 @@ class CIDR
 
 # - Arguments:
 #   * Hash with the following fields:
-#       :CIDR -- IPv4 or IPv6 cidr block
-#       :Netmask -- IPv4 netmask in extended format (if not provided in :CIDR)
-#       :Tag -- Custom descriptor tag for object. Should be Hash (tag => value)
+#       - :CIDR -- IPv4 or IPv6 cidr block
+#       - :Netmask -- IPv4 netmask in extended format (if not provided in :CIDR)
+#       - :Tag -- Custom descriptor tag for object. Should be Hash (tag => value)
+#
+# Example:
+#   cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0', 
+#                             :Netmask => '255.255.255.0')
+#   cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::/64',
+#                             :Tag => {'interface' => 'g0/1'})
+#
 #
     def initialize(options)
     
         unless (options.kind_of? Hash)
-            raise "Expected Hash, but #{options.class} provided."
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
         end
         
 
@@ -1051,8 +1296,11 @@ class CIDR
         
         
         # set tag if present
-        if ( options.has_key?(:Tag) )
+        if ( options.has_key?(:Tag) )            
             @tag = options[:Tag]
+            unless (@tag.kind_of? Hash)
+                raise "Expected Hash, but #{@tag.class} provided for option :Tag."
+            end
         end
 
         
@@ -1064,6 +1312,37 @@ class CIDR
 
 
 
+#============================================================================#
+# bits()
+#============================================================================#
+
+# Provide number of bits of Netmask.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Number of bits of Netmask.
+#
+# Example:
+#   bits = cidr.bits()
+#
+    def bits()    
+        if (@version == 4)
+            bits = IPAdmin.unpack_ipv4_netmask(@netmask)
+        else
+            bits = IPAdmin.unpack_ipv6_netmask(@netmask)
+        end
+        
+        return(bits)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
 #============================================================================#
 # contains()
 #============================================================================#
@@ -1075,9 +1354,16 @@ class CIDR
 # 
 # - Returns:
 #   * 1 on true, nil on false
+#
+# Example:
+#   contains = cidr.contains(ip)
 #
     def contains(ip_obj)
                 
+        unless (ip_obj.kind_of? IPAdmin::IPAddr)
+            raise ArgumentError, "Expected IPAdmin::IPAddr object, but #{ip_obj.class} provided."
+        end
+        
         if ( (ip_obj.version == 4) && (@version == 4) )
             v4_all_f = (2**32)-1        
             hostmask = @netmask ^ v4_all_f
@@ -1117,6 +1403,9 @@ class CIDR
 # 
 # - Returns:
 #   * Description in network/netmask format
+#
+# Example:
+#   desc = cidr.desc()
 #
     def desc()
         
@@ -1147,12 +1436,15 @@ class CIDR
 # 
 # - Arguments:
 #   * Hash with the following fields
-#   - :Bitstep -- enumerate in X sized steps
-#   - :Objectify -- return IPAdmin::IPAddr objects
-#   - :Limit -- limit returned list to X number of items
+#       - :Bitstep -- enumerate in X sized steps
+#       - :Objectify -- return IPAdmin::IPAddr objects
+#       - :Limit -- limit returned list to X number of items
 # 
 # - Returns:
 #   * array of IP addresses or IPAdmin::IPAddr objects
+#
+# Example:
+#   ip_list = cidr.enumerate(:Bitstep => 2)
 #
     def enumerate(options=nil)
         bitstep = 1
@@ -1265,6 +1557,9 @@ class CIDR
 # 
 # - Returns:
 #   * Hostmask in extended (y.y.y.y) format.
+#
+# Example:
+#   hostmask = cidr.hostmask_ext()
 #
     def hostmask_ext()    
         if (@version == 4)
@@ -1292,7 +1587,10 @@ class CIDR
 #   * none
 # 
 # - Returns:
-#   * Number of bits in the netmask.
+#   * Netmask in CIDR format.
+#
+# Example:
+#   netmask = cidr.netmask()
 #
     def netmask()    
         if (@version == 4)
@@ -1301,7 +1599,7 @@ class CIDR
             bits = IPAdmin.unpack_ipv6_netmask(@netmask)
         end
         
-        return(bits)
+        return("/#{bits}")
     end
 
 #=====================================#
@@ -1321,13 +1619,16 @@ class CIDR
 # 
 # - Returns:
 #   * Netmask in extended (y.y.y.y) format.
+#
+# Example:
+#   netmask = cidr.netmask_ext()
 #
     def netmask_ext()    
         if (@version == 4)
             netmask = IPAdmin.unpack_ipv4_addr(@netmask)
         else
             raise "IPv6 does not support extended netmask notation. " +
-                  "Use bits() method instead."
+                  "Use netmask() method instead."
         end
         
         return(netmask)
@@ -1350,6 +1651,9 @@ class CIDR
 # 
 # - Returns:
 #   * Base network address.
+#
+# Example:
+#   network = cidr.network()
 #
     def network()
         if (@version == 4)
@@ -1375,11 +1679,14 @@ class CIDR
 # 
 # - Arguments:
 #   * Hash with the following fields
-#   - :Index -- index of the address to return
-#   - :Objectify -- return IPAdmin::IPAddr objects
+#       - :Index -- index number of the IP address to return
+#       - :Objectify -- return IPAdmin::IPAddr objects
 # 
 # - Returns:
 #   * IP address or IPAdmin::IPAddr object.
+#
+# Example:
+#   first_ip = cidr.nth(:Index => 1)
 #
     def nth(options)
         objectify = nil
@@ -1458,6 +1765,9 @@ class CIDR
 # 
 # - Returns:
 #   * Byte-packed Hostmask.
+#
+# Example:
+#   packed = cidr.packed_hostmask()
 #
     def packed_hostmask()    
         return(@hostmask)
@@ -1480,6 +1790,9 @@ class CIDR
 # 
 # - Returns:
 #   * Byte-packed Netmask.
+#
+# Example:
+#   packed = cidr.packed_netmask()
 #
     def packed_netmask()
         return(@netmask)        
@@ -1502,6 +1815,9 @@ class CIDR
 # 
 # - Returns:
 #   * Byte-packed Network Address.
+#
+# Example:
+#   packed = cidr.packed_network()
 #
     def packed_network()
         return(@network)        
@@ -1524,6 +1840,9 @@ class CIDR
 # 
 # - Returns:
 #   * Number of IP addresses in this CIDR block.
+#
+# Example:
+#   num_ip = cidr.size()
 #
     def size()
         return(@hostmask + 1)        
@@ -1544,16 +1863,19 @@ class CIDR
 # 
 # - Arguments:
 #   * Hash with the following fields:
-#       :Subnet --  number of bits of new subnet to create (24,26, etc...)
-#       :MinCount -- minimum number of subnets of size :Subnet to return
+#       - :Subnet --  number of bits of new subnet to create (24,26, etc...)
+#       - :MinCount -- minimum number of subnets of size :Subnet to return
 # 
 # - Returns:
 #   * array of IPAdmin::CIDR objects
+#
+# Example:
+#   cidr_list = cidr4.subnet(:Subnet => 28, :MinCount => 3)
 #
     def subnet(options)
         subnet = options[:Subnet]
         min_count = options[:MinCount]
-        mymask = self.netmask        
+        mymask = self.bits        
         num_avail = 2**(subnet - mymask)
         new_subnets = []
         
@@ -1698,12 +2020,15 @@ class CIDRTable
 #============================================================================#
 
 # - Arguments:
-#   * Table version (4 or 6)
+#   * IP version (4 or 6)
+#
+# Example:
+#   table = IPAdmin::CIDRTable.new(4)
 # 
     def initialize(version)
         
         unless ( version.kind_of? Fixnum )
-            raise "Expected Fixnum, but #{version.class} provided."
+            raise ArgumentError, "Expected Fixnum, but #{version.class} provided."
         end
         
         unless ( version == 4 || version == 6 )
@@ -1730,10 +2055,17 @@ class CIDRTable
 #   * IPAdmin::CIDR object
 # 
 # - Returns:
-#   * nil
+#   * nothing
+#
+# Example:
+#   table.add_cidr(cidr)
 #
     def add_cidr(new_cidr)
         
+        unless (new_cidr.kind_of? IPAdmin::CIDR)
+            raise ArgumentError, "Expected IPAdmin::CIDR, but #{new_cidr.class} provided."
+        end
+        
         unless (new_cidr.version == @version )
             raise "CIDR version #{new_cidr.version} is incompatible with " +
                   "CIDRTable version #{@version}."
@@ -1805,10 +2137,13 @@ class CIDRTable
 # Dump contents of this table
 # 
 # - Arguments:
-#   * nil
+#   * none
 # 
 # - Returns:
 #   * ordered array of IPAdmin::CIDR objects within this table
+#
+# Example:
+#   cidr_list = table.dump()
 #
     def dump()
     
@@ -1855,15 +2190,18 @@ class CIDRTable
 # 
 # - Returns:
 #   * IPAdmin::CIDR object, or nil on no match
+#
+# Example:
+#   cidr = table.find_ip(ip)
 #
     def find_ip(ip_obj)
         
         unless (ip_obj.kind_of? IPAdmin::IPAddr)
-            raise "Expected IPAdmin::IPAddr, but #{options.class} provided."
+            raise ArgumentError, "Expected IPAdmin::IPAddr, but #{ip_obj.class} provided."
         end
         
         unless (ip_obj.version == @version )
-            raise "IPAddr version #{ip_addr.version} is incompatible with " +
+            raise "IPAddr version #{ip_obj.version} is incompatible with " +
                   "CIDRTable version #{@version}."
         end
         
@@ -1899,11 +2237,14 @@ class CIDRTable
 # 
 # - Arguments:
 #   * Hash with the following fields:
-#       :Size -- subnet size (number of bits)
-#       :Limit -- max entries to return
+#       - :Size -- subnet size (number of bits)
+#       - :Limit -- max entries to return
 # 
 # - Returns:
 #   * ordered array of IPAdmin::CIDR objects, or nil on no match
+#
+# Example:
+#   cidr_list = table.find_space(:Size => 27)
 #
     def find_space(options)
         limit = nil
@@ -1915,11 +2256,11 @@ class CIDRTable
         
         # validate options
         unless (options.kind_of? Hash)
-            raise "Expected Hash, but #{options.class} provided."
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
         end
         
         unless ( options.has_key?(:Size) )
-            raise "Missing argument :Size."
+            raise ArgumentError, "Missing argument :Size."
         end
         subnet_size = options[:Size]
         
@@ -1953,7 +2294,7 @@ class CIDRTable
         # find space
         sorted_parents.each do |key|
             parent = parent_hash[key]            
-            if ( parent.netmask() < subnet_size )
+            if ( parent.bits() < subnet_size )
                 if (@cidr_table[parent] != 0)
                     child_list = []
                     child_list = (@cidr_table[parent]).find_space(:Size => subnet_size)
@@ -1970,7 +2311,7 @@ class CIDRTable
                     
                 end
                 
-            elsif ( (parent_hash[key].netmask() == subnet_size) &&
+            elsif ( (parent_hash[key].bits() == subnet_size) &&
                     (@cidr_table[parent] == 0) )
                 list.push(parent)
                 
@@ -1993,6 +2334,62 @@ class CIDRTable
 
 
 
+#============================================================================#
+# rem_cidr()
+#============================================================================#
+
+# Remove an IPAdmin::CIDR object from this table
+# 
+# - Arguments:
+#   * IPAdmin::CIDR object
+# 
+# - Returns:
+#   * nothing
+#
+# Example:
+#   table.rem_cidr(cidr)
+#
+    def rem_cidr(cidr)
+        
+        unless (cidr.kind_of? IPAdmin::CIDR)
+            raise ArgumentError, "Expected IPAdmin::CIDR, but #{cidr.class} provided."
+        end
+        
+        unless (cidr.version == @version )
+            raise "CIDR version #{cidr.version} is incompatible with " +
+                  "CIDRTable version #{@version}."
+        end
+        
+        # if cidr is part of this table
+        if (@cidr_table.has_key?(cidr) )            
+
+            if (@cidr_table[cidr] != 0)
+                child_table = @cidr_table[cidr]
+                child_table.cidr_table.each_key do |child|
+                    child_table.rem_cidr(child)
+                end
+            end
+            @cidr_table.delete(cidr)
+        
+        # else search @cidr_table to see if cidr is a child block
+        else        
+            @cidr_table.each_key do |entry|
+                parent,child = IPAdmin.compare_cidr(cidr,entry)
+            
+                if (parent == entry)                        
+                    (@cidr_table[entry]).rem_cidr(cidr)
+                end        
+            end
+        end
+        
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
 
 end
 
@@ -2031,17 +2428,19 @@ class IPAddr
 # attr_reader/attr_writer
 #============================================================================#
 
-    # @ip - packed ip address
-    # @netmask - packed netmask
-    # @hostmask - inverse packed netmask
-    
     # ip version 4 or 6
     attr_reader :version
     
     # hash of custom tags. should be in the format tag => value
     attr_reader :tag
-    attr_writer :tag
-
+    
+    # attr_writer - hash of custom tags. should be in the format tag => value
+    def tag=(new_tag)
+        unless (new_tag.kind_of? Hash)
+            raise ArgumentError, "Expected Hash, but #{new_tag.class} provided."
+        end
+        @tag = new_tag
+    end
     
 #=====================================#
 #        
@@ -2055,14 +2454,21 @@ class IPAddr
 
 # - Arguments:
 #   * Hash with the following fields
-#       :IPAddr -- IPv4 or IPv6 address (assume host address by default)
-#       :Netmask -- IPv4 netmask in extended format ( if not part of IPAddr)
-#       :Tag -- Custom descriptor tag for object. Should be Hash (tag => value)
+#       - :IPAddr -- IPv4 or IPv6 address (assume host address by default)
+#       - :Netmask -- IPv4 netmask in extended format ( if not part of IPAddr)
+#       - :Tag -- Custom descriptor tag for object. Should be Hash (tag => value)
+#
+# Example:
+#   ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1',
+#                             :Netmask => '255.255.255.0',
+#                             :Tag => {'desc' => 'FastEthernet0/1'})
+#
+#   ip6 = IPAdmin::IPAddr.new(:IPAddr => 'fec0::/64')
 #
     def initialize(options)
     
         unless (options.kind_of? Hash)
-            raise "Expected Hash, but #{options.class} provided."
+            raise ArgumentError, "Expected Hash, but #{options.class} provided."
         end
         
         if ( options.has_key?(:IPAddr) )
@@ -2144,10 +2550,12 @@ class IPAddr
         
         
         # set tag if present
-        if ( options.has_key?(:Tag) )
+        if ( options.has_key?(:Tag) )            
             @tag = options[:Tag]
+            unless (@tag.kind_of? Hash)
+                raise "Expected Hash, but #{@tag.class} provided for option :Tag."
+            end
         end
-
         
     end
   
@@ -2170,6 +2578,9 @@ class IPAddr
 # 
 # - Returns:
 #   * base network address.
+#
+# Example:
+#   base = ip.base()
 #
     def base()
         if (@version == 4)
@@ -2189,6 +2600,37 @@ class IPAddr
 
 
 
+#============================================================================#
+# bits()
+#============================================================================#
+
+# Provide number of bits of Netmask.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Number of bits of Netmask.
+#
+# Example:
+#   bits = ip.bits()
+#
+    def bits()    
+        if (@version == 4)
+            bits = IPAdmin.unpack_ipv4_netmask(@netmask)
+        else
+            bits = IPAdmin.unpack_ipv6_netmask(@netmask)
+        end
+        
+        return(bits)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
 #============================================================================#
 # broadcast()
 #============================================================================#
@@ -2200,6 +2642,9 @@ class IPAddr
 # 
 # - Returns:
 #   * broadcast address.
+#
+# Example:
+#   bcast = ip.broadcast()
 #
     def broadcast()
         if (@version == 4)
@@ -2230,6 +2675,9 @@ class IPAddr
 # 
 # - Returns:
 #   * ip/netmask.
+#
+# Example:
+#   desc = ip.desc()
 #
     def desc()
         if (@version == 4)
@@ -2262,6 +2710,9 @@ class IPAddr
 # 
 # - Returns:
 #   * IPv4 Hostmask in extended (y.y.y.y) format.
+#
+# Example:
+#   hostmask = ip.hostmask_ext()
 #
     def hostmask_ext()    
         if (@version == 4)
@@ -2290,6 +2741,9 @@ class IPAddr
 # 
 # - Returns:
 #   * IP address.
+#
+# Example:
+#   addr = ip.ip() 
 #
     def ip()
         if (@version == 4)
@@ -2311,13 +2765,16 @@ class IPAddr
 # netmask()
 #============================================================================#
 
-# Provide Netmask for address within IPAdmin::IPAddr object.
+# Provide Netmask in cidr format.
 # 
 # - Arguments:
 #   * none
 # 
 # - Returns:
-#   * Number of bits in the netmask.
+#   * Netmask in CIDR format.
+#
+# Example:
+#   netmask = ip.netmask()
 #
     def netmask()    
         if (@version == 4)
@@ -2326,7 +2783,7 @@ class IPAddr
             bits = IPAdmin.unpack_ipv6_netmask(@netmask)
         end
         
-        return(bits)
+        return("/#{bits}")
     end
 
 #=====================================#
@@ -2346,13 +2803,16 @@ class IPAddr
 # 
 # - Returns:
 #   * IPv4 Netmask in extended (y.y.y.y) format.
+#
+# Example:
+#   netmask = ip.netmask_ext()
 #
     def netmask_ext()    
         if (@version == 4)
             netmask = IPAdmin.unpack_ipv4_addr(@netmask)
         else
             raise "IPv6 does not support extended netmask notation. " +
-                  "Use bits() method instead."
+                  "Use netmask() method instead."
         end
         
         return(netmask)
@@ -2375,6 +2835,9 @@ class IPAddr
 # 
 # - Returns:
 #   * byte-packed Hostmask.
+#
+# Example:
+#   packed = ip.packed_hostmask()
 #
     def packed_hostmask()    
         return(@hostmask)
@@ -2397,6 +2860,9 @@ class IPAddr
 # 
 # - Returns:
 #   * byte-packed IP address.
+#
+# Example:
+#   packed = ip.packed_ip()
 #
     def packed_ip()
         return(@ip)
@@ -2419,6 +2885,9 @@ class IPAddr
 # 
 # - Returns:
 #   * byte-packed Netask.
+#
+# Example:
+#   packed = ip.packed_netmask()
 #
     def packed_netmask()
         return(@netmask)