Add parse-path-with-ellipsis, and use it for GUILE_LOAD_PATH et al.

* libguile/load.c (scm_ellipsis): New Variable.
  (scm_parse_path_with_ellipsis): New procedure.
  (scm_init_load): Initialize 'scm_ellipsis'.
  (scm_init_load_path): Use 'scm_parse_path_with_ellipsis' to
  handle GUILE_LOAD_PATH and GUILE_LOAD_COMPILED_PATH.

* libguile/load.h (scm_parse_path_with_ellipsis): Add prototype.

* doc/ref/guile-invoke.texi (Environment Variables):
  doc/ref/api-evaluation.texi (Load Paths): Add documentation.
  Correct description of default load path to reflect reality.
  Remove 'GUILE_LOAD_PATH' from the concept index; it is already
  in the variable index.  Add cross references between these two
  sections of the manual.

doc/ref/api-evaluation.texi

@@ -838,14 +838,16 @@ 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.
 
-@cindex @env{GUILE_LOAD_PATH}
 @defvar %load-path
 List of directories which should be searched for Scheme modules and
-libraries.  @code{%load-path} is initialized when Guile starts up to
-@code{(list (%site-dir) (%library-dir) (%package-data-dir))}, prepended
-with the contents of the @env{GUILE_LOAD_PATH} environment variable, if
-it is set.  @xref{Build Config}, for more on @code{%site-dir} and
-related procedures.
+libraries.  When Guile starts up, @code{%load-path} is initialized to
+the default load path @code{(list (%library-dir) (%site-dir)
+(%global-site-dir) (%package-data-dir))}.  The @env{GUILE_LOAD_PATH}
+environment variable can be used to prepend or append additional
+directories (@pxref{Environment Variables}).
+
+@xref{Build Config}, for more on @code{%site-dir} and related
+procedures.
 @end defvar
 
 @deffn {Scheme Procedure} load-from-path filename
@@ -913,7 +915,9 @@ using @code{load-compiled}.
 @defvar %load-compiled-path
 Like @code{%load-path}, but for compiled files.  By default, this path
 has two entries: one for compiled files from Guile itself, and one for
-site packages.
+site packages.  The @env{GUILE_LOAD_COMPILED_PATH} environment variable
+can be used to prepend or append additional directories
+(@pxref{Environment Variables}).
 @end defvar
 
 When @code{primitive-load-path} searches the @code{%load-compiled-path}
