1.0.10.51: New function: THREAD-YIELD
[sbcl.git] / src / code / describe.lisp
1 ;;;; most of the DESCRIBE system -- 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 \f
15 (declaim (ftype (function (t stream)) describe-object))
16 (defgeneric describe-object (x stream))
17
18 (defun describe (x &optional (stream-designator *standard-output*))
19   #+sb-doc
20   "Print a description of the object X."
21   (let ((stream (out-synonym-of stream-designator)))
22     ;; Until sbcl-0.8.0.x, we did
23     ;;   (FRESH-LINE STREAM)
24     ;;   (PPRINT-LOGICAL-BLOCK (STREAM NIL)
25     ;;     ...
26     ;; here. However, ANSI's specification of DEFUN DESCRIBE,
27     ;;   DESCRIBE exists as an interface primarily to manage argument
28     ;;   defaulting (including conversion of arguments T and NIL into
29     ;;   stream objects) and to inhibit any return values from
30     ;;   DESCRIBE-OBJECT.
31     ;; doesn't mention either FRESH-LINEing or PPRINT-LOGICAL-BLOCKing,
32     ;; and the example of typical DESCRIBE-OBJECT behavior in ANSI's
33     ;; specification of DESCRIBE-OBJECT will work poorly if we do them
34     ;; here. (The example method for DESCRIBE-OBJECT does its own
35     ;; FRESH-LINEing, which is a physical directive which works poorly
36     ;; inside a pretty-printer logical block.)
37     (describe-object x stream)
38     ;; We don't TERPRI here either (any more since sbcl-0.8.0.x), because
39     ;; again ANSI's specification of DESCRIBE doesn't mention it and
40     ;; ANSI's example of DESCRIBE-OBJECT does its own final TERPRI.
41     )
42   (values))
43 \f
44 ;;;; miscellaneous DESCRIBE-OBJECT methods
45
46 (defmethod describe-object ((x t) s)
47   (format s "~&~@<~S ~_is a ~S.~:>~%" x (type-of x)))
48
49 (defmethod describe-object ((x cons) s)
50   (call-next-method)
51   (when (and (legal-fun-name-p x)
52              (fboundp x))
53     (%describe-fun (fdefinition x) s :function x)
54     ;;was: (format s "~@:_Its FDEFINITION is ~S.~@:_" (fdefinition x))
55     ;; TO DO: should check for SETF documentation.
56     ;; TO DO: should make it clear whether the definition is a
57     ;; DEFUN (SETF FOO) or DEFSETF FOO or what.
58     ))
59
60 (defmethod describe-object ((x array) s)
61   (fresh-line s)
62   (pprint-logical-block (s nil)
63     (cond
64      ((= 1 (array-rank x))
65       (format s "~S is a vector with ~D elements."
66               x (car (array-dimensions x)))
67       (when (array-has-fill-pointer-p x)
68         (format s "~@:_It has a fill pointer value of ~S."
69                 (fill-pointer x))))
70      (t
71       (format s "~S is an array of dimension ~:S."
72               x (array-dimensions x))))
73     (let ((array-element-type (array-element-type x)))
74       (unless (eq array-element-type t)
75         (format s
76                 "~@:_Its element type is specialized to ~S."
77                 array-element-type)))
78     (if (and (array-header-p x) (%array-displaced-p x))
79         (format s "~@:_The array is displaced with offset ~S."
80                 (%array-displacement x))))
81   (terpri s))
82
83 (defmethod describe-object ((x hash-table) s)
84   (declare (type stream s))
85   (format s "~&~@<~S ~_is an ~S hash table.~:>" x (hash-table-test x))
86   (format s "~&Its SIZE is ~S." (hash-table-size x))
87   (format s
88           "~&~@<Its REHASH-SIZE is ~S. ~_Its REHASH-THRESHOLD is ~S.~:>"
89           (hash-table-rehash-size x)
90           (hash-table-rehash-threshold x))
91   (fresh-line s)
92   (pprint-logical-block (s nil)
93     (let ((count (hash-table-count x)))
94       (format s "It holds ~S key/value pair~:P~:[: ~2I~_~;.~]"
95               count (zerop count))
96       (let ((n 0))
97         (declare (type index n))
98         (dohash (k v x)
99           (unless (zerop n)
100             (write-char #\space s))
101           (incf n)
102           (when (and *print-length* (> n *print-length*))
103             (format s "~:_...")
104             (return))
105           (format s "~:_(~@<~S ~:_~S~:>)" k v)))))
106   (terpri s))
107
108 (defmethod describe-object ((condition condition) s)
109   (sb-kernel:describe-condition condition s))
110 \f
111 ;;;; DESCRIBE-OBJECT methods for symbols and functions, including all
112 ;;;; sorts of messy stuff about documentation, type information,
113 ;;;; packaging, function implementation, etc...
114
115 ;;; Print the specified kind of documentation about the given NAME. If
116 ;;; NAME is null, or not a valid name, then don't print anything.
117 (declaim (ftype (function (t stream t t) (values)) %describe-doc))
118 (defun %describe-doc (name s kind kind-doc)
119   (when (and name (typep name '(or symbol cons)))
120     (let ((doc (fdocumentation name kind)))
121       (when doc
122         (format s "~&~@(~A documentation:~)~%  ~A"
123                 (or kind-doc kind) doc))))
124   (values))
125
126 ;;; Describe various stuff about the functional semantics attached to
127 ;;; the specified NAME, if NAME is the kind of thing you can look
128 ;;; up as a name. (In the case of anonymous closures and other
129 ;;; things, it might not be.) TYPE-SPEC is the function type specifier
130 ;;; extracted from the definition, or NIL if none.
131 (declaim (ftype (function (t stream t)) %describe-fun-name))
132 (defun %describe-fun-name (name s type-spec)
133   (when (and name (typep name '(or symbol cons)))
134     (multiple-value-bind (type where)
135         (if (legal-fun-name-p name)
136             (values (type-specifier (info :function :type name))
137                     (info :function :where-from name))
138             (values type-spec :defined))
139       (when (consp type)
140         (format s "~&Its ~(~A~) argument types are:~%  ~S"
141                 where (second type))
142         (format s "~&Its result type is:~%  ~S" (third type))))
143     (let ((inlinep (info :function :inlinep name)))
144       (when inlinep
145         (format s
146                 "~&It is currently declared ~(~A~);~
147                  ~:[no~;~] expansion is available."
148                 inlinep (info :function :inline-expansion-designator name))))))
149
150 ;;; Print information from the debug-info about where CODE-OBJ was
151 ;;; compiled from.
152 (defun %describe-compiled-from (code-obj s)
153   (declare (type stream s))
154   (let ((info (sb-kernel:%code-debug-info code-obj)))
155     (when info
156       (let ((source (sb-c::debug-info-source info)))
157         (when source
158           (format s "~&On ~A it was compiled from:"
159                   ;; FIXME: The FORMAT-UNIVERSAL-TIME calls in the system
160                   ;; should become more consistent, probably not using
161                   ;; any nondefault options.
162                   (format-universal-time nil (sb-c::debug-source-compiled source)
163                                          :style :abbreviated))
164           (let ((name (sb-c::debug-source-name source)))
165             (ecase (sb-c::debug-source-from source)
166               (:file
167                (format s "~&~A~@:_  Created: " (namestring name))
168                (format-universal-time s (sb-c::debug-source-created source)))
169               (:lisp (format s "~&  ~S" (aref name 0))))))))))
170
171 ;;; Describe a compiled function. The closure case calls us to print
172 ;;; the guts.
173 (defun %describe-fun-compiled (x s kind name)
174   (declare (type stream s))
175   (let ((args (%simple-fun-arglist x)))
176     (cond ((not args)
177            (write-string "  There are no arguments." s))
178           (t
179            (format s "~&~@(The ~@[~A's ~]arguments are:~@:_~)" kind)
180            (write-string "  " s)
181             (let ((*print-pretty* t)
182                   (*print-escape* t)
183                   (*print-base* 10)
184                   (*print-radix* nil))
185               (pprint-logical-block (s nil)
186                  (pprint-indent :current 2)
187                  (format s "~A" args))))))
188   (let ((name (or name (%simple-fun-name x))))
189     (%describe-doc name s 'function kind)
190     (unless (eq kind :macro)
191       (%describe-fun-name name s (%simple-fun-type x))))
192   (%describe-compiled-from (sb-kernel:fun-code-header x) s))
193
194 (defun %describe-fun (x s &optional (kind :function) (name nil))
195   (etypecase x
196     #+sb-eval
197     (sb-eval:interpreted-function
198      (%describe-interpreted-fun x s kind name))
199     (function
200      (%describe-compiled-fun x s kind name))))
201
202 ;;; Describe a function object. KIND and NAME provide some information
203 ;;; about where the function came from.
204 (defun %describe-compiled-fun (x s &optional (kind :function) (name nil))
205   (declare (type function x))
206   (declare (type stream s))
207   (declare (type (member :macro :function) kind))
208   (fresh-line s)
209   (pprint-logical-block (s nil)
210     (ecase kind
211       (:macro (format s "Macro-function: ~S" x))
212       (:function (if name
213                      (format s "Function: ~S" x)
214                      (format s "~S is a function." x))))
215     (format s "~@:_~@<Its associated name (as in ~S) is ~2I~_~S.~:>"
216             'function-lambda-expression
217             (nth-value 2 (function-lambda-expression x)))
218     (case (widetag-of x)
219       (#.sb-vm:closure-header-widetag
220        (%describe-fun-compiled (%closure-fun x) s kind name)
221        (format s "~&Its closure environment is:")
222        (loop for value in (%closure-values x)
223           for i = 0 then (1+ i)
224           do (format s "~&  ~S: ~S" i value)))
225       (#.sb-vm:simple-fun-header-widetag
226        (%describe-fun-compiled x s kind name))
227       (#.sb-vm:funcallable-instance-header-widetag
228        ;; Only STANDARD-GENERIC-FUNCTION would be handled here, but
229        ;; since it has its own DESCRIBE-OBJECT method, it should've been
230        ;; picked off before getting here. So hopefully we never get here.
231        (format s "~@:_It is an unknown type of funcallable instance."))
232       (t
233        (format s "~@:_It is an unknown type of function."))))
234   (terpri s))
235
236 ;; Describe an interpreted function.
237 #+sb-eval
238 (defun %describe-interpreted-fun (x s &optional (kind :function) (name nil))
239   (declare (type sb-eval:interpreted-function x))
240   (declare (type stream s))
241   (declare (type (member :macro :function) kind))
242   (fresh-line s)
243   (pprint-logical-block (s nil)
244     (ecase kind
245       (:macro (format s "Macro-function: ~S" x))
246       (:function (if name
247                      (format s "Function: ~S" x)
248                      (format s "~S is a function." x))))
249     (format s "~@:_~@<Its associated name (as in ~S) is ~2I~_~S.~:>"
250             'function-lambda-expression
251             (nth-value 2 (function-lambda-expression x)))
252     (format s "~&It is an interpreted function.~%")
253     (let ((args (sb-eval:interpreted-function-lambda-list x)))
254       (cond ((not args)
255              (write-string "There are no arguments." s))
256             (t
257              (format s "~&~@(The ~@[~A's ~]arguments are:~@:_~)" kind)
258              (write-string "  " s)
259              (let ((*print-pretty* t)
260                    (*print-escape* t)
261                    (*print-base* 10)
262                    (*print-radix* nil))
263                (pprint-logical-block (s nil)
264                  (pprint-indent :current 2)
265                  (format s "~A" args)))))
266       (format s "~&It was defined as: ")
267       (let ((*print-pretty* t)
268             (*print-escape* t)
269             (*print-base* 10)
270             (*print-radix* nil))
271         (pprint-logical-block (s nil)
272           (pprint-indent :current 2)
273           (format s "~A" (function-lambda-expression x))))))
274   (terpri s))
275
276 (defmethod describe-object ((x function) s)
277   (%describe-fun x s :function))
278
279 (defgeneric describe-symbol-fdefinition (function stream &key name))
280
281 (defmethod describe-symbol-fdefinition ((fun function) stream &key name)
282   (%describe-fun fun stream :function name))
283
284 (defmethod describe-symbol-fdefinition ((fun standard-generic-function) stream
285                                         &key name)
286   (declare (ignore name))
287   ;; Just delegate.
288   (describe-object fun stream))
289
290 (defmethod describe-object ((x symbol) s)
291   (declare (type stream s))
292
293   ;; Describe the packaging.
294   (let ((package (symbol-package x)))
295     (if package
296         (multiple-value-bind (symbol status)
297             (find-symbol (symbol-name x) package)
298           (declare (ignore symbol))
299           (format s "~&~@<~S is ~_an ~(~A~) symbol ~_in ~S.~:>"
300                   x status (symbol-package x)))
301         (format s "~&~@<~S is ~_an uninterned symbol.~:>" x)))
302   ;; TO DO: We could grovel over all packages looking for and
303   ;; reporting other phenomena, e.g. IMPORT and SHADOW, or
304   ;; availability in some package even after (SYMBOL-PACKAGE X) has
305   ;; been set to NIL.
306
307   ;; Describe the value cell.
308   (let* ((kind (info :variable :kind x))
309          (wot (ecase kind
310                 (:special "special variable")
311                 (:macro "symbol macro")
312                 (:constant "constant")
313                 (:global "undefined variable")
314                 (:alien nil))))
315     (pprint-logical-block (s nil)
316       (cond
317        ((eq kind :alien)
318         (let ((info (info :variable :alien-info x)))
319           (format s "~&~@<It is an alien at #X~8,'0X of type ~3I~:_~S.~:>"
320                   (sap-int (eval (sb-alien::heap-alien-info-sap-form info)))
321                   (sb-alien-internals:unparse-alien-type
322                    (sb-alien::heap-alien-info-type info)))
323           (format s "~&~@<Its current value is ~3I~:_~S.~:>"
324                   (eval x))))
325        ((eq kind :macro)
326         (let ((expansion (info :variable :macro-expansion x)))
327           (format s "~&It is a ~A with expansion ~S." wot expansion)))
328        ((boundp x)
329         (format s "~&~@<It is a ~A; its ~_value is ~S.~:>"
330                 wot (symbol-value x)))
331        ((not (eq kind :global))
332         (format s "~&~@<It is a ~A; no current value.~:>" wot)))
333
334       (when (eq (info :variable :where-from x) :declared)
335         (format s "~&~@<Its declared type ~_is ~S.~:>"
336                 (type-specifier (info :variable :type x)))))
337
338     (%describe-doc x s 'variable kind))
339
340   ;; Print out properties.
341   (format s "~@[~&Its SYMBOL-PLIST is ~@<~2I~_~S~:>.~]" (symbol-plist x))
342
343   ;; Describe the function cell.
344   (cond ((macro-function x)
345          (%describe-fun (macro-function x) s :macro x))
346         ((special-operator-p x)
347          (%describe-doc x s :function "Special form"))
348         ((fboundp x)
349          (describe-symbol-fdefinition (fdefinition x) s :name x)))
350
351   ;; Print other documentation.
352   (%describe-doc x s 'structure "Structure")
353   (%describe-doc x s 'type "Type")
354   (%describe-doc x s 'setf "Setf macro")
355   (dolist (assoc (info :random-documentation :stuff x))
356     (format s
357             "~&~@<Documentation on the ~(~A~):~@:_~A~:>"
358             (car assoc)
359             (cdr assoc)))
360
361   ;; Mention the associated type information, if any.
362   ;;
363   ;; As of sbcl-0.7.2, (INFO :TYPE :KIND X) might be
364   ;;   * :PRIMITIVE, which is handled by the FIND-CLASS case.
365   ;;   * :DEFINED, which is handled specially.
366   ;;   * :INSTANCE, which is handled by the FIND-CLASS case.
367   ;;   * :FORTHCOMING-DEFCLASS-TYPE, which is an internal-to-the-compiler
368   ;;     note that we don't try to report.
369   ;;   * NIL, in which case there's nothing to see here, move along.
370   (when (eq (info :type :kind x) :defined)
371     (format s "~&It names a type specifier."))
372   (let ((symbol-named-class (find-class x nil)))
373     (when symbol-named-class
374       (format s "~&It names a class ~A." symbol-named-class)
375       (describe symbol-named-class s)))
376
377   (terpri s))