Update of /project/lispy/cvsroot/lispy In directory clnet:/tmp/cvs-serv26736

Modified Files: lispy.lisp packages.lisp specials.lisp Log Message: Add doc strings and fix upgrade bug.

--- /project/lispy/cvsroot/lispy/lispy.lisp 2007/07/24 04:59:00 1.10 +++ /project/lispy/cvsroot/lispy/lispy.lisp 2008/01/27 19:54:07 1.11 @@ -9,13 +9,25 @@ (apply #'format nil (cons control-string format-arguments)))))

(defclass module () - ((name :initarg :name :reader name) - (homepage :initarg :homepage :reader homepage) - (description :initarg :description :reader description) - (versions :initarg :versions :reader versions) - (map-url :initarg :map-url :reader map-url))) + ((name :initarg :name + :reader name + :documentation "The name of the Lisp package.") + (homepage :initarg :homepage + :reader homepage + :documentation "From where the Lisp package originated.") + (description :initarg :description + :reader description + :documentation "A brief description of the Lisp package to include in rendered views of maps.") + (versions :initarg :versions + :reader versions + :documentation "A list of versions of the Lisp package.") + (map-url :initarg :map-url + :reader map-url + :documentation "The URL to the map the MODULE was defined in.")) + (:documentation "A MODULE represents a Lisp package from a Lispy map."))

-(defgeneric latest-version (module)) +(defgeneric latest-version (module) + (:documentation "Determine the latest version of the Lisp package described by MODULE. Returns an instance of VERSION."))

(defmethod latest-version ((module module)) (let* ((versions (versions module)) @@ -27,7 +39,8 @@ latest-our-version (our-version version)))) latest-version))

-(defgeneric dependency-list (module)) +(defgeneric dependency-list (module) + (:documentation "Compute the dependencies of the latest version of a Lispy package described by MODULE. Returns a list of MODULE instances."))