@@ -943,6 +947,15 @@ a list and return the resulting list with @var{tail} appended. If
 @var{path} is @code{#f}, @var{tail} is returned.
 @end deffn
 
+@deffn {Scheme Procedure} parse-path-with-ellipsis path base
+@deffnx {C Function} scm_parse_path_with_ellipsis (path, base)
+Parse @var{path}, which is expected to be a colon-separated string, into
+a list and return the resulting list with @var{base} (a list) spliced in
+place of the @code{...} path component, if present, or else @var{base}
+is added to the end.  If @var{path} is @code{#f}, @var{base} is
+returned.
+@end deffn
+
 @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
 @deffnx {C Function} scm_search_path (path, filename, rest)
 Search @var{path} for a directory containing a file named

doc/ref/guile-invoke.texi

@@ -295,8 +295,10 @@ variable.  By default, the history file is @file{$HOME/.guile_history}.
 @vindex GUILE_LOAD_COMPILED_PATH
 This variable may be used to augment the path that is searched for
 compiled Scheme files (@file{.go} files) when loading.  Its value should
-be a colon-separated list of directories, which will be prefixed to the
-value of the default search path stored in @code{%load-compiled-path}.
+be a colon-separated list of directories.  If it contains the special
+path component @code{...} (ellipsis), then the default path is put in
+place of the ellipsis, otherwise the default path is placed at the end.
+The result is stored in @code{%load-compiled-path} (@pxref{Load Paths}).
 
 Here is an example using the Bash shell that adds the current directory,
 @file{.}, and the relative directory @file{../my-library} to
@@ -312,18 +314,23 @@ $ guile -c '(display %load-compiled-path) (newline)'
 @vindex GUILE_LOAD_PATH
 This variable may be used to augment the path that is searched for
 Scheme files when loading.  Its value should be a colon-separated list
-of directories, which will be prefixed to the value of the default
-search path stored in @code{%load-path}.
+of directories.  If it contains the special path component @code{...}
+(ellipsis), then the default path is put in place of the ellipsis,
+otherwise the default path is placed at the end.  The result is stored
+in @code{%load-path} (@pxref{Load Paths}).
 
-Here is an example using the Bash shell that adds the current directory
-and the parent of the current directory to @code{%load-path}:
+Here is an example using the Bash shell that prepends the current
+directory to @code{%load-path}, and adds the relative directory
+@file{../srfi} to the end:
 
 @example
-$ env GUILE_LOAD_PATH=".:.." \
+$ env GUILE_LOAD_PATH=".:...:../srfi" \
 guile -c '(display %load-path) (newline)'
-(. .. /usr/local/share/guile/2.0 \
+(. /usr/local/share/guile/2.0 \
 /usr/local/share/guile/site/2.0 \
-/usr/local/share/guile/site /usr/local/share/guile)
+/usr/local/share/guile/site \
+/usr/local/share/guile \
+../srfi)
 @end example
 
 (Note: The line breaks, above, are for documentation purposes only, and

libguile/load.c

@@ -221,6 +221,9 @@ static SCM *scm_loc_fresh_auto_compile;
 /* The fallback path for auto-compilation */
 static SCM *scm_loc_compile_fallback_path;
 
+/* Ellipsis: "..." */
+static SCM scm_ellipsis;
+
 SCM_DEFINE (scm_parse_path, "parse-path", 1, 1, 0, 
             (SCM path, SCM tail),
 	    "Parse @var{path}, which is expected to be a colon-separated\n"
@@ -243,6 +246,32 @@ SCM_DEFINE (scm_parse_path, "parse-path", 1, 1, 0,
 }
 #undef FUNC_NAME
 
+SCM_DEFINE (scm_parse_path_with_ellipsis, "parse-path-with-ellipsis", 2, 0, 0,
+            (SCM path, SCM base),
+	    "Parse @var{path}, which is expected to be a colon-separated\n"
+	    "string, into a list and return the resulting list with\n"
+	    "@var{base} (a list) spliced in place of the @code{...} path\n"
+            "component, if present, or else @var{base} is added to the end.\n"
+            "If @var{path} is @code{#f}, @var{base} is returned.")
+#define FUNC_NAME s_scm_parse_path_with_ellipsis
+{
+  SCM lst = scm_parse_path (path, SCM_EOL);
+  SCM walk = lst;
+  SCM *prev = &lst;
+
+  while (!scm_is_null (walk) &&
+         scm_is_false (scm_equal_p (scm_car (walk), scm_ellipsis)))
+    {
+      prev = SCM_CDRLOC (walk);
+      walk = *prev;
+    }
+  *prev = scm_is_null (walk)
+    ? base
+    : scm_append (scm_list_2 (base, scm_cdr (walk)));
+  return lst;
+}
+#undef FUNC_NAME
+
 
 /* Initialize the global variable %load-path, given the value of the
    SCM_SITE_DIR and SCM_LIBRARY_DIR preprocessor symbols and the
@@ -316,11 +345,11 @@ scm_init_load_path ()
 
   env = getenv ("GUILE_LOAD_PATH");
   if (env)
-    path = scm_parse_path (scm_from_locale_string (env), path);
+    path = scm_parse_path_with_ellipsis (scm_from_locale_string (env), path);
 
   env = getenv ("GUILE_LOAD_COMPILED_PATH");
   if (env)
-    cpath = scm_parse_path (scm_from_locale_string (env), cpath);
+    cpath = scm_parse_path_with_ellipsis (scm_from_locale_string (env), cpath);
 
   *scm_loc_load_path = path;
   *scm_loc_load_compiled_path = cpath;
@@ -1047,6 +1076,8 @@ scm_init_load ()
   scm_loc_fresh_auto_compile
     = SCM_VARIABLE_LOC (scm_c_define ("%fresh-auto-compile", SCM_BOOL_F));
 
+  scm_ellipsis = scm_from_latin1_string ("...");
+
   the_reader = scm_make_fluid_with_default (SCM_BOOL_F);
   scm_c_define("current-reader", the_reader);
 

libguile/load.h

@@ -27,6 +27,7 @@
 
 
 SCM_API SCM scm_parse_path (SCM path, SCM tail);
+SCM_API SCM scm_parse_path_with_ellipsis (SCM path, SCM base);
 SCM_API SCM scm_primitive_load (SCM filename);
 SCM_API SCM scm_c_primitive_load (const char *filename);
 SCM_API SCM scm_sys_package_data_dir (void);