(dired.info)Dired Mark Internals

Prev: Tree Dired Internals Up: Dired Internals

Dired Mark Internals

   This is a short overview about how marking files and retrieving
marked files in Dired works.

   `ls' output is indented two spaces two make room for an optional
marker character in front of each file line.  Marking simply replaces
the first space with the marker character, usually `*' or, for
deletions, `D'.  Indenting just by one would leave the markers adjacent
to the permission bits.

     The macro `dired-mark-if' is used internally to mark files matching
     certain criteria. It takes two arguments, the PREDICATE, a lisp
     expression evaluating non-nil on file lines to be marked, and MSG,
     a message to be displayed while scanning the buffer.  MSG may be
     nil to suppress the message.

     To operate on the marked files, all internal Dired functions
     ultimately call the macro `dired-mark-map'.  It takes two
     arguments, BODY and ARG, plus an optional argument SHOW-PROGRESS:

     Perform BODY with point somewhere on each marked line (inside a
     `save-excursion') and return a list of BODY's results.  If no
     marked file could be found, execute BODY on the current line.

     If ARG is an integer, use the next ARG (or previous -ARG, if
     ARG<0) files instead of the marked files.  In that case point is
     dragged along.  This is so that commands on the next ARG (instead
     of the marked) files can be chained easily.  Note that for
     positive ARG point is left on the first file not operated upon, for
     negative on the last file operated upon

     If ARG is otherwise non-nil, use current file instead.

     If optional third argument SHOW-PROGRESS evaluates to non-nil, we
     redisplay the Dired buffer after each file is processed.  No
     guarantee is made about the position on the marked line.  BODY
     must ensure this itself if it depends on this.  Search starts at
     the beginning of the buffer, thus the `car' of the list
     corresponds to the line nearest to the buffer's bottom.  This is
     also true for (positive and negative) integer values of ARG.  The
     BODY should not be too long as it is expanded four times.

A common case is to retrieve the names of all marked files:

     Return the marked files as list of strings.  The list is in the
     same order as the buffer, that is, the car is the first marked
     file.  Values returned are normally absolute pathnames.  Optional
     argument LOCALP equal to `no-dir' means return the filename proper
     only, with no directory information; any other non-nil value means
     make them relative to default-directory.  Optional second argument
     ARG forces use of other files.  If ARG is an integer, use the next
     ARG files.  If ARG is otherwise non-nil, use the current file.

automatically generated by info2www