Re: locate-with-filter

[Luc Teirlinck]

Eli Zaretskii wrote:

   I think "executable command" is not clear enough.  How about "program"
   or "executable program"?

I used this in the patch below.  In addition, I also noticed that
even after my changes, it may not be clear what the database consists
of or where it comes from.  So I suggest the following updated patch,
which addresses this.

===File ~/locate-diff=======================================
*** locate.el   06 Feb 2006 16:01:50 -0600      1.35
--- locate.el   13 Mar 2006 23:39:11 -0600      
***************
*** 122,128 ****
    :group 'external)
  
  (defcustom locate-command "locate"
!   "*The executable program used to search a database of files."
    :type 'string
    :group 'locate)
  
--- 122,148 ----
    :group 'external)
  
  (defcustom locate-command "locate"
!   "Executable program for searching a database of files.
! The Emacs commands `locate' and `locate-with-filter' use this.
! The value should be a program that can be called from a shell
! with one argument, SEARCH-STRING.  The program determines which
! database it searches.  The output of the program should consist
! of those file names in the database that match SEARCH-STRING,
! listed one per line, possibly with leading or trailing
! whitespace.  If the output is in another form, you may have to
! redefine the function `locate-get-file-positions'.
! 
! The program may interpret SEARCH-STRING as a literal string, a
! shell pattern or a regular expression.  The exact rules of what
! constitutes a match may also depend on the program.
! 
! The standard value of this variable is \"locate\".
! This program normally searches a database of all files on your
! system, or of all files that you have access to.  Do
! `M-x man RET locate RET' to check whether you have this program
! installed, how it interprets SEARCH-STRING, how it determines
! which files match SEARCH-STRING, and how it maintains its
! database.  (The details vary highly with the version.)"
    :type 'string
    :group 'locate)
  
***************
*** 133,139 ****
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "*Function used to create the locate command line."
    :type 'function
    :group 'locate)
  
--- 153,164 ----
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "Function used to create the locate command line.
! The Emacs commands `locate' and `locate-with-filter' use this.
! This function should take one argument, a string (the name to find)
! and return a list.  The first element of the list should be a command
! to be executed by a shell, the remaining elements should be the arguments
! to that command (including the name to find)."
    :type 'function
    :group 'locate)
  
***************
*** 143,149 ****
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "*File name for the database of file names."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
--- 168,181 ----
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "File name for the database of file names used by `locate'.
! If non-nil, `locate' uses this name in the header of the `*Locate*'
! buffer.  If nil, it mentions no file name in that header.
! 
! Just setting this variable does not actually change the database
! that `locate' searches.  The executive program that the Emacs
! function `locate' uses, as given by the variables `locate-command'
! or `locate-make-command-line', determines the database."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
***************
*** 161,172 ****
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The command used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the locate command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
--- 193,204 ----
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The executable program used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the `locate' command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
***************
*** 190,197 ****
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the program `locate', putting results in `*Locate*' buffer.
! With prefix arg, prompt for the locate command to run."
    (interactive
        (list
         (if (or (and current-prefix-arg
--- 222,246 ----
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run a \"locate\" type program, putting results in `*Locate*' buffer.
! Pass it SEARCH-STRING as argument.  Interactively, prompt for SEARCH_STRING.
! With prefix arg, prompt for the exact \"locate\" command to run instead.
! 
! Without prefix arg, this normally runs the executable program GNU locate.
! This program searches for those file names in a database that match
! SEARCH-STRING and normally outputs all matching absolute file names,
! one per line.  The database normally consists of all files on your
! system, or of all files that you have access to.  Do
! `M-x man RET locate RET' to check whether you have this program
! installed, how it interprets SEARCH-STRING, how it determines
! what constitutes a match, and how it maintains its database.
! \(The details vary highly with the version.)
! 
! You can specify another program for this command to run by customizing
! the variables `locate-command' or `locate-make-command-line'.
! 
! The main use of FILTER is to implement `locate-with-filter'.  See
! the docstring of that function for its meaning."
    (interactive
        (list
         (if (or (and current-prefix-arg
***************
*** 255,264 ****
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate command with a filter.
  
! The filter is a regular expression. Only results matching the filter are
! shown; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
                               nil 'locate-history-list)
--- 304,319 ----
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run a \"locate\" type program with a filter.
! This is similar to `locate', which see.  The difference is that,
! when invoked interactively, this command prompts for both SEARCH-STRING
! and FILTER.  It passes SEARCH-STRING to the locate program.
! It only shows those lines in the output of the locate program
! that contain a match for the regular expression FILTER in the
! `*Locate*' buffer; this is often useful to constrain a big search.
  
! When called from Lisp, this function is identical with `locate',
! except that FILTER is not optional."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
                               nil 'locate-history-list)
***************
*** 269,275 ****
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (delete-non-matching-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
--- 324,330 ----
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (keep-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
============================================================