Net.Mac

This module provides the Mac data type and functions for working with it.

Convert

mac :: Word64 -> Mac

Construct a Mac address from a Word64. Only the lower 48 bits are used.

fromOctets :: Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Word8 -> Mac

Create a Mac address from six octets.

toOctets :: Mac -> (Word8, Word8, Word8, Word8, Word8, Word8)

Convert a Mac address to the six octets that make it up. This function and fromOctets are inverses:

m == (let (a,b,c,d,e,f) = Mac.toOctets m in Mac.fromOctets a b c d e f)

Textual Conversion

Text

encode :: Mac -> Text

Encode a Mac address using the default MacCodec defCodec.

>>> T.putStrLn (Mac.encode (Mac 0xA47F247AB423))
a4:7f:24:7a:b4:23

encodeWith :: MacCodec -> Mac -> Text

Encode a Mac address using the given MacCodec.

>>> m = Mac 0xA47F247AB423
>>> T.putStrLn $ Mac.encodeWith Mac.defCodec m
a4:7f:24:7a:b4:23

>>> T.putStrLn $ Mac.encodeWith (Mac.MacCodec (Mac.MacGroupingTriples '-') True) m
A47-F24-7AB-423

decode :: Text -> Maybe Mac

Decode a Mac address using the default MacCodec defCodec.

>>> Mac.decode (Text.pack "a4:7f:24:7a:b4:23")
Just (mac 0xa47f247ab423)

>>> Mac.decode (Text.pack "a47-f24-7ab-423")
Nothing

decodeWith :: MacCodec -> Text -> Maybe Mac

Decode a Mac address from Text using the given MacCodec.

>>> Mac.decodeWith Mac.defCodec (Text.pack "a4:7f:24:7a:b4:23")
Just (mac 0xa47f247ab423)

>>> Mac.decodeWith (Mac.MacCodec Mac.MacGroupingNoSeparator False) (Text.pack "a47f247ab423")
Just (mac 0xa47f247ab423)

builder :: Mac -> Builder

Encode a Mac address as a Builder.

parser :: Parser Mac

Parse a Mac address using a Parser.

>>> AT.parseOnly Mac.parser (Text.pack "a4:7f:24:7a:b4:23")
Right (mac 0xa47f247ab423)

>>> AT.parseOnly Mac.parser (Text.pack "a47-f24-7ab-423")
Left "':': Failed reading: satisfy"

parserWith :: MacCodec -> Parser Mac

Parser a Mac address using the given MacCodec.

>>> p1 = Mac.parserWith Mac.defCodec
>>> AT.parseOnly p1 (Text.pack "a4:7f:24:7a:b4:23")
Right (mac 0xa47f247ab423)

>>> p2 = Mac.parserWith (Mac.MacCodec Mac.MacGroupingNoSeparator False)
>>> AT.parseOnly p2 (Text.pack "a47f247ab423")
Right (mac 0xa47f247ab423)

ShortText

encodeShort :: Mac -> ShortText

Encode a Mac address as colon-separated hexadecimal octets, preferring lowercase for alphabetical characters.

UTF-8 ByteString

encodeUtf8 :: Mac -> ByteString

Encode a Mac address using the default MacCodec defCodec.

>>> BC.putStrLn (Mac.encodeUtf8 (Mac.mac 0x64255A0F2C47))
64:25:5a:0f:2c:47

encodeWithUtf8 :: MacCodec -> Mac -> ByteString

Encode a Mac address as a ByteString using the given MacCodec.

>>> m = Mac 0xA47F247AB423
>>> BC.putStrLn $ Mac.encodeWithUtf8 Mac.defCodec m
a4:7f:24:7a:b4:23

>>> BC.putStrLn $ Mac.encodeWithUtf8 (Mac.MacCodec (Mac.MacGroupingTriples '-') True) m
A47-F24-7AB-423

decodeUtf8 :: ByteString -> Maybe Mac

Lenient decoding of MAC address that accepts lowercase, uppercase, and any kind of separator.

>>> Mac.decodeUtf8 "A2:DE:AD:BE:EF:67"
Just (mac 0xa2deadbeef67)
>>> Mac.decodeUtf8 "13-a2-fe-a4-17-96"
Just (mac 0x13a2fea41796)
>>> Mac.decodeUtf8 "0A42.47BA.67C2"
Just (mac 0x0a4247ba67c2)

decodeWithUtf8 :: MacCodec -> ByteString -> Maybe Mac

Decode a ByteString as a Mac address using the given MacCodec.

>>> Mac.decodeWithUtf8 Mac.defCodec (BC.pack "64:25:5a:0f:2c:47")
Just (mac 0x64255a0f2c47)

