ipadmin 0.3.0 → 0.4.0

data/lib/eui.rb

@@ -1,14 +1,10 @@
-=begin rdoc
- Copyright (c) 2006 Dustin Spinhirne -  
- Licensed under the same terms as Ruby, No Warranty is provided.
-=end
-
-
 module IPAdmin
+
+# Generic EUI address. By default, it will act as an EUI48 address. 
+# As a general rule, it is probably better to use the EUI48 and EUI64 classes.
 class EUI
 
 # instance variables
-# @type - eui-48 or eui-64
 # @oui - Organizationally Unique Identifier 
 # @ei - Extention Identifier
 
@@ -17,82 +13,65 @@ class EUI
 #==============================================================================#
 
 # - Arguments:
-#   * Hash with the following fields:
-#       - :EUI -- Extended Unique Identifier - String (optional)
+#   * EUI as a string, or a Hash with the following fields:
+#       - :EUI -- Extended Unique Identifier - String
 #       - :PackedEUI -- Integer representing an Extended Unique Identifier (optional)
-#       - :Length --  bit length of PackedEUI - Integer (optional)
 #
 # - Note:
-#   * At a minimum, EUI or PackedEUI must be provided.
 #   * PackedEUI takes precedence over EUI.
-#   * Length is only needed when using PackedEUI
 #
-# Example:
-#   addr = IPAdmin::EUI.new(:EUI => 'aa-bb-cc-dd-ee-ff')
-#   addr = IPAdmin::EUI.new(:EUI => 'aa:bb:cc:dd:ee:ff')
-#   addr = IPAdmin::EUI.new(:EUI => 'aabb.ccdd.eeff')
-#   addr = IPAdmin::EUI.new(:EUI => 'aa-bb-cc-dd-ee-ff-00-01')
+# Examples:
+#   addr = IPAdmin::EUI48.new('aa-bb-cc-dd-ee-ff')
+#   addr = IPAdmin::EUI48.new('aa:bb:cc:dd:ee:ff')
+#   addr = IPAdmin::EUI48.new('aabb.ccdd.eeff')
+#   addr = IPAdmin::EUI64.new('aa-bb-cc-dd-ee-ff-00-01')
 #
     def initialize(options)
-        if (!options.kind_of? Hash)
-            raise ArgumentError, "Expected Hash, but #{options.class} provided."
-        end
-        
-        if (options.has_key?(:PackedEUI))
-            packed_eui = options[:PackedEUI]
-            
-            if (options.has_key?(:Length) && options[:Length].kind_of?(Integer))
-                @type = options[:Length]
-                @type = 48 if (@type != 48 && @type != 64)
+        if (options.kind_of? String)
+            eui = options
+        elsif (options.kind_of? Hash)
+            if (options.has_key?(:PackedEUI))
+                packed_eui = options[:PackedEUI]
+            elsif(options.has_key?(:EUI))
+                eui = options[:EUI]
             else
-                @type = 48
+                raise ArgumentError, "Missing argument: [EUI|PackedEUI]."
             end
-        
+        else
+            raise ArgumentError, "Expected Hash or String, but #{options.class} provided."
+        end
+
+        if (packed_eui)
             if (packed_eui.kind_of?(Integer))
-                if (@type == 48)
-                    @oui = packed_eui >> 24
-                    @ei = packed_eui & 0xffffff
-                else
+                if (self.kind_of?(IPAdmin::EUI64))
                     @oui = packed_eui >> 40
                     @ei = packed_eui & 0xffffffffff
+                else
+                    @oui = packed_eui >> 24
+                    @ei = packed_eui & 0xffffff
                 end
             else
                 raise ArgumentError, "Expected Integer, but #{eui.class} " +
                                      "provided for argument :PackedEUI."
             end
-            
-        elsif(options.has_key?(:EUI))
-            eui = options[:EUI]
-            
+
+        elsif(eui)
             if (eui.kind_of?(String))
                 # validate
                 IPAdmin.validate_eui(:EUI => eui)
-            
+
                 # remove formatting characters
-                eui.gsub!(/[\.\:\-]/, '')           
-            
-                # check if eui-48 or eui-64
-                if (eui.length == 12)
-                    @type = 48
-                elsif (eui.length == 16)
-                    @type = 64
-                else
-                    raise "#{eui} is invalid (address is neither EUI-48 nor EUI-64)."
-                end
-            
+                eui.gsub!(/[\.\:\-]/, '')
+
                 # split into oui & ei, pack, and store
                 @oui = eui.slice!(0..5).to_i(16)
                 @ei = eui.to_i(16)
-        
+
             else
                 raise ArgumentError, "Expected String, but #{eui.class} " +
                                      "provided for argument :EUI."
             end
-            
-        else
-            raise ArgumentError, "Missing argument: [EUI|PackedEUI]."
         end
-  
     end
 
 #======================================#
@@ -113,30 +92,33 @@ class EUI
 # - Returns:
 #   * String
 #
-# Example:
+# - Notes:
+#   * The default address format is xxxx.xxxx.xxxx
+#
+# Examples:
 #   puts addr.address(:Delimiter => '.')   --> 'aabb.ccdd.eeff'
 #
     def address(options=nil)
         delimiter = '-'
-        
+
         octets = []
         octets.concat(unpack_oui)
         octets.concat(unpack_ei)
-        
+
         if (options)
             if (!options.kind_of? Hash)
                 raise ArgumentError, "Expected Hash, but #{options.class} provided."
             end
