new() method (constructor)

  mac           a string representing a MAC address
  base          a number corresponding to the numeric base of the MAC 
                possible values: 10 16
  delimiter     the delimiter in the MAC address string from above 
                possible values: : - . space
  bit_group     the number of bits between each delimiter 
                possible values: 8 16 48
  zero_padded   whether bit groups have leading zero characters
                (Net::MAC only allows zero-padding for bit groups of 8 bits)
                possible values: 0 1 
  format        the name of a MAC address format specification which takes
                the place of the base,delimiter,bit_group and zero_padded
                options above
  verbose       write informational messages (useful for debugging)
                possible values: 0 1
  die           die() on invalid MAC address (default is to die on invalid MAC) 
                possible values: 0 1 (default is 1)

When the new() method is called with a 'mac' argument and nothing else, the object will attempt to auto-discover metadata like bit grouping, number base, delimiter, etc. If the MAC is in an invalid or unknown format, the object will call the croak() function. If you don't want the object to croak(), you can give the new() method a die argument, such as:

  my $m_obj = Net::MAC->new('mac' => '000adf012345', 'die' => 0);

There are cases where the auto-discovery will not be able to guess the numeric base of a MAC. If this happens, try giving the new() method a hint, like so:

  # Example: this MAC is actually in decimal-dotted notation, not hex
  my $mac = Net::MAC->new('mac' => '10.0.0.12.14.8', 'base' => 10);

This is necessary for cases like the one above, where the class has no way of knowing that an address is decimal instead of hexadecimal.

If you have installed a custom MAC address format into the class (see below) then you can also pass the "format" option as a hint:

  my $mac = Net::MAC->new('mac' => 'ab01~ab01~ab01', 'format' => 'My_Format');

class methods

When discovering MAC address formats, and converting between different formats (using "convert" or "as_*") the module can use predefined common formats or you can install your own for local circumstances.

For example consider a fictional device which uses MAC addresses formatted like "ab01~ab01~ab01", which would otherwise not be understood. You can install a new Format for this address style:

  Net::MAC->set_format_for( 'My_Format_Name' => {
      base => 16,
      bit_group => 16,
      delimiter => '~',
  });

Now when using either the "format" option to "new()", or the "convert()" or "as_*" methods, the module will recognise this new format "My_Format_Name". The Hashref supplied can include any of the standard options for formats as listed elsewhere in this documentation.

  my $mac = Net::MAC->new('mac' => 'ab01~ab01~ab01', 'format' => 'My_Format_Name');

Custom formats sharing the same name as one shipping with the module (such as "Cisco") will override that built-in format.

accessor methods

Returns the MAC address stored in the object.

get_base() method

Returns the numeric base of the MAC address. There are two possible return values:

  16    hexadecimal (common)
  10    decimal (uncommon)

get_delimiter() method

Returns the delimiter, if any, in the specified MAC address. A valid delimiter matches the following regular expression:

  /\:|\-|\.|\s/

In other words, either a colon, a dash, a dot, or a space. If there is no delimiter, this method will return the undefined value (undef). If an invalid delimiter is found (like an asterisk or something), the object will call the croak() function.

get_bit_group() method

Returns the number of bits between the delimiters. A MAC address is a 48 bit address, usually delimited into 8 bit groupings (called octets), i.e.

  08:20:00:AB:CD:EF

Sometimes, MAC addresses are specified with fewer than 5 delimiters, or even no delimiters at all:

  0820.00ab.cdef    # get_bit_group() returns 16
  082000abcdef      # get_bit_group() returns 48, no delimiters at all

get_zero_padded() method

Returns a boolean value indicating whether or not the bit groups are zero-padded. A return value of 0 (false) means that the bit groups are not zero-padded, and a return value of 1 (true) means that they are zero-padded:

  00.80.02.ac.4f.ff     # get_zero_padded() returns 1
  0:80:2:ac:4f:ff       # get zero_padded() returns 0
  0.125.85.122.155.64   # get_zero_padded() returns 0

Net::MAC only allows bit groups of 8 bits to be zero-padded.

convert() method

  # Example: convert to a different MAC address format (dotted-decimal)
  my $new_mac_obj = $existing_mac_obj->convert(
          'base' => 16,         # convert to base 16, if necessary
          'bit_group' => 16,    # 16 bit grouping
          'delimiter' => '.'    # dot-delimited
  );

Note that if any of the above arguments are not provided, they will be set to the following default values:

 base       16
 bit_group  8  (i.e. a delimiter will be used)
 delimiter  :

Conversion to common formats

as_Cisco() method

Cisco routers seem to usually represent MAC addresses in hexadecimal, dot-delimited, 16 bit groups.

  my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF'); 
  my $cisco_mac = $mac->as_Cisco(); 
  print "$cisco_mac"; 
  # should print 0002.03aa.abff

as_IEEE() method

The IEEE 802 2001 specification represents MAC addresses in hexadecimal, colon-delimited, upper case, 8 bit groups.

  my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF'); 
  my $IEEE_mac = Net::MAC->as_IEEE(); 
  print "$IEEE_mac"; 
  # should print 00:02:03:AA:AB:FF

as_Microsoft() method

Microsoft usually represents MAC addresses in hexadecimal, dash delimited, upper case, 8 bit groups.

  my $mac = Net::MAC->new(mac => '00:02:03:AA:AB:FF'); 
  my $microsoft_mac = $mac->as_Microsoft(); 
  print "$microsoft_mac"; 
  # should print 00-02-03-AA-AB-FF

as_Sun() method

Sun represents MAC addresses in hexadecimal, colon-delimited, non-zero-padded, lower case, 8 bit groups.

  my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF'); 
  my $sun_mac = $mac->as_Sun(); 
  print "$sun_mac"; 
  # should print 0:2:3:aa:ab:ff

Stringification

  my $mac = Net::MAC->new(mac => '00:0a:23:4f:ff:ef'); 
  print "object created for MAC address $mac"; 
  # Should print:
  # object created for MAC address 00:0a:23:4f:ff:ef

MAC address comparison

Example (two MAC addresses numerically identical but in different formats):

  my $d = Net::MAC->new(mac => '0.8.1.9.16.16', base => 10); 
  my $h = Net::MAC->new(mac => '00:08:01:0A:10:10', base => 16); 
  if ($d == $h) { print "$d and $h are numerically equal"; } 
  if ($d ne $h) { print " but $d and $h are not the same string"; }

Malformed MAC addresses

  7.122.32.41.5 (should be 0.7.122.32.41.5)

Arguably, that's their problem and not mine, but maybe someday I'll get around to supporting that case as well.

Case is not preserved

Case is however altered when using the as_foo() formatted output methods.