(defmethod dependency-list ((module module)) (let ((dependencies '())) @@ -42,15 +55,34 @@ dependencies))

(defclass version () - ((name :initarg :name :reader name) - (map-url :initarg :map-url :reader map-url) - (our-version :initarg :our-version :reader our-version) - (version :initarg :version :reader version) - (source :initarg :source :reader source) - (md5sum :initarg :md5sum :reader md5sum) - (root :initarg :root :reader root) - (asdf-paths :initarg :asdf-paths :reader asdf-paths) - (dependencies :initarg :dependencies :reader dependencies))) + ((name :initarg :name + :reader name + :documentation "The name of the module to which a VERSION belongs.") + (map-url :initarg :map-url + :reader map-url + :documentation "The URL to the map the VERSION was defined in.") + (our-version :initarg :our-version + :reader our-version + :documentation "A synthetic version number which is used in VERSION comparisons.") + (version :initarg :version + :reader version + :documentation "The upstream author's version number or a date of the form YYYY-MM-DD if no version is available or the version is from version control.") + (source :initarg :source + :reader source + :documentation "The Lisp package's source file name.") + (md5sum :initarg :md5sum + :reader md5sum + :documentation "The MD5 checksum of the Lisp package's source archive.") + (root :initarg :root + :reader root + :documentation "The directory where the Lisp package's source archive unpacks to.") + (asdf-paths :initarg :asdf-paths + :reader asdf-paths + :documentation "A list of ASDF paths to be added to the ASDF configuration for Lispy packages which include more than one ASDF file in more than one location. If not specified, then ROOT is used.") + (dependencies :initarg :dependencies + :reader dependencies + :documentation "A list of MODULE names which the VERSION depends on.")) + (:documentation "A VERSION represents a specific version of a MODULE."))

(defmethod print-object ((m module) stream) (print-unreadable-object (m stream :type t :identity t) @@ -63,9 +95,11 @@ (defvar *lispy-map* (make-hash-table :test 'eq))

(defun module-by-name (name) + "Returns the instance of MODULE described by NAME." (gethash name *lispy-map*))

(defun read-map (map-url) + "Read the map at MAP-URL and merge the modules into *LISPY-MAP*." (log-message "read-map" "Reading ~A" (uri-to-string map-url)) (multiple-value-bind (stream status-code headers uri http-stream must-close) (drakma:http-request map-url :want-stream t) @@ -79,6 +113,8 @@ (close stream))))

(defun read-maps (&optional (map-urls *lispy-map-urls*)) + "Read all maps in the list MAP-URLS, merging each map into *LISPY-MAPS*. +Returns the mutated *LISPY-MAPS*." (dolist (map-url map-urls) (read-map map-url)) (log-message "read-maps" "Map contains ~A entr~:@p" @@ -112,11 +148,22 @@ :map-url map-url)))

(defclass install () - ((name :initarg :name :reader name) - (our-version :initarg :our-version :reader our-version) - (version :initarg :version :reader version) - (root :initarg :root :reader root) - (asdf-paths :initarg :asdf-paths :reader asdf-paths))) + ((name :initarg :name + :reader name + :documentation "The MODULE name the INSTALL references.") + (our-version :initarg :our-version + :reader our-version + :documentation "The synthetic version number.") + (version :initarg :version + :reader version + :documentation "The upstream author's version number.") + (root :initarg :root + :reader root + :documentation "The directory the install is located in.") + (asdf-paths :initarg :asdf-paths + :reader asdf-paths + :documentation "The list of ASDF paths the installation references.")) + (:documentation "An INSTALL represents a Lisp package that has been installed by Lispy."))

(defmethod print-object ((i install) stream) (print-unreadable-object (i stream :type t :identity t) @@ -125,6 +172,7 @@ (defvar *lispy-installation* (make-hash-table :test 'eq))

(defun read-installation () + "Read the installation file into *LISPY-INSTALLATION*" (log-message "read-installation" "Reading ~A" (namestring *lispy-installation-pathname*)) (with-open-file (stream *lispy-installation-pathname* :direction :input @@ -136,6 +184,7 @@ *lispy-installation*)

(defun write-installation () + "Write *LISPY-INSTALLATION* to the installtaion file." (log-message "write-installation" "Writing ~A" (namestring *lispy-installation-pathname*)) (with-open-file (stream *lispy-installation-pathname* :direction :output @@ -165,10 +214,14 @@ :asdf-paths asdf-paths)))

(defun read-asdf-config () + "Load the Lispy ASDF configuration, which in turn adds paths to +ASDF:*CENTRAL-REGISTRY*." (log-message "read-asdf-config" "Loading ~A" (namestring *lispy-asdf-config-pathname*)) (load *lispy-asdf-config-pathname*))

(defun write-asdf-config () + "Write a Lispy ASDF configuration file which can be loaded +indepedent of Lispy." (log-message "write-asdf-config" "Writing ~A" (namestring *lispy-asdf-config-pathname*)) (with-open-file (stream *lispy-asdf-config-pathname* :direction :output @@ -190,7 +243,8 @@ (pushnew (merge-pathnames cl-user::path cl-user::root) asdf:*central-registry* :test 'equal))) stream)))))

-(defgeneric fetch (module)) +(defgeneric fetch (module) + (:documentation "Download Lisp package source."))

(defmethod fetch ((module module)) (log-message "fetch" "Fetching ~A" (name module)) @@ -230,7 +284,8 @@ parsed-path) result)))

-(defgeneric install (module)) +(defgeneric install (module) + (:documentation "Install Lisp package source."))

(defmethod install ((module module)) (log-message "install" "Installing ~A" (name module)) @@ -257,7 +312,8 @@ (write-asdf-config) (read-asdf-config))))

-(defgeneric extract (module)) +(defgeneric extract (module) + (:documentation "Extract Lisp package source."))

(defmethod extract ((module module)) (log-message "extract" "Extracting ~A" (name module)) @@ -269,9 +325,11 @@ (extract-archive pathname *lispy-pathname*)))

(defun install-by-name (name) + "Return the instance of INSTALL given by NAME." (gethash name *lispy-installation*))

-(defgeneric uninstall (install)) +(defgeneric uninstall (install) + (:documentation "Uninstall Lisp package source."))

(defmethod uninstall ((install install)) (cl-fad:delete-directory-and-files (merge-pathnames (root install) *lispy-pathname*) :if-does-not-exist :ignore) @@ -279,10 +337,18 @@ (write-installation) (values))

-(defun list-map () (hash-to-list *lispy-map*)) -(defun list-installation () (hash-to-list *lispy-installation*)) +(defun list-map () + "Return the merged list of modules." + (hash-to-list *lispy-map*)) + +(defun list-installation () + "Return the list of installed modules versions." + (hash-to-list *lispy-installation*))

(defun initialize () + "Initialize Lispy. This reads and merges all maps in +*LISPY-MAP-URLS*, reads the installation, writes a fresh ASDF +configuration file and updates ASDF:*CENTRAL-REGISTRY*." (setf *lispy-installation* (make-hash-table :test 'eq) *lispy-map* (make-hash-table :test 'eq)) (log-message "initialize" "Initializing Lispy system on ~A ~A" (lisp-implementation-type) (lisp-implementation-version)) @@ -292,7 +358,8 @@ (read-asdf-config) (values))

-(defgeneric upgradable-p (install module)) +(defgeneric upgradable-p (install module) + (:documentation "Non-NIL if the Lisp package source can be upgraded."))

(defmethod upgradable-p ((install install) (module module)) (let ((latest-version (latest-version module))) @@ -300,6 +367,7 @@ (our-version install))))

(defun list-upgrades () + "Returns a list of VERSION instances for all modules that can be upgraded." (let ((result '())) (dolist (i (list-installation)) (let ((module (module-by-name (name i)))) @@ -308,7 +376,8 @@ (push (list i (latest-version module)) result)))) result))

-(defgeneric upgrade (install)) +(defgeneric upgrade (install) + (:documentation "Upgrade a Lisp source package installation."))

(defmethod upgrade ((install install)) (let ((module (module-by-name (name install)))) @@ -318,19 +387,15 @@ (name install) (version install) (version latest-version)) - - (if (equal install (root latest-version)) - (progn ;less ideal - (uninstall install) - (install latest-version)) - (progn ;ideal - (install latest-version) - (uninstall install)))) + ;; FIXME: this needs to be transactional + (uninstall install) + (install latest-version)) (log-message "upgrade" "~A ~A is already the latest version." (name install) (version install)))))

(defun upgrade-all () + "Upgrade all upgradable Lisp source packages." (dolist (upgrade (list-upgrades)) (destructuring-bind (install version) upgrade --- /project/lispy/cvsroot/lispy/packages.lisp 2007/07/23 14:25:58 1.5 +++ /project/lispy/cvsroot/lispy/packages.lisp 2008/01/27 19:54:07 1.6 @@ -15,10 +15,12 @@ #:install-by-name #:list-map #:list-installation + #:module #:name #:homepage #:description #:versions + #:version #:latest-version #:our-version #:version @@ -35,4 +37,5 @@ #:upgradable-p #:list-upgrades #:upgrade - #:upgrade-all)) + #:upgrade-all) + (:documentation "Lispy is Common Lisp package management in Common Lisp.")) --- /project/lispy/cvsroot/lispy/specials.lisp 2007/07/23 14:25:58 1.5 +++ /project/lispy/cvsroot/lispy/specials.lisp 2008/01/27 19:54:07 1.6 @@ -1,19 +1,26 @@ (in-package #:lispy)

(define-constant +lispy-default-map-url+ - (puri:parse-uri "http://common-lisp.net/project/lispy/repository/map.lisp-expr")) + (puri:parse-uri "http://common-lisp.net/project/lispy/repository/map.lisp-expr") + "The URL to the official Lispy map.")

-(defvar *lispy-map-urls* (list +lispy-default-map-url+)) +(defvar *lispy-map-urls* (list +lispy-default-map-url+) + "A list of map URLs Lispy should read and merge.")

(defvar *lispy-pathname* (let ((path (make-pathname :name nil :type nil :version nil :defaults (parse-namestring *load-truename*)))) - (make-pathname :directory (butlast (pathname-directory path)) :defaults path))) + (make-pathname :directory (butlast (pathname-directory path)) :defaults path)) + "Where Lispy is installed. You should never need to modify this.")

-(defvar *lispy-installation-pathname* (merge-pathnames #p"installation.lisp-expr" *lispy-pathname*)) +(defvar *lispy-installation-pathname* (merge-pathnames #p"installation.lisp-expr" *lispy-pathname*) + "The path to the installation list file.")

-(defvar *lispy-asdf-config-pathname* (merge-pathnames #p"asdf-config.lisp" *lispy-pathname*)) +(defvar *lispy-asdf-config-pathname* (merge-pathnames #p"asdf-config.lisp" *lispy-pathname*) + "The path to the Lispy ASDF configuration file.")

-(defvar *lispy-distfiles-pathname* (merge-pathnames #p"distfiles/" *lispy-pathname*)) +(defvar *lispy-distfiles-pathname* (merge-pathnames #p"distfiles/" *lispy-pathname*) + "The path where source packages should be downloaded to.")

-(defvar *lispy-log-stream* t) +(defvar *lispy-log-stream* t + "A stream Lispy should use to write log messages.")