luci-lib-ip: add api documentation

Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>

1 files changed, 831 insertions, 0 deletions

diff --git a/libs/luci-lib-ip/src/ip.luadoc b/libs/luci-lib-ip/src/ip.luadoc
new file mode 100644
index 000000000..00738832c
--- /dev/null
+++ b/libs/luci-lib-ip/src/ip.luadoc
@@ -0,0 +1,831 @@
+--- LuCI IP calculation and netlink access library.
+module "luci.ip"
+
+---[[
+Construct a new luci.ip.cidr instance and autodetect the address family.
+Throws an error if the given strings do not represent a valid address or
+if the given optional netmask is of a different family.
+@class function
+@sort 1
+@name new
+@param address	String containing a valid IPv4 or IPv6 address, optionally
+with prefix size (CIDR notation) or netmask separated by slash.
+@param netmask	String containing a valid IPv4 or IPv6 netmask or number
+containing a prefix size in bits (`0..32` for IPv4,
+`0..128` for IPv6). Overrides mask embedded in the first argument
+if specified. (optional)
+@return A `luci.ip.cidr` object representing the given
+address/mask range.
+@usage `addr = luci.ip.new("10.24.0.1/24")
+addr = luci.ip.new("10.24.0.1/255.255.255.0")
+addr = luci.ip.new("10.24.0.1", "255.255.255.0")        -- separate netmask
+addr = luci.ip.new("10.24.0.1/24", 16)                  -- override netmask
+
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64")
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::")
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::")
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64", 128) -- override netmask`
+@see IPv4
+@see IPv6
+]]
+
+---[[
+Construct a new IPv4 luci.ip.cidr instance.
+Throws an error if the given string does not represent a valid IPv4 address or
+if the given optional netmask is of a different family.
+@class function
+@sort 2
+@name IPv4
+@param address	String containing a valid IPv4, optionally with prefix size
+(CIDR notation) or netmask separated by slash.
+@param netmask	String containing a valid IPv4 netmask or number
+containing a prefix size between `0` and `32` bit.
+Overrides mask embedded in the first argument if specified. (optional)
+@return A `luci.ip.cidr` object representing the given IPv4 range.
+@usage `addr = luci.ip.new("10.24.0.1/24")
+addr = luci.ip.new("10.24.0.1/255.255.255.0")
+addr = luci.ip.new("10.24.0.1", "255.255.255.0")        -- separate netmask
+addr = luci.ip.new("10.24.0.1/24", 16)                  -- override netmask`
+@see IPv6
+]]
+
+---[[
+Construct a new IPv6 luci.ip.cidr instance.
+Throws an error if the given string does not represent a valid IPv6 address or
+if the given optional netmask is of a different family.
+@class function
+@sort 3
+@name IPv6
+@param address	String containing a valid IPv6, optionally with prefix size
+(CIDR notation) or netmask separated by slash.
+@param netmask	String containing a valid IPv4 netmask or number
+containing a prefix size between `0` and `128` bit.
+Overrides mask embedded in the first argument if specified. (optional)
+@return A `luci.ip.cidr` object representing the given IPv6 range.
+@usage `addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64")
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/ffff:ffff:ffff:ffff::")
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17", "ffff:ffff:ffff:ffff::")
+addr6 = luci.ip.new("fe80::221:63ff:fe75:aa17/64", 128) -- override netmask`
+@see IPv4
+]]
+
+---[[
+Determine the route leading to the given destination.
+@class function
+@sort 4
+@name route
+@param address	A `luci.ip.cidr` instance or a string containing
+a valid IPv4 or IPv6 range as specified by `luci.ip.new()`.
+@return <p>Table containing the fields described below.</p>
+<table id="routetable">
+<tr><th>Field</th><th>Description</th></tr>
+<tr><td>`type`<td>
+  <p>Route type with one of the following numeric values:</p>
+  <table>
+  <tr>
+	<td>`1`</td>
+	<td>`RTN_UNICAST` - Gateway or direct route</td>
+  </tr>
+  <tr>
+	<td>`2`</td>
+	<td>`RTN_LOCAL` - Accept locally</td>
+  </tr>
+  <tr>
+	<td>`3`</td>
+	<td>`RTN_BROADCAST` -
+	    Accept locally as broadcast send as broadcast</td>
+  </tr>
+  <tr>
+	<td>`4`</td>
+	<td>`RTN_ANYCAST` -
+        Accept locally as broadcast but send as unicast</td>
+  </tr>
+  <tr>
+	<td>`5`</td>
+	<td>`RTN_MULTICAST` - Multicast route</td>
+  </tr>
+  </table>
+</td></tr>
+<tr>
+  <td>`family`</td>
+  <td>Number containing the route family, `4` for IPv4 or
+      `6` for IPv6</td>
+</tr>
+<tr>
+  <td>`dest`</td>
+  <td>Destination `luci.ip.cidr` instance</td>
+</tr>
+<tr>
+  <td>`gw`</td>
+  <td>Gateway `luci.ip.cidr` instance (optional)</td>
+</tr>
+<tr>
+  <td>`from`</td>
+  <td>Source address `luci.ip.cidr` instance (optional)</td>
+</tr>
+<tr>
+  <td>`src`</td>
+  <td>Preferred source `luci.ip.cidr` instance (optional)</td>
+</tr>
+<tr>
+  <td>`dev`</td>
+  <td>String containing the name of the outgoing interface</td>
+</tr>
+<tr>
+  <td>`iif`</td>
+  <td>String containing the name of the incoming interface (optional)</td>
+</tr>
+<tr>
+  <td>`table`</td>
+  <td>Number of the associated routing table (`0..65535`)</td>
+</tr>
+<tr>
+  <td>`proto`</td>
+  <td>Number of the associated routing protocol</td>
+</tr>
+<tr>
+  <td>`scope`</td>
+  <td>Number describing the scope of the route, most commonly
+      `0` for global or `253` for on-link</td>
+</tr>
+<tr>
+  <td>`metric`</td>
+  <td>Number describing the route metric (optional)</td>
+</tr>
+<tr>
+  <td>`expires`</td>
+  <td>Number of seconds the prefix is valid (IPv6 only, optional)</td>
+</tr>
+<tr>
+  <td>`error`</td>
+  <td>Route destination error code (optional)</td>
+</tr>
+</table>
+@usage <ul>
+<li>Find default gateway by getting route to Google's public NS server
+`rt = luci.ip.route("8.8.8.8")
+if rt ~= nil then
+	print("gateway is", rt.gw)
+end`</li>
+<li>Determine IPv6 upstream interface `rt = luci.ip.route("2001::/7")
+if rt ~= nil then
+	print("ipv6 upstream device is", rt.dev)
+end`</li>
+</ul>
+@see routes
+]]
+
+---[[
+Fetch all routes, optionally matching the given criteria.
+@class function
+@sort 5
+@name routes
+@param filter  <p>Table containing one or more of the possible filter
+critera described below (optional)</p><table>
+<tr><th>Field</th><th>Description</th></tr>
+<tr><td>`family`</td><td>
+ Number describing the address family to return - `4` selects
+ IPv4 routes, `6` IPv6 ones. Any other value selects both.
+</td></tr>
+<tr><td>`iif`</td><td>
+ String containing the incoming route interface to match.
+</td></tr>
+<tr><td>`oif`</td><td>
+ String containing the outgoing route interface to match.
+</td></tr>
+<tr><td>`type`</td><td>
+ Numeric type to match, e.g. `1` for unicast.
+</td></tr>
+<tr><td>`scope`</td><td>
+ Numeric scope to match, e.g. `253` for onlink.
+</td></tr>
+<tr><td>`proto`</td><td>
+ Numeric protocol to match, e.g. `2` for boot.
+</td></tr>
+<tr><td>`table`</td><td>
+ Numeric routing table to match (`0..65535`).
+</td></tr>
+<tr><td>`gw`</td><td>
+ String containing the gateway address to match. Can be in any notation
+ specified by `luci.ip.new()`. Prefix matching is performed when
+ comparing the routes, e.g. "192.168.1.0/24" would select routes with gateway
+ addresses `192.168.1.1 .. 192.168.1.255`.
+</td></tr>
+<tr><td>`dest`</td><td>
+ String containing the destination to match. Prefix matching is performed.
+</td></tr>
+<tr><td>`from`</td><td>
+ String containing the source address to match. Prefix matching is performed.
+</td></tr>
+<tr><td>`src`</td><td>
+ String containing the preferred source address to match.
+ Prefix matching is performed.
+</td></tr>
+<tr><td>`dest_exact`</td><td>
+ String containing the destination to match. Exact matching is performed,
+ e.g. `dest = "0.0.0.0/0"` would match <em>any</em> IPv4 route
+ while `dest_exact = "0.0.0.0/0"` will <em>only</em> match the
+ default route.
+</td></tr>
+<tr><td>`from_exact`</td><td>
+ String containing the source address to match. Exact matching is performed.
+</td></tr>
+</table>
+@param callback  <p>Callback function to invoke for each found route
+instead of returning one table of route objects (optional)</p>
+@return If no callback function is provided, a table of routes
+<a href="#routetable">as specified by `luci.ip.route()`</a>
+is returned. If a callback function is given, it is invoked for each route
+and nothing is returned.
+@see route
+@usage <ul>
+<li>Find all IPv4 default routes:
+`luci.ip.routes({ dest_exact = "0.0.0.0/0" }, function(rt)
+	print(rt.type, rt.gw, rt.dev)
+end)`</li>
+<li>Find all global IPv6 prefixes on the current system:
+`luci.ip.routes({ from = "2001::/7" }, function(rt)
+	print(rt.from)
+end)`</li>
+<li>Fetch all IPv4 routes:
+`routes = luci.ip.routes({ family = 4 })
+for _, rt in ipairs(routes) do
+	print(rt.dest, rt.gw, rt.dev)
+end`</li>
+</ul>
+]]
+
+---[[
+Fetches entries from the IPv4 ARP and IPv6 neighbour kernel table
+@class function
+@sort 6
+@name neighbors
+@param filter  <p>Table containing one or more of the possible filter
+critera described below (optional)</p><table>
+<tr><th>Field</th><th>Description</th></tr>
+<tr><td>`family`</td><td>
+ Number describing the address family to return - `4` selects
+ IPv4 ARP, `6` select IPv6 neighbour entries. Any other value
+ selects both.
+</td></tr>
+<tr><td>`dev`</td><td>
+ String containing the associated interface to match.
+</td></tr>
+<tr><td>`dest`</td><td>
+ String containing the associated address to match. Can be in any notation
+ specified by `luci.ip.new()`. Prefix matching is performed when
+ comparing the addresses, e.g. "192.168.1.0/24" would select ARP entries
+ for `192.168.1.1 .. 192.168.1.255`.
+</td></tr>
+<tr><td>`mac`</td><td>
+ String containing MAC address to match.
+</td></tr>
+</table>
+@param callback  <p>Callback function to invoke for each found neighbour
+entry instead of returning one table of neighbour entries (optional)</p>
+@return If no callback function is provided, a table of neighbour entries
+is returned. If a callback function is given, it is invoked for each entry
+and nothing is returned.
+
+A neighbour entry is a table containing the following fields:
+
+<table>
+<tr><th>Field</th><th>Description</th></tr>
+<tr>
+  <td>`family`</td>
+  <td>Number containing the neighbour entry family, `4` for IPv4
+      ARP or `6` for IPv6 NDP</td>
+</tr>
+<tr>
+  <td>`dev`</td>
+  <td>String containing the associated device of the neighbour entry</td>
+</tr>
+<tr>
+  <td>`dest`</td>
+  <td>IP address `luci.ip.cidr` instance</td>
+</tr>
+<tr>
+  <td>`mac`</td>
+  <td>String containing the associated MAC address</td>
+</tr>
+<tr>
+  <td>`router`</td>
+  <td>Boolean "true" if the neighbour entry is a router (IPv6, optional)</td>
+</tr>
+<tr>
+  <td>`proxy`</td>
+  <td>Boolean "true" if this is a proxy entry (optional)</td>
+</tr>
+<tr>
+  <td>`incomplete`</td>
+  <td>Boolean "true" if the entry is in incomplete state (optional)</td>
+</tr>
+<tr>
+  <td>`reachable`</td>
+  <td>Boolean "true" if the entry is in reachable state (optional)</td>
+</tr>
+<tr>
+  <td>`stale`</td>
+  <td>Boolean "true" if the entry is stale (optional)</td>
+</tr>
+<tr>
+  <td>`delay`</td>
+  <td>Boolean "true" if the entry is delayed (optional)</td>
+</tr>
+<tr>
+  <td>`probe`</td>
+  <td>Boolean "true" if the entry is in probe state (optional)</td>
+</tr>
+<tr>
+  <td>`failed`</td>
+  <td>Boolean "true" if the entry is in failed state (optional)</td>
+</tr>
+<tr>
+  <td>`noarp`</td>
+  <td>Boolean "true" if the entry is not caused by NDP or
+      ARP (optional)</td>
+</tr>
+<tr>
+  <td>`permanent`</td>
+  <td>Boolean "true" if the entry was statically configured from
+      userspace (optional)</td>
+</tr>
+</table>
+@usage <ul>
+<li>Find all ARP neighbours in the LAN:
+`luci.ip.neighbors({ dest = "192.168.0.0/16" }, function(n)
+	print(n.dest, n.mac)
+end)`</li>
+<li>Find all active IPv6 addresses of host with given MAC:
+`luci.ip.neighbors({ family = 6, mac = "00:21:63:75:aa:17" },
+	function(n)
+		print(n.dest)
+	end)`</li>
+</ul>
+]]
+
+---[[
+Fetch basic device information
+@class function
+@sort 7
+@name link
+@param device  String containing the network device to query
+@return  If the given interface is found, a table containing the fields
+described below is returned, else an empty table.
+
+<table>
+<tr><th>Field</th><th>Description</th></tr>
+<tr>
+  <td>`up`</td>
+  <td>Boolean indicating whether the device is in IFF_RUNNING state</td>
+</tr>
+<tr>
+  <td>`type`</td>
+  <td>Numeric value indicating the type of the device, e.g. `1`
+      for ethernet.</td>
+</tr>
+<tr>
+  <td>`name`</td>
+  <td>String containing the name of the device</td>
+</tr>
+<tr>
+  <td>`master`</td>
+  <td>If queried device is a bridge port, string containing the name of
+      parent bridge device (optional)</td>
+</tr>
+<tr>
+  <td>`mtu`</td>
+  <td>Number containing the current MTU of the device</td>
+</tr>
+<tr>
+  <td>`qlen`</td>
+  <td>Number containing the TX queue length of the device</td>
+</tr>
+<tr>
+  <td>`mac`</td>
+  <td>String containing the link local address of the device in
+      dotted hex notation</td>
+</tr>
+</table>
+@usage <ul>
+<li>Test whether device br-lan exists:
+`print(luci.ip.link("br-lan").name ~= nil)
+`</li>
+<li>Query MAC address of eth0:
+`print(luci.ip.link("eth0").mac)
+`</li>
+</ul>
+]]
+
+
+--- IP CIDR Object.
+-- Represents an IPv4 or IPv6 address range.
+-- @cstyle instance
+module "luci.ip.cidr"
+
+---[[
+Checks whether the CIDR instance is an IPv4 address range
+
+@class function
+@sort 1
+@name cidr.is4
+@see cidr.is6
+@return `true` if the CIDR is an IPv4 range, else `false`
+]]
+
+---[[
+Checks whether the CIDR instance is within the private RFC1918 address space
+
+@class function
+@sort 2
+@name cidr.is4rfc1918
+@return `true` if the entire range of this CIDR lies within one of
+	the ranges `10.0.0.0-10.255.255.255`,
+	`172.16.0.0-172.31.0.0` or
+	`192.168.0.0-192.168.255.255`, else `false`.
+@usage `local addr = luci.ip.new("192.168.45.2/24")
+if addr:is4rfc1918() then
+	print("Is a private address")
+end`
+]]
+
+---[[
+Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
+
+@class function
+@sort 3
+@name cidr.is4linklocal
+@return `true` if the entire range of this CIDR lies within the range
+	the range `169.254.0.0-169.254.255.255`, else `false`.
+@usage `local addr = luci.ip.new("169.254.34.125")
+if addr:is4linklocal() then
+	print("Is a zeroconf address")
+end`
+]]
+
+---[[
+Checks whether the CIDR instance is an IPv6 address range
+
+@class function
+@sort 4
+@name cidr.is6
+@see cidr.is4
+@return `true` if the CIDR is an IPv6 range, else `false`
+]]
+
+---[[
+Checks whether the CIDR instance is an IPv6 link local address
+
+@class function
+@sort 5
+@name cidr.is6linklocal
+@return `true` if the entire range of this CIDR lies within the range
+	the `fe80::/10` range, else `false`.
+@usage `local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
+if addr:is6linklocal() then
+	print("Is a linklocal address")
+end`
+]]
+
+---[[
+Checks whether the CIDR instance is an IPv6 mapped IPv4 address
+
+@class function
+@sort 6
+@name cidr.is6mapped4
+@return `true` if the address is an IPv6 mapped IPv4 address in the
+	form `::ffff:1.2.3.4`.
+@usage `local addr = luci.ip.new("::ffff:192.168.1.1")
+if addr:is6mapped4() then
+	print("Is a mapped IPv4 address")
+end`
+]]
+
+---[[
+Checks whether this CIDR instance is lower than the given argument.
+The comparisation follows these rules:
+<ul><li>An IPv4 address is always lower than an IPv6 address</li>
+<li>Prefix sizes are ignored</li></ul>
+
+@class function
+@sort 7
+@name cidr.lower
+@param addr A `luci.ip.cidr` instance or a string convertable by
+	`luci.ip.new()` to compare against.
+@return `true` if this CIDR is lower than the given address,
+	else `false`.
+@usage `local addr = luci.ip.new("192.168.1.1")
+print(addr:lower(addr)) -- false
+print(addr:lower("10.10.10.10/24")) -- false
+print(addr:lower(luci.ip.new("::1"))) -- true
+print(addr:lower(luci.ip.new("192.168.200.1"))) -- true`
+@see cidr.higher
+@see cidr.equal
+]]
+
+---[[
+Checks whether this CIDR instance is higher than the given argument.
+The comparisation follows these rules:
+<ul><li>An IPv4 address is always lower than an IPv6 address</li>
+<li>Prefix sizes are ignored</li></ul>
+
+@class function
+@sort 8
+@name cidr.higher
+@param addr A `luci.ip.cidr` instance or a string convertable by
+	`luci.ip.new()` to compare against.
+@return `true` if this CIDR is higher than the given address,
+	else `false`.
+@usage `local addr = luci.ip.new("192.168.1.1")
+print(addr:higher(addr)) -- false
+print(addr:higher("10.10.10.10/24")) -- true
+print(addr:higher(luci.ip.new("::1"))) -- false
+print(addr:higher(luci.ip.new("192.168.200.1"))) -- false`
+@see cidr.lower
+@see cidr.equal
+]]
+
+---[[
+Checks whether this CIDR instance is equal to the given argument.
+
+@class function
+@sort 9
+@name cidr.equal
+@param addr A `luci.ip.cidr` instance or a string convertable by
+	`luci.ip.new()` to compare against.
+@return `true` if this CIDR is equal to the given address,
+	else `false`.
+@usage `local addr = luci.ip.new("192.168.1.1")
+print(addr:equal(addr)) -- true
+print(addr:equal("192.168.1.1")) -- true
+print(addr:equal(luci.ip.new("::1"))) -- false
+
+local addr6 = luci.ip.new("::1")
+print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
+print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false`
+@see cidr.lower
+@see cidr.higher
+]]
+
+---[[
+Get or set prefix size of CIDR instance.
+If the optional mask parameter is given, the prefix size of this CIDR is altered
+else the current prefix size is returned.
+
+@class function
+@sort 10
+@name cidr.prefix
+@param mask Either a number containing the number of bits (`0..32`
+	for IPv4, `0..128` for IPv6) or a string containing a valid
+	netmask (optional)
+@return Bit count of the current prefix size
+@usage `local range = luci.ip.new("192.168.1.1/255.255.255.0")
+print(range:prefix()) -- 24
+
+range:prefix(16)
+print(range:prefix()) -- 16
+
+range:prefix("255.255.255.255")
+print(range:prefix()) -- 32`
+]]
+
+---[[
+Derive network address of CIDR instance.
+
+Returns a new CIDR instance representing the network address of this instance
+with all host parts masked out. The used prefix size can be overridden by the
+optional mask parameter.
+
+@class function
+@sort 11
+@name cidr.network
+@param mask Either a number containing the number of bits (`0..32`
+	for IPv4, `0..128` for IPv6) or a string containing a valid
+	netmask (optional)
+@return CIDR instance representing the network address
+@usage `local range = luci.ip.new("192.168.62.243/255.255.0.0")
+print(range:network())                -- "192.168.0.0"
+print(range:network(24))              -- "192.168.62.0"
+print(range:network("255.255.255.0")) -- "192.168.62.0"
+
+local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
+print(range6:network())               -- "fd9b:62b3:9cc5::"`
+]]
+
+---[[
+Derive host address of CIDR instance.
+
+This function essentially constructs a copy of this CIDR with the prefix size
+set to `32` for IPv4 and `128` for IPv6.
+
+@class function
+@sort 12
+@name cidr.host
+@return CIDR instance representing the host address
+@usage `local range = luci.ip.new("172.19.37.45/16")
+print(range)        -- "172.19.37.45/16"
+print(range:host()) -- "172.19.37.45"`
+]]
+
+---[[
+Derive netmask of CIDR instance.
+
+Constructs a CIDR instance representing the netmask of this instance. The used
+prefix size can be overridden by the optional mask parameter.
+
+@class function
+@sort 13
+@name cidr.mask
+@param mask Either a number containing the number of bits (`0..32`
+	for IPv4, `0..128` for IPv6) or a string containing a valid
+	netmask (optional)
+@return CIDR instance representing the netmask
+@usage `local range = luci.ip.new("172.19.37.45/16")
+print(range:mask())            -- "255.255.0.0"
+print(range:mask(24))          -- "255.255.255.0"
+print(range:mask("255.0.0.0")) -- "255.0.0.0"`
+]]
+
+---[[
+Derive broadcast address of CIDR instance.
+
+Constructs a CIDR instance representing the broadcast address of this instance.
+The used prefix size can be overridden by the optional mask parameter.
+
+This function has no effect on IPv6 instances, it will return nothing in this
+case.
+
+@class function
+@sort 14
+@name cidr.broadcast
+@param mask Either a number containing the number of bits (`0..32`
+	for IPv4, `0..128` for IPv6) or a string containing a valid
+	netmask (optional)
+@return Return a new CIDR instance representing the broadcast address if this
+	instance is an IPv4 range, else return nothing.
+@usage `local range = luci.ip.new("172.19.37.45/16")
+print(range:broadcast())            -- "172.19.255.255"
+print(range:broadcast(24))          -- "172.19.37.255"
+print(range:broadcast("255.0.0.0")) -- "172.255.255.255"`
+]]
+
+---[[
+Derive mapped IPv4 address of CIDR instance.
+
+Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
+IPv4 address in this instance.
+
+This function has no effect on IPv4 instances or IPv6 instances which are not a
+mapped address, it will return nothing in this case.
+
+@class function
+@sort 15
+@name cidr.mapped4
+@return Return a new CIDR instance representing the IPv4 address if this
+	instance is an IPv6 mapped IPv4 address, else return nothing.
+@usage `local addr = luci.ip.new("::ffff:172.16.19.1")
+print(addr:mapped4()) -- "172.16.19.1"`
+]]
+
+---[[
+Test whether CIDR contains given range.
+
+@class function
+@sort 16
+@name cidr.contains
+@param addr A `luci.ip.cidr` instance or a string convertable by
+	`luci.ip.new()` to test.
+@return `true` if this instance fully contains the given address else
+	`false`.
+@usage `local range = luci.ip.new("10.24.0.0/255.255.0.0")
+print(range:contains("10.24.5.1"))  -- true
+print(range:contains("::1"))        -- false
+print(range:contains("10.0.0.0/8")) -- false
+
+local range6 = luci.ip.new("fe80::/10")
+print(range6:contains("fe80::221:63f:fe75:aa17/64"))         -- true
+print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false`
+]]
+
+---[[
+Add given amount to CIDR instance. If the result would overflow the maximum
+address space, the result is set to the highest possible address.
+
+@class function
+@sort 17
+@name cidr.add
+@param amount A numeric value between 0 and 0xFFFFFFFF, a
+	`luci.ip.cidr` instance or a string convertable by
+	`luci.ip.new()`.
+@param inplace If `true`, modify this instance instead of returning
+	a new derived CIDR instance.
+@return <ul>
+	<li>When adding inplace: Return `true` if the addition succeded
+	    or `false` when the addition overflowed.</li>
+	<li>When deriving new CIDR: Return new instance representing the value of
+        this instance plus the added amount or the highest possible address if
+	    the addition overflowed the available address space.</li></ul>
+@usage `local addr = luci.ip.new("192.168.1.1/24")
+print(addr:add(250))         -- "192.168.1.251/24"
+print(addr:add("0.0.99.0"))  -- "192.168.100.1/24"
+
+addr:add(256, true)          -- true
+print(addr)                  -- "192.168.2.1/24
+
+addr:add("255.0.0.0", true)  -- false (overflow)
+print(addr)                  -- "255.255.255.255/24
+
+local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
+print(addr6:add(256))        -- "fe80::221:63f:fe75:ab17/64"
+print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
+
+addr:add(256, true)          -- true
+print(addr)                  -- "fe80::221:63f:fe75:ab17/64
+
+addr:add("ffff::", true)     -- false (overflow)
+print(addr)                  -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"`
+]]
+
+---[[
+Substract given amount from CIDR instance. If the result would under, the lowest
+possible address is returned.
+
+@class function
+@sort 18
+@name cidr.sub
+@param amount A numeric value between 0 and 0xFFFFFFFF, a
+	`luci.ip.cidr` instance or a string convertable by
+	`luci.ip.new()`.
+@param inplace If `true`, modify this instance instead of returning
+	a new derived CIDR instance.
+@return <ul>
+	<li>When substracting inplace: Return `true` if the substraction
+	    succeded or `false` when the substraction underflowed.</li>
+	<li>When deriving new CIDR: Return new instance representing the value of
+        this instance minus the substracted amount or the lowest address if
+	    the substraction underflowed.</li></ul>
+@usage `local addr = luci.ip.new("192.168.1.1/24")
+print(addr:sub(256))         -- "192.168.0.1/24"
+print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
+
+addr:sub(256, true)          -- true
+print(addr)                  -- "192.168.0.1/24
+
+addr:sub("255.0.0.0", true)  -- false (underflow)
+print(addr)                  -- "0.0.0.0/24
+
+local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
+print(addr6:sub(256))        -- "fe80::221:63f:fe75:a917/64"
+print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
+
+addr:sub(256, true)          -- true
+print(addr)                  -- "fe80::221:63f:fe75:a917/64"
+
+addr:sub("ffff::", true)     -- false (underflow)
+print(addr)                  -- "::/64"`
+]]
+
+---[[
+Calculate the lowest possible host address within this CIDR instance.
+
+@class function
+@sort 19
+@name cidr.minhost
+@return Returns a new CIDR instance representing the lowest host address
+	within this range.
+@usage `local addr = luci.ip.new("192.168.123.56/24")
+print(addr:minhost())  -- "192.168.123.1"
+
+local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
+print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"`
+]]
+
+---[[
+Calculate the highest possible host address within this CIDR instance.
+
+@class function
+@sort 20
+@name cidr.maxhost
+@return Returns a new CIDR instance representing the highest host address
+	within this range.
+@usage `local addr = luci.ip.new("192.168.123.56/24")
+print(addr:maxhost())  -- "192.168.123.254" (.255 is broadcast)
+
+local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
+print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"`
+]]
+
+---[[
+Convert CIDR instance into string representation.
+
+If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, the
+address is returned in the form "address/prefix" otherwise just "address".
+
+It is usually not required to call this function directly as CIDR objects
+define it as __tostring function in the associated metatable.
+
+@class function
+@sort 21
+@name cidr.string
+@return Returns a string representing the range or address of this CIDR instance
+]]