X-Git-Url: https://git.distorted.org.uk/~mdw/zone/blobdiff_plain/8fcf1ae3524d2c7d914997b32c24ca697ab5a303..f4e0c48f17d3c959d3751faba9ce9cd0becfba41:/net.lisp

diff --git a/net.lisp b/net.lisp
index e764581..d5f4d76 100644
--- a/net.lisp
+++ b/net.lisp
@@ -54,10 +54,10 @@
 
 (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))
@@ -95,8 +95,10 @@
   (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))))
@@ -121,8 +123,10 @@
 
 (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))))
@@ -178,9 +182,11 @@
 
 (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))))
@@ -215,8 +221,9 @@
 
 (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))
@@ -261,7 +268,9 @@
 
 (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
@@ -343,21 +352,26 @@
 
 (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)
@@ -379,8 +393,10 @@ acceptable to the ipnet function."
 
 (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))
@@ -390,7 +406,9 @@ acceptable to the ipnet function."
 
 (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)))
@@ -408,8 +426,9 @@ acceptable to the ipnet function."
 
 (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