Commit 156a8013 authored by Francois-Rene Rideau's avatar Francois-Rene Rideau

Update comments and docstrings in component.lisp

parent d0bae719
......@@ -48,24 +48,38 @@
(defgeneric component-system (component)
(:documentation "Find the top-level system containing COMPONENT"))
(defgeneric component-pathname (component)
(:documentation "Extracts the pathname applicable for a particular component."))
(:documentation "Extracts the pathname applicable for a particular COMPONENT."))
(defgeneric (component-relative-pathname) (component)
(:documentation "Returns a pathname for the component argument intended to be
interpreted relative to the pathname of that component's parent.
Despite the function's name, the return value may be an absolute
pathname, because an absolute pathname may be interpreted relative to
another pathname in a degenerate way."))
(defgeneric component-external-format (component))
(defgeneric component-encoding (component))
(defgeneric version-satisfies (component version))
(defgeneric component-version (component))
(defgeneric (setf component-version) (new-version component))
(defgeneric component-parent (component))
;; in ASDF4, rename that to component-specified-pathname ?
(:documentation "Returns a pathname for the COMPONENT argument,
intended to be interpreted relative to the pathname of that component's parent.
Despite the function's name, the return value may be an absolute pathname,
because an absolute pathname may be interpreted relative to another pathname in a degenerate way."))
(defgeneric component-external-format (component)
(:documentation "The external-format of the COMPONENT.
By default, deduced from the COMPONENT-ENCODING."))
(defgeneric component-encoding (component)
(:documentation "The encoding of the COMPONENT. By default, only :utf-8 is supported.
Use asdf-encodings to support more encodings."))
(defgeneric version-satisfies (component version)
(:documentation "Check whether a COMPONENT satisfies the constraint of being no less recent
than specified VERSION."))
(defgeneric component-version (component)
(:documentation "Return the version of a COMPONENT, which must be a string of dot-separated
natural integers, or NIL."))
(defgeneric (setf component-version) (new-version component)
(:documentation "Updates the version of a COMPONENT, which must be a string of dot-separated
natural integers, or NIL."))
(defgeneric component-parent (component)
(:documentation "The parent of a child COMPONENT,
or NIL for top-level components (a.k.a. systems)"))
;; NIL is a designator for the absence of a component, in which case the parent is also absent.
(defmethod component-parent ((component null)) nil)
;; Backward compatible way of computing the FILE-TYPE of a component.
;; Deprecated: Backward compatible way of computing the FILE-TYPE of a component.
;; TODO: find users, have them stop using that, remove it for ASDF4.
(defgeneric (source-file-type) (component system))
(defgeneric (source-file-type) (component system)
(:documentation "DEPRECATED. Use the FILE-TYPE of a COMPONENT instead."))
(define-condition system-definition-error (error) ()
;; [this use of :report should be redundant, but unfortunately it's not.
......@@ -133,7 +147,8 @@ another pathname in a degenerate way."))
;; For backward-compatibility, this slot is part of component rather than of child-component. ASDF4: stop it.
(parent :initarg :parent :initform nil :reader component-parent)
(build-operation
:initarg :build-operation :initform nil :reader component-build-operation)))
:initarg :build-operation :initform nil :reader component-build-operation))
(:documentation "Base class for all components of a build"))
(defun component-find-path (component)
"Return a path from a root system to the COMPONENT.
......@@ -157,11 +172,12 @@ The return value is a list of component NAMES; a list of strings."
;; The tree typically but not necessarily follows the filesystem hierarchy.
(with-upgradability ()
(defclass child-component (component) ()
(:documentation "A CHILD-COMPONENT is a component that may be part of
(:documentation "A CHILD-COMPONENT is a COMPONENT that may be part of
a PARENT-COMPONENT."))
(defclass file-component (child-component)
((type :accessor file-type :initarg :type))) ; no default
((type :accessor file-type :initarg :type)) ; no default
(:documentation "a COMPONENT that represents a file"))
(defclass source-file (file-component)
((type :accessor source-file-explicit-type ;; backward-compatibility
:initform nil))) ;; NB: many systems have come to rely on this default.
......@@ -170,7 +186,8 @@ a PARENT-COMPONENT."))
(defclass java-source-file (source-file)
((type :initform "java")))
(defclass static-file (source-file)
((type :initform nil)))
((type :initform nil))
(:documentation "Component for a file that is copied as is in the build output"))
(defclass doc-file (static-file) ())
(defclass html-file (doc-file)
((type :initform "html")))
......@@ -188,10 +205,13 @@ a PARENT-COMPONENT."))
:initform nil
:initarg :default-component-class
:accessor module-default-component-class))
(:documentation "A PARENT-COMPONENT is a component that may have
children.")))
(:documentation "A PARENT-COMPONENT is a component that may have children.")))
(with-upgradability ()
;; (Private) Function that given a PARENT component,
;; the list of children of which has been initialized,
;; compute the hash-table in slot children-by-name that allows to retrieve its children by name.
;; If ONLY-IF-NEEDED-P is defined, skip any (re)computation if the slot is already populated.
(defun compute-children-by-name (parent &key only-if-needed-p)
(unless (and only-if-needed-p (slot-boundp parent 'children-by-name))
(let ((hash (make-hash-table :test 'equal)))
......@@ -205,15 +225,22 @@ children.")))
(with-upgradability ()
(defclass module (child-component parent-component)
(#+clisp (components)))) ;; backward compatibility during upgrade only
(#+clisp (components)) ;; backward compatibility during upgrade only
(:documentation "A module is a intermediate component with both a parent and children,
typically but not necessarily representing the files in a subdirectory of the build source.")))
;;;; component pathnames
(with-upgradability ()
(defgeneric* (component-parent-pathname) (component))
(defgeneric* (component-parent-pathname) (component)
(:documentation "The pathname of a component's parent"))
(defmethod component-parent-pathname (component)
(component-pathname (component-parent component)))
;; The default method for component-pathname tries to extract a cached precomputed
;; absolute-pathname from the relevant slot, and if not, computes it by merging the
;; component-relative-pathname (which should be component-specified-pathname, it can be absolute)
;; with the directory of the component-parent-pathname.
(defmethod component-pathname ((component component))
(if (slot-boundp component 'absolute-pathname)
(slot-value component 'absolute-pathname)
......@@ -227,6 +254,9 @@ children.")))
(setf (slot-value component 'absolute-pathname) pathname)
pathname)))
;; Default method for component-relative-pathname:
;; combine the contents of slot relative-pathname (from specified initarg :pathname)
;; with the appropriate source-file-type, which defaults to the file-type of the component.
(defmethod component-relative-pathname ((component component))
;; SOURCE-FILE-TYPE below is strictly for backward-compatibility with ASDF1.
;; We ought to be able to extract this from the component alone with FILE-TYPE.
......@@ -260,7 +290,9 @@ children.")))
;;;; around-compile-hook
(with-upgradability ()
(defgeneric around-compile-hook (component))
(defgeneric around-compile-hook (component)
(:documentation "An optional user-specifiable function to call around actions that compile code
from the component, as passed to the function in as a thunk in unique argument."))
(defmethod around-compile-hook ((c component))
(cond
((slot-boundp c 'around-compile)
......@@ -289,6 +321,7 @@ children.")))
;;; all sub-components (of a given type)
(with-upgradability ()
(defun sub-components (component &key (type t))
"Compute the transitive sub-components of given COMPONENT that are of given TYPE"
(while-collecting (c)
(labels ((recurse (x)
(when (if-let (it (component-if-feature x)) (featurep it) t)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment