From 2f1d381d7cf464f2ce50d6754a538d9e0fc89876 Mon Sep 17 00:00:00 2001 Message-Id: <2f1d381d7cf464f2ce50d6754a538d9e0fc89876.1714049873.git.mdw@distorted.org.uk> From: Mark Wooding Date: Sun, 23 Apr 2006 16:23:03 +0100 Subject: [PATCH] Reformat the docstrings. Organization: Straylight/Edgeware From: Mark Wooding --- net.lisp | 87 ++++++++++++++++++++++++++++++------------------------- zone.lisp | 87 ++++++++++++++++++++++++++++--------------------------- 2 files changed, 91 insertions(+), 83 deletions(-) diff --git a/net.lisp b/net.lisp index 9e893c1..35e4340 100644 --- a/net.lisp +++ b/net.lisp @@ -71,9 +71,9 @@ (defun count-low-zero-bits (n) (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." + 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." (setf str (stringify str)) (unless end (setf end (length str))) @@ -110,7 +110,7 @@ (defun ipaddrp (ip) (defun ipaddr (ip) "Convert IP to an IP address. If it's an integer, return it unchanged; -otherwise convert by `string-ipaddr'." + otherwise convert by `string-ipaddr'." (typecase ip (ipaddr ip) (t (string-ipaddr ip)))) @@ -124,8 +124,8 @@ (defun integer-netmask (i) (defun ipmask (ip) "Transform IP into a netmask. If it's a small integer then it's converted -by `integer-netmask'; if nil, then all-bits-set; otherwise convert using -`ipaddr'." + by `integer-netmask'; if nil, then all-bits-set; otherwise convert using + `ipaddr'." (typecase ip (null (mask 32)) ((integer 0 32) (integer-netmask ip)) @@ -133,7 +133,7 @@ (defun ipmask (ip) (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." + MASK, or nil if this is impossible." (dotimes (i 33) (when (= mask (integer-netmask i)) (return i)))) @@ -143,7 +143,7 @@ (defun ipmask-cidl-slash (mask) (defun make-ipnet (net mask) "Construct an IP-network object given the NET and MASK; these are -transformed as though by `ipaddr' and `ipmask'." + transformed as though by `ipaddr' and `ipmask'." (let ((net (ipaddr net)) (mask (ipmask mask))) (cons (logand net mask) mask))) @@ -164,12 +164,13 @@ (defun string-ipnet (str &key (start 0) (end nil)) (integer-netmask 32))))) (defun ipnet (net) - "Construct an IP-network object from the given argument. A number of -forms are acceptable: + "Construct an IP-network object from the given argument. A number of forms + are acceptable: - * ADDR -- a single address (equivalent to ADDR 32) - * (NET . MASK|nil) -- a single-object representation. - * IPNET -- return an equivalent (`equal', not necessarily `eql') version." + * ADDR -- a single address (equivalent to ADDR 32) + * (NET . MASK|nil) -- a single-object representation. + * IPNET -- return an equivalent (`equal', not necessarily `eql') + version." (cond ((or (stringp net) (symbolp net)) (string-ipnet net)) (t (apply #'make-ipnet (pairify net 32))))) @@ -183,7 +184,8 @@ (defun ipnet-mask (ipn) (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." + IPN. Either NET or MASK (or, less usefully, both) may be nil if not + wanted." (with-gensyms tmp `(let ((,tmp ,ipn)) (let (,@(and net `((,net (ipnet-net ,tmp)))) @@ -214,7 +216,7 @@ (defun ipnet-hosts (ipn) (defun ipnet-host (ipn host) "Return the address of the given HOST in network IPN. This works even with -a non-contiguous netmask." + a non-contiguous netmask." (check-type host u32) (with-ipnet (net mask) ipn (let ((i 0) (m 1) (a net) (h host)) @@ -246,7 +248,7 @@ (defun ipnet-subnetp (ipn subn) (defun ipnet-changeable-bytes (mask) "Answers how many low-order bytes of MASK are (entirely or partially) -changeable. This is used when constructing reverse zones." + changeable. This is used when constructing reverse zones." (dotimes (i 4 4) (when (/= (ipaddr-byte mask i) 255) (return (- 4 i))))) @@ -274,13 +276,17 @@ (defun canonify-hostname (name) (defun parse-ipaddr (addr) "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 symbols understood by net-host, - and defaults to :next - INTEGER -- an integer IP address - IPADDR -- an IP address in dotted-quad form - HOST -- a host name defined by defhost - DNSNAME -- a name string to look up in the DNS" + (NET [INDEX]) index a network: NET is a network name defined by + defnet; INDEX is an index or one of the special + symbols understood by net-host, and defaults to :next + + INTEGER an integer IP address + + IPADDR an IP address in dotted-quad form + + HOST a host name defined by defhost + + DNSNAME a name string to look up in the DNS" (cond ((listp addr) (destructuring-bind (net host) @@ -325,10 +331,10 @@ (defmacro defhost (name addr) (defstruct (net (:predicate netp)) "A network structure. Slots: -NAME The network's name, as a string -IPNET The network base address and mask -HOSTS Number of hosts in the network -NEXT Index of the next unassigned host" + NAME The network's name, as a string + IPNET The network base address and mask + HOSTS Number of hosts in the network + NEXT Index of the next unassigned host" name ipnet hosts @@ -354,13 +360,13 @@ (defun net-get-as-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." + 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) @@ -382,7 +388,7 @@ (defun process-net-form (root addr subnets) (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." + 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)) @@ -399,7 +405,7 @@ (defmacro defnet (name net &rest subnets) (defun net-next-host (net) "Given a NET, return the IP address (as integer) of the next available -address in the network." + address in the network." (unless (< (net-next net) (net-hosts net)) (error "No more hosts left in network ~A" (net-name net))) (let ((next (net-next net))) @@ -408,10 +414,11 @@ (defun net-next-host (net) (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: -:NEXT next host, as by net-next-host -:NET network base address -:BROADCAST network broadcast address" + course), or one of the keywords: + + :NEXT next host, as by net-next-host + :NET network base address + :BROADCAST network broadcast address" (case host (:next (net-next-host net)) (:net (ipnet-net (net-ipnet net))) diff --git a/zone.lisp b/zone.lisp index 79c6c19..35e6f80 100644 --- a/zone.lisp +++ b/zone.lisp @@ -49,7 +49,7 @@ (defun to-integer (x) (defun from-mixed-base (base val) "BASE is a list of the ranges for the `digits' of a mixed-base -representation. Convert VAL, a list of digits, into an integer." + representation. Convert VAL, a list of digits, into an integer." (do ((base base (cdr base)) (val (cdr val) (cdr val)) (a (car val) (+ (* a (car base)) (car val)))) @@ -57,7 +57,7 @@ (defun from-mixed-base (base val) (defun to-mixed-base (base val) "BASE is a list of the ranges for the `digits' of a mixed-base -representation. Convert VAL, an integer, into a list of digits." + representation. Convert VAL, an integer, into a list of digits." (let ((base (reverse base)) (a nil)) (loop @@ -70,8 +70,8 @@ (defun to-mixed-base (base val) (defun timespec-seconds (ts) "Convert a timespec TS to seconds. A timespec may be a real count of -seconds, or a list (COUNT UNIT): UNIT may be any of a number of obvious time -units." + seconds, or a list (COUNT UNIT): UNIT may be any of a number of obvious + time units." (cond ((null ts) 0) ((realp ts) (floor ts)) ((atom ts) @@ -99,9 +99,9 @@ (defun hash-table-keys (ht) (defun iso-date (&optional time &key datep timep (sep #\ )) "Construct a textual date or time in ISO format. The TIME is the universal -time to convert, which defaults to now; DATEP is whether to emit the date; -TIMEP is whether to emit the time, and SEP (default is space) is how to -separate the two." + time to convert, which defaults to now; DATEP is whether to emit the date; + TIMEP is whether to emit the time, and SEP (default is space) is how to + separate the two." (multiple-value-bind (sec min hr day mon yr dow dstp tz) (decode-universal-time (if (or (null time) (eq time :now)) @@ -175,7 +175,7 @@ (defvar *default-mx-priority* 50 (defun make-zone-serial (name) "Given a zone NAME, come up with a new serial number. This will (very -carefully) update a file ZONE.serial in the current directory." + carefully) update a file ZONE.serial in the current directory." (let* ((file (format nil "~(~A~).serial" name)) (last (with-open-file (in file :direction :input @@ -223,7 +223,7 @@ (defsubp nil) (defstruct (zone-subdomain (:conc-name zs-)) "A subdomain. Slightly weird. Used internally by zone-process-records -below, and shouldn't escape." + below, and shouldn't escape." name ttl records) @@ -233,7 +233,7 @@ (defstruct (zone-subdomain (:conc-name zs-)) (defun zone-process-records (rec ttl func) "Sort out the list of records in REC, calling FUNC for each one. TTL is -the default time-to-live for records which don't specify one." + the default time-to-live for records which don't specify one." (labels ((sift (rec ttl) (collecting (top sub) (loop @@ -283,7 +283,7 @@ (defun zone-process-records (rec ttl func) (defun zone-parse-host (f zname) "Parse a host name F: if F ends in a dot then it's considered absolute; -otherwise it's relative to ZNAME." + otherwise it's relative to ZNAME." (setf f (stringify f)) (cond ((string= f "@") (stringify zname)) ((and (plusp (length f)) @@ -293,7 +293,7 @@ (defun zone-parse-host (f zname) (stringify zname)))))) (defun default-rev-zone (base bytes) "Return the default reverse-zone name for the given BASE address and number -of fixed leading BYTES." + of fixed leading BYTES." (join-strings #\. (collecting () (loop for i from (- 3 bytes) downto 0 do (collect (ipaddr-byte base i))) @@ -301,7 +301,7 @@ (defun default-rev-zone (base bytes) (defun zone-name-from-net (net &optional bytes) "Given a NET, and maybe the BYTES to use, convert to the appropriate -subdomain of in-addr.arpa." + subdomain of in-addr.arpa." (let ((ipn (net-get-as-ipnet net))) (with-ipnet (net mask) ipn (unless bytes @@ -341,8 +341,8 @@ (defun zone-net-from-name (name) (defun zone-reverse-records (records net list bytes dom) "Construct a reverse zone given a forward zone's RECORDS list, the NET that -the reverse zone is to serve, a LIST to collect the records into, how -many BYTES of data need to end up in the zone, and the DOM-ain suffix." + the reverse zone is to serve, a LIST to collect the records into, how many + BYTES of data need to end up in the zone, and the DOM-ain suffix." (dolist (zr records) (when (and (eq (zr-type zr) :a) (not (zr-defsubp zr)) @@ -363,7 +363,7 @@ (defun zone-reverse-records (records net list bytes dom) (defun zone-reverse (data name list) "Process a :reverse record's DATA, for a domain called NAME, and add the -records to the LIST." + records to the LIST." (destructuring-bind (net &key bytes zones) (listify data) @@ -378,15 +378,15 @@ (defun zone-reverse (data name list) name)))) (defun zone-parse-net (net name) - "Given a NET, and the NAME of a domain to guess from if NET is null, -return the ipnet for the network." + "Given a NET, and the NAME of a domain to guess from if NET is null, return + the ipnet for the network." (if net (net-get-as-ipnet net) (zone-net-from-name name))) (defun zone-cidr-delg-default-name (ipn bytes) "Given a delegated net IPN and the parent's number of changing BYTES, -return the default deletate zone prefix." + return the default deletate zone prefix." (with-ipnet (net mask) ipn (join-strings #\. (reverse @@ -397,7 +397,7 @@ (defun zone-cidr-delg-default-name (ipn bytes) (defun zone-cidr-delegation (data name ttl list) "Given :cidr-delegation info DATA, for a record called NAME and the current -TTL, write lots of CNAME records to LIST." + TTL, write lots of CNAME records to LIST." (destructuring-bind (net &key bytes) (listify (car data)) @@ -444,8 +444,8 @@ (defun zone-parse-head (head) (NAME &key :source :admin :refresh :retry :expire :min-ttl :ttl :serial) -though a singleton NAME needn't be a list. Returns the default TTL and an -soa structure representing the zone head." + though a singleton NAME needn't be a list. Returns the default TTL and an + soa structure representing the zone head." (destructuring-bind (zname &key @@ -475,30 +475,31 @@ (defmacro defzoneparse (types (name data list (defsubp (gensym "DEFSUBP"))) &body body) "Define a new zone record type (or TYPES -- a list of synonyms is -permitted). The arguments are as follows: + permitted). The arguments are as follows: -NAME The name of the record to be added. + NAME The name of the record to be added. -DATA The content of the record to be added (a single object, unevaluated). + DATA The content of the record to be added (a single object, + unevaluated). -LIST A function to add a record to the zone. See below. + LIST A function to add a record to the zone. See below. -ZNAME The name of the zone being constructed. + ZNAME The name of the zone being constructed. -TTL The TTL for this record. + TTL The TTL for this record. -DEFSUBP Whether this is the default subdomain for this entry. + DEFSUBP Whether this is the default subdomain for this entry. -You get to choose your own names for these. ZNAME, TTL and DEFSUBP are -optional: you don't have to accept them if you're not interested. + You get to choose your own names for these. ZNAME, TTL and DEFSUBP are + optional: you don't have to accept them if you're not interested. -The LIST argument names a function to be bound in the body to add a new -low-level record to the zone. It has the prototype + The LIST argument names a function to be bound in the body to add a new + low-level record to the zone. It has the prototype - (LIST &key :name :type :data :ttl :defsubp) + (LIST &key :name :type :data :ttl :defsubp) -Except for defsubp, these default to the above arguments (even if you didn't -accept the arguments)." + Except for defsubp, these default to the above arguments (even if you + didn't accept the arguments)." (setf types (listify types)) (let* ((type (car types)) (func (intern (format nil "ZONE-PARSE/~:@(~A~)" type)))) @@ -557,12 +558,12 @@ (defun zone-parse-records (zone records) (defun zone-parse (zf) "Parse a ZONE form. The syntax of a zone form is as follows: -ZONE-FORM: - ZONE-HEAD ZONE-RECORD* + ZONE-FORM: + ZONE-HEAD ZONE-RECORD* -ZONE-RECORD: - ((NAME*) ZONE-RECORD*) -| SYM ARGS" + ZONE-RECORD: + ((NAME*) ZONE-RECORD*) + | SYM ARGS" (multiple-value-bind (zname ttl soa) (zone-parse-head (car zf)) (let ((zone (make-zone :name zname :default-ttl ttl @@ -573,7 +574,7 @@ (defun zone-parse (zf) (defun zone-create (zf) "Zone construction function. Given a zone form ZF, construct the zone and -add it to the table." + add it to the table." (let* ((zone (zone-parse zf)) (name (zone-name zone))) (setf (zone-find name) zone) @@ -795,7 +796,7 @@ (defun zone-write (zone &optional (stream *standard-output*)) (defun zone-save (zones) "Write the named ZONES to files. If no zones are given, write all the -zones." + zones." (unless zones (setf zones (hash-table-keys *zones*))) (safely (safe) -- [mdw]