Added (declare (stepper trace)) for functions.
[com-informatimago:com-informatimago.git] / common-lisp / lisp / stepper-packages.lisp
1 ;;;; -*- mode:lisp;coding:utf-8 -*-
2 ;;;;**************************************************************************
3 ;;;;FILE:               stepper-packages.lisp
4 ;;;;LANGUAGE:           Common-Lisp
5 ;;;;SYSTEM:             Common-Lisp
6 ;;;;USER-INTERFACE:     NONE
7 ;;;;DESCRIPTION
8 ;;;;    
9 ;;;;    Defines the Common Lisp Stepper packages.
10 ;;;;    
11 ;;;;AUTHORS
12 ;;;;    <PJB> Pascal J. Bourguignon <pjb@informatimago.com>
13 ;;;;MODIFICATIONS
14 ;;;;    2012-08-09 <PJB> Extracted from stepper.lisp
15 ;;;;BUGS
16 ;;;;LEGAL
17 ;;;;    AGPL3
18 ;;;;    
19 ;;;;    Copyright Pascal J. Bourguignon 2012 - 2012
20 ;;;;    
21 ;;;;    This program is free software: you can redistribute it and/or modify
22 ;;;;    it under the terms of the GNU Affero General Public License as published by
23 ;;;;    the Free Software Foundation, either version 3 of the License, or
24 ;;;;    (at your option) any later version.
25 ;;;;    
26 ;;;;    This program is distributed in the hope that it will be useful,
27 ;;;;    but WITHOUT ANY WARRANTY; without even the implied warranty of
28 ;;;;    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
29 ;;;;    GNU Affero General Public License for more details.
30 ;;;;    
31 ;;;;    You should have received a copy of the GNU Affero General Public License
32 ;;;;    along with this program.  If not, see <http://www.gnu.org/licenses/>.
33 ;;;;**************************************************************************
34
35
36 ;; We define an internal package that uses COMMON-LISP to easily
37 ;; define functions and macros, since the CL-STEPPER package shadows
38 ;; all the special operators and defun, defgeneric and defmacro
39 ;; macros.
40 ;;
41 ;; The CL-STEPPER package only contains those shadowed macro
42 ;; definitions.
43
44
45 (defpackage "COM.INFORMATIMAGO.COMMON-LISP.LISP.STEPPER.INTERNAL"
46   
47   (:use "COMMON-LISP"
48         "COM.INFORMATIMAGO.COMMON-LISP.LISP-SEXP.SOURCE-FORM")
49
50   (:export
51    "*STEP-PACKAGE*"
52    "*STEP-PRINT-READABLY*" 
53    "*STEP-PRINT-LENGTH*"   
54    "*STEP-PRINT-LEVEL*"     
55    "*STEP-PRINT-CASE*"    
56    "*STEP-TRACE-OUTPUT*"
57    "*STEP-MAX-TRACE-DEPTH*"
58    
59    "STEP-TRACE-FUNCTION" "STEP-UNTRACE-FUNCTION"
60    "STEP-BREAK-ENTRY" "STEP-UNBREAK-ENTRY"
61    "STEP-BREAK-EXIT" "STEP-UNBREAK-EXIT"
62
63    "*STEP-MODE*" "*STEP-LEVEL*"
64
65    "WILL-STEP" "DID-BIND" "PRINT-STEP-RESULTS" "DID-STEP" "DID-TAG"
66    
67    "STEP-CONDITION" "STEP-MESSAGE" "STEP-CHOICE"
68
69    "STEPPER" "DISABLE" "STEPPER-DECLARATION-P"
70
71    "STEP-DISABLED"
72    "SUBSTITUTE-IGNORABLE"
73    "SIMPLE-STEP"
74    "STEP-SIMPLE-FORM" "STEP-ATOM"
75    "STEP-EXPRESSION"
76    "STEP-BODY"
77    "STEP-FUNCTION"
78    "STEP-LAMBDA"
79    "STEP-BINDINGS")
80   
81   (:documentation "
82 This is an internal package of the Common Lisp stepper.
83 This package exports the  stepper generator functions,
84 and defines stepper interactive functions (not exported).
85
86 See the documentation of the package
87 COM.INFORMATIMAGO.COMMON-LISP.LISP.STEPPER.
88
89 BUGS: we should probably design it with hooks so that clients may
90       define the stepping/tracing user interface.
91
92 Copyright Pascal J. Bourguignon 2012 - 2012
93 This package is provided under the Afero General Public License 3.
94 See the source file for details.
95
96 "))
97
98
99 (defpackage "COM.INFORMATIMAGO.COMMON-LISP.LISP.STEPPER"
100
101   (:nicknames "COMMON-LISP-STEPPER"
102               "CL-STEPPER"
103               "STEPPER")
104   
105   (:use "COMMON-LISP"
106         "COM.INFORMATIMAGO.COMMON-LISP.LISP-SEXP.SOURCE-FORM"
107         "COM.INFORMATIMAGO.COMMON-LISP.LISP.STEPPER.INTERNAL")
108
109   (:shadow ;; macros
110    "DEFUN" "DEFGENERIC" "DEFMETHOD" "LAMBDA"
111    "DEFINE-CONDITION"
112    "STEP")
113   
114   (:shadow ;; special operators
115    "BLOCK" "CATCH" "EVAL-WHEN" "FLET" "FUNCTION" "GO" "IF" "LABELS" "LET" "LET*"
116    "LOAD-TIME-VALUE" "LOCALLY" "MACROLET" "MULTIPLE-VALUE-CALL"
117    "MULTIPLE-VALUE-PROG1" "PROGN" "PROGV" "QUOTE" "RETURN-FROM" "SETQ"
118    "SYMBOL-MACROLET" "TAGBODY" "THE" "THROW" "UNWIND-PROTECT")
119   
120   (:export ;; everything from COMMON-LISP
121    . #.(cl:let ((e '()))
122          (cl:do-external-symbols (s "COMMON-LISP" e)
123            (push (string s) e))))
124
125   (:export
126    "*STEP-MODE*"
127    "*STEP-PRINT-LENGTH*"   
128    "*STEP-PRINT-LEVEL*"     
129    "*STEP-PRINT-CASE*"    
130    "*STEP-PACKAGE*"
131    "*STEP-TRACE-OUTPUT*"
132    "*STEP-MAX-TRACE-DEPTH*"
133    
134    "STEP-TRACE-FUNCTION" "STEP-UNTRACE-FUNCTION"
135    "STEP-BREAK-ENTRY"    "STEP-UNBREAK-ENTRY"
136    "STEP-BREAK-EXIT"     "STEP-UNBREAK-EXIT"
137
138    
139    "STEPPER" "DISABLE" #| "TRACE" already exported as CL symbol |#
140    ;; (declare (stepper disable)) ; to prevent instrumentation of the
141    ;; enclosing sexp and sub expressions.
142    )
143   
144   (:documentation "
145 Implements a Portable Common Lisp Stepper.
146
147 This package should be used instead of COMMON-LISP, and the code
148 recompiled or reloaded.  This will instrumentalize the functions so
149 that tracing and stepping is available.
150
151 To start running some code step-by-step, you can use:
152
153     (step (some-expression)) ; note: it's cl-stepper:step, not cl:step.
154
155 Or you may use STEP-TRACE-FUNCTION, to activate tracing of some functions (that
156 must have been compiled with CL-STEPPER), or STEP-BREAK-ENTRY or
157 STEP-BREAK-EXIT to enter the stepper upon entry or exit of the named
158 functions.
159
160 It is also possible to run the tracer on all the code that has been
161 compiled with CL-STEPPER, with:
162
163    (setf *step-mode* :trace)
164
165 Reset it with:
166
167    (setf *step-mode* :run)
168
169 If you load a lot of packages with CL-STEPPER, you may want to set
170 *STEP-MAX-CALL-DEPTH* to a small integer when using *STEP-MODE*
171 :trace, to avoid very big output.  You may also redirect the tracing
172 output to a different stream setting *STEP-TRACE-OUTPUT*.
173
174 Note: when tracing a function with (step-trace-function fun), the depth is
175 reset while tracing that function (*step-max-call-depth* still applies
176 for the call tree starting from that function).
177
178
179 The stepper menu is:
180
181     Step Into (s, si, RET), Step over (so), Trace (t), Run (r),
182     Debugger (d), Abort (a, q)?
183
184 Step Into:
185
186     Continue evaluating each forms and subforms step by step.
187
188 Step Over:
189
190     Evaluate the current form in one step. 
191
192 Trace:
193
194     The code is executed, and all the instrumented code produces traces.
195
196 Run:
197
198     The code is executed silently.
199
200 Debugger:
201
202     The debugger is invoked with a STEP-CONDITION.  There are restarts
203     installed to invoke all the stepper menu commands.
204
205 Abort:
206
207     The evaluation of the STEP form is aborted.
208
209 With the Step Over, Trace, and Run commands,  if a function with a
210 break-point or an active trace is reached, it will still enter the
211 stepper menu again, or trace it.
212
213
214
215 To disable instrumentation of a form, you can insert (stepper disable)
216 declarations in the places where declarations are allowed.
217
218    (declaim (declaration stepper)) ; for when CL-STEPPER is not used.
219
220    (…
221      (declare (stepper disable))
222      …)
223
224 declarations.  Use (locally (declare (stepper disable)) …) to disable
225 in random places.
226
227
228 Similarly, to force tracing a function or a form,
229 use the (declare (stepper trace)) declaration.
230 \(stepper disable) has priority over (stepper trace).
231
232
233
234 Copyright Pascal J. Bourguignon 2012 - 2012
235 This package is provided under the Afero General Public License 3.
236 See the source file for details.
237
238 "))
239
240
241 ;;;; THE END ;;;;