From: Jo-Philipp Wich Date: Fri, 8 Aug 2008 19:06:37 +0000 (+0000) Subject: * luci/libs: added inline documentation and luci.ip.cidr.sub() to luci.ip; allow... X-Git-Tag: 0.8.0~492 X-Git-Url: https://git.archive.openwrt.org/?p=project%2Fluci.git;a=commitdiff_plain;h=9592b80af66f27ebce7804673ae7535549c3c49a * luci/libs: added inline documentation and luci.ip.cidr.sub() to luci.ip; allow CIDR notation _and_ netmask argument in IPv4() and IPv6() constructors --- diff --git a/libs/core/luasrc/ip.lua b/libs/core/luasrc/ip.lua index 761a78110..a7e6bab65 100644 --- a/libs/core/luasrc/ip.lua +++ b/libs/core/luasrc/ip.lua @@ -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