モジュール:IP/doc

モジュール:IPはIPアドレスとサブネットを取り扱うライブラリモジュールです。IPv4とIPv6の両方をカバーしており、IPAddress、 Subnet、 IPv4Collection、IPv6Collection4つのクラスがあります。

**ライブラリの読み込み**
local IP = require('Module:IP')
local IPAddress = IP.IPAddress
local Subnet = IP.Subnet
local Util = IP.Util

**IPAddress**
IPAddressクラスは、単一のIPアドレスの取り扱いに使用します。以下の要領で新しいIPAddressオブジェクトを作成できます。
local ipAddress = IPAddress.new(ipString)
引数となるipStringには、有効なIPv4またはIPv6を渡してください。
例：
local ipv4Address = IPAddress.new('1.2.3.4')
local ipv6Address = IPAddress.new('2001:db8::ff00:12:3456')
なお、IPアドレスではない文字列または無効なIPアドレスが渡された場合、エラーが返ります。ある文字列がIPアドレスかどうかを単純に判別し、呼び出し元モジュール内の処理は継続したい場合pcallを使用してください。
local isIp, ip = pcall(IPAddress.new, '1.2.3.4') -- isIp: true, ip: IPAddressオブジェクト
local isIp, ip = pcall(IPAddress.new, 'ウィキ助') -- isIp: false, ip: nil
local isIp, ip = pcall(IPAddress.new, '1.2.3.256') -- isIp: false, ip: nil
IPAddressオブジェクトは関係演算子による比較が可能です。
-- 等価演算子
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
-- 比較演算子
IPAddress.new('1.2.3.4')  IPAddress.new('1.2.3.5')  -- false
IPAddress.new('1.2.3.4') 
tostringを用いることでオブジェクトを文字列にすることも可能です。（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"
-- キャストされたIPv6アドレスは省略形で出力されます：
tostring(IPAddress.new('2001:db8:0:0:0:0:0:0'))   -- "2001:db8::"
IPAddressオブジェクトに対し結合演算子を用いることも可能です。
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オブジェクトのメソッドについては以下を参照してください。

**getIP**
ipAddress:getIP()
IPアドレスを文字列として返します。tostringを用いた場合と同様、IPv6アドレスは省略形が出力されます。
例：
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()
IPプロトコルのバージョンを返します。IPv4アドレスの場合はIPv4、IPv6アドレスの場合はIPv6です。
例：
IPAddress.new('1.2.3.4'):getVersion()                -- "IPv4"
IPAddress.new('2001:db8::ff00:12:3456'):getVersion() -- "IPv6"

**isIPv4**
ipAddress:isIPv4()
インスタンスに紐づけられたIPアドレスがIPv4の場合はtrueを、そうでなければfalseを返します。
例：
IPAddress.new('1.2.3.4'):isIPv4()                -- true
IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false

**isIPv6**
ipAddress:isIPv6()
インスタンスに紐づけられたIPアドレスがIPv6の場合はtrueを、そうでなければfalseを返します。
例：
IPAddress.new('1.2.3.4'):isIPv6()                -- false
IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true

**isInSubnet**
ipAddress:isInSubnet(subnet)
インスタンスに紐づけられたIPアドレスが、subnet引数で指定されたサブネットに属する場合はtrueを、そうでなければfalseを返します。subnet引数に対する有効な値はSubnetオブジェクトまたはCIDRの文字列です。
例：
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)
インスタンスに紐づけられたIPアドレスに対し、bitLengthで指定したビット長のサブネットに対応するSubnetオブジェクトを返します。bitLength引数は、IPv4アドレスの場合は0-32の整数、IPv6アドレスの場合は0-128の整数のみ指定できます。
例：
IPAddress.new('1.2.3.4'):getSubnet(24) -- Subnet.new('1.2.3.0/24')と等価

