---

6.26.2 Source Properties

How best to associate source locations with datums parsed from a port? The right way to do this is to annotate all components of each parsed datum. See Reading Scheme Code, For the Compiler, for more on read-syntax.

Guile only switched to use read-syntax in 2021, however. For the previous thirty years, it used a mechanism known as source properties.

As Guile reads in Scheme code from file or from standard input, it can record the file name, line number and column number where each expression begins in a side table.

The way that this side table associates datums with source properties has a limitation, however: Guile can only associate source properties with freshly allocated objects. This notably excludes individual symbols, keywords, characters, booleans, or small integers. This limitation finally motivated the switch to read-syntax.

Scheme Procedure: supports-source-properties? obj ¶

C Function: scm_supports_source_properties_p (obj) ¶

Return #t if source properties can be associated with obj, otherwise return #f.

The recording of source properties is controlled by the read option named “positions” (see Reading Scheme Code). This option is switched on by default. Now that read-syntax is available, however, Guile may change the default for this flag to off in the future.

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, supported expressions will have values set for the filename, line and column properties.

Source properties are also associated with syntax objects. Procedural macros can get at the source location of their input using the syntax-source accessor. See Syntax Transformer Helpers, for more.

Guile also defines a couple of convenience macros built on syntax-source:

Scheme Syntax: current-source-location ¶

Expands to the source properties corresponding to the location of the (current-source-location) form.

Scheme Syntax: current-filename ¶

Expands to the current filename: the filename that the (current-filename) form appears in. Expands to #f if this information is unavailable.

If you’re stuck with defmacros (see 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.