Module:IP/doc

Module:IP is a library for working with IP addresses and subnets. It can handle both IPv4 and IPv6. The library exports four classes, IPAddress, Subnet, IPv4Collection, and IPv6Collection.

Loading the library

<syntaxhighlight lang="lua"> local IP = require('Module:IP') local IPAddress = IP.IPAddress local Subnet = IP.Subnet </syntaxhighlight>

IPAddress

The IPAddress class is used to work with single IP addresses. To create a new IPAddress object:

<syntaxhighlight lang="lua"> local ipAddress = IPAddress.new(ipString) </syntaxhighlight>

The ipString variable can be a valid IPv4 or IPv6 address.

Examples:

<syntaxhighlight lang="lua"> local ipv4Address = IPAddress.new('1.2.3.4') local ipv6Address = IPAddress.new('2001:db8::ff00:12:3456') </syntaxhighlight>

If a non-IP string or an invalid IP address is passed to the function, that returns an error. If you want to check whether a given string is an IP address and continue the procedure in the caller module, use pcall.

<syntaxhighlight lang="lua"> local isIp, ip = pcall(IPAddress.new, '1.2.3.4') -- isIp: true, ip: IPAddress object local isIp, ip = pcall(IPAddress.new, 'Example') -- isIp: false, ip: nil local isIp, ip = pcall(IPAddress.new, '1.2.3.256') -- isIp: false, ip: nil </syntaxhighlight>

IPAddress objects can be compared with relational operators:

<syntaxhighlight lang="lua"> -- Equality IPAddress.new('1.2.3.4') == IPAddress.new('1.2.3.4') -- true IPAddress.new('1.2.3.4') == IPAddress.new('1.2.3.5') -- false

-- Less than / greater than IPAddress.new('1.2.3.4') < IPAddress.new('1.2.3.5') -- true IPAddress.new('1.2.3.4') > IPAddress.new('1.2.3.5') -- false IPAddress.new('1.2.3.4') <= IPAddress.new('1.2.3.5') -- true IPAddress.new('1.2.3.4') <= IPAddress.new('1.2.3.4') -- true </syntaxhighlight>

You can use tostring on them (this is equivalent to using getIP):

<syntaxhighlight lang="lua"> tostring(IPAddress.new('1.2.3.4')) -- "1.2.3.4" tostring(IPAddress.new('2001:db8::ff00:12:3456')) -- "2001:db8::ff00:12:3456"

-- Expanded IPv6 addresses are abbreviated: tostring(IPAddress.new('2001:db8:0:0:0:0:0:0')) -- "2001:db8::" </syntaxhighlight>

You can also concatenate them:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4') .. ' foo' -- "1.2.3.4 foo" IPAddress.new('1.2.3.4') .. IPAddress.new('5.6.7.8') -- "1.2.3.45.6.7.8" </syntaxhighlight>

IPAddress objects have several methods, outlined below.

getIP

<syntaxhighlight lang="lua"> ipAddress:getIP() </syntaxhighlight>

Returns a string representation of the IP address. IPv6 addresses are abbreviated if possible.

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):getIP() -- "1.2.3.4" IPAddress.new('2001:db8::ff00:12:3456'):getIP() -- "2001:db8::ff00:12:3456" IPAddress.new('2001:db8:0:0:0:0:0:0'):getIP() -- "2001:db8::" </syntaxhighlight>

getVersion

<syntaxhighlight lang="lua"> ipAddress:getVersion() </syntaxhighlight>

Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses.

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):getVersion() -- "IPv4" IPAddress.new('2001:db8::ff00:12:3456'):getVersion() -- "IPv6" </syntaxhighlight>

isIPv4

<syntaxhighlight lang="lua"> ipAddress:isIPv4() </syntaxhighlight>

Returns true if the IP address is an IPv4 address, and false otherwise.

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):isIPv4() -- true IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false </syntaxhighlight>

isIPv6

<syntaxhighlight lang="lua"> ipAddress:isIPv6() </syntaxhighlight>

Returns true if the IP address is an IPv6 address, and false otherwise.

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):isIPv6() -- false IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true </syntaxhighlight>

isInSubnet

<syntaxhighlight lang="lua"> ipAddress:isInSubnet(subnet) </syntaxhighlight>