**getNextIP**
ipAddress:getNextIP()
インスタンスに紐づけられたIPアドレスに1を加算したIPAddressオブジェクトを返します。255.255.255.255のIPv4アドレスは0.0.0.0となり、ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffのIPv6アドレスは::となります。
例：
IPAddress.new('1.2.3.4'):getNextIP()                -- IPAddress.new('1.2.3.5')と等価
IPAddress.new('2001:db8::ff00:12:3456'):getNextIP() -- IPAddress.new('2001:db8::ff00:12:3457')と等価
IPAddress.new('255.255.255.255'):getNextIP()        -- IPAddress.new('0.0.0.0')と等価

**getPreviousIP**
ipAddress:getPreviousIP()
インスタンスに紐づけられたIPアドレスから1を減算したIPAddressオブジェクトを返します。0.0.0.0のIPv4アドレスは255.255.255.255となり、::のIPv6アドレスはffff:ffff:ffff:ffff:ffff:ffff:ffff:ffffとなります。
例：
IPAddress.new('1.2.3.4'):getPreviousIP()                -- IPAddress.new('1.2.3.3')と等価
IPAddress.new('2001:db8::ff00:12:3456'):getPreviousIP() -- IPAddress.new('2001:db8::ff00:12:3455')と等価
IPAddress.new('0.0.0.0'):getPreviousIP()                -- IPAddress.new('255.255.255.255')と等価

**Subnet**
Subnetクラスは、IPv4またはIPv6アドレスのサブネットの取り扱いに使用します。以下の要領で新しいSubnetオブジェクトを作成できます。
local subnet = Subnet.new(cidrString)
cidrString引数は、IPv4またはIPv6の有効なCIDRである必要があります。
local cidr = Subnet.new('255.255.255.0/24') -- Subnetオブジェクト
local cidr = Subnet.new('255.255.255.1/24') -- エラー
Subnetオブジェクトは等価演算子による比較が可能です。
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
tostringを用いることでオブジェクトを文字列にすることも可能です。（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"
Subnetオブジェクトに対し結合演算子を用いることも可能です。
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オブジェクトのメソッドについては以下を参照してください。

**getPrefix**
subnet:getPrefix()
サブネット内で最初のIPアドレスをIPAddressオブジェクトとして返します。
例：
Subnet.new('1.2.3.0/24'):getPrefix()              -- IPAddress.new('1.2.3.0')と等価
Subnet.new('2001:db8::ff00:12:0/112'):getPrefix() -- IPAddress.new('2001:db8::ff00:12:0')と等価

**getHighestIP**
subnet:getHighestIP()
サブネット内で最後のIPアドレスをIPAddressオブジェクトとして返します。
例：
Subnet.new('1.2.3.0/24'):getHighestIP()              -- IPAddress.new('1.2.3.255')と等価
Subnet.new('2001:db8::ff00:12:0/112'):getHighestIP() -- IPAddress.new('2001:db8::ff00:12:ffff')と等価

**getBitLength**
subnet:getBitLength()
インスタンスに紐づけられたCIDRのビット長を返します。IPv4アドレスの場合は0-32の整数、IPv6アドレスの場合は0-128の整数です。
例：
Subnet.new('1.2.3.0/24'):getBitLength()              -- 24
Subnet.new('2001:db8::ff00:12:0/112'):getBitLength() -- 112

**getCIDR**
subnet:getCIDR()
CIDRを文字列として返します。
例：
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()
IPプロトコルのバージョンを返します。IPv4アドレスの場合はIPv4、IPv6アドレスの場合はIPv6です。
例：
Subnet.new('1.2.3.0/24'):getVersion()              -- "IPv4"
Subnet.new('2001:db8::ff00:12:0/112'):getVersion() -- "IPv6"

**isIPv4**
subnet:isIPv4()
インスタンスに紐づけられたCIDRがIPv4の場合はtrueを、そうでなければfalseを返します。
例：
Subnet.new('1.2.3.0/24'):isIPv4()              -- true
Subnet.new('2001:db8::ff00:12:0/112'):isIPv4() -- false

