وحدة:IP/شرح

وحدة:IP هي مكتبة للعمل مع عناوين IP والشبكات الفرعية. يمكنها التعامل مع كل من IPv4 و IPv6. تصدر المكتبة أربع فئات، IPAddress، Subnet، IPv4Collection، و IPv6Collection.

تحميل المكتبة

local IP = require('Module:IP')
local IPAddress = IP.IPAddress
local Subnet = IP.Subnet

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 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

يمكن مقارنة عناصر IPAddress مع العوامل ذات الصلة:

-- 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

يمكنك استخدام الوتر عليها (هذا يعادل استخدام 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::"

يمكنك أيضًا تجميعها:

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. يتم اختصار عناوين 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، ويعيد النتيجة خطأ إذا كان عنوان IP هو عنوان IPv4.

أمثلة:

IPAddress.new('1.2.3.4'):isIPv4()                -- true
IPAddress.new('2001:db8::ff00:12:3456'):isIPv4() -- false

isIPv6

ipAddress:isIPv6()

يعود صحيحًا إذا كان عنوان IP هو عنوان IPv6، ويعيد النتيجة خطأ إذا كان عنوان IP هو عنوان IPv6.

أمثلة:

IPAddress.new('1.2.3.4'):isIPv6()                -- false
IPAddress.new('2001:db8::ff00:12:3456'):isIPv6() -- true

isInSubnet

ipAddress:isInSubnet(subnet)

يعود صحيحًا إذا كان عنوان IP موجودًا في الشبكة الفرعية 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)

يقوم بإرجاع عنصر شبكة فرعية للشبكة الفرعية بطول بت من bitLength يحتوي على عنوان IP الحالي. يجب أن تكون معلمة bitLength عددًا صحيحًا بين 0 و 32 لعناوين IPv4، أو عددًا صحيحًا بين 0 و 128 لعناوين IPv6.

أمثلة:

IPAddress.new('1.2.3.4'):getSubnet(24) -- Equivalent to Subnet.new('1.2.3.0/24')

getNextIP

ipAddress:getNextIP()

يُرجع عنصر IPAddress جديدًا مكافئًا لعنوان IP الحالي متزايدًا بواحد. يتحول عنوان (IPv4) "255.255.255.255" إلى "0.0.0.0"، وعنوان (IPv6) "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" إلى "::".

أمثلة:

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".

أمثلة:

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.

local cidr = Subnet.new('255.255.255.0/24') -- Subnet object
local cidr = Subnet.new('255.255.255.1/24') -- error

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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.

أمثلة:

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 المختلفة والشبكات الفرعية IPv6. تتشابه عناصر IPv6Collection بشكل مباشر مع عناصر IPv4Collection: فهي تحتوي على نفس الأساليب وتعمل بنفس الطريقة، ولكن يجب أن تكون جميع عناوين IP والشبكات الفرعية المضافة إليها IPv6، وليس IPv4.

لإنشاء عنصر IPv6Collection جديد:

local collection = IPv6Collection.new()