* luci/libs: added inline documentation and luci.ip.cidr.sub() to luci.ip; allow...

diff --git a/libs/core/luasrc/ip.lua b/libs/core/luasrc/ip.lua
index 761a781..a7e6bab 100644 (file)
--- 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")
 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,
        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    =
                __lt    = luci.ip.cidr.lower,
                __eq    = luci.ip.cidr.equal,
                __le    =


@@ -54,8 +56,11 @@ local function __length(family)
        end
 end
 
        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(
 function htons(x)
        if LITTLE_ENDIAN then
                return bit.bor(


@@ -67,6 +72,11 @@ function htons(x)
        end
 end
 
        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(
 function htonl(x)
        if LITTLE_ENDIAN then
                return bit.bor(


@@ -78,10 +88,31 @@ function htonl(x)
        end
 end
 
        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
 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
 
 
 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"
 
 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("/(.+)")
 
        local data = {}
        local prefix = address:match("/(.+)")

+       address = address:gsub("/.+","")

 
        if netmask then
                prefix = obj:prefix(netmask)
        elseif prefix then
 
        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
                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
 
        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"
 
 function IPv6(address, netmask)
        address = address or "::/0"
 


@@ -126,11 +167,11 @@ function IPv6(address, netmask)
 
        local data = {}
        local prefix = address:match("/(.+)")
 
        local data = {}
        local prefix = address:match("/(.+)")

+       address = address:gsub("/.+","")

 
        if netmask then
                prefix = obj:prefix(netmask)
        elseif prefix then
 
        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
                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 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
                        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)
        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
 
                table.insert(data, block)
        elseif #chunk > 4 then


@@ -198,6 +239,15 @@ function IPv6(address, netmask)
        end
 end
 
        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
 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
 
 
 end
 
 

+--- LuCI IP Library / CIDR instances
+-- @class      module
+-- @name       luci.ip.cidr

 cidr = luci.util.class()
 
 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
 
 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
 
 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
 function cidr.string( self )
        local str
        if self:is4() then


@@ -260,6 +323,13 @@ function cidr.string( self )
        return str
 end
 
        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
 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
 
        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
 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
 
        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
 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 true
 end
 

+--- Return the prefix length of this CIDR instance.
+-- @return     Prefix length in bit

 function cidr.prefix( self, mask )
        local prefix = self[3]
 
 function cidr.prefix( self, mask )
        local prefix = self[3]
 


@@ -322,6 +408,12 @@ function cidr.prefix( self, mask )
        return prefix
 end
 
        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]
 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 __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
 
 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]
 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
 
        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" )
 
 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
 
        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]) }
 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
 
        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