Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   This is a small step in the wrong direction, so please don't do it.

The problem with `locate' in the docstring of `locate' is that it
creates a confusing self-referential link.  The problem with `locate'
to refer to the executable program of that name is that it creates a
link to the _Emacs_ command locate, creating even more confusion.

   The problem is that this description is not self-contained.  It
   assumes the reader knows about the `locate' program and knows what its
   output looks like.

   This command should have a self-contained description which is
   comprehensible without knowing about `locate'.

That is not as easy as it sounds.  There appear to be _very_ different
versions of locate, even of GNU locate, around.  Some treat
SEARCH-STRING as a literal string, some treat it as a shell pattern
and in certain cases, it treats SEARCH-STRING as a POSIX regular
expression.  The Info documentation I have installed says that locate
treats SEARCH-STRING as a shell pattern.  The man page says that it
treats it as a literal string, but that it has an option to treat it
as a POSIX regular expression instead.  The actual behavior matches
the man page.  Many operating systems, even UNIX style ones, have, by
default, no locate program installed at all.

Currently, you may need to read the comments at the beginning of
locate.el to use its functionality.  The patch below tries to put more
of that info in the docstrings.

I kept some references to "locate program", but in a context where I
first refer to the program as a `"locate" type program', so that no
confusion with relocation programs is possible.  I could
systematically write "locate executable program" instead, but in the
given context, that seemed redundant.

===File ~/locate-diff=======================================
*** locate.el   06 Feb 2006 16:01:50 -0600      1.35
--- locate.el   13 Mar 2006 20:35:53 -0600      
***************
*** 122,128 ****
    :group 'external)
  
  (defcustom locate-command "locate"
!   "*The executable program used to search a database of files."
    :type 'string
    :group 'locate)
  
--- 122,144 ----
    :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 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\".
! Do `M-x man RET locate RET' to check whether you have this
! program installed, how it interprets SEARCH-STRING and how it
! determines which files match SEARCH-STRING."
    :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)
  
--- 149,160 ----
    "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)
  
--- 164,170 ----
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "File name for the database of file names used by `locate'."
    :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
--- 182,193 ----
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The executable 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
***************
*** 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
--- 211,232 ----
  
  ;;;###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.  Do `M-x man RET locate RET' to check whether you have this
! program installed, how it interprets SEARCH-STRING and how it determines
! what constitutes a match.  (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)
--- 290,305 ----
  
  ;;;###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.")
--- 310,316 ----
  (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.")
============================================================
 LocalWords:  docstrings