Source Properties - Guile Reference Manual

Next: Using Traps, Previous: Breakpoints, Up: Debugging

5.21.3 Source Properties

As Guile reads in Scheme code from file or from standard input, it remembers the file name, line number and column number where each expression begins. These pieces of information are known as the source properties of the expression. If an expression undergoes transformation — for example, if there is a syntax transformer in effect, or the expression is a macro call — the source properties are copied from the untransformed to the transformed expression so that, if an error occurs when evaluating the transformed expression, Guile's debugger can point back to the file and location where the expression originated.

The way that source properties are stored means that Guile can only associate source properties with parenthesized expressions, and not, for example, with individual symbols, numbers or strings. The difference can be seen by typing (xxx) and xxx at the Guile prompt (where the variable xxx has not been defined):

     guile> (xxx)
     standard input:2:1: In expression (xxx):
     standard input:2:1: Unbound variable: xxx
     ABORT: (unbound-variable)
     guile> xxx
     <unnamed port>: In expression xxx:
     <unnamed port>: Unbound variable: xxx
     ABORT: (unbound-variable)

In the latter case, no source properties were stored, so the best that Guile could say regarding the location of the problem was “<unnamed port>”.

The recording of source properties is controlled by the read option named “positions” (see Reader options). This option is switched on by default, together with the debug options “debug” and “backtrace” (see Debugger options), when Guile is run interactively; all these options are 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.

— Scheme Procedure: set-source-properties! obj plist
— C Function: scm_set_source_properties_x (obj, plist)

Install the association list plist as the source property list for obj.

— Scheme Procedure: set-source-property! obj key datum
— C Function: scm_set_source_property_x (obj, key, datum)

Set the source property of object obj, which is specified by key to datum. Normally, the key will be a symbol.

— Scheme Procedure: source-properties obj
— C Function: scm_source_properties (obj)

Return the source property association list of obj.

— Scheme Procedure: source-property obj key
— C Function: scm_source_property (obj, key)

Return the source property specified by key from obj's source property list.

In practice there are only two ways that you should use the ability to set an expression's source breakpoints.

To set a breakpoint on an expression, use (set-source-property!expr 'breakpoint #t). If you do this, you should also set the traps and enter-frame-handler trap options (see Evaluator trap options) and breakpoints debug option (see Debugger options) appropriately, and the evaluator will then call your enter frame handler whenever it is about to evaluate that expression.
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 set-source-property! to set the expression's filename, line and column properties. The properties that you set will then show up later if that expression is involved in a backtrace or error report.

If you are looking for a way to attach arbitrary information to an expression other than these properties, you should use make-object-property instead (see 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.