diff options
author | Andy Wingo <wingo@pobox.com> | 2021-03-04 21:41:28 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2021-03-04 21:42:22 +0100 |
commit | 579870abbc5cce00793933a9ab81b93e138f68da (patch) | |
tree | 25702fd7243362a61e0d4e2e8ebf7d8c7dc34182 /doc/ref/api-debug.texi | |
parent | 2c3029e6608455d2a60fad90060db9ef49530a12 (diff) | |
download | guile-579870abbc5cce00793933a9ab81b93e138f68da.tar.gz |
Update documentation to incorporate read-syntax
* NEWS: Update a bit.
* doc/ref/api-debug.texi (Source Properties): Mention read-syntax.
* doc/ref/api-evaluation.texi (Annotated Scheme Read): New section.
* doc/ref/api-macros.texi (Syntax Case): Update for source vectors.
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r-- | doc/ref/api-debug.texi | 47 |
1 files changed, 19 insertions, 28 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index 6718752fa..e60c2ae9f 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, 2011, 2012, 2013, 2014, 2018 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, 2011, 2012, 2013, 2014, 2018, 2021 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -245,35 +245,24 @@ frame. See its source code for more details. @node Source Properties @subsection 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. @xref{Annotated Scheme Read}, for more on @code{read-syntax}. + @cindex 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 -@dfn{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 cannot -associate source properties with individual symbols, keywords, -characters, booleans, or small integers. This can be seen by typing -@code{(xxx)} and @code{xxx} at the Guile prompt (where the variable -@code{xxx} has not been defined): +Guile only switched to use @code{read-syntax} in 2021, however. For the +previous thirty years, it used a mechanism known as @dfn{source +properties}. -@example -scheme@@(guile-user)> (xxx) -<unnamed port>:4:1: In procedure module-lookup: -<unnamed port>:4:1: Unbound variable: xxx +As Guile reads in Scheme code from file or from standard input, it can +record remembers the file name, line number and column number where each +expression begins in a side table. -scheme@@(guile-user)> xxx -ERROR: In procedure module-lookup: -ERROR: Unbound variable: xxx -@end example - -@noindent -In the latter case, no source properties were stored, so the error -doesn't have any source information. +The way that source properties are stored means that 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 +@code{read-syntax}. @deffn {Scheme Procedure} supports-source-properties? obj @deffnx {C Function} scm_supports_source_properties_p (obj) @@ -283,7 +272,9 @@ otherwise return #f. The recording of source properties is controlled by the read option named ``positions'' (@pxref{Scheme Read}). This option is switched -@emph{on} by default. +@emph{on} by default. Now that @code{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. |