Returns true if the IP address is in the subnet subnet, and false otherwise. subnet may be a Subnet object or a CIDR string.

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):isInSubnet('1.2.3.0/24') -- true IPAddress.new('1.2.3.4'):isInSubnet('1.2.4.0/24') -- false IPAddress.new('1.2.3.4'):isInSubnet(Subnet.new('1.2.3.0/24')) -- true IPAddress.new('2001:db8::ff00:12:3456'):isInSubnet('2001:db8::ff00:12:0/112') -- true </syntaxhighlight>

getSubnet

<syntaxhighlight lang="lua"> ipAddress:getSubnet(bitLength) </syntaxhighlight>

Returns a Subnet object for the subnet with a bit length of bitLength which contains the current IP. The bitLength parameter must be an integer between 0 and 32 for IPv4 addresses, or an integer between 0 and 128 for IPv6 addresses.

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):getSubnet(24) -- Equivalent to Subnet.new('1.2.3.0/24') </syntaxhighlight>

getNextIP

<syntaxhighlight lang="lua"> ipAddress:getNextIP() </syntaxhighlight>

Returns a new IPAddress object equivalent to the current IP address incremented by one. The IPv4 address "255.255.255.255" rolls around to "0.0.0.0", and the IPv6 address "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" rolls around to "::".

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):getNextIP() -- Equivalent to IPAddress.new('1.2.3.5') IPAddress.new('2001:db8::ff00:12:3456'):getNextIP() -- Equivalent to IPAddress.new('2001:db8::ff00:12:3457') IPAddress.new('255.255.255.255'):getNextIP() -- Equivalent to IPAddress.new('0.0.0.0') </syntaxhighlight>

getPreviousIP

<syntaxhighlight lang="lua"> ipAddress:getPreviousIP() </syntaxhighlight>

Returns a new IPAddress object equivalent to the current IP address decremented by one. The IPv4 address "0.0.0.0" rolls around to "255.255.255.255", and the IPv6 address "::" rolls around to "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff".

Examples:

<syntaxhighlight lang="lua"> IPAddress.new('1.2.3.4'):getPreviousIP() -- Equivalent to IPAddress.new('1.2.3.3') IPAddress.new('2001:db8::ff00:12:3456'):getPreviousIP() -- Equivalent to IPAddress.new('2001:db8::ff00:12:3455') IPAddress.new('0.0.0.0'):getPreviousIP() -- Equivalent to IPAddress.new('255.255.255.255') </syntaxhighlight>

Subnet

The Subnet class is used to work with subnetworks of IPv4 or IPv6 addresses. To create a new Subnet object:

<syntaxhighlight lang="lua"> local subnet = Subnet.new(cidrString) </syntaxhighlight>

cidrString must be a valid IPv4 or IPv6 CIDR string.

<syntaxhighlight lang="lua"> local cidr = Subnet.new('255.255.255.0/24') -- Subnet object local cidr = Subnet.new('255.255.255.1/24') -- error </syntaxhighlight>

Subnet objects can be compared for equality:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24') == Subnet.new('1.2.3.0/24') -- true Subnet.new('1.2.3.0/24') == Subnet.new('1.2.3.0/25') -- false Subnet.new('1.2.3.0/24') == Subnet.new('2001:db8::ff00:12:0/112') -- false Subnet.new('2001:db8::ff00:12:0/112') == Subnet.new('2001:db8::ff00:12:0/112') -- true Subnet.new('2001:db8:0:0:0:0:0:0/112') == Subnet.new('2001:db8::/112') -- true </syntaxhighlight>

You can use tostring on them (this is equivalent to getCIDR): <syntaxhighlight lang="lua"> tostring(Subnet.new('1.2.3.0/24')) -- "1.2.3.0/24" tostring(Subnet.new('2001:db8::ff00:12:0/112')) -- "2001:db8::ff00:12:0/112" tostring(Subnet.new('2001:db8:0:0:0:0:0:0/112')) -- "2001:db8::/112" </syntaxhighlight>

You can also concatenate them: <syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24') .. ' foo' -- "1.2.3.0/24 foo" Subnet.new('1.2.3.0/24') .. Subnet.new('4.5.6.0/24') -- "1.2.3.0/244.5.6.0/24" </syntaxhighlight>

Subnet objects have several methods, outlined below.

getPrefix

<syntaxhighlight lang="lua"> subnet:getPrefix() </syntaxhighlight>

