[net-nittin-irc-cvs] CVS update: net-nittin-irc/parse-message.lisp

[Erik Enge]

Update of /project/net-nittin-irc/cvsroot/net-nittin-irc
In directory common-lisp.net:/tmp/cvs-serv10244

Modified Files:
	parse-message.lisp 
Log Message:
adding better docstrings

Date: Sat Nov 22 14:21:33 2003
Author: eenge

Index: net-nittin-irc/parse-message.lisp
diff -u net-nittin-irc/parse-message.lisp:1.4 net-nittin-irc/parse-message.lisp:1.5
--- net-nittin-irc/parse-message.lisp:1.4	Mon Nov 10 12:25:38 2003
+++ net-nittin-irc/parse-message.lisp	Sat Nov 22 14:21:33 2003
@@ -1,4 +1,4 @@
-;;;; $Id: parse-message.lisp,v 1.4 2003/11/10 17:25:38 eenge Exp $
+;;;; $Id: parse-message.lisp,v 1.5 2003/11/22 19:21:33 eenge Exp $
 ;;;; $Source: /project/net-nittin-irc/cvsroot/net-nittin-irc/parse-message.lisp,v $
 
 ;;;; See the LICENSE file for licensing information.
@@ -6,6 +6,11 @@
 (in-package :irc)
 
 (defun find-reply-name (reply-number &key (reply-names *reply-names*))
+  "Numeric replies in the IRC RFCs have more meaningful names.  Given
+a numeric reply (`reply-number') this function will either return the
+symbol representing the reply or raise a continuable error
+(`no-such-reply') which gives you the opportunity to ignore the
+situation."
   (let ((name (assoc reply-number reply-names)))
     (if name
         (cadr name)
@@ -15,29 +20,58 @@
           :unknown-reply))))
 
 (defun return-source (string &key (start 0))
+  "Assuming `string' is a valid IRC message this function returns the
+source part of the message.  Returns nil if the source part is not
+present."
   (cut-between string #\: '(#\! #\Space) :start start))
 
 (defun return-user (string &key (start 0))
+  "Assuming `string' is a valid IRC message this function returns the
+user part of the message.  Returns nil if the user part is not
+present."
   (cut-between string #\! '(#\@ #\Space) :start start))
 
 (defun return-host (string &key (start 0))
+  "Assuming `string' is a valid IRC message this function returns the
+host part of the message.  Returns nil if the host part is not
+present."
   (cut-between string #\@ '(#\Space) :start start))
 
 (defun return-command (string &key (start 0))
+  "Assuming `string' is a valid IRC message this function returns the
+command part of the message.  Returns nil if the command part is not
+present."
   (if (eql (char string start) #\Space)
       (cut-between string #\Space '(#\Space) :start start)
       (cut-between string nil '(#\Space) :start start :cut-extra nil)))
 
 (defun return-arguments (string &key (start 0))
+  "Assuming `string' is a valid IRC message this function returns the
+arguments part of the message as a list.  Returns nil if the arguments
+part is not present."
   (multiple-value-bind (end-position return-argument)
       (cut-between string nil '(#\:) :start start)
     (values end-position (tokenize-string return-argument
                                           :delimiters '(#\Space)))))
 
 (defun return-trailing-argument (string &key (start 0))
+  "Assuming `string' is a valid IRC message this function returns the
+trailing-argument part of the message.  Returns nil if the
+trailing-argument part is not present."
   (cut-between string #\: '(#\Return) :start start))
 
 (defun parse-raw-message (string &key (start 0))
+  "Assuming `string' is a valid IRC message, parse the message and
+return the values in the following order:
+
+  - source
+  - user
+  - host
+  - command
+  - arguments
+  - trailing-argument
+
+Any values not present will be represented as nil."
   (let ((index start)
         (returns nil))
     (dolist (function '(return-source
@@ -53,6 +87,8 @@
     (apply #'values (reverse returns))))
 
 (defun irc-error-reply-p (string)
+  "Returns t if `string' is a string-representation of an IRC error
+reply message, nil otherwise."
   (unless (zerop (length string))
     (if (and (every #'digit-char-p string)
              (member (char string 0) '(#\4 #\5)))
@@ -60,17 +96,20 @@
         nil)))
 
 (defun numeric-reply-p (string)
+  "Returns t if `string' is a string-representation of an IRC number
+reply, nil otherwise."
   (every #'digit-char-p string))
 
 (defun ctcp-type-p (string type)
-  "What type of CTCP message is this?"
-  (if (string-equal (subseq string 1 (min (length string)
-                                          (1+ (length (symbol-name type)))))
+  "Is the `string' actually a representation of the CTCP `type'?"
+  (if (string-equal (subseq string 1 (min (length string) 
+                                          (1+ (length (symbol-name type))))) 
                     type)
       type
       nil))
                                                        
 (defun dcc-type-p (string type)
+  "Is the `string' actually a representation of the DCC `type'?"
   (case type
     (:dcc-chat-request
      (when (string-equal (char string 5) #\C)
@@ -80,7 +119,10 @@
        :dcc-send-request))
     (otherwise nil)))
 
-(defun parse-ctcp-message (string)
+(defun ctcp-message-p (string)
+  "If `string' is a CTCP message, return the type of the message or
+nil if this is a) not a CTCP message or b) a CTCP message we don't
+know about."
   (if (or (not (stringp string))
           (zerop (length string))
           (not (eql (char string 0) +soh+)))
@@ -100,10 +142,13 @@
         (otherwise nil))))
 
 (defun create-irc-message (string)
+  "If `string' is a valid IRC message parse it and return an object of
+the correct type with its slots prefilled according to the information
+in the message."
   (multiple-value-bind (source user host command arguments trailing-argument)
       (parse-raw-message string)
     (let ((class 'irc-message)
-          (ctcp (parse-ctcp-message trailing-argument)))
+          (ctcp (ctcp-message-type trailing-argument)))
       (when command
         (cond
           ((irc-error-reply-p command)