Editing Module:IP/doc

{{Module rating|protected}}
{{used in system}}
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|IPAddress]], [[#Subnet|Subnet]], [[#IPv4Collection|IPv4Collection]], and [[#IPv6Collection|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>

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|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 <var>subnet</var>, and false otherwise. <var>subnet</var> may be a [[#Subnet|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 <var>bitLength</var> which contains the current IP. The <var>bitLength</var> 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 [[subnetwork]]s of IPv4 or IPv6 addresses. To create a new Subnet object:

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

<var>cidrString</var> must be a valid IPv4 or IPv6 [[CIDR]] string.

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|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 <var>ip</var>, and false otherwise. <var>ip</var> 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 <var>subnet</var>, and false otherwise. <var>subnet</var> 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|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|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 <var>str</var> 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 <var>ip</var> parameter can be a string or an [[#IPAddress|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|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 <var>subnet</var> overlaps this collection, where obj is the first [[#IPAddress|IPAddress]] or [[#Subnet|Subnet]] object overlapping the subnet. Otherwise, returns false. <var>subnet</var> can be a CIDR string or a [[#Subnet|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|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>

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>