Returns an IPAddress object for the lowest IP address in the subnet.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):getPrefix() -- Equivalent to IPAddress.new('1.2.3.0') Subnet.new('2001:db8::ff00:12:0/112'):getPrefix() -- Equivalent to IPAddress.new('2001:db8::ff00:12:0') </syntaxhighlight>

getHighestIP

<syntaxhighlight lang="lua"> subnet:getHighestIP() </syntaxhighlight>

Returns an IPAddress object for the highest IP address in the subnet.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):getHighestIP() -- Equivalent to IPAddress.new('1.2.3.255') Subnet.new('2001:db8::ff00:12:0/112'):getHighestIP() -- Equivalent to IPAddress.new('2001:db8::ff00:12:ffff') </syntaxhighlight>

getBitLength

<syntaxhighlight lang="lua"> subnet:getBitLength() </syntaxhighlight>

Returns the bit length of the subnet. This is an integer between 0 and 32 for IPv4 addresses, or an integer between 0 and 128 for IPv6 addresses.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):getBitLength() -- 24 Subnet.new('2001:db8::ff00:12:0/112'):getBitLength() -- 112 </syntaxhighlight>

getCIDR

<syntaxhighlight lang="lua"> subnet:getCIDR() </syntaxhighlight>

Returns a CIDR string representation of the subnet.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):getCIDR() -- "1.2.3.0/24" Subnet.new('2001:db8::ff00:12:0/112'):getCIDR() -- "2001:db8::ff00:12:0/112" Subnet.new('2001:db8:0:0:0:0:0:0/112'):getCIDR() -- "2001:db8::/112" </syntaxhighlight>

getVersion

<syntaxhighlight lang="lua"> subnet:getVersion() </syntaxhighlight>

Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):getVersion() -- "IPv4" Subnet.new('2001:db8::ff00:12:0/112'):getVersion() -- "IPv6" </syntaxhighlight>

isIPv4

<syntaxhighlight lang="lua"> subnet:isIPv4() </syntaxhighlight>

Returns true if the subnet is using IPv4, and false otherwise.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):isIPv4() -- true Subnet.new('2001:db8::ff00:12:0/112'):isIPv4() -- false </syntaxhighlight>

isIPv6

<syntaxhighlight lang="lua"> subnet:isIPv6() </syntaxhighlight>

Returns true if the subnet is using IPv6, and false otherwise.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):isIPv6() -- false Subnet.new('2001:db8::ff00:12:0/112'):isIPv6() -- true </syntaxhighlight>

containsIP

<syntaxhighlight lang="lua"> subnet:containsIP(ip) </syntaxhighlight>

Returns true if the subnet contains the IP address ip, and false otherwise. ip can be an IP address string, or an IPAddress object.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):containsIP('1.2.3.4') -- true Subnet.new('1.2.3.0/24'):containsIP('1.2.4.4') -- false Subnet.new('1.2.3.0/24'):containsIP(IPAddress.new('1.2.3.4')) -- true Subnet.new('2001:db8::ff00:12:0/112'):containsIP('2001:db8::ff00:12:3456') -- true </syntaxhighlight>

overlapsSubnet

<syntaxhighlight lang="lua"> subnet:overlapsSubnet(subnet) </syntaxhighlight>

Returns true if the current subnet overlaps with subnet, and false otherwise. subnet can be a CIDR string or a subnet object.

Examples:

<syntaxhighlight lang="lua"> Subnet.new('1.2.3.0/24'):overlapsSubnet('1.2.0.0/16') -- true Subnet.new('1.2.3.0/24'):overlapsSubnet('1.2.12.0/22') -- false Subnet.new('1.2.3.0/24'):overlapsSubnet(Subnet.new('1.2.0.0/16')) -- true Subnet.new('2001:db8::ff00:12:0/112'):overlapsSubnet('2001:db8::ff00:0:0/96') -- true </syntaxhighlight>

walk

<syntaxhighlight lang="lua"> subnet:walk() </syntaxhighlight>

The walk method iterates over all of the IPAddress objects in the subnet.

Examples:

<syntaxhighlight lang="lua"> for ipAddress in Subnet.new('192.168.0.0/30'):walk() do mw.log(tostring(ipAddress)) end -- 192.168.0.0 -- 192.168.0.1 -- 192.168.0.2 -- 192.168.0.3 </syntaxhighlight>

IPv4Collection

