عبد العزيز: شرح قيد التعريب

2023-08-14T11:09:34Z

شرح قيد التعريب

صفحة جديدة

{{used in system}}
وحدة:IP هي مكتبة للعمل مع عناوين IP والشبكات الفرعية. يمكنها التعامل مع كل من [[IPv4]] و [[IPv6]]. تصدر المكتبة أربع فئات، [[#IPAddress|IPAddress]]، [[#Subnet|Subnet]]، [[# IPv4Collection|IPv4Collection]]، و [[#IPv6Collection|IPv6Collection]].

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

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

== IPAddress ==

تستخدم فئة IPAddress للعمل مع عناوين IP الفردية. لإنشاء عنصر IPAddress جديد:

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

يمكن أن يكون المتغير ipString عنوان IPv4 أو IPv6 صالح.

أمثلة:

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

إذا تم تمرير سلسلة غير IP أو عنوان IP غير صالح إلى الوظيفة، فسيتم إظهار خطأ. إذا كنت تريد التحقق مما إذا كانت سلسلة معينة هي عنوان IP ومتابعة الإجراء في وحدة المتصل، فاستخدم [[:mw:Extension:Scribunto/Lua_reference_manual#pcall|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 مع العوامل ذات الصلة:

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

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

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

<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 على عدة طرق موضحة أدناه.

=== getIP ===

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

لإرجاع تمثيل سلسلة لعنوان IP. يتم اختصار عناوين IPv6 إن أمكن.

أمثلة:

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

يُرجع إصدار بروتوكول IP قيد الاستخدام. هذا هو "IPv4" لعناوين IPv4 و "IPv6" لعناوين IPv6.

أمثلة:

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

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

أمثلة:

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

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

أمثلة:

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

يعود صحيحًا إذا كان عنوان IP موجودًا في الشبكة الفرعية <var>subnet</var>، ويعيد القيمة خطأ في الحالات الأخرى. <var>subnet</var> قد يكون [[#Subnet|عنصر الشبكة الفرعية]] أو سلسلة [[CIDR]].

أمثلة:

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

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

أمثلة:

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

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

أمثلة:

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

أمثلة:

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

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

أمثلة:

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

تُستخدم فئة IPv6Collection للعمل مع العديد من عناوين IPv6 المختلفة والشبكات الفرعية IPv6. تتشابه عناصر IPv6Collection بشكل مباشر مع عناصر [[# IPv4Collection|IPv4Collection]]: فهي تحتوي على نفس الأساليب وتعمل بنفس الطريقة، ولكن يجب أن تكون جميع عناوين IP والشبكات الفرعية المضافة إليها IPv6، وليس IPv4.

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

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

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |


}}</includeonly>

وحدة:IP/شرح - تاريخ المراجعة

عبد العزيز: شرح قيد التعريب