src/code/describe.lisp

   1 ;;;; most of the DESCRIBE mechanism -- that part which isn't derived
   2 ;;;; from PCL code
   3
   4 ;;;; This software is part of the SBCL system. See the README file for
   5 ;;;; more information.
   6 ;;;;
   7 ;;;; This software is derived from the CMU CL system, which was
   8 ;;;; written at Carnegie Mellon University and released into the
   9 ;;;; public domain. The software is in the public domain and is
  10 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
  11 ;;;; files for more information.
  12
  13 (in-package "SB-IMPL") ;(SB-IMPL, not SB!IMPL, since we're built in warm load.)
  14
  15 (declaim #.*optimize-byte-compilation*)
  16
  17 \f
  18 (defvar *describe-indentation-step* 3
  19   #+sb-doc
  20   "the number of spaces that sets off each line of a recursive description")
  21
  22 (declaim (ftype (function (t stream)) describe-object))
  23 (defgeneric describe-object ((x t) stream))
  24
  25 (defun describe (x &optional (stream-designator *standard-output*))
  26   #+sb-doc
  27   "Print a description of the object X."
  28   (declare #.*optimize-external-despite-byte-compilation*)
  29   (let ((stream (out-synonym-of stream-designator)))
  30     (pprint-logical-block (stream nil)
  31       (fresh-line stream)
  32       (describe-object x stream)
  33       (fresh-line stream)))
  34   (values))
  35 \f
  36 ;;;; miscellaneous DESCRIBE-OBJECT methods
  37
  38 (defmethod describe-object ((x t) s)
  39   (format s "~@<~S ~_is a ~S.~:>" x (type-of x)))
  40
  41 (defmethod describe-object ((x cons) s)
  42   (call-next-method)
  43   (when (and (legal-function-name-p x)
  44              (fboundp x))
  45     (%describe-function (fdefinition x) s :function x)
  46     ;;was: (format s "~@:_Its FDEFINITION is ~S.~@:_" (fdefinition x))
  47     ;; TO DO: should check for SETF documentation.
  48     ;; TO DO: should make it clear whether the definition is a
  49     ;; DEFUN (SETF FOO) or DEFSETF FOO or what.
  50     ))
  51
  52 (defmethod describe-object ((x array) s)
  53   (let ((rank (array-rank x)))
  54     (cond ((> rank 1)
  55            (format s "~S ~_is " x)
  56            (write-string (if (%array-displaced-p x) "a displaced" "an") s)
  57            (format s " array of rank ~S." rank)
  58            (format s "~@:_Its dimensions are ~S." (array-dimensions x)))
  59           (t
  60            (format s
  61                    "~@:_~S is a ~:[~;displaced ~]vector of length ~S." x
  62                    (and (array-header-p x) (%array-displaced-p x)) (length x))
  63            (when (array-has-fill-pointer-p x)
  64              (format s "~@:_It has a fill pointer, currently ~S."
  65                      (fill-pointer x))))))
  66   (let ((array-element-type (array-element-type x)))
  67     (unless (eq array-element-type t)
  68       (format s
  69               "~@:_Its element type is specialized to ~S."
  70               array-element-type))))
  71
  72 (defmethod describe-object ((x hash-table) s)
  73   (declare (type stream s))
  74   (format s "~@<~S ~_is an ~S hash table.~:>" x (hash-table-test x))
  75   (format s "~_Its SIZE is ~S." (hash-table-size x))
  76   (format s
  77           "~@:_~@<Its REHASH-SIZE is ~S. ~_Its REHASH-THRESHOLD is ~S.~:>"
  78           (hash-table-rehash-size x)
  79           (hash-table-rehash-threshold x))
  80   (let ((count (hash-table-count x)))
  81     (format s "~@:_It holds ~S key/value pair~:P~:[: ~2I~_~;.~]"
  82             count (zerop count))
  83     (let ((n 0))
  84       (declare (type index n))
  85       (dohash (k v x)
  86         (unless (zerop n)
  87           (write-char #\space s))
  88         (incf n)
  89         (when (and *print-length* (> n *print-length*))
  90           (format s "~:_...")
  91           (return))
  92         (format s "~:_(~@<~S ~:_~S~:>)" k v)))))
  93
  94 (defmethod describe-object ((condition condition) s)
  95   (sb-kernel:describe-condition condition s))
  96 \f
  97 ;;;; DESCRIBE-OBJECT methods for symbols and functions, including all
  98 ;;;; sorts of messy stuff about documentation, type information,
  99 ;;;; packaging, function implementation, etc..
 100
 101 ;;; Print the specified kind of documentation about the given NAME. If
 102 ;;; NAME is null, or not a valid name, then don't print anything.
 103 (declaim (ftype (function (t stream t t) (values)) %describe-doc))
 104 (defun %describe-doc (name s kind kind-doc)
 105   (when (and name (typep name '(or symbol cons)))
 106     (let ((doc (fdocumentation name kind)))
 107       (when doc
 108         (format s "~_~@(~A documentation:~)~@:_  ~A"
 109                 (or kind-doc kind) doc))))
 110   (values))
 111
 112 ;;; Describe various stuff about the functional semantics attached to
 113 ;;; the specified NAME, if NAME is the kind of thing you can look
 114 ;;; up as a name. (In the case of anonymous closures and other
 115 ;;; things, it might not be.) TYPE-SPEC is the function type specifier
 116 ;;; extracted from the definition, or NIL if none.
 117 (declaim (ftype (function (t stream t)) %describe-function-name))
 118 (defun %describe-function-name (name s type-spec)
 119   (when (and name (typep name '(or symbol cons)))
 120     (multiple-value-bind (type where)
 121         (if (or (symbolp name) (and (listp name) (eq (car name) 'setf)))
 122             (values (type-specifier (info :function :type name))
 123                     (info :function :where-from name))
 124             (values type-spec :defined))
 125       (when (consp type)
 126         (format s "~@:_Its ~(~A~) argument types are:~@:_  ~S"
 127                 where (second type))
 128         (format s "~@:_Its result type is:~@:_  ~S" (third type))))
 129     (let ((inlinep (info :function :inlinep name)))
 130       (when inlinep
 131         (format s
 132                 "~@:_It is currently declared ~(~A~);~
 133                  ~:[no~;~] expansion is available."
 134                 inlinep (info :function :inline-expansion name))))))
 135
 136 ;;; Print information from the debug-info about where CODE-OBJ was
 137 ;;; compiled from.
 138 (defun %describe-compiled-from (code-obj s)
 139   (declare (type stream s))
 140   (let ((info (sb-kernel:%code-debug-info code-obj)))
 141     (when info
 142       (let ((sources (sb-c::debug-info-source info)))
 143         (when sources
 144           (format s "~@:_On ~A it was compiled from:"
 145                   ;; FIXME: The FORMAT-UNIVERSAL-TIME calls in the system
 146                   ;; should become more consistent, probably not using
 147                   ;; any nondefault options.
 148                   (format-universal-time nil
 149                                          (sb-c::debug-source-compiled
 150                                           (first sources))
 151                                          :style :abbreviated))
 152           (dolist (source sources)
 153             (let ((name (sb-c::debug-source-name source)))
 154               (ecase (sb-c::debug-source-from source)
 155                 (:file
 156                  (format s "~@:_~A~@:_  Created: " (namestring name))
 157                  (format-universal-time s (sb-c::debug-source-created
 158                                            source)))
 159                 (:lisp (format s "~@:_~S" name))))))))))
 160
 161 ;;; Describe a compiled function. The closure case calls us to print
 162 ;;; the guts.
 163 (defun %describe-function-compiled (x s kind name)
 164   (declare (type stream s))
 165   ;; FIXME: The lowercaseness of %FUNCTION-ARGLIST results, and the
 166   ;; non-sentenceness of the "Arguments" label, makes awkward output.
 167   ;; Better would be "Its arguments are: ~S" (with uppercase argument
 168   ;; names) when arguments are known, and otherwise "There is no
 169   ;; information available about its arguments." or "It has no
 170   ;; arguments." (And why is %FUNCTION-ARGLIST a string instead of a
 171   ;; list of symbols anyway?)
 172   (let ((args (%function-arglist x)))
 173     (format s "~@:_~@(~@[~A ~]arguments:~@:_~)" kind)
 174     (cond ((not args)
 175            (format s "  There is no argument information available."))
 176           ((string= args "()")
 177            (write-string "  There are no arguments." s))
 178           (t
 179            (write-string "  " s)
 180            (pprint-logical-block (s nil)
 181              (pprint-indent :current 2)
 182              (write-string args s)))))
 183   (let ((name (or name (%function-name x))))
 184     (%describe-doc name s 'function kind)
 185     (unless (eq kind :macro)
 186       (%describe-function-name name s (%function-type x))))
 187   (%describe-compiled-from (sb-kernel:function-code-header x) s))
 188
 189 ;;; FIXME: byte compiler to go away completely
 190 #|
 191 (defun %describe-function-byte-compiled (x s kind name)
 192   (declare (type stream s))
 193   (let ((name (or name (sb-c::byte-function-name x))))
 194     (%describe-doc name s 'function kind)
 195     (unless (eq kind :macro)
 196       (%describe-function-name name s 'function)))
 197   (%describe-compiled-from (sb-c::byte-function-component x) s))
 198 |#
 199
 200 ;;; Describe a function with the specified kind and name. The latter
 201 ;;; arguments provide some information about where the function came
 202 ;;; from. Kind NIL means not from a name.
 203 (defun %describe-function (x s &optional (kind nil) name)
 204   (declare (type function x))
 205   (declare (type stream s))
 206   (declare (type (member :macro :function nil) kind))
 207   (fresh-line s)
 208   (ecase kind
 209     (:macro (format s "Macro-function: ~S" x))
 210     (:function (format s "Function: ~S" x))
 211     ((nil) (format s "~S is a function." x)))
 212   (case (get-type x)
 213     (#.sb-vm:closure-header-type
 214      (%describe-function-compiled (%closure-function x) s kind name)
 215      (format s "~@:_Its closure environment is:")
 216      (pprint-logical-block (s nil)
 217        (pprint-indent :current 8)
 218        (dotimes (i (- (get-closure-length x) (1- sb-vm:closure-info-offset)))
 219          (format s "~@:_~S: ~S" i (%closure-index-ref x i)))))
 220     ((#.sb-vm:function-header-type #.sb-vm:closure-function-header-type)
 221      (%describe-function-compiled x s kind name))
 222     (#.sb-vm:funcallable-instance-header-type
 223      (typecase x
 224        ;; FIXME: byte compiler to go away completely
 225        #|
 226        (sb-kernel:byte-function
 227         (%describe-function-byte-compiled x s kind name))
 228        (sb-kernel:byte-closure
 229         (%describe-function-byte-compiled (byte-closure-function x)
 230                                           s kind name)
 231         (format s "~@:_Its closure environment is:")
 232         (pprint-logical-block (s nil)
 233           (pprint-indent :current 8)
 234           (let ((data (byte-closure-data x)))
 235             (dotimes (i (length data))
 236               (format s "~@:_~S: ~S" i (svref data i))))))
 237        |#
 238        (standard-generic-function
 239         ;; There should be a special method for this case; we'll
 240         ;; delegate to that.
 241         (describe-object x s))
 242        (t
 243         (format s "~@:_It is an unknown type of funcallable instance."))))
 244     (t
 245      (format s "~@:_It is an unknown type of function."))))
 246
 247 (defmethod describe-object ((x function) s)
 248   (%describe-function x s))
 249
 250 (defmethod describe-object ((x symbol) s)
 251   (declare (type stream s))
 252
 253   ;; Describe the packaging.
 254   (let ((package (symbol-package x)))
 255     (if package
 256         (multiple-value-bind (symbol status)
 257             (find-symbol (symbol-name x) package)
 258           (declare (ignore symbol))
 259           (format s "~S is ~_an ~(~A~) symbol ~_in ~S."
 260                   x status (symbol-package x)))
 261         (format s "~S is ~_an uninterned symbol." x)))
 262   ;; TO DO: We could grovel over all packages looking for and
 263   ;; reporting other phenomena, e.g. IMPORT and SHADOW, or
 264   ;; availability in some package even after (SYMBOL-PACKAGE X) has
 265   ;; been set to NIL.
 266
 267   ;; Describe the value cell.
 268   (let* ((kind (info :variable :kind x))
 269          (wot (ecase kind
 270                 (:special "special variable")
 271                 (:constant "constant")
 272                 (:global "undefined variable")
 273                 (:alien nil))))
 274     (cond
 275      ((eq kind :alien)
 276       (let ((info (info :variable :alien-info x)))
 277         (format s "~@:_~@<It is an alien at #X~8,'0X of type ~3I~:_~S.~:>~@:_"
 278                 (sap-int (eval (sb-alien::heap-alien-info-sap-form info)))
 279                 (sb-alien-internals:unparse-alien-type
 280                  (sb-alien::heap-alien-info-type info)))
 281         (format s "~@<Its current value is ~3I~:_~S.~:>"
 282                 (eval x))))
 283      ((boundp x)
 284       (format s "~@:_It is a ~A; its ~_value is ~S." wot (symbol-value x)))
 285      ((not (eq kind :global))
 286       (format s "~@:_It is a ~A; no current value." wot)))
 287
 288     (when (eq (info :variable :where-from x) :declared)
 289       (format s "~@:_Its declared type ~_is ~S."
 290               (type-specifier (info :variable :type x))))
 291
 292     (%describe-doc x s 'variable kind))
 293
 294   ;; Print out properties.
 295   (format s "~@[~@:_Its SYMBOL-PLIST is ~@<~2I~_~S~:>.~]" (symbol-plist x))
 296
 297   ;; Describe the function cell.
 298   (cond ((macro-function x)
 299          (%describe-function (macro-function x) s :macro x))
 300         ((special-operator-p x)
 301          (%describe-doc x s 'function "Special form"))
 302         ((fboundp x)
 303          (%describe-function (fdefinition x) s :function x)))
 304
 305   ;; FIXME: Print out other stuff from the INFO database:
 306   ;;   * Does it name a type?
 307   ;;   * Is it a structure accessor? (This is important since those are
 308   ;;     magical in some ways, e.g. blasting the structure if you
 309   ;;     redefine them.)
 310
 311   ;; Print other documentation.
 312   (%describe-doc x s 'structure "Structure")
 313   (%describe-doc x s 'type "Type")
 314   (%describe-doc x s 'setf "Setf macro")
 315
 316   (dolist (assoc (info :random-documentation :stuff x))
 317     (format s
 318             "~@:_Documentation on the ~(~A~):~@:_~A"
 319             (car assoc)
 320             (cdr assoc)))
 321
 322   ;; Describe the associated class, if any.
 323   (let ((symbol-named-class (cl:find-class x nil)))
 324     (when symbol-named-class
 325       (format t "~&It names a class ~A." symbol-named-class)
 326       (describe symbol-named-class))))