>>> Mac.decodeWithUtf8 (Mac.MacCodec Mac.MacGroupingNoSeparator False) (BC.pack "64255a0f2c47")
Just (mac 0x64255a0f2c47)

builderUtf8 :: Mac -> Builder

Make a bytestring builder from a Mac address using a colon as the separator.

parserUtf8 :: Parser Mac

Lenient parser for a Mac address using any character as the separator and accepting any digit grouping (i.e. FA:43:B2:C0:0F:99 or A065.647B.87FA).

parserWithUtf8 :: MacCodec -> Parser Mac

Parser for a Mac address using the provided settings.

ByteString

decodeBytes :: ByteString -> Maybe Mac

Deprecated: Prefer decodeOctets

This function is deprecated. It will be renamed in a future release since the name is misleading.

decodeOctets :: ByteString -> Maybe Mac

Decode a Mac address from a ByteString. Each byte is interpreted as an octet of the Mac address. Consequently, ByteStrings of length 6 successfully decode, and all other ByteStrings fail to decode.

>>> Mac.decodeOctets (B.pack [0x6B,0x47,0x18,0x90,0x55,0xC3])
Just (mac 0x6b47189055c3)
>>> Mac.decodeOctets (B.replicate 6 0x3A)
Just (mac 0x3a3a3a3a3a3a)
>>> Mac.decodeOctets (B.replicate 7 0x3A)
Nothing

Note that the octets are interpreted in a big-endian fashion.

UTF-8 Bytes

boundedBuilderUtf8 :: Mac -> Builder 17

Encode a Mac address as colon-separated hexadecimal octets, preferring lowercase for alphabetical characters.

>>> BBB.run Nat.constant $ Mac.boundedBuilderUtf8 $ Mac.mac 0xDEADBEEF1609
[0x64, 0x65, 0x3a, 0x61, 0x64, 0x3a, 0x62, 0x65, 0x3a, 0x65, 0x66, 0x3a, 0x31, 0x36, 0x3a, 0x30, 0x39]

decodeUtf8Bytes :: Bytes -> Maybe Mac

Lenient decoding of MAC address. This is case insensitive and allows either : or - as the separator. It also allows leading zeroes to be missing.

>>> Mac.decodeUtf8Bytes (Ascii.fromString "A2:DE:AD:BE:EF:67")
Just (mac 0xa2deadbeef67)
>>> Mac.decodeUtf8Bytes (Ascii.fromString "13-a2-FE-A4-17-96")
Just (mac 0x13a2fea41796)

parserUtf8Bytes :: e -> Parser e s Mac

Leniently parse UTF-8-encoded Bytes as a Mac address. This is case insensitive and allows either : or - as the separator. It also allows leading zeroes to be missing.

>>> Parser.parseBytes (Mac.parserUtf8Bytes ()) (Ascii.fromString "de:ad:BE:EF:1:23")
Success (Slice {offset = 16, length = 0, value = mac 0xdeadbeef0123})

Printing

print :: Mac -> IO ()

Print a Mac address using the textual encoding.

Default Codec

defCodec :: MacCodec

The default MacCodec: all characters are lowercase hex, separated by colons into pairs.

>>> T.putStrLn $ Mac.encodeWith Mac.defCodec (Mac 0xa47f247ab423)
a4:7f:24:7a:b4:23

Types

newtype Mac

A 48-bit MAC address. Do not use the data constructor for this type. It is not considered part of the stable API, and it allows you to construct invalid MAC addresses.

Constructors

Mac Word64

Instances

FromJSON Mac

Defined in Net.Mac

Methods

parseJSON :: Value -> Parser Mac

parseJSONList :: Value -> Parser [Mac]

omittedField :: Maybe Mac

FromJSONKey Mac

Defined in Net.Mac

Methods

fromJSONKey :: FromJSONKeyFunction Mac

fromJSONKeyList :: FromJSONKeyFunction [Mac]

ToJSON Mac

Defined in Net.Mac

Methods

toJSON :: Mac -> Value

toEncoding :: Mac -> Encoding

toJSONList :: [Mac] -> Value

toEncodingList :: [Mac] -> Encoding

omitField :: Mac -> Bool

ToJSONKey Mac

Defined in Net.Mac

Methods

toJSONKey :: ToJSONKeyFunction Mac

toJSONKeyList :: ToJSONKeyFunction [Mac]

Data Mac

Defined in Net.Mac

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Mac -> c Mac

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Mac

toConstr :: Mac -> Constr

dataTypeOf :: Mac -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Mac)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Mac)

gmapT :: (forall b. Data b => b -> b) -> Mac -> Mac

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Mac -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Mac -> r

gmapQ :: (forall d. Data d => d -> u) -> Mac -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Mac -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Mac -> m Mac

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Mac -> m Mac

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Mac -> m Mac

Bounded Mac

Defined in Net.Mac

