/[slime]/slime/swank-backend.lisp
ViewVC logotype

Contents of /slime/swank-backend.lisp

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (show annotations)
Sun Nov 23 14:13:05 2003 UTC (10 years, 4 months ago) by lgorrie
Branch: MAIN
Changes since 1.2: +63 -1 lines
(backtrace, eval-in-frame, frame-catch-tags, frame-locals,
frame-source-location-for-emacs): More interface functions.
1 ;;;; -*- Mode: lisp; indent-tabs-mode: nil; outline-regexp: ";;;;;*" -*-
2 ;;;
3 ;;; slime-impl.lisp --- Slime interface reference implementation.
4 ;;;
5 ;;; Copyright (C) 2003, James Bielman <jamesjb@jamesjb.com>
6 ;;; Released into the public domain.
7 ;;;
8 ;;; $Id: swank-backend.lisp,v 1.3 2003/11/23 14:13:05 lgorrie Exp $
9 ;;;
10
11 ;; This is a skeletal implementation of the Slime internals interface.
12 ;;
13 ;; The idea is to create a de-facto standard interface that can be
14 ;; used by editor <-> CL integration software, such as Slime. Vendors
15 ;; are encouraged to comment on this interface.
16
17 (defpackage :swank
18 (:use :common-lisp)
19 (:nicknames #:swank-backend)
20 (:export #:start-server #:create-swank-server
21 #:*sldb-pprint-frames*))
22
23
24 (in-package :swank)
25
26
27 ;;;; Conditions and Error Handling
28
29 ;; XXX need to specify restart behavior for errors/warnings?
30
31 (define-condition not-implemented-error (error)
32 ())
33
34 (deftype severity () '(member :error :warning :style-warning :note))
35
36 ;; Base condition type for compiler errors, warnings and notes.
37 (define-condition compiler-condition (condition)
38 ((original-condition
39 ;; The original condition thrown by the compiler if appropriate.
40 ;; May be NIL if a compiler does not report using conditions.
41 :initarg :original-condition
42 :accessor original-condition)
43
44 (severity
45 :type severity
46 :initarg :severity
47 :accessor severity)
48
49 (message
50 :documentation "The error or warning message, must be a non-NIL string."
51 :initarg :message
52 :accessor message)
53
54 (location
55 :initarg :location
56 :accessor location)))
57
58
59 ;;;; Compilation
60
61 (defgeneric compile-string-for-emacs (string &key buffer position)
62 (:documentation
63 "Compile source from STRING. During compilation, compiler
64 conditions must be trapped and resignalled as COMPILER-CONDITIONs.
65
66 If supplied, BUFFER and POSITION specify the source location in Emacs.
67
68 Additionally, if POSITION is supplied, it must be added to source
69 positions reported in compiler conditions."))
70
71 (defgeneric compile-file-for-emacs (filename load-p)
72 (:documentation
73 "Compile FILENAME signalling COMPILE-CONDITIONs.
74 If LOAD-P is true, load the file after compilation."))
75
76
77 ;;;; Documentation
78
79 (defgeneric arglist-string (function-name)
80 (:documentation
81 "Return the argument for FUNCTION-NAME as a string.
82 The result should begin and end with parenthesis."))
83
84 (defgeneric macroexpand-all (form)
85 (:documentation
86 "Recursively expand all macros in FORM.
87 Return the resulting form."))
88
89 (defgeneric describe-symbol-for-emacs (symbol)
90 (:documentation
91 "Return a property list describing SYMBOL.
92
93 The property list has an entry for each interesting aspect of the
94 symbol. The recognised keys are:
95
96 :VARIABLE :FUNCTION :SETF :TYPE :CLASS :MACRO :COMPILER-MACRO
97 :ALIEN-TYPE :ALIEN-STRUCT :ALIEN-UNION :ALIEN-ENUM
98
99 The value of each property is the corresponding documentation string,
100 or :NOT-DOCUMENTED. It is legal to include keys not listed here.
101
102 Properties should be included if and only if they are applicable to
103 the symbol. For example, only (and all) fbound symbols should include
104 the :FUNCTION property.
105
106 Example:
107 \(describe-symbol-for-emacs 'vector)
108 => (:CLASS :NOT-DOCUMENTED
109 :TYPE :NOT-DOCUMENTED
110 :FUNCTION \"Constructs a simple-vector from the given objects.\")"))
111
112
113 ;;;; Debugging
114
115 (defgeneric call-with-debugging-environment (debugger-loop-fn)
116 (:documentation
117 "Call DEBUGGER-LOOP-FN in a suitable debugging environment.
118
119 This function is called recursively at each debug level to invoke the
120 debugger loop. The purpose is to setup any necessary environment for
121 other debugger callbacks that will be called within the debugger loop.
122
123 For example, this is a reasonable place to compute a backtrace, switch
124 to safe reader/printer settings, and so on."))
125
126 (define-condition sldb-condition (condition)
127 ((original-condition
128 :initarg :original-condition
129 :accessor :original-condition))
130 (:documentation
131 "Wrapper for conditions that should not be debugged.
132
133 When a condition arises from the internals of the debugger, it is not
134 desirable to debug it -- we'd risk entering an endless loop trying to
135 debug the debugger! Instead, such conditions can be reported to the
136 user without (re)entering the debugger by wrapping them as
137 `sldb-condition's."))
138
139 (defgeneric debugger-info-for-emacs (start end)
140 (:documentation
141 "Return debugger state, with stack frames from START to END.
142 The result is a list:
143 (condition-description ({restart}*) ({stack-frame}*)
144 where
145 restart ::= (name description)
146 stack-frame ::= (number description)
147
148 condition-description---a string describing the condition that
149 triggered the debugger.
150
151 restart---a pair of strings: restart name, and description.
152
153 stack-frame---a number from zero (the top), and a printed
154 representation of the frame's call.
155
156 Below is an example return value. In this case the condition was a
157 division by zero (multi-line description), and only one frame is being
158 fetched (start=0, end=1).
159
160 (\"Arithmetic error DIVISION-BY-ZERO signalled.
161 Operation was KERNEL::DIVISION, operands (1 0).
162 [Condition of type DIVISION-BY-ZERO]\"
163 ((\"ABORT\" \"Return to Slime toplevel.\")
164 (\"ABORT\" \"Return to Top-Level.\"))
165 ((0 \"0: (KERNEL::INTEGER-/-INTEGER 1 0)\")))"))
166
167 (defgeneric backtrace (start end)
168 (:documentation
169 "Return a list containing a backtrace of the condition current
170 being debugged. The results are unspecified if this function is
171 called outside the dynamic contour of a debugger hook defined by
172 DEFINE-DEBUGGER-HOOK.
173
174 START and END are zero-based indices constraining the number of
175 frames returned. Frame zero is defined as the frame which invoked
176 the debugger.
177
178 The backtrace is returned as a list of tuples of the form
179 \(FRAME-NUMBER FRAME-DESCRIPTION), where FRAME-NUMBER is the
180 index of the frame, defined like START/END, and FRAME-DESCRIPTION
181 is a string containing text to display in the debugger for this
182 frame.
183
184 An example return value:
185
186 ((0 \"(HELLO \"world\")\")
187 (1 \"(RUN-EXCITING-LISP-DEMO)\")
188 (2 \"(SYS::%TOPLEVEL #<SYS::ENVIRONMENT #x394834>)\"))"))
189
190 (defgeneric frame-source-location-for-emacs (frame-number)
191 (:documentation
192 "Return the source location for FRAME-NUMBER."))
193
194 (defgeneric frame-catch-tags (frame-number)
195 (:documentation
196 "Return a list of XXX list of what? catch tags for a debugger
197 stack frame. The results are undefined unless this is called
198 within the dynamic contour of a function defined by
199 DEFINE-DEBUGGER-HOOK."))
200
201 (defgeneric frame-locals (frame-number)
202 (:documentation
203 "Return a list of XXX local variable designators define me
204 for a debugger stack frame. The results are undefined unless
205 this is called within the dynamic contour of a function defined
206 by DEFINE-DEBUGGER-HOOK."))
207
208 (defgeneric eval-in-frame (form frame-number)
209 (:documentation
210 "Evaluate a Lisp form in the lexical context of a stack frame
211 in the debugger. The results are undefined unless called in the
212 dynamic contour of a function defined by DEFINE-DEBUGGER-HOOK.
213
214 FRAME-NUMBER must be a positive integer with 0 indicating the
215 frame which invoked the debugger.
216
217 The return value is the result of evaulating FORM in the
218 appropriate context."))
219
220
221 ;;;; Queries
222
223 (defgeneric function-source-location-for-emacs (function-name)
224 (:documentation
225 "Return the canonical source location FUNCTION-NAME.
226
227 FIXME: Document the plethora of valid return types."))
228

  ViewVC Help
Powered by ViewVC 1.1.5