Function: dired-insert-directory
dired-insert-directory is a byte-compiled function defined in
dired.el.gz.
Signature
(dired-insert-directory DIR SWITCHES &optional FILE-LIST WILDCARD HDR)
Documentation
Insert a directory listing of DIR, Dired style.
Use SWITCHES to make the listings.
If FILE-LIST is non-nil, list only those files.
Otherwise, if WILDCARD is non-nil, expand wildcards;
in that case, DIR should be a file name that uses wildcards.
In other cases, DIR should be a directory name or a directory filename.
If HDR is non-nil, insert a header line with the directory name.
Probably introduced at or before Emacs version 29.1.
Source Code
;; Defined in /usr/src/emacs/lisp/dired.el.gz
(defun dired-insert-directory (dir switches &optional file-list wildcard hdr)
"Insert a directory listing of DIR, Dired style.
Use SWITCHES to make the listings.
If FILE-LIST is non-nil, list only those files.
Otherwise, if WILDCARD is non-nil, expand wildcards;
in that case, DIR should be a file name that uses wildcards.
In other cases, DIR should be a directory name or a directory filename.
If HDR is non-nil, insert a header line with the directory name."
(let ((opoint (point))
(process-environment (copy-sequence process-environment))
(remotep (file-remote-p dir))
end)
(if (and
;; Don't try to invoke `ls' if ls-lisp emulation should be used.
(files--use-insert-directory-program-p)
;; FIXME: Big ugly hack for Eshell's eshell-ls-use-in-dired.
(not (bound-and-true-p eshell-ls-use-in-dired))
(or remotep
(if (eq dired-use-ls-dired 'unspecified)
;; Check whether "ls --dired" gives exit code 0, and
;; save the answer in `dired-use-ls-dired'.
(or (setq dired-use-ls-dired
(eq 0 (call-process insert-directory-program
nil nil nil "--dired" "-N")))
(progn
(message "ls does not support --dired -N; \
see `dired-use-ls-dired' for more details.")
nil))
dired-use-ls-dired)))
;; Use -N with --dired, to countermand possible non-default
;; quoting style, in particular via the environment variable
;; QUOTING_STYLE.
(unless remotep
(setq switches (concat "--dired -N " switches))))
;; Expand directory wildcards and fill file-list.
(let ((dir-wildcard (and (null file-list) wildcard
(insert-directory-wildcard-in-dir-p dir))))
(cond ((and dir-wildcard (files--use-insert-directory-program-p))
(setq switches (concat "-d " switches))
(let* ((default-directory (car dir-wildcard))
(ls (or (and remotep "ls")
insert-directory-program))
(script (format "%s %s %s"
ls switches (cdr dir-wildcard)))
(sh (or (and remotep "/bin/sh")
(executable-find shell-file-name)
(executable-find "sh")))
(switch (if remotep "-c" shell-command-switch)))
;; Enable globstar
(when-let* ((globstar dired-maybe-use-globstar)
(enable-it
(assoc-default
(file-truename sh) dired-enable-globstar-in-shell
(lambda (reg shell) (string-match reg shell)))))
(setq script (format "%s; %s" enable-it script)))
(unless
(zerop
(process-file sh nil (current-buffer) nil switch script))
(user-error
"%s: No files matching wildcard" (cdr dir-wildcard)))
(insert-directory-clean (point) switches)))
;; We used to specify the C locale here, to force English
;; month names; but this should not be necessary any
;; more, with the new value of
;; `directory-listing-before-filename-regexp'.
((or file-list dir-wildcard)
(let ((default-directory
(or (car dir-wildcard) default-directory)))
(dolist (f (or file-list
(file-expand-wildcards (cdr dir-wildcard))))
(let ((beg (point)))
(insert-directory f switches nil nil)
;; `dired-align-file' doesn't fare well with dired
;; implementations that don't indent entries by one
;; column, which in all known implementations is
;; equivalent to not supporting `--dired'.
(save-excursion
(goto-char beg)
(unless (looking-at " ")
(insert " ")))
;; Re-align fields, if necessary.
(dired-align-file beg (point))))))
(t
(insert-directory dir switches wildcard (not wildcard))))
;; Quote certain characters, unless ls quoted them for us.
(if (not (dired-switches-escape-p dired-actual-switches))
(save-excursion
(setq end (point-marker))
(goto-char opoint)
(while (search-forward "\\" end t)
(replace-match (apply #'propertize
"\\\\"
(text-properties-at (match-beginning 0)))
nil t))
(goto-char opoint)
(while (search-forward "\^m" end t)
(replace-match (apply #'propertize
"\\015"
(text-properties-at (match-beginning 0)))
nil t))
(set-marker end nil))
;; Replace any newlines in DIR with literal "\n"s, for the sake
;; of the header line. To disambiguate a literal "\n" in the
;; actual dirname, we also replace "\" with "\\".
;; Personally, I think this should always be done, irrespective
;; of the value of dired-actual-switches, because:
;; i) Dired simply does not work with an unescaped newline in
;; the directory name used in the header (bug=10469#28), and
;; ii) "\" is always replaced with "\\" in the listing, so doing
;; it in the header as well makes things consistent.
;; But at present it is only done if "-b" is in ls-switches,
;; because newlines in dirnames are uncommon, and people may
;; have gotten used to seeing unescaped "\" in the headers.
;; Note: adjust dired-build-subdir-alist if you change this.
(setq dir (string-replace "\\" "\\\\" dir)
dir (string-replace "\n" "\\n" dir)))
;; If we used --dired and it worked, the lines are already indented.
;; Otherwise, indent them.
(unless (save-excursion
(goto-char opoint)
(looking-at-p " "))
(let ((indent-tabs-mode nil))
(indent-rigidly opoint (point) 2)))
;; Insert text at the beginning to standardize things.
(let ((content-point opoint))
(save-excursion
(goto-char opoint)
(when (and (or hdr wildcard)
(not (and (looking-at "^ \\(.*\\):$")
(file-name-absolute-p (match-string 1)))))
(let* ((dir-indent " ")
(dir-name (or (car-safe dir-wildcard)
(directory-file-name
(file-name-directory dir))))
(dir-name-point (+ (point) (length dir-indent)))
(hideable-location
(and dired-hide-details-hide-absolute-location
(not (string-empty-p (file-name-nondirectory
dir-name))))))
;; Inserted directory name must be absolute, but keep in
;; mind it may be replaced in some instances like in
;; `dired-build-subdir-alist'.
(insert dir-indent dir-name ":\n")
(when hideable-location
(put-text-property
dir-name-point
(+ dir-name-point
(length (file-name-directory dir-name)))
'invisible 'dired-hide-details-absolute-location)))
(setq content-point (point)))
(when wildcard
;; Insert "wildcard" line where "total" line would be for a full dir.
(insert " wildcard " (or (cdr-safe (insert-directory-wildcard-in-dir-p dir))
(file-name-nondirectory dir))
"\n"))
(setq content-point (dired--insert-disk-space opoint dir)))
(dired-insert-set-properties content-point (point))))))