Methods

minBound :: Mac

maxBound :: Mac

Enum Mac

Defined in Net.Mac

Methods

succ :: Mac -> Mac

pred :: Mac -> Mac

toEnum :: Int -> Mac

fromEnum :: Mac -> Int

enumFrom :: Mac -> [Mac]

enumFromThen :: Mac -> Mac -> [Mac]

enumFromTo :: Mac -> Mac -> [Mac]

enumFromThenTo :: Mac -> Mac -> Mac -> [Mac]

Generic Mac

Defined in Net.Mac

Associated Types

type Rep Mac :: Type -> Type

Methods

from :: Mac -> Rep Mac x

to :: Rep Mac x -> Mac

Ix Mac

Defined in Net.Mac

Methods

range :: (Mac, Mac) -> [Mac]

index :: (Mac, Mac) -> Mac -> Int

unsafeIndex :: (Mac, Mac) -> Mac -> Int

inRange :: (Mac, Mac) -> Mac -> Bool

rangeSize :: (Mac, Mac) -> Int

unsafeRangeSize :: (Mac, Mac) -> Int

Read Mac

Defined in Net.Mac

Methods

readsPrec :: Int -> ReadS Mac

readList :: ReadS [Mac]

readPrec :: ReadPrec Mac

readListPrec :: ReadPrec [Mac]

Show Mac

Defined in Net.Mac

Methods

showsPrec :: Int -> Mac -> ShowS

show :: Mac -> String

showList :: [Mac] -> ShowS

NFData Mac

Defined in Net.Mac

Methods

rnf :: Mac -> ()

Eq Mac

Defined in Net.Mac

Methods

(==) :: Mac -> Mac -> Bool

(/=) :: Mac -> Mac -> Bool

Ord Mac

Defined in Net.Mac

Methods

compare :: Mac -> Mac -> Ordering

(<) :: Mac -> Mac -> Bool

(<=) :: Mac -> Mac -> Bool

(>) :: Mac -> Mac -> Bool

(>=) :: Mac -> Mac -> Bool

max :: Mac -> Mac -> Mac

min :: Mac -> Mac -> Mac

Hashable Mac

Defined in Net.Mac

Methods

hashWithSalt :: Int -> Mac -> Int

hash :: Mac -> Int

Prim Mac

This only preserves the lower 6 bytes of the 8-byte word that backs a mac address. It runs slower than it would if it used a full 8-byte word, but it consumes less space. When storing millions of mac addresses, this is a good trade to make. When storing a small number of mac address, it might be preferable to make a primitive array of Word64 instead and use the mac address data constructor to coerce between the two.

Defined in Net.Mac

Methods

sizeOfType# :: Proxy Mac -> Int#

sizeOf# :: Mac -> Int#

alignmentOfType# :: Proxy Mac -> Int#

alignment# :: Mac -> Int#

indexByteArray# :: ByteArray# -> Int# -> Mac

readByteArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Mac #)

writeByteArray# :: MutableByteArray# s -> Int# -> Mac -> State# s -> State# s

setByteArray# :: MutableByteArray# s -> Int# -> Int# -> Mac -> State# s -> State# s

indexOffAddr# :: Addr# -> Int# -> Mac

readOffAddr# :: Addr# -> Int# -> State# s -> (# State# s, Mac #)

writeOffAddr# :: Addr# -> Int# -> Mac -> State# s -> State# s

setOffAddr# :: Addr# -> Int# -> Int# -> Mac -> State# s -> State# s

type Rep Mac

Defined in Net.Mac

type Rep Mac = D1 ('MetaData "Mac" "Net.Mac" "ip-1.7.8-LlpdK7rg6it5d78V5ukAkK" 'True) (C1 ('MetaCons "Mac" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word64)))

data MacCodec

A MacCodec allows users to control the encoding/decoding of their Mac addresses.

Constructors

MacCodec

Fields

• macCodecGrouping :: !MacGrouping
• macCodecUpperCase :: !Bool

Instances

Data MacCodec

Defined in Net.Mac

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> MacCodec -> c MacCodec

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c MacCodec

toConstr :: MacCodec -> Constr

dataTypeOf :: MacCodec -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c MacCodec)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c MacCodec)

gmapT :: (forall b. Data b => b -> b) -> MacCodec -> MacCodec

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> MacCodec -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> MacCodec -> r

gmapQ :: (forall d. Data d => d -> u) -> MacCodec -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> MacCodec -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> MacCodec -> m MacCodec

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> MacCodec -> m MacCodec

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> MacCodec -> m MacCodec

Generic MacCodec

Defined in Net.Mac

Associated Types

type Rep MacCodec :: Type -> Type

Methods

from :: MacCodec -> Rep MacCodec x

to :: Rep MacCodec x -> MacCodec