The IPv4Collection class is used to work with several different IPv4 addresses and IPv4 subnets. To create a new IPv4Collection object:

<syntaxhighlight lang="lua"> local collection = IPv4Collection.new() </syntaxhighlight>

IPv4Collection objects have several methods, outlined below.

getVersion

<syntaxhighlight lang="lua"> collection:getVersion() </syntaxhighlight>

Returns the string "IPv4".

addIP

<syntaxhighlight lang="lua"> collection:addIP(ip) </syntaxhighlight>

Adds an IP to the collection. The IP can be either a string or an IPAddress object.

Examples:

<syntaxhighlight lang="lua"> collection:addIP('1.2.3.4') collection:addIP(IPAddress.new('1.2.3.4')) </syntaxhighlight>

This method is chainable:

<syntaxhighlight lang="lua"> collection:addIP('1.2.3.4'):addIP('5.6.7.8') </syntaxhighlight>

addSubnet

<syntaxhighlight lang="lua"> collection:addSubnet(subnet) </syntaxhighlight>

Adds a subnet to the collection. The subnet can be either a CIDR string or a Subnet object.

Examples:

<syntaxhighlight lang="lua"> collection:addSubnet('1.2.3.0/24') collection:addSubnet(Subnet.new('1.2.3.0/24')) </syntaxhighlight>

This method is chainable:

<syntaxhighlight lang="lua"> collection:addSubnet('1.2.0.0/24'):addSubnet('1.2.1.0/24') </syntaxhighlight>

addFromString

<syntaxhighlight lang="lua"> collection:addFromString(str) </syntaxhighlight>

Extracts any IPv4 addresses and IPv4 CIDR subnets from str and adds them to the collection. Any text that is not an IPv4 address or CIDR subnet is ignored.

Examples:

<syntaxhighlight lang="lua"> collection:addFromString('Add some IPs and subnets: 1.2.3.4 1.2.3.5 2001:0::f foo 1.2.4.0/24') </syntaxhighlight>

This method is chainable:

<syntaxhighlight lang="lua"> collection:addFromString('foo 1.2.3.4'):addFromString('bar 5.6.7.8') </syntaxhighlight>

containsIP

<syntaxhighlight lang="lua"> collection:containsIP(ip) </syntaxhighlight>

Returns true if the collection contains the specified IP; otherwise returns false. The ip parameter can be a string or an IPAddress object.

Examples:

<syntaxhighlight lang="lua"> collection:containsIP('1.2.3.4') collection:containsIP(IPAddress.new('1.2.3.4')) </syntaxhighlight>

getRanges

<syntaxhighlight lang="lua"> collection:getRanges() </syntaxhighlight>

Returns a sorted array of IP pairs equivalent to the collection. Each IP pair is an array representing a contiguous range of IP addresses from pair[1] to pair[2] inclusive. pair[1] and pair[2] are IPAddress objects.

Examples:

<syntaxhighlight lang="lua"> collection:addSubnet('1.2.0.0/24') collection:addSubnet('1.2.1.0/24') collection:addSubnet('1.2.10.0/24') mw.logObject(collection:getRanges()) -- Logs the following: -- table#1 { -- table#2 { -- 1.2.0.0, -- 1.2.1.255, -- }, -- table#3 { -- 1.2.10.0, -- 1.2.10.255, -- }, -- } </syntaxhighlight>

overlapsSubnet

<syntaxhighlight lang="lua"> collection:overlapsSubnet(subnet) </syntaxhighlight>

Returns true, obj if subnet overlaps this collection, where obj is the first IPAddress or Subnet object overlapping the subnet. Otherwise, returns false. subnet can be a CIDR string or a Subnet object.

Examples:

<syntaxhighlight lang="lua"> collection:addIP('1.2.3.4') collection:overlapsSubnet('1.2.3.0/24') -- true, IPAddress.new('1.2.3.4') collection:overlapsSubnet('1.2.4.0/24') -- false </syntaxhighlight>

IPv6Collection

The IPv6Collection class is used to work with several different IPv6 addresses and IPv6 subnets. IPv6Collection objects are directly analogous to IPv4Collection objects: they contain the same methods and work the same way, but all IP addresses and subnets added to it must be IPv6, not IPv4.

To create a new IPv6Collection object:

<syntaxhighlight lang="lua"> local collection = IPv6Collection.new() </syntaxhighlight>