From 8f626f81d2dd58758492f1708d5ff449d53ef731 Mon Sep 17 00:00:00 2001 From: Gerd Heber Date: Wed, 5 Aug 2015 17:58:21 -0500 Subject: [PATCH] Documentation updates. --- exports.lisp | 19 ++++++++++ src/chain-complexes.lisp | 76 ++++++++++++++++++++++++++++++------- src/chcm-elementary-op.lisp | 6 ++- src/combinations.lisp | 6 +++ src/macros.lisp | 31 +++++++++++++++ 5 files changed, 124 insertions(+), 14 deletions(-) diff --git a/exports.lisp b/exports.lisp index ec6e894..e054606 100644 --- a/exports.lisp +++ b/exports.lisp @@ -1,10 +1,19 @@ ( + ? + 2CMBN-ADD 2CMBN-SBTR 2N-2CMBN + ALL-OBJECTS + + BASIS + BUILD-CHCM + + CAT-INIT CHECK-CMBN + CHCM CMBN CMBN-CMBN CMBN-DEGR @@ -13,9 +22,18 @@ CMBN-OPPS CMBN-PRINT CMBN-ZERO-P + CMPR + + DFFR F-CMPR + HOW-MANY-OBJECTS + + K + KD + KD2 + L-CMPR N-CMBN @@ -27,6 +45,7 @@ TERM-CMBN ZERO-CMBN + ZERO-INTR-DFFR ZERO-PURE-DFFR ) diff --git a/src/chain-complexes.lisp b/src/chain-complexes.lisp index 6c15d92..6934561 100644 --- a/src/chain-complexes.lisp +++ b/src/chain-complexes.lisp @@ -6,10 +6,15 @@ (PROVIDE "chain-complexes") + (DEFUN CAT-INIT () (declare (special *idnm-counter* *results-n* *results-cmlt-tm*)) - "Clear the list of user created chain complexes *CHCM-LIST* and reset the -global counter to 0." + "--------------------------------------------------------------[function-doc] +CAT-INIT +Args: () +Clear the list of user created chain complexes *CHCM-LIST* and reset the +global counter to 0. +------------------------------------------------------------------------------" (setf *idnm-counter* 0 *results-n* 0 *results-cmlt-tm* 0.0) (map nil #'(lambda (listname) (declare (symbol listname)) @@ -17,8 +22,13 @@ global counter to 0." *list-list*) (done)) + (DEFUN HOW-MANY-OBJECTS () - "Return the number of user created objects by object type." + "--------------------------------------------------------------[function-doc] +HOW-MANY-OBJECTS +Args: () +Return the number of user created objects by object type. +------------------------------------------------------------------------------" (mapc #'(lambda (symbol) (declare (type (or string symbol) symbol)) (let ((length (length (eval symbol)))) @@ -29,8 +39,13 @@ global counter to 0." *list-list*) (done)) + (DEFUN ALL-OBJECTS () - "Return a string representation of a user created objects." + "--------------------------------------------------------------[function-doc] +ALL-OBJECTS +Args: () +Return a string representation of a user created objects. +------------------------------------------------------------------------------" (let ((object-list (sort (delete-duplicates (mapcan #'(lambda (symbol) @@ -43,10 +58,15 @@ global counter to 0." (format t "~%~A = ~A" item (orgn item)))) (done)) + (DEFUN KD (idnm) (declare (fixnum idnm)) - "Return the type of Kenzo object number IDNM and print the comment list -(SLOT :ORGN) of the object." + "--------------------------------------------------------------[function-doc] +KD +Args: (idnm) +Return the type of Kenzo object number IDNM and print the comment list +(SLOT :ORGN) of the object. +------------------------------------------------------------------------------" (dolist (list *list-list*) (let ((found (find idnm (eval list) :key #'idnm))) (when found @@ -54,20 +74,30 @@ global counter to 0." ~3TOrigin: ~A~2%" found (orgn found)) (return-from kd (values)))))) + (DEFUN K (idnm) (declare (fixnum idnm)) - "Get the IDNM-th Kenzo object." + "--------------------------------------------------------------[function-doc] +K +Args: (idnm) +Returns the IDNM-th Kenzo object. +------------------------------------------------------------------------------" (dolist (list *list-list*) (let ((found (find idnm (eval list) :key #'idnm))) (when found (return-from k found))))) + (DEFUN KD2 (idnm) (declare (fixnum idnm)) - "Return the type of Kenzo object number IDNM, print the comment list + "--------------------------------------------------------------[function-doc] +KD2 +Args: (idnm) +Return the type of Kenzo object number IDNM, print the comment list (SLOT :ORGN) of the object and, recursively, return the same information for all Kenzo objects of the same type in relation with this object. Return -the list of object numbers." +the list of object numbers. +------------------------------------------------------------------------------" (let ((k-list (k idnm))) (declare (list k-list)) (unless k-list @@ -97,13 +127,19 @@ the list of object numbers." #+clisp(eval-when (:compile-toplevel :load-toplevel :execute) (setf (ext:package-lock :clos) t)) + (DEFUN CHCM (idnm) (declare (fixnum idnm)) - "Return from the list *CHCM-LIST* the chain complex instance with Kenzo -identifier IDNUM or NIL, if it doesn't exist." + "--------------------------------------------------------------[function-doc] +CHCM +Args: (idnm) +Return from the list *CHCM-LIST* the chain complex instance with Kenzo +identifier IDNUM or NIL, if it doesn't exist. +------------------------------------------------------------------------------" (the (or chain-complex null) (find idnm *chcm-list* :key #'idnm))) + (DEFUN RESULT-PRINT (result stream depth) (declare (type result result) (stream stream) @@ -117,21 +153,26 @@ identifier IDNUM or NIL, if it doesn't exist." (result-clnm result) (result-rntm result)) result) + (DEFGENERIC ?2 (chcm-or-mrph cmbn)) + (DEFMETHOD ?2 ((mrph morphism) cmbn) (declare (type cmbn cmbn)) (the cmbn (cmbn-? mrph cmbn))) + (DEFMETHOD ?2 ((chcm chain-complex) cmbn) (declare (type cmbn cmbn)) (the cmbn (cmbn-? (dffr1 chcm) cmbn))) + (DEFGENERIC ?3 (chcm-or-mrph degr gnrt)) + (DEFMETHOD ?3 ((mrph morphism) degr gnrt) (declare (fixnum degr) @@ -139,12 +180,14 @@ identifier IDNUM or NIL, if it doesn't exist." (the cmbn (gnrt-? mrph degr gnrt))) + (DEFMETHOD ?3 ((chcm chain-complex) degr gnrt) (declare (fixnum degr) (type gnrt gnrt)) (gnrt-? (dffr1 chcm) degr gnrt)) + #+clisp(eval-when (:compile-toplevel :load-toplevel :execute) (setf (ext:package-lock :clos) nil)) (DEFMETHOD PRINT-OBJECT ((mrph morphism) stream) @@ -167,6 +210,7 @@ IDNUM or NIL, if it doesn't exist." (the (or morphism null) (find n *mrph-list* :key #'idnm))) + (DEFUN BUILD-CHCM (&key cmpr basis bsgn intr-dffr strt orgn) (declare (type cmprf cmpr) @@ -175,8 +219,12 @@ IDNUM or NIL, if it doesn't exist." (type (or intr-mrph null) intr-dffr) (type strt strt) (type list orgn)) - "Returns an instance of CHAIN-COMPLEX. Use this function instead of creating -instances via the standard constructor MAKE-INSTANCE." + "--------------------------------------------------------------[function-doc] +BUILD-CHCM +Args: (&key cmpr basis bsgn intr-dffr strt orgn) +Returns an instance of CHAIN-COMPLEX. Use this function instead of creating +instances via the standard constructor MAKE-INSTANCE. +------------------------------------------------------------------------------" (the chain-complex (progn (let ((already (find orgn *chcm-list* :test #'equal :key #'orgn))) @@ -200,6 +248,7 @@ instances via the standard constructor MAKE-INSTANCE." (push chcm *chcm-list*) chcm)))) + (DEFUN BASIS2 (object n) ;;; (declare (type t object) @@ -211,6 +260,7 @@ instances via the standard constructor MAKE-INSTANCE." (error "The object ~A is locally-effective." object)) (funcall basis n)))) + (DEFUN BUILD-MRPH (&key sorc trgt degr intr strt orgn) (declare (type chain-complex sorc trgt) diff --git a/src/chcm-elementary-op.lisp b/src/chcm-elementary-op.lisp index d3de64f..36b6d7b 100644 --- a/src/chcm-elementary-op.lisp +++ b/src/chcm-elementary-op.lisp @@ -7,7 +7,11 @@ (PROVIDE "chcm-elementary-op") (DEFUN Z-CHCM () - "Build the unit chain complex." + "--------------------------------------------------------------[function-doc] +Z-CHCM +Args: () +Build the unit chain complex. +------------------------------------------------------------------------------" (the chain-complex (build-chcm :cmpr #'(lambda (gnrt1 gnrt2) diff --git a/src/combinations.lisp b/src/combinations.lisp index 85fcbda..da4b900 100644 --- a/src/combinations.lisp +++ b/src/combinations.lisp @@ -202,6 +202,12 @@ degree -1. (DEFUN ZERO-INTR-DFFR (cmbn) (declare (type cmbn cmbn)) + "--------------------------------------------------------------[function-doc] +ZERO-INTR-DFFR +Args: (cmbn) +Returns the null combination of degree p-1, for any combination CMBN of +degree p. +------------------------------------------------------------------------------" (the cmbn (zero-cmbn (1- (cmbn-degr cmbn))))) diff --git a/src/macros.lisp b/src/macros.lisp index 00d0794..e022bd2 100644 --- a/src/macros.lisp +++ b/src/macros.lisp @@ -147,6 +147,14 @@ Tests if the combination CMBN is the null combination of any degree. ;;; (DEFMACRO CMPR (&rest rest) + "------------------------------------------------------------------[macro-doc] +CMPR +Args: (&rest rest) +Args: (chcm gnrt1 gnrt2) +Typically invoked with a chain complex CHCM and two generators GNRT1 and GNRT2. +Applies the comparison function associated with CHCM to GNRT1 and GNRT2, and +return the result. +------------------------------------------------------------------------------" (ecase (length rest) (1 `(cmpr1 ,@rest)) (3 `(cmpr3 ,@rest)))) @@ -157,6 +165,20 @@ Tests if the combination CMBN is the null combination of any degree. (DEFMACRO BASIS (&rest rest) + "------------------------------------------------------------------[macro-doc] +BASIS +Args: (&rest rest) +Args: (chcm) +Args: (chcm n) +Args: (chcm n :dgnr) +When invoked with only one argument, returns the function attached to the slot +BASIS of the chain complex. +When invoked with two arguments, returns the basis of the group of degree N of + the chain complex. +When invoked with three arguments, the keyword :DGNR, it also returns the +degenerate elements of the basis in degree N. +This function returns an error if the chain complex is locally effective. +------------------------------------------------------------------------------" (ecase (length rest) (1 `(basis1 ,@rest)) (2 `(basis2 ,@rest)) @@ -169,6 +191,15 @@ Tests if the combination CMBN is the null combination of any degree. (DEFMACRO DFFR (&rest rest) + "------------------------------------------------------------------[macro-doc] +DFFR +Args: (&rest rest) +Args: (chcm cmbn) +Args: (chcm degr gnrt) +Applies the differential morphism of the chain complex CHCM to a combination +CMBN or a generator GNRT of a degree DEGR. +See also the macro ?. +------------------------------------------------------------------------------" (ecase (length rest) (1 `(dffr1 ,@rest)) ((2 3) `(? (dffr1 ,(first rest)) ,@(rest rest)))))