Read MacCodec

Defined in Net.Mac

Methods

readsPrec :: Int -> ReadS MacCodec

readList :: ReadS [MacCodec]

readPrec :: ReadPrec MacCodec

readListPrec :: ReadPrec [MacCodec]

Show MacCodec

Defined in Net.Mac

Methods

showsPrec :: Int -> MacCodec -> ShowS

show :: MacCodec -> String

showList :: [MacCodec] -> ShowS

Eq MacCodec

Defined in Net.Mac

Methods

(==) :: MacCodec -> MacCodec -> Bool

(/=) :: MacCodec -> MacCodec -> Bool

Ord MacCodec

Defined in Net.Mac

Methods

compare :: MacCodec -> MacCodec -> Ordering

(<) :: MacCodec -> MacCodec -> Bool

(<=) :: MacCodec -> MacCodec -> Bool

(>) :: MacCodec -> MacCodec -> Bool

(>=) :: MacCodec -> MacCodec -> Bool

max :: MacCodec -> MacCodec -> MacCodec

min :: MacCodec -> MacCodec -> MacCodec

type Rep MacCodec

Defined in Net.Mac

type Rep MacCodec = D1 ('MetaData "MacCodec" "Net.Mac" "ip-1.7.8-LlpdK7rg6it5d78V5ukAkK" 'False) (C1 ('MetaCons "MacCodec" 'PrefixI 'True) (S1 ('MetaSel ('Just "macCodecGrouping") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 MacGrouping) :*: S1 ('MetaSel ('Just "macCodecUpperCase") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool)))

data MacGrouping

The format expected by the mac address parser. The Word8 taken by some of these constructors is the ascii value of the character to be used as the separator. This is typically a colon, a hyphen, or a space character. All decoding functions are case insensitive.

Constructors

MacGroupingPairs !Char

Two-character groups, FA:2B:40:09:8C:11

MacGroupingTriples !Char

Three-character groups, 24B-F0A-025-829

MacGroupingQuadruples !Char

Four-character groups, A220.0745.CAC7

MacGroupingNoSeparator

No separator, 24AF4B5B0780

Instances

Data MacGrouping

Defined in Net.Mac

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> MacGrouping -> c MacGrouping

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c MacGrouping

toConstr :: MacGrouping -> Constr

dataTypeOf :: MacGrouping -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c MacGrouping)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c MacGrouping)

gmapT :: (forall b. Data b => b -> b) -> MacGrouping -> MacGrouping

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> MacGrouping -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> MacGrouping -> r

gmapQ :: (forall d. Data d => d -> u) -> MacGrouping -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> MacGrouping -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> MacGrouping -> m MacGrouping

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> MacGrouping -> m MacGrouping

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> MacGrouping -> m MacGrouping

Generic MacGrouping

Defined in Net.Mac

Associated Types

type Rep MacGrouping :: Type -> Type

Methods

from :: MacGrouping -> Rep MacGrouping x

to :: Rep MacGrouping x -> MacGrouping

Read MacGrouping

Defined in Net.Mac

Methods

readsPrec :: Int -> ReadS MacGrouping

readList :: ReadS [MacGrouping]

readPrec :: ReadPrec MacGrouping

readListPrec :: ReadPrec [MacGrouping]

Show MacGrouping

Defined in Net.Mac

Methods

showsPrec :: Int -> MacGrouping -> ShowS

show :: MacGrouping -> String

showList :: [MacGrouping] -> ShowS

Eq MacGrouping

Defined in Net.Mac

Methods

(==) :: MacGrouping -> MacGrouping -> Bool

(/=) :: MacGrouping -> MacGrouping -> Bool

Ord MacGrouping

Defined in Net.Mac

Methods

compare :: MacGrouping -> MacGrouping -> Ordering

(<) :: MacGrouping -> MacGrouping -> Bool

(<=) :: MacGrouping -> MacGrouping -> Bool

(>) :: MacGrouping -> MacGrouping -> Bool

(>=) :: MacGrouping -> MacGrouping -> Bool

max :: MacGrouping -> MacGrouping -> MacGrouping

min :: MacGrouping -> MacGrouping -> MacGrouping

type Rep MacGrouping

Defined in Net.Mac

type Rep MacGrouping = D1 ('MetaData "MacGrouping" "Net.Mac" "ip-1.7.8-LlpdK7rg6it5d78V5ukAkK" 'False) ((C1 ('MetaCons "MacGroupingPairs" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Char)) :+: C1 ('MetaCons "MacGroupingTriples" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Char))) :+: (C1 ('MetaCons "MacGroupingQuadruples" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Char)) :+: C1 ('MetaCons "MacGroupingNoSeparator" 'PrefixI 'False) (U1 :: Type -> Type)))