src/code/inspect.lisp

   1 ;;;; the CL:INSPECT function
   2
   3 ;;;; This software is part of the SBCL system. See the README file for
   4 ;;;; more information.
   5 ;;;;
   6 ;;;; This software is derived from the CMU CL system, which was
   7 ;;;; written at Carnegie Mellon University and released into the
   8 ;;;; public domain. The software is in the public domain and is
   9 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
  10 ;;;; files for more information.
  11
  12 (in-package "SB-IMPL") ;(SB-IMPL, not SB!IMPL, since we're built in warm load.)
  13
  14 (defparameter *inspect-length* 10)
  15
  16 ;;; When *INSPECT-UNBOUND-OBJECT-MARKER* occurs in a parts list, it
  17 ;;; indicates that that a slot is unbound.
  18 (defvar *inspect-unbound-object-marker* (gensym "INSPECT-UNBOUND-OBJECT-"))
  19
  20 (defun inspect (object)
  21   (catch 'quit-inspect
  22     (%inspect object *standard-output*))
  23   (values))
  24
  25 (defvar *inspected*)
  26 (setf (documentation '*inspected* 'variable)
  27       "the value currently being inspected in CL:INSPECT")
  28
  29 (defvar *help-for-inspect*
  30   "
  31 help for INSPECT:
  32   Q, E        -  Quit the inspector.
  33   <integer>   -  Inspect the numbered slot.
  34   R           -  Redisplay current inspected object.
  35   U           -  Move upward/backward to previous inspected object.
  36   ?, H, Help  -  Show this help.
  37   <other>     -  Evaluate the input as an expression.
  38 Within the inspector, the special variable SB-EXT:*INSPECTED* is bound
  39 to the current inspected object, so that it can be referred to in
  40 evaluated expressions.
  41 ")
  42
  43 (defun %inspect (*inspected* s)
  44   (named-let redisplay () ; "LAMBDA, the ultimate GOTO":-|
  45     (multiple-value-bind (description named-p elements)
  46         (inspected-parts *inspected*)
  47       (tty-display-inspected-parts description named-p elements s)
  48       (named-let reread ()
  49         (format s "~&> ")
  50         (force-output)
  51         (let (;; KMP idiom, using stream itself as EOF value
  52               (command (read *standard-input* nil *standard-input*)))
  53           (typecase command
  54             (stream ; i.e. EOF
  55              ;; currently-undocumented feature: EOF is handled as Q.
  56              ;; If there's ever consensus that this is *the* right
  57              ;; thing to do (as opposed to e.g. handling it as U), we
  58              ;; could document it. Meanwhile, it seems more Unix-y to
  59              ;; do this than to signal an error.
  60              (/show0 "THROWing QUIT-INSPECT for EOF")
  61              (throw 'quit-inspect nil))
  62             (integer
  63              (let ((elements-length (length elements)))
  64                (cond ((< -1 command elements-length)
  65                       (let* ((element (nth command elements))
  66                              (value (if named-p (cdr element) element)))
  67                         (cond ((eq value *inspect-unbound-object-marker*)
  68                                (format s "~%That slot is unbound.~%")
  69                                (return-from %inspect (reread)))
  70                               (t
  71                                (%inspect value s)
  72                                ;; If we ever return, then we should be
  73                                ;; looking at *INSPECTED* again.
  74                                (return-from %inspect (redisplay))))))
  75                      ((zerop elements-length)
  76                       (format s "~%The object contains nothing to inspect.~%")
  77                       (return-from %inspect (reread)))
  78                      (t
  79                       (format s "~%Enter a valid index (~:[0-~W~;0~]).~%"
  80                               (= elements-length 1) (1- elements-length))
  81                       (return-from %inspect (reread))))))
  82             (symbol
  83              (case (find-symbol (symbol-name command) *keyword-package*)
  84                ((:q :e)
  85                 (/show0 "THROWing QUIT-INSPECT for :Q or :E")
  86                 (throw 'quit-inspect nil))
  87                (:u
  88                 (return-from %inspect))
  89                (:r
  90                 (return-from %inspect (redisplay)))
  91                ((:h :? :help)
  92                 (write-string *help-for-inspect* s)
  93                 (return-from %inspect (reread)))
  94                (t
  95                 (eval-for-inspect command s)
  96                 (return-from %inspect (reread)))))
  97             (t
  98              (eval-for-inspect command s)
  99              (return-from %inspect (reread)))))))))
 100
 101 (defun eval-for-inspect (command stream)
 102   (let ((result-list (restart-case (multiple-value-list (eval command))
 103                        (nil () :report "Return to the inspector."
 104                           (format stream "~%returning to the inspector~%")
 105                           (return-from eval-for-inspect nil)))))
 106     ;; FIXME: Much of this interactive-EVAL logic is shared with
 107     ;; the main REPL EVAL and with the debugger EVAL. The code should
 108     ;; be shared explicitly.
 109     (setf /// // // / / result-list)
 110     (setf +++ ++ ++ + + - - command)
 111     (setf *** ** ** * * (car /))
 112     (format stream "~&~{~S~%~}" /)))
 113
 114 (defun tty-display-inspected-parts (description named-p elements stream)
 115   (format stream "~%~A" description)
 116   (let ((index 0))
 117     (dolist (element elements)
 118       (if named-p
 119           (destructuring-bind (name . value) element
 120             (format stream "~W. ~A: ~W~%" index name
 121                     (if (eq value *inspect-unbound-object-marker*)
 122                         "unbound"
 123                         value)))
 124           (format stream "~W. ~W~%" index element))
 125       (incf index))))
 126 \f
 127 ;;;; INSPECTED-PARTS
 128
 129 ;;; Destructure an object for inspection, returning
 130 ;;;   (VALUES DESCRIPTION NAMED-P ELEMENTS),
 131 ;;; where..
 132 ;;;
 133 ;;;   DESCRIPTION is a summary description of the destructured object,
 134 ;;;   e.g. "The object is a CONS.~%".
 135 ;;;
 136 ;;;   NAMED-P determines what representation is used for elements
 137 ;;;   of ELEMENTS. If NAMED-P is true, then each element is
 138 ;;;   (CONS NAME VALUE); otherwise each element is just VALUE.
 139 ;;;
 140 ;;;   ELEMENTS is a list of the component parts of OBJECT (whose
 141 ;;;   representation is determined by NAMED-P).
 142 ;;;
 143 ;;; (The NAMED-P dichotomy is useful because symbols and instances
 144 ;;; need to display both a slot name and a value, while lists and
 145 ;;; vectors need only display a value.)
 146 (defgeneric inspected-parts (object))
 147
 148 (defmethod inspected-parts ((object symbol))
 149   (values (format nil "The object is a SYMBOL.~%" object)
 150           t
 151           (list (cons "Name" (symbol-name object))
 152                 (cons "Package" (symbol-package object))
 153                 (cons "Value" (if (boundp object)
 154                                   (symbol-value object)
 155                                   *inspect-unbound-object-marker*))
 156                 (cons "Function" (if (fboundp object)
 157                                      (symbol-function object)
 158                                      *inspect-unbound-object-marker*))
 159                 (cons "Plist" (symbol-plist object)))))
 160
 161 (defun inspected-structure-elements (object)
 162   (let ((parts-list '())
 163         (info (layout-info (sb-kernel:layout-of object))))
 164     (when (sb-kernel::defstruct-description-p info)
 165       (dolist (dd-slot (dd-slots info) (nreverse parts-list))
 166         (push (cons (dsd-%name dd-slot)
 167                     (funcall (dsd-accessor-name dd-slot) object))
 168               parts-list)))))
 169
 170 (defmethod inspected-parts ((object structure-object))
 171   (values (format nil "The object is a STRUCTURE-OBJECT of type ~S.~%"
 172                   (type-of object))
 173           t
 174           (inspected-structure-elements object)))
 175
 176 (defun inspected-standard-object-elements (object)
 177   (let ((reversed-elements nil)
 178         (class-slots (sb-pcl::class-slots (class-of object))))
 179     (dolist (class-slot class-slots (nreverse reversed-elements))
 180       (let* ((slot-name (slot-value class-slot 'sb-pcl::name))
 181              (slot-value (if (slot-boundp object slot-name)
 182                              (slot-value object slot-name)
 183                              *inspect-unbound-object-marker*)))
 184         (push (cons slot-name slot-value) reversed-elements)))))
 185
 186 (defmethod inspected-parts ((object standard-object))
 187   (values (format nil "The object is a STANDARD-OBJECT of type ~S.~%"
 188                   (type-of object))
 189           t
 190           (inspected-standard-object-elements object)))
 191
 192 (defmethod inspected-parts ((object funcallable-instance))
 193   (values (format nil "The object is a FUNCALLABLE-INSTANCE of type ~S.~%"
 194                   (type-of object))
 195           t
 196           (inspected-structure-elements object)))
 197
 198 (defmethod inspected-parts ((object function))
 199   (let* ((type (sb-kernel:widetag-of object))
 200          (object (if (= type sb-vm:closure-header-widetag)
 201                      (sb-kernel:%closure-fun object)
 202                      object)))
 203     (values (format nil "FUNCTION ~S.~@[~%Argument List: ~A~]." object
 204                     (sb-kernel:%simple-fun-arglist object)
 205                     ;; Defined-from stuff used to be here. Someone took
 206                     ;; it out. FIXME: We should make it easy to get
 207                     ;; to DESCRIBE from the inspector.
 208                     )
 209             t
 210             nil)))
 211
 212 (defmethod inspected-parts ((object vector))
 213   (values (format nil
 214                   "The object is a ~:[~;displaced ~]VECTOR of length ~W.~%"
 215                   (and (array-header-p object)
 216                        (%array-displaced-p object))
 217                   (length object))
 218           nil
 219           ;; FIXME: Should we respect *INSPECT-LENGTH* here? If not, what
 220           ;; does *INSPECT-LENGTH* mean?
 221           (coerce object 'list)))
 222
 223 (defun inspected-index-string (index rev-dimensions)
 224   (if (null rev-dimensions)
 225       "[]"
 226       (let ((list nil))
 227         (dolist (dim rev-dimensions)
 228           (multiple-value-bind (q r) (floor index dim)
 229             (setq index q)
 230             (push r list)))
 231         (format nil "[~W~{,~W~}]" (car list) (cdr list)))))
 232
 233 (defmethod inspected-parts ((object array))
 234   (let* ((length (min (array-total-size object) *inspect-length*))
 235          (reference-array (make-array length :displaced-to object))
 236          (dimensions (array-dimensions object))
 237          (reversed-elements nil))
 238     ;; FIXME: Should we respect *INSPECT-LENGTH* here? If not, what does
 239     ;; *INSPECT-LENGTH* mean?
 240     (dotimes (i length)
 241       (push (cons (format nil
 242                           "~A "
 243                           (inspected-index-string i (reverse dimensions)))
 244                   (aref reference-array i))
 245             reversed-elements))
 246     (values (format nil "The object is ~:[a displaced~;an~] ARRAY of ~A.~%~
 247                          Its dimensions are ~S.~%"
 248                     (array-element-type object)
 249                     (and (array-header-p object)
 250                          (%array-displaced-p object))
 251                     dimensions)
 252             t
 253             (nreverse reversed-elements))))
 254
 255 (defmethod inspected-parts ((object cons))
 256   (if (consp (cdr object))
 257       (inspected-parts-of-nontrivial-list object)
 258       (inspected-parts-of-simple-cons object)))
 259
 260 (defun inspected-parts-of-simple-cons (object)
 261   (values "The object is a CONS.
 262 "
 263           t
 264           (list (cons 'car (car object))
 265                 (cons 'cdr (cdr object)))))
 266
 267 (defun inspected-parts-of-nontrivial-list (object)
 268   (let ((length 0)
 269         (in-list object)
 270         (reversed-elements nil))
 271     (flet ((done (description-format)
 272              (return-from inspected-parts-of-nontrivial-list
 273                (values (format nil description-format length)
 274                        t
 275                        (nreverse reversed-elements)))))
 276       (loop
 277        (cond ((null in-list)
 278               (done "The object is a proper list of length ~S.~%"))
 279              ((>= length *inspect-length*)
 280               (push (cons 'rest in-list) reversed-elements)
 281               (done "The object is a long list (more than ~S elements).~%"))
 282              ((consp in-list)
 283               (push (cons length (pop in-list)) reversed-elements)
 284               (incf length))
 285              (t
 286               (push (cons 'rest in-list) reversed-elements)
 287               (done "The object is an improper list of length ~S.~%")))))))
 288
 289 (defmethod inspected-parts ((object t))
 290   (values (format nil "The object is an ATOM:~%  ~W~%" object) nil nil))