Module talk:IP/doc 20230319

Util

The Util class provides (static) utility methods to work with single IP addresses and subnetworks.

removeDirMarkers

Util.removeDirMarkers(str)

Removes LEFT-TO-RIGHT MARK (U+200E), LEFT-TO-RIGHT EMBEDDING (U+202A), and POP DIRECTIONAL FORMATTING (U+202C) from a given string and returns a new string. For instance, the LEFT-TO-RIGHT MARK (U+200E) is a special character represented by a red dot in the wikitext editor. Template parameters can occasionally involve these special characters, and methods in this module throw an error if a string involving such characters is passed to them. removeDirMarkers prevents this issue. The methods in the Util class, listed below, all call this method internally at the very first step of their procedures.

isIPAddress

Util.isIPAddress(str, allowCidr, cidrOnly)

Returns true if a given string is a valid IP address, or false if not. If a CIDR string should be allowed, pass true to allowCidr, and if a CIDR string should only be allowed, pass true to cidrOnly. (Note that the value of allowCidr is ignored if cidrOnly is true.)

Examples:

Util.isIPAddress('1.2.3.4') -- true
Util.isIPAddress('1.2.3.0/24') -- false
Util.isIPAddress('1.2.3.0/24', true) -- true
Util.isIPAddress('1.2.3.4', nil, true) -- false
Util.isIPAddress('1.2.3.0/24', nil, true) -- true

In more detail, Util.isIPAddress returns 3 values: boolean, string, string/nil.

local isIp, input, corrected = Util.isIPAddress('1.2.3.4') -- true, "1.2.3.4", nil
local isCidr, input, corrected = Util.isIPAddress('1.2.3.0/24') -- false, "1.2.3.0/24", nil
local isCidr, input, corrected = Util.isIPAddress('1.2.3.0/24', true) -- true, "1.2.3.0/24", nil
local isCidr, input, corrected = Util.isIPAddress('1.2.3.4/24', true) -- true, "1.2.3.4/24", "1.2.3.0/24"

v[1] is the result of whether the input string is a valid IP address or CIDR, v[2] is the input string, and v[3] is a corrected CIDR string or nil. In the fourth example above, "1.2.3.0/24" is a CIDR for "1.2.3.0 - 1.2.3.255"; hence "1.2.3.4/24" is an inappropriate subnet and evaluated as a non-CIDR (for this reason Subnet.new('1.2.3.4/24') throws an error). Beware that Util.isIPAddress attempts to correct an inappropriate subnet to an appropriate one and then evaluates whether the input string is a CIDR, if either allowCidr or cidrOnly is true. v[3] is always nil if v[1] is false, and can have a string value only if v[1] is true. It is also important that if v[3] has a value, the input string in itself is not a valid CIDR.

-- Strict CIDR evaluation
local isCidr, _, corrected = Util.isIPAddress('1.2.3.4/24', true) -- true, "1.2.3.4/24", "1.2.3.0/24"
if corrected ~= nil then
    isCidr = false
end

isIPv4Address

Util.isIPv4Address(str, allowCidr, cidrOnly)

Returns true if a given string is a valid IPv4 address, or false if not. If a CIDR string should be allowed, pass true to allowCidr, and if a CIDR string should only be allowed, pass true to cidrOnly. (Note that the value of allowCidr is ignored if cidrOnly is true.) As well as Util.isIPAddress, Util.isIPv4Address returns 3 values.

isIPv6Address

Util.isIPv6Address(str, allowCidr, cidrOnly)

Returns true if a given string is a valid IPv6 address, or false if not. If a CIDR string should be allowed, pass true to allowCidr, and if a CIDR string should only be allowed, pass true to cidrOnly. (Note that the value of allowCidr is ignored if cidrOnly is true.) As well as Util.isIPAddress, Util.isIPv6Address returns 3 values.