* luci/libs: added inline documentation and luci.ip.cidr.sub() to luci.ip; allow CIDR notation _and_ netmask argument in IPv4() and IPv6() constructors
This commit is contained in:
Jo-Philipp Wich
parent
a87b197aa8
commit
9592b80af6
1 changed files with 140 additions and 6 deletions
|
|
@ -14,6 +14,7 @@ $Id$
|
|||
|
||||
]]--
|
||||
|
||||
--- LuCI IP calculation library.
|
||||
module( "luci.ip", package.seeall )
|
||||
|
||||
require("bit")
|
||||
|
|
@ -30,6 +31,7 @@ local function __bless(x)
|
|||
return setmetatable( x, {
|
||||
__index = luci.ip.cidr,
|
||||
__add = luci.ip.cidr.add,
|
||||
__sub = luci.ip.cidr.sub,
|
||||
__lt = luci.ip.cidr.lower,
|
||||
__eq = luci.ip.cidr.equal,
|
||||
__le =
|
||||
|
|
@ -54,8 +56,11 @@ local function __length(family)
|
|||
end
|
||||
end
|
||||
|
||||
-- htons(), htonl(), ntohs(), ntohl()
|
||||
|
||||
--- Convert given short value to network byte order on little endian hosts
|
||||
-- @param x Unsigned integer value between 0x0000 and 0xFFFF
|
||||
-- @return Byte-swapped value
|
||||
-- @see htonl
|
||||
-- @see ntohs
|
||||
function htons(x)
|
||||
if LITTLE_ENDIAN then
|
||||
return bit.bor(
|
||||
|
|
@ -67,6 +72,11 @@ function htons(x)
|
|||
end
|
||||
end
|
||||
|
||||
--- Convert given long value to network byte order on little endian hosts
|
||||
-- @param x Unsigned integer value between 0x00000000 and 0xFFFFFFFF
|
||||
-- @return Byte-swapped value
|
||||
-- @see htons
|
||||
-- @see ntohl
|
||||
function htonl(x)
|
||||
if LITTLE_ENDIAN then
|
||||
return bit.bor(
|
||||
|
|
@ -78,10 +88,31 @@ function htonl(x)
|
|||
end
|
||||
end
|
||||
|
||||
--- Convert given short value to host byte order on little endian hosts
|
||||
-- @param x Unsigned integer value between 0x0000 and 0xFFFF
|
||||
-- @return Byte-swapped value
|
||||
-- @see htonl
|
||||
-- @see ntohs
|
||||
ntohs = htons
|
||||
|
||||
--- Convert given short value to host byte order on little endian hosts
|
||||
-- @param x Unsigned integer value between 0x00000000 and 0xFFFFFFFF
|
||||
-- @return Byte-swapped value
|
||||
-- @see htons
|
||||
-- @see ntohl
|
||||
ntohl = htonl
|
||||
|
||||
|
||||
--- Parse given IPv4 address in dotted quad or CIDR notation. If an optional
|
||||
-- netmask is given as second argument and the IP address is encoded in CIDR
|
||||
-- notation then the netmask parameter takes precedence. If neither a CIDR
|
||||
-- encoded prefix nor a netmask parameter is given, then a prefix length of
|
||||
-- 32 bit is assumed.
|
||||
-- @param address IPv4 address in dotted quad or CIDR notation
|
||||
-- @param netmask IPv4 netmask in dotted quad notation (optional)
|
||||
-- @return luci.ip.cidr instance or nil if given address was invalid
|
||||
-- @see IPv6
|
||||
-- @see Hex
|
||||
function IPv4(address, netmask)
|
||||
address = address or "0.0.0.0/0"
|
||||
|
||||
|
|
@ -89,11 +120,11 @@ function IPv4(address, netmask)
|
|||
|
||||
local data = {}
|
||||
local prefix = address:match("/(.+)")
|
||||
address = address:gsub("/.+","")
|
||||
|
||||
if netmask then
|
||||
prefix = obj:prefix(netmask)
|
||||
elseif prefix then
|
||||
address = address:gsub("/.+","")
|
||||
prefix = tonumber(prefix)
|
||||
if not prefix or prefix < 0 or prefix > 32 then return nil end
|
||||
else
|
||||
|
|
@ -119,6 +150,16 @@ function IPv4(address, netmask)
|
|||
end
|
||||
end
|
||||
|
||||
--- Parse given IPv6 address in full, compressed, mixed or CIDR notation.
|
||||
-- If an optional netmask is given as second argument and the IP address is
|
||||
-- encoded in CIDR notation then the netmask parameter takes precedence.
|
||||
-- If neither a CIDR encoded prefix nor a netmask parameter is given, then a
|
||||
-- prefix length of 128 bit is assumed.
|
||||
-- @param address IPv6 address in full/compressed/mixed or CIDR notation
|
||||
-- @param netmask IPv6 netmask in full/compressed/mixed notation (optional)
|
||||
-- @return luci.ip.cidr instance or nil if given address was invalid
|
||||
-- @see IPv4
|
||||
-- @see Hex
|
||||
function IPv6(address, netmask)
|
||||
address = address or "::/0"
|
||||
|
||||
|
|
@ -126,11 +167,11 @@ function IPv6(address, netmask)
|
|||
|
||||
local data = {}
|
||||
local prefix = address:match("/(.+)")
|
||||
address = address:gsub("/.+","")
|
||||
|
||||
if netmask then
|
||||
prefix = obj:prefix(netmask)
|
||||
elseif prefix then
|
||||
address = address:gsub("/.+","")
|
||||
prefix = tonumber(prefix)
|
||||
if not prefix or prefix < 0 or prefix > 128 then return nil end
|
||||
else
|
||||
|
|
@ -147,7 +188,7 @@ function IPv6(address, netmask)
|
|||
if not borderh then break end
|
||||
|
||||
block = tonumber(address:sub(borderl, borderh - 1), 16)
|
||||
if block and block <= 65535 then
|
||||
if block and block <= 0xFFFF then
|
||||
table.insert(data, block)
|
||||
else
|
||||
if zeroh or borderh - borderl > 1 then return nil end
|
||||
|
|
@ -160,7 +201,7 @@ function IPv6(address, netmask)
|
|||
chunk = address:sub(borderl)
|
||||
if #chunk > 0 and #chunk <= 4 then
|
||||
block = tonumber(chunk, 16)
|
||||
if not block or block > 65535 then return nil end
|
||||
if not block or block > 0xFFFF then return nil end
|
||||
|
||||
table.insert(data, block)
|
||||
elseif #chunk > 4 then
|
||||
|
|
@ -198,6 +239,15 @@ function IPv6(address, netmask)
|
|||
end
|
||||
end
|
||||
|
||||
--- Transform given hex-encoded value to luci.ip.cidr instance of specified
|
||||
-- address family.
|
||||
-- @param hex String containing hex encoded value
|
||||
-- @param prefix Prefix length of CIDR instance (optional, default is 32/128)
|
||||
-- @param family Address family, either luci.ip.FAMILY_INET4 or FAMILY_INET6
|
||||
-- @param swap Bool indicating weather to swap byteorder on low endian host
|
||||
-- @return luci.ip.cidr instance or nil if given value was invalid
|
||||
-- @see IPv4
|
||||
-- @see IPv6
|
||||
function Hex( hex, prefix, family, swap )
|
||||
family = ( family ~= nil ) and family or FAMILY_INET4
|
||||
swap = ( swap == nil ) and true or swap
|
||||
|
|
@ -230,16 +280,29 @@ function Hex( hex, prefix, family, swap )
|
|||
end
|
||||
|
||||
|
||||
--- LuCI IP Library / CIDR instances
|
||||
-- @class module
|
||||
-- @name luci.ip.cidr
|
||||
cidr = luci.util.class()
|
||||
|
||||
--- Test weather the instance is a IPv4 address.
|
||||
-- @return Boolean indicating a IPv4 address type
|
||||
-- @see is6
|
||||
function cidr.is4( self )
|
||||
return self[1] == FAMILY_INET4
|
||||
end
|
||||
|
||||
--- Test weather the instance is a IPv6 address.
|
||||
-- @return Boolean indicating a IPv6 address type
|
||||
-- @see is4
|
||||
function cidr.is6( self )
|
||||
return self[1] == FAMILY_INET6
|
||||
end
|
||||
|
||||
--- Return a corresponding string representation of the instance.
|
||||
-- If the prefix length is lower then the maximum possible prefix length for the
|
||||
-- corresponding address type then the address is returned in CIDR notation,
|
||||
-- otherwise the prefix will be left out.
|
||||
function cidr.string( self )
|
||||
local str
|
||||
if self:is4() then
|
||||
|
|
@ -260,6 +323,13 @@ function cidr.string( self )
|
|||
return str
|
||||
end
|
||||
|
||||
--- Test weather the value of the instance is lower then the given address.
|
||||
-- This function will throw an exception if the given address has a different
|
||||
-- family than this instance.
|
||||
-- @param addr A luci.ip.cidr instance to compare against
|
||||
-- @return Boolean indicating weather this instance is lower
|
||||
-- @see higher
|
||||
-- @see equal
|
||||
function cidr.lower( self, addr )
|
||||
assert( self[1] == addr[1], "Can't compare IPv4 and IPv6 addresses" )
|
||||
for i = 1, #self[2] do
|
||||
|
|
@ -270,6 +340,13 @@ function cidr.lower( self, addr )
|
|||
return false
|
||||
end
|
||||
|
||||
--- Test weather the value of the instance is higher then the given address.
|
||||
-- This function will throw an exception if the given address has a different
|
||||
-- family than this instance.
|
||||
-- @param addr A luci.ip.cidr instance to compare against
|
||||
-- @return Boolean indicating weather this instance is higher
|
||||
-- @see lower
|
||||
-- @see equal
|
||||
function cidr.higher( self, addr )
|
||||
assert( self[1] == addr[1], "Can't compare IPv4 and IPv6 addresses" )
|
||||
for i = 1, #self[2] do
|
||||
|
|
@ -280,6 +357,13 @@ function cidr.higher( self, addr )
|
|||
return false
|
||||
end
|
||||
|
||||
--- Test weather the value of the instance is uequal to the given address.
|
||||
-- This function will throw an exception if the given address is a different
|
||||
-- family than this instance.
|
||||
-- @param addr A luci.ip.cidr instance to compare against
|
||||
-- @return Boolean indicating weather this instance is equal
|
||||
-- @see lower
|
||||
-- @see higher
|
||||
function cidr.equal( self, addr )
|
||||
assert( self[1] == addr[1], "Can't compare IPv4 and IPv6 addresses" )
|
||||
for i = 1, #self[2] do
|
||||
|
|
@ -290,6 +374,8 @@ function cidr.equal( self, addr )
|
|||
return true
|
||||
end
|
||||
|
||||
--- Return the prefix length of this CIDR instance.
|
||||
-- @return Prefix length in bit
|
||||
function cidr.prefix( self, mask )
|
||||
local prefix = self[3]
|
||||
|
||||
|
|
@ -322,6 +408,12 @@ function cidr.prefix( self, mask )
|
|||
return prefix
|
||||
end
|
||||
|
||||
--- Return a corresponding CIDR representing the network address of this
|
||||
-- instance.
|
||||
-- @param bits Override prefix length of this instance (optional)
|
||||
-- @return CIDR instance containing the network address
|
||||
-- @see host
|
||||
-- @see mask
|
||||
function cidr.network( self, bits )
|
||||
local data = { }
|
||||
bits = bits or self[3]
|
||||
|
|
@ -341,10 +433,20 @@ function cidr.network( self, bits )
|
|||
return __bless({ self[1], data, __length(self[1]) })
|
||||
end
|
||||
|
||||
--- Return a corresponding CIDR representing the host address of this
|
||||
-- instance. This is intended to extract the host address from larger subnet.
|
||||
-- @return CIDR instance containing the network address
|
||||
-- @see network
|
||||
-- @see mask
|
||||
function cidr.host( self )
|
||||
return __bless({ self[1], data, __length(self[1]) })
|
||||
end
|
||||
|
||||
--- Return a corresponding CIDR representing the netmask of this instance.
|
||||
-- @param bits Override prefix length of this instance (optional)
|
||||
-- @return CIDR instance containing the netmask
|
||||
-- @see network
|
||||
-- @see host
|
||||
function cidr.mask( self, bits )
|
||||
local data = { }
|
||||
bits = bits or self[3]
|
||||
|
|
@ -364,6 +466,9 @@ function cidr.mask( self, bits )
|
|||
return __bless({ self[1], data, __length(self[1]) })
|
||||
end
|
||||
|
||||
--- Test weather this instance fully contains the given CIDR instance.
|
||||
-- @param addr CIDR instance to test against
|
||||
-- @return Boolean indicating weather this instance contains the given CIDR
|
||||
function cidr.contains( self, addr )
|
||||
assert( self[1] == addr[1], "Can't compare IPv4 and IPv6 addresses" )
|
||||
|
||||
|
|
@ -374,6 +479,10 @@ function cidr.contains( self, addr )
|
|||
return false
|
||||
end
|
||||
|
||||
--- Add specified amount of hosts to this instance.
|
||||
-- @param amount Number of hosts to add to this instance
|
||||
-- @return CIDR representing the new address or nil on overflow error
|
||||
-- @see sub
|
||||
function cidr.add( self, amount )
|
||||
local shorts = { bit.rshift(amount, 16), bit.band(amount, 0xFFFF) }
|
||||
local data = { unpack(self[2]) }
|
||||
|
|
@ -394,3 +503,28 @@ function cidr.add( self, amount )
|
|||
|
||||
return __bless({ self[1], data, self[3] })
|
||||
end
|
||||
|
||||
--- Substract specified amount of hosts from this instance.
|
||||
-- @param amount Number of hosts to substract from this instance
|
||||
-- @return CIDR representing the new address or nil on underflow error
|
||||
-- @see add
|
||||
function cidr.sub( self, amount )
|
||||
local shorts = { bit.rshift(amount, 16), bit.band(amount, 0xFFFF) }
|
||||
local data = { unpack(self[2]) }
|
||||
|
||||
for pos = #data, 1, -1 do
|
||||
local sub = ( #shorts > 0 ) and table.remove( shorts, #shorts ) or 0
|
||||
if ( data[pos] - sub ) < 0 then
|
||||
data[pos] = ( sub - data[pos] ) % 0xFFFF
|
||||
if pos > 1 then
|
||||
data[pos-1] = data[pos-1] - ( sub + data[pos] )
|
||||
else
|
||||
return nil
|
||||
end
|
||||
else
|
||||
data[pos] = data[pos] - sub
|
||||
end
|
||||
end
|
||||
|
||||
return __bless({ self[1], data, self[3] })
|
||||
end
|
||||
|
|
|
|||
Loading…
Reference in a new issue