6.25.2 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. Syntax expanders and the compiler propagate these source properties to compiled procedures, 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):

scheme@(guile-user)> (xxx)
<unnamed port>:4:1: In procedure module-lookup:
<unnamed port>:4:1: Unbound variable: xxx

scheme@(guile-user)> xxx
ERROR: In procedure module-lookup:
ERROR: Unbound variable: xxx

In the latter case, no source properties were stored, so the error doesn’t have any source information.

The recording of source properties is controlled by the read option named “positions” (see section Reading Scheme Code). This option is switched on by default.

The following procedures can be used to access and set the source properties of read expressions.

Scheme Procedure: set-source-properties! obj alist

C Function: scm_set_source_properties_x (obj, alist)

Install the association list alist 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 property specified by key from obj’s source properties.

If the positions reader option is enabled, each parenthesized expression will have values set for the filename, line and column properties.

If you’re stuck with defmacros (see section Lisp-style Macro Definitions), and want to preserve source information, the following helper function might be useful to you:

Scheme Procedure: cons-source xorig x y

C Function: scm_cons_source (xorig, x, y)

Create and return a new pair whose car and cdr are x and y. Any source properties associated with xorig are also associated with the new pair.