From a06b38ac51e22c59f6a13349862428a0596ba09e Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 24 May 2025 10:23:11 +0300 Subject: [PATCH] ; Fix documentation of a recent commit * etc/NEWS: * doc/lispref/loading.texi (How Programs Do Loading): Document the new variable and function. * src/lread.c (load-path-filter-function): * lisp/startup.el (load-path-filter-cache-directory-files) (load-path-filter--cache): Doc fixes. (cherry picked from commit da174e4a15229ae498713444e70c382d7e0e90cd) --- doc/lispref/loading.texi | 20 ++++++++++++++++++++ lisp/startup.el | 22 ++++++++++++++-------- src/lread.c | 13 +++++++------ 3 files changed, 41 insertions(+), 14 deletions(-) diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index c0cf5de8a7f..6a650f443c3 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -221,6 +221,26 @@ Functions}. Instead of using this variable, it is cleaner to use another, newer feature: to pass the function as the @var{read-function} argument to @code{eval-region}. @xref{Definition of eval-region,, Eval}. +@end defvar + +@defun load-path-filter-cache-directory-files path filename suffixes +This function filters @var{path} to remove any directories that could +not hold @var{filename} with any of @var{suffixes}, and returns the +filtered list of directories. The function caches the directories it +scans and the files inside them, and uses the cache in subsequent calls, +which speeds up repeated lookups of files in @var{path}. +@end defun + +@defvar load-path-filter-function +If this variable names a function, @code{load} will call that function +when it scans @code{load-path} to find files. The function will be +called with 3 arguments: the value of @code{load-path}, @var{filename}, +the name of a file being looked up as passed to @code{load}, and a list +of suffixes to append to @var{filename}. It should return a shorter +list of directories where @var{filename} can reside, thus making the +lookup faster. The function +@code{load-path-filter-cache-directory-files} is a good candidate to be +such a function. @end defvar For information about how @code{load} is used in building Emacs, see diff --git a/lisp/startup.el b/lisp/startup.el index 29a04bef706..9caefe8a6d3 100644 --- a/lisp/startup.el +++ b/lisp/startup.el @@ -1100,19 +1100,25 @@ the `--debug-init' option to view a complete error backtrace." (defvar load-path-filter--cache nil "A cache used by `load-path-filter-cache-directory-files'. -This is an alist. The car of each entry is a list of load suffixes, +The value is an alist. The car of each entry is a list of load suffixes, such as returned by `get-load-suffixes'. The cdr of each entry is a -cons whose car is an optimized regex matching those suffixes at the end -of a string, and whose cdr is a hashtable mapping directories to files -in that directory which end with one of the suffixes.") +cons whose car is an `regex-opt' optimized regex matching those suffixes +at the end of a string, and whose cdr is a hash-table mapping directories +to files in those directories which end with one of the suffixes. +The hash-table uses `equal' as its key comparison function.") (defun load-path-filter-cache-directory-files (path file suffixes) - "Filter PATH to only directories which might contain FILE with SUFFIXES. + "Filter PATH to leave only directories which might contain FILE with SUFFIXES. -Doesn't filter if FILE is an absolute file name or if FILE is a relative -file name with more than one component. +PATH should be a list of directories such as `load-path'. +Returns a copy of PATH with any directories that cannot contain FILE +with SUFFIXES removed from it. +Doesn't filter PATH if FILE is an absolute file name or if FILE is +a relative file name with leading directories. -Caches directory contents in `load-path-filter--cache'." +Caches contents of directories in `load-path-filter--cache'. + +This function is called from `load' via `load-path-filter-function'." (if (file-name-directory file) ;; FILE has more than one component, don't bother filtering. path diff --git a/src/lread.c b/src/lread.c index ed481c19721..9b902532393 100644 --- a/src/lread.c +++ b/src/lread.c @@ -6113,14 +6113,15 @@ through `require'. */); DEFVAR_LISP ("load-path-filter-function", Vload_path_filter_function, - doc: /* Non-nil means to call this function to filter `load-path' for `load'. + doc: /* If non-nil, a function to filter `load-path' for `load'. -When load is called, this function is called with three arguments: the -current value of `load-path' (a list of directories), the FILE argument -to load, and the current load-suffixes. +If this variable is a function, it is called when `load' is about to +search for a file along `load-path'. This function is called with three +arguments: the current value of `load-path' (a list of directories), +the FILE argument to `load', and the current list of load-suffixes. -It should return a list of directories, which `load' will use instead of -`load-path'. */); +It should return a (hopefully shorter) list of directories, which `load' +will use instead of `load-path' to look for the file to load. */); Vload_path_filter_function = Qnil; /* Vsource_directory was initialized in init_lread. */ -- 2.39.5