Module:IP/doc: Difference between revisions
(add section links) |
m (27 revisions imported from wikipedia:Module:IP/doc) |
||
(21 intermediate revisions by 8 users not shown) | |||
Line 1: | Line 1: | ||
{{Module rating|protected}} |
|||
Module:IP is a library for working with IP addresses and subnets. It can handle both [[IPv4]] and [[IPv6]]. The library exports two classes, [[#IPAddress|IPAddress]] and [[#Subnet|Subnet]]. |
|||
{{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 == |
== Loading the library == |
||
< |
<syntaxhighlight lang="lua"> |
||
local IP = require('Module:IP') |
local IP = require('Module:IP') |
||
local IPAddress = IP.IPAddress |
local IPAddress = IP.IPAddress |
||
local Subnet = IP.Subnet |
local Subnet = IP.Subnet |
||
</syntaxhighlight> |
|||
</source> |
|||
== IPAddress == |
== IPAddress == |
||
Line 13: | Line 15: | ||
The IPAddress class is used to work with single IP addresses. To create a new IPAddress object: |
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) |
local ipAddress = IPAddress.new(ipString) |
||
</syntaxhighlight> |
|||
</source> |
|||
The ipString variable can be a valid IPv4 or IPv6 address. |
The ipString variable can be a valid IPv4 or IPv6 address. |
||
Line 21: | Line 23: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
local ipv4Address = IPAddress.new('1.2.3.4') |
local ipv4Address = IPAddress.new('1.2.3.4') |
||
local ipv6Address = IPAddress.new('2001:db8::ff00:12:3456') |
local ipv6Address = IPAddress.new('2001:db8::ff00:12:3456') |
||
</syntaxhighlight> |
|||
</source> |
|||
IPAddress objects can be compared with relational operators: |
IPAddress objects can be compared with relational operators: |
||
< |
<syntaxhighlight lang="lua"> |
||
-- Equality |
-- 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.4') -- true |
||
Line 38: | Line 40: | ||
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') -- true |
||
IPAddress.new('1.2.3.4') <= IPAddress.new('1.2.3.4') -- true |
IPAddress.new('1.2.3.4') <= IPAddress.new('1.2.3.4') -- true |
||
</syntaxhighlight> |
|||
</source> |
|||
You can use tostring on them (this is equivalent to using [[#getIP|getIP]]): |
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('1.2.3.4')) -- "1.2.3.4" |
||
tostring(IPAddress.new('2001:db8::ff00:12:3456')) -- "2001:db8::ff00:12:3456" |
tostring(IPAddress.new('2001:db8::ff00:12:3456')) -- "2001:db8::ff00:12:3456" |
||
Line 48: | Line 50: | ||
-- Expanded IPv6 addresses are abbreviated: |
-- Expanded IPv6 addresses are abbreviated: |
||
tostring(IPAddress.new('2001:db8:0:0:0:0:0:0')) -- "2001:db8::" |
tostring(IPAddress.new('2001:db8:0:0:0:0:0:0')) -- "2001:db8::" |
||
</syntaxhighlight> |
|||
</source> |
|||
You can also concatenate them: |
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') .. ' 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" |
IPAddress.new('1.2.3.4') .. IPAddress.new('5.6.7.8') -- "1.2.3.45.6.7.8" |
||
</syntaxhighlight> |
|||
</source> |
|||
IPAddress objects have several methods, outlined below. |
IPAddress objects have several methods, outlined below. |
||
Line 61: | Line 63: | ||
=== getIP === |
=== getIP === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:getIP() |
ipAddress:getIP() |
||
</syntaxhighlight> |
|||
</source> |
|||
Returns a string representation of the IP address. IPv6 addresses are abbreviated if possible. |
Returns a string representation of the IP address. IPv6 addresses are abbreviated if possible. |
||
Line 69: | Line 71: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):getIP() -- "1.2.3.4" |
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::ff00:12:3456'):getIP() -- "2001:db8::ff00:12:3456" |
||
IPAddress.new('2001:db8:0:0:0:0:0:0'):getIP() -- "2001:db8::" |
IPAddress.new('2001:db8:0:0:0:0:0:0'):getIP() -- "2001:db8::" |
||
</syntaxhighlight> |
|||
</source> |
|||
=== getVersion === |
=== getVersion === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:getVersion() |
ipAddress:getVersion() |
||
</syntaxhighlight> |
|||
</source> |
|||
Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses. |
Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses. |
||
Line 85: | Line 87: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):getVersion() -- "IPv4" |
IPAddress.new('1.2.3.4'):getVersion() -- "IPv4" |
||
IPAddress.new('2001:db8::ff00:12:3456'):getVersion() -- "IPv6" |
IPAddress.new('2001:db8::ff00:12:3456'):getVersion() -- "IPv6" |
||
</syntaxhighlight> |
|||
</source> |
|||
=== isIPv4 === |
=== isIPv4 === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:isIPv4() |
ipAddress:isIPv4() |
||
</syntaxhighlight> |
|||
</source> |
|||
Returns true if the IP address is an IPv4 address, and false otherwise. |
Returns true if the IP address is an IPv4 address, and false otherwise. |
||
Line 100: | Line 102: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):isIPv4() -- true |
IPAddress.new('1.2.3.4'):isIPv4() -- true |
||
IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false |
IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false |
||
</syntaxhighlight> |
|||
</source> |
|||
=== isIPv6 === |
=== isIPv6 === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:isIPv6() |
ipAddress:isIPv6() |
||
</syntaxhighlight> |
|||
</source> |
|||
Returns true if the IP address is an IPv6 address, and false otherwise. |
Returns true if the IP address is an IPv6 address, and false otherwise. |
||
Line 115: | Line 117: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):isIPv6() -- false |
IPAddress.new('1.2.3.4'):isIPv6() -- false |
||
IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true |
IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true |
||
</syntaxhighlight> |
|||
</source> |
|||
=== isInSubnet === |
=== isInSubnet === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:isInSubnet(subnet) |
ipAddress:isInSubnet(subnet) |
||
</syntaxhighlight> |
|||
</source> |
|||
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. |
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. |
||
Line 130: | Line 132: | ||
Examples: |
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.3.0/24') -- true |
||
IPAddress.new('1.2.3.4'):isInSubnet('1.2.4.0/24') -- false |
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('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 |
IPAddress.new('2001:db8::ff00:12:3456'):isInSubnet('2001:db8::ff00:12:0/112') -- true |
||
</syntaxhighlight> |
|||
</source> |
|||
=== getSubnet === |
=== getSubnet === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:getSubnet(bitLength) |
ipAddress:getSubnet(bitLength) |
||
</syntaxhighlight> |
|||
</source> |
|||
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. |
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. |
||
Line 147: | Line 149: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):getSubnet(24) -- Equivalent to Subnet.new('1.2.3.0/24') |
IPAddress.new('1.2.3.4'):getSubnet(24) -- Equivalent to Subnet.new('1.2.3.0/24') |
||
</syntaxhighlight> |
|||
</source> |
|||
=== getNextIP === |
=== getNextIP === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:getNextIP() |
ipAddress:getNextIP() |
||
</syntaxhighlight> |
|||
</source> |
|||
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 "::". |
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 "::". |
||
Line 161: | Line 163: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):getNextIP() -- Equivalent to IPAddress.new('1.2.3.5') |
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('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') |
IPAddress.new('255.255.255.255'):getNextIP() -- Equivalent to IPAddress.new('0.0.0.0') |
||
</syntaxhighlight> |
|||
</source> |
|||
=== getPreviousIP === |
=== getPreviousIP === |
||
< |
<syntaxhighlight lang="lua"> |
||
ipAddress:getPreviousIP() |
ipAddress:getPreviousIP() |
||
</syntaxhighlight> |
|||
</source> |
|||
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". |
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". |
||
Line 177: | Line 179: | ||
Examples: |
Examples: |
||
< |
<syntaxhighlight lang="lua"> |
||
IPAddress.new('1.2.3.4'):getPreviousIP() -- Equivalent to IPAddress.new('1.2.3.3') |
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('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') |
IPAddress.new('0.0.0.0'):getPreviousIP() -- Equivalent to IPAddress.new('255.255.255.255') |
||
</syntaxhighlight> |
|||
</source> |
|||
== 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 | | |
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | | |
Latest revision as of 20:27, February 19, 2022
This Lua module is used in system messages. Changes to it can cause immediate changes to the Wikipedia user interface. To avoid major disruption, any changes should be tested in the module's /sandbox or /testcases subpages, or in your own module sandbox. The tested changes can be added to this page in a single edit. Please discuss changes on the talk page before implementing them. |
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
local IP = require('Module:IP')
local IPAddress = IP.IPAddress
local Subnet = IP.Subnet
IPAddress
The IPAddress class is used to work with single IP addresses. To create a new IPAddress object:
local ipAddress = IPAddress.new(ipString)
The ipString variable can be a valid IPv4 or IPv6 address.
Examples:
local ipv4Address = IPAddress.new('1.2.3.4')
local ipv6Address = IPAddress.new('2001:db8::ff00:12:3456')
IPAddress objects can be compared with relational operators:
-- 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
You can use tostring on them (this is equivalent to using getIP):
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::"
You can also concatenate them:
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"
IPAddress objects have several methods, outlined below.
getIP
ipAddress:getIP()
Returns a string representation of the IP address. IPv6 addresses are abbreviated if possible.
Examples:
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::"
getVersion
ipAddress:getVersion()
Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses.
Examples:
IPAddress.new('1.2.3.4'):getVersion() -- "IPv4"
IPAddress.new('2001:db8::ff00:12:3456'):getVersion() -- "IPv6"
isIPv4
ipAddress:isIPv4()
Returns true if the IP address is an IPv4 address, and false otherwise.
Examples:
IPAddress.new('1.2.3.4'):isIPv4() -- true
IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false
isIPv6
ipAddress:isIPv6()
Returns true if the IP address is an IPv6 address, and false otherwise.
Examples:
IPAddress.new('1.2.3.4'):isIPv6() -- false
IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true
isInSubnet
ipAddress:isInSubnet(subnet)
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:
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
getSubnet
ipAddress:getSubnet(bitLength)
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:
IPAddress.new('1.2.3.4'):getSubnet(24) -- Equivalent to Subnet.new('1.2.3.0/24')
getNextIP
ipAddress:getNextIP()
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:
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')
getPreviousIP
ipAddress:getPreviousIP()
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:
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')
Subnet
The Subnet class is used to work with subnetworks of IPv4 or IPv6 addresses. To create a new Subnet object:
local subnet = Subnet.new(cidrString)
cidrString must be a valid IPv4 or IPv6 CIDR string.
Subnet objects can be compared for equality:
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
You can use tostring on them (this is equivalent to getCIDR):
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"
You can also concatenate them:
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"
Subnet objects have several methods, outlined below.
getPrefix
subnet:getPrefix()
Returns an IPAddress object for the lowest IP address in the subnet.
Examples:
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')
getHighestIP
subnet:getHighestIP()
Returns an IPAddress object for the highest IP address in the subnet.
Examples:
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')
getBitLength
subnet:getBitLength()
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:
Subnet.new('1.2.3.0/24'):getBitLength() -- 24
Subnet.new('2001:db8::ff00:12:0/112'):getBitLength() -- 112
getCIDR
subnet:getCIDR()
Returns a CIDR string representation of the subnet.
Examples:
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"
getVersion
subnet:getVersion()
Returns the version of the IP protocol being used. This is "IPv4" for IPv4 addresses, and "IPv6" for IPv6 addresses.
Examples:
Subnet.new('1.2.3.0/24'):getVersion() -- "IPv4"
Subnet.new('2001:db8::ff00:12:0/112'):getVersion() -- "IPv6"
isIPv4
subnet:isIPv4()
Returns true if the subnet is using IPv4, and false otherwise.
Examples:
Subnet.new('1.2.3.0/24'):isIPv4() -- true
Subnet.new('2001:db8::ff00:12:0/112'):isIPv4() -- false
isIPv6
subnet:isIPv6()
Returns true if the subnet is using IPv6, and false otherwise.
Examples:
Subnet.new('1.2.3.0/24'):isIPv6() -- false
Subnet.new('2001:db8::ff00:12:0/112'):isIPv6() -- true
containsIP
subnet:containsIP(ip)
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:
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
overlapsSubnet
subnet:overlapsSubnet(subnet)
Returns true if the current subnet overlaps with subnet, and false otherwise. subnet can be a CIDR string or a subnet object.
Examples:
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
walk
subnet:walk()
The walk method iterates over all of the IPAddress objects in the subnet.
Examples:
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
IPv4Collection
The IPv4Collection class is used to work with several different IPv4 addresses and IPv4 subnets. To create a new IPv4Collection object:
local collection = IPv4Collection.new()
IPv4Collection objects have several methods, outlined below.
getVersion
collection:getVersion()
Returns the string "IPv4".
addIP
collection:addIP(ip)
Adds an IP to the collection. The IP can be either a string or an IPAddress object.
Examples:
collection:addIP('1.2.3.4')
collection:addIP(IPAddress.new('1.2.3.4'))
This method is chainable:
collection:addIP('1.2.3.4'):addIP('5.6.7.8')
addSubnet
collection:addSubnet(subnet)
Adds a subnet to the collection. The subnet can be either a CIDR string or a Subnet object.
Examples:
collection:addSubnet('1.2.3.0/24')
collection:addSubnet(Subnet.new('1.2.3.0/24'))
This method is chainable:
collection:addSubnet('1.2.0.0/24'):addSubnet('1.2.1.0/24')
addFromString
collection:addFromString(str)
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:
collection:addFromString('Add some IPs and subnets: 1.2.3.4 1.2.3.5 2001:0::f foo 1.2.4.0/24')
This method is chainable:
collection:addFromString('foo 1.2.3.4'):addFromString('bar 5.6.7.8')
containsIP
collection:containsIP(ip)
Returns true if the collection contains the specified IP; otherwise returns false. The ip parameter can be a string or an IPAddress object.
Examples:
collection:containsIP('1.2.3.4')
collection:containsIP(IPAddress.new('1.2.3.4'))
getRanges
collection:getRanges()
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:
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,
-- },
-- }
overlapsSubnet
collection:overlapsSubnet(subnet)
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:
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
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:
local collection = IPv6Collection.new()