Info Catalog elisp: File Names elisp: Files elisp: Create/Delete Dirs

elisp: Contents of Directories

 
 24.9 Contents of Directories
 ============================
 
 A directory is a kind of file that contains other files entered under
 various names.  Directories are a feature of the file system.
 
    Emacs can list the names of the files in a directory as a Lisp list,
 or display the names in a buffer using the ‘ls’ shell command.  In the
 latter case, it can optionally display information about each file,
 depending on the options passed to the ‘ls’ command.
 
  -- Function: directory-files directory &optional full-name match-regexp
           nosort
      This function returns a list of the names of the files in the
      directory DIRECTORY.  By default, the list is in alphabetical
      order.
 
      If FULL-NAME is non-‘nil’, the function returns the files’ absolute
      file names.  Otherwise, it returns the names relative to the
      specified directory.
 
      If MATCH-REGEXP is non-‘nil’, this function returns only those file
      names that contain a match for that regular expression—the other
      file names are excluded from the list.  On case-insensitive
      filesystems, the regular expression matching is case-insensitive.
 
      If NOSORT is non-‘nil’, ‘directory-files’ does not sort the list,
      so you get the file names in no particular order.  Use this if you
      want the utmost possible speed and don’t care what order the files
      are processed in.  If the order of processing is visible to the
      user, then the user will probably be happier if you do sort the
      names.
 
           (directory-files "~lewis")
                ⇒ ("#foo#" "#foo.el#" "." ".."
                    "dired-mods.el" "files.texi"
                    "files.texi.~1~")
 
      An error is signaled if DIRECTORY is not the name of a directory
      that can be read.
 
  -- Function: directory-files-recursively directory regexp &optional
           include-directories
      Return all files under DIRECTORY whose names match REGEXP.  This
      function searches the specified DIRECTORY and its sub-directories,
      recursively, for files whose basenames (i.e., without the leading
      directories) match the specified REGEXP, and returns a list of the
      absolute file names of the matching files (absolute file
      names Relative File Names.).  The file names are returned in
      depth-first order, meaning that files in some sub-directory are
      returned before the files in its parent directory.  In addition,
      matching files found in each subdirectory are sorted alphabetically
      by their basenames.  By default, directories whose names match
      REGEXP are omitted from the list, but if the optional argument
      INCLUDE-DIRECTORIES is non-‘nil’, they are included.
 
  -- Function: directory-files-and-attributes directory &optional
           full-name match-regexp nosort id-format
      This is similar to ‘directory-files’ in deciding which files to
      report on and how to report their names.  However, instead of
      returning a list of file names, it returns for each file a list
      ‘(FILENAME . ATTRIBUTES)’, where ATTRIBUTES is what
      ‘file-attributes’ would return for that file.  The optional
      argument ID-FORMAT has the same meaning as the corresponding
      argument to ‘file-attributes’ (Definition of
      file-attributes).
 
  -- Function: file-expand-wildcards pattern &optional full
      This function expands the wildcard pattern PATTERN, returning a
      list of file names that match it.
 
      If PATTERN is written as an absolute file name, the values are
      absolute also.
 
      If PATTERN is written as a relative file name, it is interpreted
      relative to the current default directory.  The file names returned
      are normally also relative to the current default directory.
      However, if FULL is non-‘nil’, they are absolute.
 
  -- Function: insert-directory file switches &optional wildcard
           full-directory-p
      This function inserts (in the current buffer) a directory listing
      for directory FILE, formatted with ‘ls’ according to SWITCHES.  It
      leaves point after the inserted text.  SWITCHES may be a string of
      options, or a list of strings representing individual options.
 
      The argument FILE may be either a directory name or a file
      specification including wildcard characters.  If WILDCARD is
      non-‘nil’, that means treat FILE as a file specification with
      wildcards.
 
      If FULL-DIRECTORY-P is non-‘nil’, that means the directory listing
      is expected to show the full contents of a directory.  You should
      specify ‘t’ when FILE is a directory and switches do not contain
      ‘-d’.  (The ‘-d’ option to ‘ls’ says to describe a directory itself
      as a file, rather than showing its contents.)
 
      On most systems, this function works by running a directory listing
      program whose name is in the variable ‘insert-directory-program’.
      If WILDCARD is non-‘nil’, it also runs the shell specified by
      ‘shell-file-name’, to expand the wildcards.
 
      MS-DOS and MS-Windows systems usually lack the standard Unix
      program ‘ls’, so this function emulates the standard Unix program
      ‘ls’ with Lisp code.
 
      As a technical detail, when SWITCHES contains the long ‘--dired’
      option, ‘insert-directory’ treats it specially, for the sake of
      dired.  However, the normally equivalent short ‘-D’ option is just
      passed on to ‘insert-directory-program’, as any other option.
 
  -- Variable: insert-directory-program
      This variable’s value is the program to run to generate a directory
      listing for the function ‘insert-directory’.  It is ignored on
      systems which generate the listing with Lisp code.
 

Info Catalog elisp: File Names elisp: Files elisp: Create/Delete Dirs