add current-filename, add-to-path, add-to-load-path

* module/ice-9/boot-9.scm (current-filename, add-to-path)
  (add-to-load-path): New syntaxen.

* doc/ref/api-evaluation.texi (Loading): Move load-path related
  procedures to a new section:
  (Load Paths): Hither.  Document add-to-path and add-to-load-path.

* doc/ref/api-debug.texi (Source Properties): Document
  current-source-location and current-filename.

* doc/ref/api-modules.texi:
* doc/ref/guile-invoke.texi:
* doc/ref/scheme-using.texi: Update @ref for Load Paths change.

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))