diff options
-rw-r--r-- | doc/ref/api-debug.texi | 21 | ||||
-rw-r--r-- | doc/ref/api-evaluation.texi | 125 | ||||
-rw-r--r-- | doc/ref/api-modules.texi | 2 | ||||
-rw-r--r-- | doc/ref/guile-invoke.texi | 2 | ||||
-rw-r--r-- | doc/ref/scheme-using.texi | 4 | ||||
-rw-r--r-- | module/ice-9/boot-9.scm | 21 |
6 files changed, 124 insertions, 51 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index bdb616656..2083daab6 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 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2010, 2011, 2012 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -292,6 +292,25 @@ If the @code{positions} reader option is enabled, each parenthesized expression will have values set for the @code{filename}, @code{line} and @code{column} properties. +Source properties are also associated with syntax objects. Procedural +macros can get at the source location of their input using the +@code{syntax-source} accessor. @xref{Syntax Transformer Helpers}, for +more. + +Guile also defines a couple of convenience macros built on +@code{syntax-source}: + +@deffn {Scheme Syntax} current-source-location +Expands to the source properties corresponding to the location of the +@code{(current-source-location)} form. +@end deffn + +@deffn {Scheme Syntax} current-filename +Expands to the current filename: the filename that the +@code{(current-filename)} form appears in. Expands to @code{#f} if this +information is unavailable. +@end deffn + If you're stuck with defmacros (@pxref{Defmacros}), and want to preserve source information, the following helper function might be useful to you: diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 2e48dcbe2..ed3b88cbb 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -17,6 +17,7 @@ loading, evaluating, and compiling Scheme code at run time. * Fly Evaluation:: Procedures for on the fly evaluation. * Compilation:: How to compile Scheme files and procedures. * Loading:: Loading Scheme code from file. +* Load Paths:: Where Guile looks for code. * Character Encoding of Source Files:: Loading non-ASCII Scheme code from file. * Delayed Evaluation:: Postponing evaluation until it is needed. @end menu @@ -711,7 +712,7 @@ useful compilation warnings. It can be customized from @file{~/.guile}. @rnindex load @deffn {Scheme Procedure} load filename [reader] Load @var{filename} and evaluate its contents in the top-level -environment. The load paths are not searched. +environment. @var{reader} if provided should be either @code{#f}, or a procedure with the signature @code{(lambda (port) @dots{})} which reads the next @@ -730,29 +731,21 @@ documentation for @code{%load-hook} later in this section. @end deffn @deffn {Scheme Procedure} load-compiled filename -Load the compiled file named @var{filename}. The load paths are not -searched. +Load the compiled file named @var{filename}. Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then calling @code{load-compiled} on the resulting file is equivalent to calling @code{load} on the source file. @end deffn -@deffn {Scheme Procedure} load-from-path filename -Similar to @code{load}, but searches for @var{filename} in the load -paths. Preferentially loads a compiled version of the file, if it is -available and up-to-date. -@end deffn - @deffn {Scheme Procedure} primitive-load filename @deffnx {C Function} scm_primitive_load (filename) -Load the file named @var{filename} and evaluate its contents in -the top-level environment. The load paths are not searched; -@var{filename} must either be a full pathname or be a pathname -relative to the current directory. If the variable -@code{%load-hook} is defined, it should be bound to a procedure -that will be called before any code is loaded. See the -documentation for @code{%load-hook} later in this section. +Load the file named @var{filename} and evaluate its contents in the +top-level environment. @var{filename} must either be a full pathname or +be a pathname relative to the current directory. If the variable +@code{%load-hook} is defined, it should be bound to a procedure that +will be called before any code is loaded. See the documentation for +@code{%load-hook} later in this section. @end deffn @deftypefn {C Function} SCM scm_c_primitive_load (const char *filename) @@ -760,33 +753,6 @@ documentation for @code{%load-hook} later in this section. @code{SCM}. @end deftypefn -@deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found] -@deffnx {C Function} scm_primitive_load_path (filename) -Search @code{%load-path} for the file named @var{filename} and -load it into the top-level environment. If @var{filename} is a -relative pathname and is not found in the list of search paths, -an error is signalled. Preferentially loads a compiled version of the -file, if it is available and up-to-date. - -By default or if @var{exception-on-not-found} is true, an exception is -raised if @var{filename} is not found. If @var{exception-on-not-found} -is @code{#f} and @var{filename} is not found, no exception is raised and -@code{#f} is returned. For compatibility with Guile 1.8 and earlier, -the C function takes only one argument, which can be either a string -(the file name) or an argument list. -@end deffn - -@deffn {Scheme Procedure} %search-load-path filename -@deffnx {C Function} scm_sys_search_load_path (filename) -Search @code{%load-path} for the file named @var{filename}, -which must be readable by the current user. If @var{filename} -is found in the list of paths to search or is an absolute -pathname, return its full pathname. Otherwise, return -@code{#f}. Filenames may have any of the optional extensions -in the @code{%load-extensions} list; @code{%search-load-path} -will try each extension automatically. -@end deffn - @defvar current-reader @code{current-reader} holds the read procedure that is currently being used by the above loading procedures to read expressions (from the file @@ -814,9 +780,9 @@ change occurs at the right time. @defvar %load-hook A procedure to be called @code{(%load-hook @var{filename})} whenever a file is loaded, or @code{#f} for no such call. @code{%load-hook} is -used by all of the above loading functions (@code{load}, -@code{load-path}, @code{primitive-load} and -@code{primitive-load-path}). +used by all of the loading functions (@code{load} and +@code{primitive-load}, and @code{load-path} and +@code{primitive-load-path} documented in the next section). For example an application can set this to show what's loaded, @@ -834,6 +800,72 @@ Return the current-load-port. The load port is used internally by @code{primitive-load}. @end deffn +@node Load Paths +@subsection Load Paths + +The procedure in the previous section look for Scheme code in the file +system at specific location. Guile also has some procedures to search +the load path for code. + +For more on the @code{%load-path} variable, @xref{Build Config}. + +@deffn {Scheme Procedure} load-from-path filename +Similar to @code{load}, but searches for @var{filename} in the load +paths. Preferentially loads a compiled version of the file, if it is +available and up-to-date. +@end deffn + +A user can extend the load path by calling @code{add-to-load-path}. + +@deffn {Scheme Syntax} add-to-load-path dir +Add @var{dir} to the load path. + +For example, a script might include this form to add the directory that +it is in to the load path: + +@example +(add-to-load-path (dirname (current-filename))) +@end example +@end deffn + +It's better to use @code{add-to-load-path} than to modify +@code{%load-path} directly, because @code{add-to-load-path} takes care +of modifying the path both at compile-time and at run-time. + +There is a more general version for use with other paths, like +@code{%load-compiled-path}: + +@deffn {Scheme Syntax} add-to-path path dir +Add @var{dir} to @var{path}. +@end deffn + +@deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found] +@deffnx {C Function} scm_primitive_load_path (filename) +Search @code{%load-path} for the file named @var{filename} and +load it into the top-level environment. If @var{filename} is a +relative pathname and is not found in the list of search paths, +an error is signalled. Preferentially loads a compiled version of the +file, if it is available and up-to-date. + +By default or if @var{exception-on-not-found} is true, an exception is +raised if @var{filename} is not found. If @var{exception-on-not-found} +is @code{#f} and @var{filename} is not found, no exception is raised and +@code{#f} is returned. For compatibility with Guile 1.8 and earlier, +the C function takes only one argument, which can be either a string +(the file name) or an argument list. +@end deffn + +@deffn {Scheme Procedure} %search-load-path filename +@deffnx {C Function} scm_sys_search_load_path (filename) +Search @code{%load-path} for the file named @var{filename}, +which must be readable by the current user. If @var{filename} +is found in the list of paths to search or is an absolute +pathname, return its full pathname. Otherwise, return +@code{#f}. Filenames may have any of the optional extensions +in the @code{%load-extensions} list; @code{%search-load-path} +will try each extension automatically. +@end deffn + @defvar %load-extensions A list of default file extensions for files containing Scheme code. @code{%search-load-path} tries each of these extensions when looking for @@ -841,6 +873,7 @@ a file to load. By default, @code{%load-extensions} is bound to the list @code{("" ".scm")}. @end defvar + @node Character Encoding of Source Files @subsection Character Encoding of Source Files diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index 9830cfd53..3c96c2a55 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -468,7 +468,7 @@ the @code{%load-path} (@pxref{Build Config}). For each directory in @code{%load-path}, Guile will try to find the file name, concatenated with the extensions from @code{%load-extensions}. By default, this will cause Guile to @code{stat} @file{ice-9/popen.scm}, and then -@file{ice-9/popen}. @xref{Loading}, for more on +@file{ice-9/popen}. @xref{Load Paths}, for more on @code{primitive-load-path}. If a corresponding compiled @file{.go} file is found in the diff --git a/doc/ref/guile-invoke.texi b/doc/ref/guile-invoke.texi index ccb530157..08c169864 100644 --- a/doc/ref/guile-invoke.texi +++ b/doc/ref/guile-invoke.texi @@ -73,7 +73,7 @@ the user's @file{.guile} file. @item -x @var{extension} Add @var{extension} to the front of Guile's load extension list -(@pxref{Loading, @code{%load-extensions}}). The specified extensions +(@pxref{Load Paths, @code{%load-extensions}}). The specified extensions are tried in the order given on the command line, and before the default load extensions. Extensions added here are @emph{not} in effect during execution of the user's @file{.guile} file. diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi index 73e1a5dec..07096bb41 100644 --- a/doc/ref/scheme-using.texi +++ b/doc/ref/scheme-using.texi @@ -750,8 +750,8 @@ The first thing to do is to install your Scheme files where Guile can find them. When Guile goes to find a Scheme file, it will search a @dfn{load path} to find the file: first in Guile's own path, then in paths for @dfn{site packages}. A site package is any Scheme code that -is installed and not part of Guile itself. @xref{Loading}, for more on -load paths. +is installed and not part of Guile itself. @xref{Load Paths}, for more +on load paths. There are several site paths, for historical reasons, but the one that should generally be used can be obtained by invoking the diff --git a/module/ice-9/boot-9.scm b/module/ice-9/boot-9.scm index 86ca875a5..3e43b8ca0 100644 --- a/module/ice-9/boot-9.scm +++ b/module/ice-9/boot-9.scm @@ -512,6 +512,18 @@ If there is no handler at all, Guile prints an error and then exits." (with-syntax ((s (datum->syntax x (syntax-source x)))) #''s))))) +;; We provide this accessor out of convenience. current-line and +;; current-column aren't so interesting, because they distort what they +;; are measuring; better to use syntax-source from a macro. +;; +(define-syntax current-filename + (lambda (x) + "A macro that expands to the current filename: the filename that +the (current-filename) form appears in. Expands to #f if this +information is unavailable." + (and=> (syntax-source x) + (lambda (s) (assq-ref s 'filename))))) + (define-syntax-rule (define-once sym val) (define sym (if (module-locally-bound? (current-module) 'sym) sym val))) @@ -1390,6 +1402,15 @@ VALUE." (start-stack 'load-stack (primitive-load-path name))) +(define-syntax-rule (add-to-path path elt) + "Add ELT to PATH, at compile-time and at run-time." + (eval-when (compile load eval) + (set! path (cons elt path)))) + +(define-syntax-rule (add-to-load-path elt) + "Add ELT to Guile's load path, at compile-time and at run-time." + (add-to-path %load-path elt)) + (define %load-verbosely #f) (define (assert-load-verbosity v) (set! %load-verbosely v)) |