Much inspired by @magnars's excellent s.el and dash.el, f.el is a modern API for working with files and directories in Emacs.
It's available on Melpa:
M-x package-install f
Or you can just dump f.el
in your load path somewhere.
- f-join
(&rest args)
- f-expand
(path &optional dir)
- f-filename
(path)
- f-dirname
(path)
- f-ext
(path)
- f-no-ext
(path)
- f-base
(path)
- f-relative
(path &optional file)
- f-abbrev
(path)
- f-write
(path &optional content)
- f-mkdir
(&rest dirs)
- f-delete
(path &optional force)
- f-symlink
(source path)
- f-move
(from to)
- f-exists?
(path)
- f-directory?
(path)
- f-file?
(path)
- f-symlink?
(path)
- f-readable?
(path)
- f-writable?
(path)
- f-executable?
(path)
- f-absolute?
(path)
- f-relative?
(path)
- f-root?
(path)
- f-size
(path)
- f-read
(path)
- f-glob
(pattern &optional path)
- f-entries
(path &optional fn recursive)
- f-directories
(path &optional fn recursive)
- f-files
(path &optional fn recursive)
Join ARGS to a single path.
(f-join "path") ;; => "path"
(f-join "path" "to") ;; => "path/to"
(f-join "path" "to" "heaven") ;; => "path/to/heaven"
Expand PATH relative to DIR (or `default-directory').
(f-expand "name") ;; => "/default/directory/name"
(f-expand "name" "other/directory") ;; => "other/directory/name"
Return the name of PATH.
(f-filename "path/to/file.ext") ;; => "file.ext"
(f-filename "path/to/directory") ;; => "directory"
Return the parent directory to PATH.
Alias: f-parent
(f-dirname "path/to/file.ext") ;; => "path/to"
(f-dirname "path/to/directory") ;; => "path/to"
Return the file extension of PATH.
(f-ext "path/to/file.ext") ;; => "ext"
(f-ext "path/to/directory") ;; => nil
Return everything but the file extension of PATH.
(f-no-ext "path/to/file.ext") ;; => "path/to/file"
(f-no-ext "path/to/directory") ;; => "path/to/directory"
Return the name of PATH, excluding the extension if file.
(f-base "path/to/file.ext") ;; => "file"
(f-base "path/to/directory") ;; => nil
Return PATH relative to DIR.
(f-relative "/some/path/relative/to/my/file.txt" "/some/path/") ;; => relative/to/my/file.txt
(f-relative "/default/directory/my/file.txt") ;; => my/file.txt
Abbrev PATH. See `abbreviate-file-name'.
Alias: f-short
(f-abbrev "/Users/foo/Code/bar") ;; => ~/Code/bar
(f-abbrev "/path/to/Code/bar") ;; => /path/to/Code/bar
Write CONTENT or nothing to PATH. If no content, just create file.
(f-write "path/to/file.txt")
(f-write "path/to/file.txt" "some-content")
Create directories DIRS.
(f-mkdir "dir") ;; => /default/directory/dir
(f-mkdir "other" "dir") ;; => /default/directory/other/dir
Delete PATH, which can be file or directory.
If FORCE is t, a directory will be deleted recursively.
(f-delete "dir")
(f-delete "other/dir" t)
(f-delete "path/to/file.txt")
Create a symlink to source
from path
.
(f-symlink "path/to/source" "path/to/link")
Move or rename FROM to TO.
(f-move "path/to/file.txt" "new-file.txt")
(f-move "path/to/file.txt" "other/path")
Return t if PATH exists, false otherwise.
(f-exists? "path/to/file.txt")
(f-exists? "path/to/dir")
Return t if PATH is directory, false otherwise.
Alias: f-dir?
(f-directory? "path/to/file.txt") ;; => nil
(f-directory? "path/to/dir") ;; => t
Return t if PATH is file, false otherwise.
(f-directory? "path/to/file.txt") ;; => t
(f-directory? "path/to/dir") ;; => nil
Return t if PATH is symlink, false otherwise.
(f-symlink? "path/to/file.txt") ;; => nil
(f-symlink? "path/to/dir") ;; => nil
(f-symlink? "path/to/link") ;; => t
Return t if PATH is readable, false otherwise.
(f-readable? "path/to/file.txt")
(f-readable? "path/to/dir")
Return t if PATH is writable, false otherwise.
(f-writable? "path/to/file.txt")
(f-writable? "path/to/dir")
Return t if PATH is executable, false otherwise.
(f-executable? "path/to/file.txt")
(f-executable? "path/to/dir")
Return t if PATH is absolute, false otherwise.
(f-absolute? "path/to/dir") ;; => nil
(f-absolute? "/full/path/to/dir") ;; => t
Return t if PATH is relative, false otherwise.
(f-relative? "path/to/dir") ;; => t
(f-relative? "/full/path/to/dir") ;; => nil
Return t if PATH is root directory, false otherwise.
(f-root? "/") ;; => t
(f-root? "/not/root") ;; => nil
Return size of PATH.
If PATH is a file, return size of that file. If PATH is directory, return sum of all files in PATH.
(f-size "path/to/file.txt")
(f-size "path/to/dir")
Return content of PATH.
(f-read "path/to/file.txt")
Find PATTERN in PATH.
See: file-expand-wildcards
(f-glob "path/to/*.el")
(f-glob "*.el" "path/to")
Find all files and directories in PATH.
FN - called for each found file and directory. If FN returns a thruthy value, file or directory will be included. RECURSIVE - Search for files and directories recursive.
(f-entries "path/to/dir")
(f-entries "path/to/dir" (lambda (file) (equal (f-ext file) "el")))
(f-entries "path/to/dir" nil t)
Find all directories in PATH. See f-entries
.
(f-directories "path/to/dir")
(f-directories "path/to/dir" (lambda (dir) ((f-filename dir) "test")))
(f-directories "path/to/dir" nil t)
Find all files in PATH. See f-entries
.
(f-files "path/to/dir")
(f-files "path/to/dir" (lambda (file) (equal (f-ext file) "el")))
(f-files "path/to/dir" nil t)
Here's an example of a function that finds the Git project root.
(defun find-git-root (&optional dir)
(unless dir (setq dir (expand-file-name (file-name-directory (buffer-file-name)))))
(let ((parent (expand-file-name ".." dir)))
(unless (equal parent dir)
(if (file-exists-p (expand-file-name ".git" dir))
dir
(find-git-root parent)))))
(defun find-git-root (&optional dir)
(interactive)
(unless dir (setq dir (f-dirname (buffer-file-name))))
(let ((parent (f-parent dir)))
(unless (f-root? parent)
(if (f-exists? (f-expand ".git" dir))
dir
(find-git-root parent)))))
Be sure to!
Install Carton if you haven't already.
Run the unit tests with:
$ make test
Do not change README.md
directly. If you want to change the README
or if you change any function comments, update the README with:
$ make docs