-        
+
             if (options.has_key?(:Delimiter))
                 delimiter = options[:Delimiter]
                 delimiter = '-' if (delimiter != '-' && delimiter != ':' && delimiter != '.' )
             end
         end
-        
+
         if (delimiter == '-' || delimiter == ':')
                     address = octets.join(delimiter)
-        elsif (delimiter == '.')                
+        elsif (delimiter == '.')
                 toggle = 0
                 octets.each do |x|
                     if (!address)
@@ -152,8 +134,8 @@ class EUI
                 end 
 
         end
-        
-        return(address)       
+
+        return(address)
     end
 
 #======================================#
@@ -174,18 +156,21 @@ class EUI
 # - Returns:
 #   * String
 #
-# Example:
-#   puts addr.ei(:Delimiter => '-')   --> 'aa-bb-cc'
+# - Notes:
+#   * The default address format is xx-xx-xx
+#
+# Examples:
+#   puts addr.ei(:Delimiter => '-')
 #
     def ei(options=nil)
         octets = unpack_ei()
         delimiter = '-'
-        
+
         if (options)
             if (!options.kind_of? Hash)
                 raise ArgumentError, "Expected Hash, but #{options.class} provided."
             end
-        
+
             if (options.has_key?(:Delimiter))
                 if (options[:Delimiter] == ':')
                     delimiter = options[:Delimiter]
@@ -193,8 +178,8 @@ class EUI
             end
         end
         ei = octets.join(delimiter)
-        
-        return(ei)       
+
+        return(ei)
     end
 
 #======================================#
@@ -214,36 +199,36 @@ class EUI
 #       - :Objectify -- if true, return CIDR objects (optional)
 #
 # - Returns:
-#   * String
+#   * CIDR address String or an IPAdmin::CIDR object
 #
-# Example:
-#   puts addr.link_local() --> fe80:0000:0000:0000:aabb:ccff:fedd:eeff
+# Examples:
+#   puts addr.link_local()
 #
-    def link_local(options=nil)        
+    def link_local(options=nil)
         objectify = false
         short = false
-                
+
         if (options)
             if (!options.kind_of? Hash)
                 raise ArgumentError, "Expected Hash, but #{options.class} provided."
             end
-        
+
             if (options.has_key?(:Objectify) && options[:Objectify] == true)
                 objectify = true
             end
-            
+
             if (options.has_key?(:Short) && options[:Short] == true)
                 short = true
             end
         end
-        
-        if (@type == 48)
-            link_local = @ei | 0xfffe000000 | (@oui << 40)
-        else
+
+        if (self.kind_of?(IPAdmin::EUI64))
             link_local = @ei | (@oui << 40)
+        else
+            link_local = @ei | 0xfffe000000 | (@oui << 40)
         end
         link_local = link_local | (0xfe80 << 112)
-        
+
         if (!objectify)
             link_local = IPAdmin.unpack_ip_addr(:Integer => link_local, :Version => 6)
             link_local = IPAdmin.shorten(link_local) if (short)
@@ -251,7 +236,7 @@ class EUI
             link_local = IPAdmin::CIDR.new(:PackedIP => link_local,  
                                            :Version => 6)
         end
-        
+
         return(link_local)
     end
 
@@ -273,18 +258,21 @@ class EUI
 # - Returns:
 #   * String
 #
-# Example:
-#   puts addr.oui(:Delimiter => '-')   --> 'dd-ee-ff'
+# - Notes:
+#   * The default address format is xx-xx-xx
+#
+# Examples:
+#   puts addr.oui(:Delimiter => '-')
 #
     def oui(options=nil)
         octets = unpack_oui()
         delimiter = '-'
-        
+
         if (options)
             if (!options.kind_of? Hash)
                 raise ArgumentError, "Expected Hash, but #{options.class} provided."
             end
-        
+
             if (options.has_key?(:Delimiter))
                 if (options[:Delimiter] == ':')
                     delimiter = options[:Delimiter]
@@ -292,36 +280,8 @@ class EUI
             end
         end
         oui = octets.join(delimiter)
-        
-        return(oui)                
-    end
-
-#======================================#
-#
-#======================================#
-
-
-#==============================================================================#
-# type()
-#==============================================================================#
 
-# Provide address type (EUI-48 or EUI-64).
-#
-# - Arguments:
-#   * none
-#
-# - Returns:
-#   * String
-#
-# Example:
-#   puts addr.type   --> EUI-48
-#
-    def type()
-        if (@type == 48)
-            return('EUI-48')
-        else
-            return('EUI-64')
-        end        
+        return(oui)
     end
 
 #======================================#
@@ -340,7 +300,14 @@ private
     def unpack_ei()
         hex = @ei
         octets = []
-        loop_count = (@type - 24)/8
+
+        if (self.kind_of?(IPAdmin::EUI64))
+            length = 64
+        else
+            length = 48
+        end
+
+        loop_count = (length - 24)/8
         loop_count.times do
            octet = (hex & 0xff).to_s(16)
            octet = '0' << octet if (octet.length != 2)
@@ -377,5 +344,15 @@ private
 
 end
 
+# EUI-48 Address - Inherits all methods from IPAdmin::EUI. 
+# Addresses of this type have a 24-bit OUI and a 24-bit EI.
+class EUI48 < EUI
+end
+
+# EUI-64 Address - Inherits all methods from IPAdmin::EUI. 
+# Addresses of this type have a 24-bit OUI and a 40-bit EI.
+class EUI64 < EUI
+end
+
 end # module IPAdmin
 __END__