(export 'string-ipaddr)
(defun string-ipaddr (str &key (start 0) (end nil))
- "Parse STR as an IP address in dotted-quad form and return the integer
- equivalent. STR may be anything at all: it's converted as if by
- `stringify'. The START and END arguments may be used to parse out a
- substring."
+ "Parse STR into an address.
+
+ STR may be anything at all: it's converted as if by `stringify'.
+ The START and END arguments may be used to parse out a substring."
(setf str (stringify str))
(setf-default end (length str))
(let ((addr 0) (noct 0))
(typep ip 'ipaddr))
(defun ipaddr (ip)
- "Convert IP to an IP address. If it's an integer, return it unchanged;
- otherwise convert by `string-ipaddr'."
+ "Convert IP to an IP address.
+
+ If it's an integer, return it unchanged; otherwise convert by
+ `string-ipaddr'."
(typecase ip
(ipaddr ip)
(t (string-ipaddr ip))))
(export 'ipmask-cidl-slash)
(defun ipmask-cidl-slash (mask)
- "Given a netmask MASK, return an integer N such that (integer-netmask N) =
- MASK, or nil if this is impossible."
+ "Given a netmask MASK, try to compute a prefix length.
+
+ Return an integer N such that (integer-netmask N) = MASK, or nil if this
+ is impossible."
(dotimes (i 33)
(when (= mask (integer-netmask i))
(return i))))
(export 'with-ipnet)
(defmacro with-ipnet ((net mask) ipn &body body)
- "Evaluate BODY with NET and MASK bound to the base address and netmask of
- IPN. Either NET or MASK (or, less usefully, both) may be nil if not
- wanted."
+ "Evaluate the BODY with components of IPN in scope.
+
+ The NET is bound to the underlying network base address and MASK is bound
+ to the netmask, again as an integer. Either (or both) of these may be nil
+ if not wanted."
(with-gensyms tmp
`(let ((,tmp ,ipn))
(let (,@(and net `((,net (ipnet-net ,tmp))))
(export 'ipnet-host)
(defun ipnet-host (ipn host)
- "Return the address of the given HOST in network IPN. This works even with
- a non-contiguous netmask."
+ "Return the address of the given HOST in network IPN.
+
+ This works even with a non-contiguous netmask."
(check-type host u32)
(with-ipnet (net mask) ipn
(let ((i 0) (m 1) (a net) (h host))
(export 'parse-ipaddr)
(defun parse-ipaddr (addr)
- "Convert the string ADDR into an IP address: tries all sorts of things:
+ "Convert the string ADDR into an IP address.
+
+ Tries all sorts of things:
(NET [INDEX]) index a network: NET is a network name defined by
defnet; INDEX is an index or one of the special
(export 'net-get-as-ipnet)
(defun net-get-as-ipnet (form)
- "Transform FORM into an ipnet. FORM may be a network name, or something
-acceptable to the ipnet function."
+ "Transform FORM into an ipnet.
+
+ FORM may be a network name, or something acceptable to the ipnet
+ function."
(let ((net (net-find form)))
(if net (net-ipnet net)
(ipnet form))))
(defun process-net-form (root addr subnets)
- "Unpack a net-form. The return value is a list of entries, each of which
- is a list of the form (NAME ADDR MASK). The first entry is merely repeats
- the given ROOT and ADDR arguments (unpacking ADDR into separate network
- address and mask). The SUBNETS are then processed: they are a list of
- items of the form (NAME NUM-HOSTS . SUBNETS), where NAME names the subnet,
- NUM-HOSTS is the number of hosts in it, and SUBNETS are its sub-subnets in
- the same form. An error is signalled if a net's subnets use up more hosts
- than the net has to start with."
+ "Unpack a net-form.
+
+ The return value is a list of entries, each of which is a list of the form
+ (NAME ADDR MASK). The first entry is merely repeats the given ROOT and
+ ADDR arguments (unpacking ADDR into separate network address and mask).
+ The SUBNETS are then processed: they are a list of items of the form (NAME
+ NUM-HOSTS . SUBNETS), where NAME names the subnet, NUM-HOSTS is the number
+ of hosts in it, and SUBNETS are its sub-subnets in the same form. An
+ error is signalled if a net's subnets use up more hosts than the net has
+ to start with."
+
(labels ((frob (subnets limit finger)
(when subnets
(destructuring-bind (name size &rest subs) (car subnets)
(export 'net-create)
(defun net-create (name net)
- "Construct a new network called NAME and add it to the map. The ARGS
- describe the new network, in a form acceptable to the ipnet function."
+ "Construct a new network called NAME and add it to the map.
+
+ The ARGS describe the new network, in a form acceptable to the `ipnet'
+ function."
(let ((ipn (ipnet net)))
(setf (net-find name)
(make-net :name (string-downcase (stringify name))
(export 'defnet)
(defmacro defnet (name net &rest subnets)
- "Main network definition macro. None of the arguments is evaluated."
+ "Main network definition macro.
+
+ None of the arguments is evaluated."
`(progn
,@(loop for (name addr mask) in (process-net-form name net subnets)
collect `(net-create ',name '(,addr . ,mask)))
(export 'net-host)
(defun net-host (net host)
- "Return the given HOST on the NEXT. HOST may be an index (in range, of
- course), or one of the keywords:
+ "Return the given HOST on the NEXT.
+
+ HOST may be an index (in range, of course), or one of the keywords:
:NEXT next host, as by net-next-host
:NET network base address