New function canonicalize_macaddress().

We here add a function for canonicalizing Ethernet MAC addresses into
a standard format (six groups of two hexadecimal digits, separated by
colons).  The input MAC address can be on any of several formats that
are commonly used by network software and equipment (e.g. Cisco and
HPE ProCurve).

lib/puppet/parser/functions/canonicalize_macaddress.rb

+# Copyright (C) 2020 Thomas Bellman.
+# Licensed under the GNU LGPL v3+; see the README file for more information.
+
+
+module Puppet::Parser::Functions
+    newfunction(:canonicalize_macaddress, :type => :rvalue, :doc => '
+        Canonicalize Ethernet MAC addresses.
+
+        The single argument is a string, or a (possibly nested) list of
+        strings, each string being an Ethernet MAC address on one of a few
+        commonly used formats.  The function returns these addresses
+        canonicalized to a standard format.  If the argument was a string,
+        the return value will also be a string; if it was a (nested) list,
+        a flat list will instead be returned.
+
+        The input format can be one of:
+          - Six groups of one or two hexadecimal digits each
+            This is the standard (IEEE) format
+          - Two groups of exactly six hexadecimal digits each
+            This format is used by e.g. HPE ProCurve switches
+          - Three groups of exactly four hexadecimal digits each
+            This format is used by e.g. Cisco equipment
+        In the first case, the groups can be separated by a colon (":"), a
+        dash ("-"), or a period ("."); in the two latter cases, only dashes
+        and periods are acceptable.  All separators must be the same.
+
+        The addresses will be canonicalized to six groups of exactly two
+        digits each, separated by colon (":").
+
+        Examples of valid inputs:
+            0:4:6:a8:ee:ff
+            0-4-6-a8-EE-ff
+            00.4.6.a8.EE.ff
+            0004-06a8-eeFF
+            0004.06a8.eeFF
+            000406-a8EEFf
+            000406.a8eEfF
+        All these represent the same MAC address, and will be canonicalized
+        to "00:04:06:a8:ee:ff".
+
+        Examples of illegal inputs:
+            0:4:6-a8:ee:ff              # Different separators
+            00406-a8eeff                # First group is not six digits
+    ') \
+    do |args|
+	# Ideas for future enhancments:
+	#  - Flag parameter to select style of canonicalization
+
+        if args.length != 1
+            raise(Puppet::ParseError,
+                  "parse_host_mac_ip_list(): Wrong number of arguments")
+        end
+        canon_macs = []
+        [args[0]].flatten.each do |mac|
+            groups = mac.split(/[-.:]/)
+
+            if mac =~ /^(([0-9a-f]{1,2})[-.:]){5}([0-9a-f]{1,2})$/i
+                # Six groups of one or two digits each
+                canon = groups.collect {|octet|
+                    "%02x" % [octet.to_i(16)]
+                }.join(":")
+            elsif mac =~ /^([0-9a-f]{4})([-.])([0-9a-f]{4})\2([0-9a-f]{4})$/i
+                # Three groups of four digits each; "-" or "." as separator
+                canon = groups.join("").gsub(/(..)/, '\1:').chomp(":")
+            elsif mac =~ /^([0-9a-f]{6})([-.])([0-9a-f]{6})$/i
+                # Two groups of six digits each; "-" or "." as separator
+                canon = groups.join("").gsub(/(..)/, '\1:').chomp(":")
+            else
+                raise(Puppet::ParseError, "Badly formed MAC address `#{mac}'")
+            end
+            canon_macs << canon.downcase
+        end
+        # Return a string if the argument was a string, else return a flat list
+        if args[0].is_a?(String)
+            return canon_macs[0]
+        else
+            return canon_macs
+        end
+    end
+end