**isIPv6**
subnet:isIPv6()
インスタンスに紐づけられたCIDRがIPv6の場合はtrueを、そうでなければfalseを返します。
例：
Subnet.new('1.2.3.0/24'):isIPv6()              -- false
Subnet.new('2001:db8::ff00:12:0/112'):isIPv6() -- true

**containsIP**
subnet:containsIP(ip)
インスタンスに紐づけられたCIDRがip引数のIPアドレスを内包する場合はtrueを、そうでなければfalseを返します。ip引数として有効な値は、IPアドレスを示す文字列またはIPAddressオブジェクトです。
例：
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)
インスタンスに紐づけられたCIDRがsubnet引数のCIDRに含まれる場合trueを、そうでなければfalseを返します。subnet引数として有効な値は、CIDRを示す文字列またはSubnetオブジェクトです。
例：
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()
walkメソッドは、サブネットに含まれるすべてのIPAddressオブジェクトをループ処理します。
例：
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**
IPv4CollectionクラスはIPv4アドレスとサブネットの取り扱いに使用します。以下の要領で新しいIPv4Collectionオブジェクトを作成できます。
local collection = IPv4Collection.new()
IPv4Collectionオブジェクトのメソッドについては以下を参照してください。

**getVersion**
collection:getVersion()
IPv4の文字列を返します。

**addIP**
collection:addIP(ip)
コレクションにIPアドレスを追加します。ip引数に対する有効な値はIPアドレスの文字列またはIPAddressオブジェクトです。
例：
collection:addIP('1.2.3.4')
collection:addIP(IPAddress.new('1.2.3.4'))
このメソッドはチェーンできます。
collection:addIP('1.2.3.4'):addIP('5.6.7.8')

**addSubnet**
collection:addSubnet(subnet)
コレクションにサブネットを追加します。subnet引数に対する有効な値はCIDRの文字列またはSubnetオブジェクトです。
例：
collection:addSubnet('1.2.3.0/24')
collection:addSubnet(Subnet.new('1.2.3.0/24'))
このメソッドはチェーンできます。
collection:addSubnet('1.2.0.0/24'):addSubnet('1.2.1.0/24')

**addFromString**
collection:addFromString(str)
ランダムな文字列からIPv4アドレスとサブネットを抽出し、コレクションに追加します。文字列内で該当しない部分は無視されます。
例：
collection:addFromString('Add some IPs and subnets: 1.2.3.4 1.2.3.5 2001:0::f foo 1.2.4.0/24')
このメソッドはチェーンできます。
collection:addFromString('foo 1.2.3.4'):addFromString('bar 5.6.7.8')

**containsIP**
collection:containsIP(ip)
コレクションが特定のIPアドレスを含む場合はtrueを、そうでない場合はfalseを返します。ip引数に対する有効な値はIPアドレスの文字列またはIPAddressオブジェクトです。
例：
collection:containsIP('1.2.3.4')
collection:containsIP(IPAddress.new('1.2.3.4'))

**getRanges**
collection:getRanges()
コレクション内のIPをソートし、ペアを配列として返します。それぞれのIPペアはpair1からpair2までの連続したIPレンジとなります。pair1とpair2はIPAddressオブジェクトです。
例：
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())
-- 返り値:
-- 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)
subnet引数がコレクション内のIPアドレスまたはサブネットに含まれる場合true, objを、そうでない場合falseを返します。返り値のobjは指定のサブネットと包含関係になるIPAddressまたはSubnetオブジェクトです。
例：
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**
IPv6CollectionクラスはIPv6アドレスとサブネットの取り扱いに使用します。IPv6CollectionオブジェクトはIPv4Collectionと同じメソッドを有しており、平行的に機能します。ただし、コレクションに追加されるIPアドレスまたはサブネットはIPv6である必要があります。以下の要領で新しいIPv6Collectionオブジェクトを作成できます。
local collection = IPv6Collection.new()