diff options
-rw-r--r-- | doc/ref/ChangeLog | 11 | ||||
-rw-r--r-- | doc/ref/api-debug.texi | 54 | ||||
-rw-r--r-- | doc/ref/api-procedures.texi | 29 |
3 files changed, 65 insertions, 29 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index c4470dec2..c84c951f6 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,14 @@ +2005-10-15 Neil Jerram <neil@ossau.uklinux.net> + + * api-debug.texi (Source Properties): Add text describing/advising + limited use of source properties. + + * api-debug.texi (Source Properties): Documentation of source + property procedures moved here from ... + + * api-procedures.texi (Procedure Properties): ... where it didn't + belong. + 2005-10-05 Kevin Ryde <user42@zip.com.au> * api-data.texi (Regexp Functions): Notes on zero bytes and locale diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index adf40af61..458ea034e 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -161,6 +161,60 @@ named ``positions'' (@pxref{Reader options}). This option is switched interactively; all these options are @emph{off} by default when Guile runs a script non-interactively. +The following procedures can be used to access and set the source +properties of read expressions. + +@deffn {Scheme Procedure} set-source-properties! obj plist +@deffnx {C Function} scm_set_source_properties_x (obj, plist) +Install the association list @var{plist} as the source property +list for @var{obj}. +@end deffn + +@deffn {Scheme Procedure} set-source-property! obj key datum +@deffnx {C Function} scm_set_source_property_x (obj, key, datum) +Set the source property of object @var{obj}, which is specified by +@var{key} to @var{datum}. Normally, the key will be a symbol. +@end deffn + +@deffn {Scheme Procedure} source-properties obj +@deffnx {C Function} scm_source_properties (obj) +Return the source property association list of @var{obj}. +@end deffn + +@deffn {Scheme Procedure} source-property obj key +@deffnx {C Function} scm_source_property (obj, key) +Return the source property specified by @var{key} from +@var{obj}'s source property list. +@end deffn + +In practice there are only two ways that you should use the ability to +set an expression's source breakpoints. + +@itemize +@item +To set a breakpoint on an expression, use @code{(set-source-property! +@var{expr} 'breakpoint #t)}. If you do this, you should also set the +@code{traps} and @code{enter-frame-handler} trap options +(@pxref{Evaluator trap options}) and @code{breakpoints} debug option +(@pxref{Debugger options}) appropriately, and the evaluator will then +call your enter frame handler whenever it is about to evaluate that +expression. + +@item +To make a read or constructed expression appear to have come from a +different source than what the expression's source properties already +say, you can use @code{set-source-property!} to set the expression's +@code{filename}, @code{line} and @code{column} properties. The +properties that you set will then show up later if that expression is +involved in a backtrace or error report. +@end itemize + +If you are looking for a way to attach arbitrary information to an +expression other than these properties, you should use +@code{make-object-property} instead (@pxref{Object Properties}), because +that will avoid bloating the source property hash table, which is really +only intended for the specific purposes described in this section. + @node Using Traps @subsection Using Traps diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index d623f62f9..e6d520ddf 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -463,35 +463,6 @@ first expression is a string constant, that string is assumed to contain documentation for that procedure. @end deffn -@cindex source properties -@c FIXME::martin: Is the following true? -Source properties are properties which are related to the source code of -a procedure, such as the line and column numbers, the file name etc. - -@deffn {Scheme Procedure} set-source-properties! obj plist -@deffnx {C Function} scm_set_source_properties_x (obj, plist) -Install the association list @var{plist} as the source property -list for @var{obj}. -@end deffn - -@deffn {Scheme Procedure} set-source-property! obj key datum -@deffnx {C Function} scm_set_source_property_x (obj, key, datum) -Set the source property of object @var{obj}, which is specified by -@var{key} to @var{datum}. Normally, the key will be a symbol. -@end deffn - -@deffn {Scheme Procedure} source-properties obj -@deffnx {C Function} scm_source_properties (obj) -Return the source property association list of @var{obj}. -@end deffn - - -@deffn {Scheme Procedure} source-property obj key -@deffnx {C Function} scm_source_property (obj, key) -Return the source property specified by @var{key} from -@var{obj}'s source property list. -@end deffn - @node Procedures with Setters @subsection Procedures with Setters |