NAME
    Net::MAC - Perl extension for representing and manipulating MAC
    addresses

VERSION
    version 1.103621

SYNOPSIS
      use Net::MAC;
      my $mac = Net::MAC->new('mac' => '08:20:00:AB:CD:EF'); 

      # Example: convert to a different MAC address format (dotted-decimal)
      my $dec_mac = $mac->convert(
          'base' => 10,         # convert from base 16 to base 10
          'bit_group' => 8,     # octet grouping
          'delimiter' => '.'    # dot-delimited
      ); 

      print "$dec_mac\n"; # Should print 8.32.0.171.205.239

      # Example: find out whether a MAC is base 16 or base 10
      my $base = $mac->get_base();
      if ($base == 16) { 
          print "$mac is in hexadecimal format\n"; 
      } 
      elsif ($base == 10) { 
          print "$mac is in decimal format\n"; 
      }
      else { die "This MAC is neither base 10 nor base 16"; }

DESCRIPTION
    This is a module that allows you to

      - store a MAC address in a Perl object
      - find out information about a stored MAC address
      - convert a MAC address into a specified format
      - easily compare two MAC addresses for string or numeric equality

    There are quite a few different ways that MAC addresses may be
    represented in textual form. The most common is arguably colon-delimited
    octets in hexadecimal form. When working with Cisco devices, however,
    you are more likely to encounter addresses that are dot-delimited 16-bit
    groups in hexadecimal form. In the Windows world, addresses are usually
    dash-delimited octets in hexadecimal form. MAC addresses in a Sun ethers
    file are usually non-zero-padded, colon-delimited hexadecimal octets.
    And sometimes, you come across dot-delimited octets in decimal form
    (certain Cisco SNMP MIBS actually use this). Hence the need for a common
    way to represent and manipulate MAC addresses in Perl.

    There is a surprising amount of complexity involved in converting MAC
    addresses between types. This module does not attempt to understand all
    possible ways of representing a MAC address in a string, though most of
    the common ways of representing MAC addresses are supported.

METHODS
  new() method (constructor)
    The new() method creates a new Net::MAC object. Possible arguments are

      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
   set_format_for()
    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
   get_mac() method
    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
    Convert an already-defined Net::MAC object into a different MAC address
    format. With this function you can change the delimiter, the bit
    grouping, or the numeric base.

      # 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
    The most common formats have shortcut conversion methods that can be
    used instead of the convert() method with its many options.

   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
    The stringification operator "" has been overloaded to allow for the
    meaningful use of the instance variable in a string.

      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
    The Perl operators 'eq' and 'ne' (string comparison) and '==' '!='
    (numeric comparison) have been overloaded to allow simple, meaningful
    comparisons of two MAC addresses.

    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"; }

BUGS
  Malformed MAC addresses
    Net::MAC can't handle MAC addresses where whole leading zero octets are
    omitted. Example:

      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
    Net::MAC doesn't reliably preserve case in a MAC address. I might add a
    flag to the new() and convert() methods to do this. I might not.

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

SEE ALSO
    Net::MacMap Net::MAC::Vendor

MAINTAINER
    Oliver Gorwits <oliver@cpan.org>

CONTRIBUTORS
    Oliver Gorwits, Robin Crook, Kevin Brintnall

AUTHOR
    Karl Ward <karlward@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2010 by Karl Ward <karlward@cpan.org>.

    This is free software, licensed under:

      The GNU General Public License, Version 2, June 1991

