/ 
NetObj-MacAddress-1.0
River stage zero No dependents
/ NetObj::MacAddress

NAME

NetObj::MacAddress - represent a MAC address

VERSION

version 1.0

SYNOPSIS

use NetObj::MacAddress;

# construct, supports various typical notations
my $mac1 = NetObj::MacAddress->new('08:00:20:1e:bc:78');
my $mac2 = NetObj::MacAddress->new('08-00-20-1E-BC-78');
my $mac3 = NetObj::MacAddress->new('6c40.087c.5e90');

# comparison, numerically
$mac1 == $mac2;  # true
$mac1 != $mac2;  # false
$mac1 == $mac3;  # false
$mac1 != $mac3;  # true

# comparison, stringwise
$mac1 eq $mac2;  # true
$mac1 ne $mac2;  # false
$mac1 eq $mac3;  # false
$mac1 ne $mac3;  # true

# reject invalid MAC addresses
my $invalid_mac = NetObj::MacAddress->new('foo'); # throws exception

# test for validity
NetObj::MacAddress::is_valid('08:00:20:1e:bc:78'); # true
NetObj::MacAddress::is_valid('foo');               # false

# allow raw binary MAC addresses (any combination of 6 bytes)
my $mac4 = NetObj::MacAddress->new('l@,foo');
# represent as hex (base16)
$mac4->to_string(); # '6c402c666f6f'
# or as the raw binary
$mac4->binary(); # 'l@,foo'

DESCRIPTION

NetObj::MacAddress represents MAC addresses. The constructor makes sure that only valid MAC addresses can be instantiated. Two MAC addresses compare equal if they represent the same address independently of the notation used in the constructor.

NetObj::MacAddress is implemented as a Moose style object class (using Moo).

METHODS

is_valid

The class method NetObj::MacAddress::is_valid tests for the validity of a MAC address represented by a string. It does not throw an exception but returns false for an invalid and true for a valid MAC address.

new

The constructor expects exactly one argument either as a raw 6 byte value or a string representation in a typically notation of hex characters. It throws an exception for invalid MAC addresses.

binary

The binary method returns the raw 6 bytes of the MAC address.

to_string

The to_string method returns the MAC address in hex notation (base16). Optionally, if it is given the name of a formatter it will format the string in the corresponding style. The default style is called 'base16'.

my $mac = NetObj::MacAddress->new('0800201ebc78');

$mac->to_string();         # '0800201ebc78'
$mac->to_string('base16'); # '0800201ebc78'

use NetObj::MacAddress::Formatter::Colons;
$mac->to_string('colons'); # '08:00:20:1e:bc:78'

use NetObj::MacAddress::Formatter::Dashes;
$mac->to_string('dashes'); # '08-00-20-1E-BC-78'

use NetObj::MacAddress::Formatter::Dots;
$mac->to_string('dots'); # '0800.201e.bc78'

Some formatters are available by default (see examples above), others can be added if needed by providing a module with a package name beginning with NetObj::MacAddress::Formatter:: similarly to the existing ones.

is_multicast =method is_unicast

The methods is_multicast and is_unicast indicate whether a MAC address is multicast or unicast, respectively.

my $unicast_mac   = NetObj::MacAddress->new('000001abcdef');
my $multicast_mac = NetObj::MacAddress->new('010001abcdef');
$unicast_mac->is_unicast();     # true
$unicast_mac->is_multicast();   # false
$multicast_mac->is_unicast();   # false
$multicast_mac->is_multicast(); # true

is_global =method is_local

The methods is_global and is_local indicate whether a MAC address is globally or locally assigned, respectively.

my $local_mac  = NetObj::MacAddress->new('000001abcdef');
my $global_mac = NetObj::MacAddress->new('020001abcdef');
$local_mac->is_local();   # true
$local_mac->is_global();  # false
$global_mac->is_local();  # false
$global_mac->is_global(); # true

AUTHOR

Elmar S. Heeb <elmar@heebs.ch>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2015 by Elmar S. Heeb.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007