f.el 
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.
Installation
It's available on Melpa:
M-x package-install f
Or you can just dump f.el in your load path somewhere.
API
Paths
- f-join
(&rest args) - f-split
(path) - f-expand
(path &optional dir) - f-filename
(path) - f-dirname
(path) - f-common-parent
(paths) - f-ext
(path) - f-no-ext
(path) - f-swap-ext
(path ext) - f-base
(path) - f-relative
(path &optional dir) - f-short
(path) - f-long
(path) - f-canonical
(path) - f-slash
(path) - f-full
(path) - f-uniquify
(paths) - f-uniquify-alist
(paths)
I/O
- f-read-bytes
(path) - f-write-bytes
(data path) - f-read-text
(path &optional coding) - f-write-text
(text coding path) - f-append-text
(text coding path) - f-append-bytes
(text coding path)
Destructive
- f-mkdir
(&rest dirs) - f-delete
(path &optional force) - f-symlink
(source path) - f-move
(from to) - f-copy
(from to) - f-copy-contenst
(from to) - f-touch
(path)
Predicates
- 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-ext?
(path ext) - f-same?
(path-a path-b) - f-parent-of?
(path-a path-b) - f-child-of?
(path-a path-b) - f-ancestor-of?
(path-a path-b) - f-descendant-of?
(path-a path-b) - f-hidden?
(path) - f-empty?
(path)
Stats
Misc
- f-this-file
() - f-path-separator
() - f-glob
(pattern &optional path) - f-entries
(path &optional fn recursive) - f-directories
(path &optional fn recursive) - f-files
(path &optional fn recursive) - f-root
() - f-traverse-upwards
(fn &optional path) - f-with-sandbox
(path-or-paths &rest body)
Documentation and examples
f-join (&rest args)
Join ARGS to a single path.
(f-join "path") ;; => "path"
(f-join "path" "to") ;; => "path/to"
(f-join "/" "path" "to" "heaven") ;; => "/path/to/heaven"f-split (path)
Split PATH and return list containing parts.
(f-split "path") ;; => '("path")
(f-split "path/to") ;; => '("path" "to")
(f-split "/path/to/heaven") ;; => '("/" "path" "to" "heaven")f-expand (path &optional dir)
Expand PATH relative to DIR (or ‘default-directory’).
(f-expand "name") ;; => "/default/directory/name"
(f-expand "name" "other/directory") ;; => "other/directory/name"f-filename (path)
Return the name of PATH.
(f-filename "path/to/file.ext") ;; => "file.ext"
(f-filename "path/to/directory") ;; => "directory"f-dirname (path)
Return the parent directory to PATH.
Alias: f-parent
(f-dirname "path/to/file.ext") ;; => "path/to"
(f-dirname "path/to/directory") ;; => "path/to"
(f-dirname "/") ;; => nilf-common-parent (paths)
Return the deepest common parent directory of PATHS.
(f-common-parent '("foo/bar/baz" "foo/bar/qux" "foo/bar/mux")) ;; => "foo/bar/"
(f-common-parent '("/foo/bar/baz" "/foo/bar/qux" "/foo/bax/mux")) ;; => "/foo/"
(f-common-parent '("foo/bar/baz" "quack/bar/qux" "lack/bar/mux")) ;; => ""f-ext (path)
Return the file extension of PATH.
The extension, in a file name, is the part that follows the last ’.’, excluding version numbers and backup suffixes.
(f-ext "path/to/file.ext") ;; => "ext"
(f-ext "path/to/directory") ;; => nilf-no-ext (path)
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"f-swap-ext (path ext)
Return PATH but with EXT as the new extension. EXT must not be nil or empty.
(f-swap-ext "path/to/file.ext" "org") ;; => "path/to/file.org"
(f-swap-ext "path/to/file.ext" "") ;; => errorf-base (path)
Return the name of PATH, excluding the extension of file.
(f-base "path/to/file.ext") ;; => "file"
(f-base "path/to/directory") ;; => nilf-relative (path &optional dir)
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.txtf-short (path)
Return abbrev of PATH. See ‘abbreviate-file-name’.
Alias: f-abbrev
(f-short "/Users/foo/Code/bar") ;; => ~/Code/bar
(f-short "/path/to/Code/bar") ;; => /path/to/Code/barf-long (path)
Return long version of PATH.
(f-long "~/Code/bar") ;; => /Users/foo/Code/bar
(f-long "/path/to/Code/bar") ;; => /path/to/Code/barf-canonical (path)
Return the canonical name of PATH.
(f-canonical "/path/to/real/file") ;; => /path/to/real/file
(f-canonical "/link/to/file") ;; => /path/to/real/filef-slash (path)
Append slash to PATH unless one already.
Some functions, such as ‘call-process’ requires there to be an ending slash.
(f-slash "/path/to/file") ;; => /path/to/file
(f-slash "/path/to/dir") ;; => /path/to/dir/
(f-slash "/path/to/dir/") ;; => /path/to/dir/f-full (path)
Return absolute path to PATH, with ending slash.
(f-full "~/path/to/file") ;; => /home/path/to/file
(f-full "~/path/to/dir") ;; => /home/path/to/dir/
(f-full "~/path/to/dir/") ;; => /home/path/to/dir/f-uniquify (paths)
Return unique suffixes of FILES.
This function expects no duplicate paths.
(f-uniquify '("/foo/bar" "/foo/baz" "/foo/quux")) ;; => '("bar" "baz" "quux")
(f-uniquify '("/foo/bar" "/www/bar" "/foo/quux")) ;; => '("foo/bar" "www/bar" "quux")
(f-uniquify '("/foo/bar" "/www/bar" "/www/bar/quux")) ;; => '("foo/bar" "www/bar" "quux")
(f-uniquify '("/foo/bar" "/foo/baz" "/home/www/bar" "/home/www/baz" "/var/foo" "/opt/foo/www/baz")) ;; => '("foo/bar" "www/bar" "foo/baz" "home/www/baz" "foo/www/baz" "foo")f-uniquify-alist (paths)
Return alist mapping FILES to unique suffixes of FILES.
This function expects no duplicate paths.
(f-uniquify-alist '("/foo/bar" "/foo/baz" "/foo/quux")) ;; => '(("/foo/bar" . "bar") ("/foo/baz" . "baz") ("/foo/quux" . "quux"))
(f-uniquify-alist '("/foo/bar" "/www/bar" "/foo/quux")) ;; => '(("/foo/bar" . "foo/bar") ("/www/bar" . "www/bar") ("/foo/quux" . "quux"))
(f-uniquify-alist '("/foo/bar" "/www/bar" "/www/bar/quux")) ;; => '(("/foo/bar" . "foo/bar") ("/www/bar" . "www/bar") ("/www/bar/quux" . "quux"))
(f-uniquify-alist '("/foo/bar" "/foo/baz" "/home/www/bar" "/home/www/baz" "/var/foo" "/opt/foo/www/baz")) ;; => '(("/foo/bar" . "foo/bar") ("/home/www/bar" . "www/bar") ("/foo/baz" . "foo/baz") ("/home/www/baz" . "home/www/baz") ("/opt/foo/www/baz" . "foo/www/baz") ("/var/foo" . "foo"))f-read-bytes (path)
Read binary data from PATH.
Return the binary data as unibyte string.
(f-read-bytes "path/to/binary/data")f-write-bytes (data path)
Write binary DATA to PATH.
DATA is a unibyte string. PATH is a file name to write to.
(f-write-bytes (unibyte-string 72 101 108 108 111 32 119 111 114 108 100) "path/to/binary/data")f-read-text (path &optional coding)
Read text with PATH, using CODING.
CODING defaults to ‘utf-8’.
Return the decoded text as multibyte string.
Alias: f-read
(f-read-text "path/to/file.txt" 'utf-8)
(f-read "path/to/file.txt" 'utf-8)f-write-text (text coding path)
Write TEXT with CODING to PATH.
TEXT is a multibyte string. CODING is a coding system to encode TEXT with. PATH is a file name to write to.
Alias: f-write
(f-write-text "Hello world" 'utf-8 "path/to/file.txt")
(f-write "Hello world" 'utf-8 "path/to/file.txt")f-append-text (text coding path)
Append TEXT with CODING to PATH.
If PATH does not exist, it is created.
Alias: f-append
(f-append-text "Hello world" 'utf-8 "path/to/file.txt")
(f-append "Hello world" 'utf-8 "path/to/file.txt")f-append-bytes (data path)
Append binary DATA to PATH.
If PATH does not exist, it is created.
(f-append-bytes "path/to/file" (unibyte-string 72 101 108 108 111 32 119 111 114 108 100))f-mkdir (&rest dirs)
Create directories DIRS.
(f-mkdir "dir") ;; => /default/directory/dir
(f-mkdir "other" "dir") ;; => /default/directory/other/dirf-delete (path &optional force)
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")f-symlink (source path)
Create a symlink to SOURCE from PATH.
(f-symlink "path/to/source" "path/to/link")f-move (from to)
Move or rename FROM to TO.
(f-move "path/to/file.txt" "new-file.txt")
(f-move "path/to/file.txt" "other/path")f-copy (from to)
Copy file or directory FROM to TO.
(f-copy "path/to/file.txt" "new-file.txt")
(f-copy "path/to/dir" "other/dir")f-copy-contents (from to)
Copy contents in directory FROM, to directory TO.
(f-copy-contents "path/to/dir" "path/to/other/dir")f-touch (path)
Update PATH last modification date or create if it does not exist.
(f-touch "path/to/existing/file.txt")
(f-touch "path/to/non/existing/file.txt")f-exists? (path)
Return t if PATH exists, false otherwise.
(f-exists? "path/to/file.txt")
(f-exists? "path/to/dir")f-directory? (path)
Return t if PATH is directory, false otherwise.
Aliases: f-directory-p f-dir? f-dir-p
(f-directory? "path/to/file.txt") ;; => nil
(f-directory? "path/to/dir") ;; => tf-file? (path)
Return t if PATH is file, false otherwise.
Alias: f-file-p
(f-file? "path/to/file.txt") ;; => t
(f-file? "path/to/dir") ;; => nilf-symlink? (path)
Return t if PATH is symlink, false otherwise.
Alias: f-symlink-p
(f-symlink? "path/to/file.txt") ;; => nil
(f-symlink? "path/to/dir") ;; => nil
(f-symlink? "path/to/link") ;; => tf-readable? (path)
Return t if PATH is readable, false otherwise.
Alias: f-readable-p
(f-readable? "path/to/file.txt")
(f-readable? "path/to/dir")f-writable? (path)
Return t if PATH is writable, false otherwise.
Alias: f-writable-p
(f-writable? "path/to/file.txt")
(f-writable? "path/to/dir")f-executable? (path)
Return t if PATH is executable, false otherwise.
Alias: f-executable-p
(f-executable? "path/to/file.txt")
(f-executable? "path/to/dir")f-absolute? (path)
Return t if PATH is absolute, false otherwise.
Alias: f-absolute-p
(f-absolute? "path/to/dir") ;; => nil
(f-absolute? "/full/path/to/dir") ;; => tf-relative? (path)
Return t if PATH is relative, false otherwise.
Alias: f-relative-p
(f-relative? "path/to/dir") ;; => t
(f-relative? "/full/path/to/dir") ;; => nilf-root? (path)
Return t if PATH is root directory, false otherwise.
Alias: f-root-p
(f-root? "/") ;; => t
(f-root? "/not/root") ;; => nilf-ext? (path ext)
Return t if extension of PATH is EXT, false otherwise.
If EXT is nil or omitted, return t if PATH has any extension, false otherwise.
The extension, in a file name, is the part that follows the last ’.’, excluding version numbers and backup suffixes.
Alias: f-ext-p
(f-ext? "path/to/file.el" "el") ;; => t
(f-ext? "path/to/file.el" "txt") ;; => nil
(f-ext? "path/to/file.el") ;; => t
(f-ext? "path/to/file") ;; => nilf-same? (path-a path-b)
Return t if PATH-A and PATH-B are references to same file.
Aliases: f-same-p f-equal? f-equal-p
(f-same? "foo.txt" "foo.txt") ;; => t
(f-same? "/path/to/foo.txt" "/path/to/bar.txt") ;; => nilf-parent-of? (path-a path-b)
Return t if PATH-A is parent of PATH-B.
Alias: f-parent-of-p
(f-parent-of? "/path/to" "/path/to/dir") ;; => t
(f-parent-of? "/path/to/dir" "/path/to") ;; => nil
(f-parent-of? "/path/to" "/path/to") ;; => nilf-child-of? (path-a path-b)
Return t if PATH-A is child of PATH-B.
Alias: f-child-of-p
(f-child-of? "/path/to" "/path/to/dir") ;; => nil
(f-child-of? "/path/to/dir" "/path/to") ;; => t
(f-child-of? "/path/to" "/path/to") ;; => nilf-ancestor-of? (path-a path-b)
Return t if PATH-A is ancestor of PATH-B.
Alias: f-ancestor-of-p
(f-ancestor-of? "/path/to" "/path/to/dir") ;; => t
(f-ancestor-of? "/path" "/path/to/dir") ;; => t
(f-ancestor-of? "/path/to/dir" "/path/to") ;; => nil
(f-ancestor-of? "/path/to" "/path/to") ;; => nilf-descendant-of? (path-a path-b)
Return t if PATH-A is desendant of PATH-B.
Alias: f-descendant-of-p
(f-descendant-of? "/path/to/dir" "/path/to") ;; => t
(f-descendant-of? "/path/to/dir" "/path") ;; => t
(f-descendant-of? "/path/to" "/path/to/dir") ;; => nil
(f-descendant-of? "/path/to" "/path/to") ;; => nilf-hidden? (path)
Return t if PATH is hidden, nil otherwise.
(f-hidden? "/path/to/foo") ;; => nil
(f-hidden? "/path/to/.foo") ;; => tAlias: f-hidden-p
f-empty? (path)
If PATH is a file, return t if the file in PATH is empty, nil otherwise. If PATH is directory, return t if directory has no files, nil otherwise.
(f-empty? "/path/to/empty-file") ;; => t
(f-empty? "/path/to/file-with-contents") ;; => nil
(f-empty? "/path/to/empty-dir/") ;; => t
(f-empty? "/path/to/dir-with-contents/") ;; => nilAlias: f-empty-p
f-size (path)
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")f-depth (path)
Return the depth of PATH.
At first, PATH is expanded with ‘f-expand’. Then the full path is used to detect the depth. ’/’ will be zero depth, ’/usr’ will be one depth. And so on.
(f-depth "/") ;; 0
(f-depth "/var/") ;; 1
(f-depth "/usr/local/bin") ;; 3f-this-file ()
Return path to this file.
(f-this-file) ;; => /path/to/this/filef-path-separator ()
Return path separator.
(f-path-separator) ;; => /f-glob (pattern &optional path)
Find PATTERN in PATH.
See: file-expand-wildcards
(f-glob "path/to/*.el")
(f-glob "*.el" "path/to")f-entries (path &optional fn recursive)
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) (s-matches? "test" file)))
(f-entries "path/to/dir" nil t)
(f--entries "path/to/dir" (s-matches? "test" it))f-directories (path &optional fn recursive)
Find all directories in PATH. See ‘f-entries‘.
(f-directories "path/to/dir")
(f-directories "path/to/dir" (lambda (dir) (equal (f-filename dir) "test")))
(f-directories "path/to/dir" nil t)
(f--directories "path/to/dir" (equal (f-filename it) "test"))f-files (path &optional fn recursive)
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)
(f--files "path/to/dir" (equal (f-ext it) "el"))f-root ()
Return absolute root.
(f-root) ;; => "/"f-traverse-upwards (fn &optional path)
Traverse up as long as FN return nil, starting at PATH.
If FN returns a non-nil value, the path sent as argument to FN is returned. If no function callback return a non-nil value, nil is returned.
(f-traverse-upwards
(lambda (path)
(f-exists? (f-expand ".git" path)))
start-path)
(f--traverse-upwards (f-exists? (f-expand ".git" it)) start-path) ;; same as abovef-with-sandbox (path-or-paths &rest body)
Only allow PATH-OR-PATHS and decendants to be modified in BODY.
(f-with-sandbox foo-path
(f-touch (f-expand "foo" foo-path)))
(f-with-sandbox (list foo-path bar-path)
(f-touch (f-expand "foo" foo-path))
(f-touch (f-expand "bar" bar-path)))
(f-with-sandbox foo-path
(f-touch (f-expand "bar" bar-path))) ;; "Destructive operation outside sandbox"Example
Here's an example of a function that finds the Git project root.
Using standard Emacs builtin functions
(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)))))Using f.el
(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)))))Now, try writing it even simpler yourself. Hint, check out f-traverse-upwards.
Contribution
Be sure to!
Install Cask 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
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent