Emacs Lisp Shortdoc Cheatsheet
Emacs shortdoc cheatsheet.
Group: alist
Alist Basics
(assoc KEY ALIST &optional TESTFN)
;; Return non-nil if KEY is equal to the car of an element of ALIST.
(assoc 'foo '((foo . bar) (zot . baz)))
=> (foo . bar)
(rassoc KEY ALIST)
;; Return non-nil if KEY is ‘equal’ to the cdr of an element of ALIST.
(rassoc 'bar '((foo . bar) (zot . baz)))
=> (foo . bar)
(assq KEY ALIST)
;; Return non-nil if KEY is ‘eq’ to the car of an element of ALIST.
(assq 'foo '((foo . bar) (zot . baz)))
=> (foo . bar)
(rassq KEY ALIST)
;; Return non-nil if KEY is ‘eq’ to the cdr of an element of ALIST.
(rassq 'bar '((foo . bar) (zot . baz)))
=> (foo . bar)
(assoc-string KEY LIST &optional CASE-FOLD)
;; Like ‘assoc’ but specifically for strings (and symbols).
(assoc-string "foo" '(("foo" . "bar") ("zot" "baz")))
=> ("foo" . "bar")
Manipulating Alists
(assoc-delete-all KEY ALIST &optional TEST)
;; Delete from ALIST all elements whose car is KEY.
(assoc-delete-all "foo" '(("foo" . "bar") ("zot" . "baz")) #'equal)
=> (("zot" . "baz"))
(assq-delete-all KEY ALIST)
;; Delete from ALIST all elements whose car is ‘eq’ to KEY.
(assq-delete-all 'foo '((foo . bar) (zot . baz)))
=> ((zot . baz))
(rassq-delete-all VALUE ALIST)
;; Delete from ALIST all elements whose cdr is ‘eq’ to VALUE.
(rassq-delete-all 'bar '((foo . bar) (zot . baz)))
=> ((zot . baz))
(alist-get KEY ALIST &optional DEFAULT REMOVE TESTFN)
;; Find the first element of ALIST whose ‘car’ equals KEY and return its ‘cdr’.
(let ((foo '((bar . baz)))) (setf (alist-get 'bar foo) 'zot) foo)
=> ((bar . zot))
Misc
(assoc-default KEY ALIST &optional TEST DEFAULT)
;; Find object KEY in a pseudo-alist ALIST.
(assoc-default "foobar" '(("foo" . baz)) #'string-match)
=> baz
(copy-alist ALIST)
;; Return a copy of ALIST.
(let* ((old '((foo . bar))) (new (copy-alist old))) (eq old new))
=> nil
Group: buffer
Buffer Basics
(current-buffer)
;; Return the current buffer as a Lisp object.
(current-buffer)
e.g. => #<buffer shortdoc.el>
(bufferp OBJECT)
;; Return t if OBJECT is an editor buffer.
(bufferp 23)
=> nil
(buffer-live-p OBJECT)
;; Return t if OBJECT is a buffer which has not been killed.
(buffer-live-p some-buffer)
e.g. => t
(buffer-modified-p &optional BUFFER)
;; Return t if BUFFER was modified since its file was last read or saved.
(buffer-modified-p (current-buffer))
=> t
(buffer-name &optional BUFFER)
;; Return the name of BUFFER, as a string.
(buffer-name)
=> "*elisp-doc-shortdoc*"
(window-buffer &optional WINDOW)
;; Return the buffer displayed in window WINDOW.
(window-buffer)
=> #<buffer *scratch*>
Selecting Buffers
(get-buffer-create BUFFER-OR-NAME &optional INHIBIT-BUFFER-HOOKS)
;; Return the buffer specified by BUFFER-OR-NAME, creating a new one if needed.
(get-buffer-create "*foo*")
e.g. => #<buffer *foo*>
(pop-to-buffer BUFFER-OR-NAME &optional ACTION NORECORD)
;; Display buffer specified by BUFFER-OR-NAME and select its window.
(pop-to-buffer "*foo*")
e.g. => #<buffer *foo*>
(with-current-buffer BUFFER-OR-NAME &rest BODY)
;; Execute the forms in BODY with BUFFER-OR-NAME temporarily current.
(with-current-buffer buffer (buffer-size))
->
Points and Positions
(point)
;; Return value of point, as an integer.
(point)
=> 5278
(point-min)
;; Return the minimum permissible value of point in the current buffer.
(point-min)
=> 1
(point-max)
;; Return the maximum permissible value of point in the current buffer.
(point-max)
=> 5663
(line-beginning-position &optional N)
;; Return the character position of the first character on the current line.
(line-beginning-position)
=> 5914
(line-end-position &optional N)
;; Return the character position of the last character on the current line.
(line-end-position)
=> 6171
(buffer-size &optional BUFFER)
;; Return the number of characters in the current buffer.
(buffer-size)
=> 6371
Moving Around
(goto-char POSITION)
;; Set point to POSITION, a number or marker.
(goto-char (point-max))
e.g. => 342
(search-forward STRING &optional BOUND NOERROR COUNT)
;; Search forward from point for STRING.
(search-forward "some-string" nil t)
e.g. => 245
(re-search-forward REGEXP &optional BOUND NOERROR COUNT)
;; Search forward from point for regular expression REGEXP.
(re-search-forward "some-s.*g" nil t)
e.g. => 245
(forward-line &optional N)
;; Move N lines forward (backward if N is negative).
(forward-line 1)
e.g. => 0
(forward-line -2)
e.g. => 0
Strings from Buffers
(buffer-string)
;; Return the contents of the current buffer as a string.
(buffer-string)
->
(buffer-substring START END)
;; Return the contents of part of the current buffer as a string.
(buffer-substring (point-min) (+ (point-min) 10))
=> "Emacs shor"
(buffer-substring-no-properties START END)
;; Return the characters of part of the buffer, without the text properties.
(buffer-substring-no-properties (point-min) (+ (point-min) 10))
=> "Emacs shor"
(following-char)
;; Return the character following point, as a number.
(following-char)
e.g. => 67
(char-after &optional POS)
;; Return character in current buffer at position POS.
(char-after 45)
=> 115
(get-byte &optional POSITION STRING)
;; Return a byte value of a character at point.
(get-byte 45)
e.g. => #xff
Altering Buffers
(delete-region START END)
;; Delete the text between START and END.
(delete-region (point-min) (point-max))
(erase-buffer)
;; Delete the entire contents of the current buffer.
(erase-buffer)
(insert &rest ARGS)
;; Insert the arguments, either strings or characters, at point.
(insert "This string will be inserted in the buffer\n")
(subst-char-in-region START END FROMCHAR TOCHAR &optional NOUNDO)
;; From START to END, replace FROMCHAR with TOCHAR each time it occurs.
(subst-char-in-region (point-min) (point-max) ?+ ?-)
(replace-string-in-region STRING REPLACEMENT &optional START END)
;; Replace STRING with REPLACEMENT in the region from START to END.
(replace-string-in-region "foo" "bar")
Locking
(lock-buffer &optional FILE)
;; Lock FILE, if current buffer is modified.
(lock-buffer "/tmp/foo")
(unlock-buffer)
;; Unlock the file visited in the current buffer.
(unlock-buffer)
Group: f
Paths
(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-join "path" "/to" "file")
=> "/to/file"
(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-split "~/back/to/earth")
=> ("~" "back" "to" "earth")
(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.
(f-dirname "path/to/file.ext")
=> "path/to/"
(f-dirname "path/to/directory")
=> "path/to/"
(f-dirname "/")
=> nil
(f-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 FILENAME &optional PERIOD)
;; Return FILENAME’s final "extension".
(f-ext "path/to/file")
=> nil
(f-ext "path/to/file.txt")
=> "txt"
(f-ext "path/to/file.txt.org")
=> "org"
(f-no-ext FILENAME)
;; Return FILENAME sans final "extension".
(f-no-ext "path/to/file")
=> "path/to/file"
(f-no-ext "path/to/file.txt")
=> "path/to/file"
(f-no-ext "path/to/file.txt.org")
=> "path/to/file.txt"
(f-swap-ext PATH EXT)
;; Return PATH but with EXT as the new extension.
(f-swap-ext "path/to/file.ext" "org")
=> "path/to/file.org"
(f-base PATH)
;; Return the name of PATH, excluding the extension of file.
(f-base "path/to/file.ext")
=> "file"
(f-base "path/to/directory")
=> "directory"
(f-relative FILENAME &optional DIRECTORY)
;; Convert FILENAME to be relative to DIRECTORY (default: ‘default-directory’).
(f-relative "/some/path/relative/to/my/file.txt" "/some/path/")
=> "relative/to/my/file.txt"
(f-relative "/default/directory/my/file.txt")
=> "../default/directory/my/file.txt"
(f-short FILENAME)
;; Return a version of FILENAME shortened using ‘directory-abbrev-alist’.
(f-short "/Users/foo/Code/on/macOS")
=> ~/Code/on/macOS
(f-short "/home/foo/Code/on/linux")
=> ~/Code/on/linux
(f-short "/path/to/Code/bar")
=> "/path/to/Code/bar"
(f-long PATH)
;; Return long version of PATH.
(f-long "~/Code/bar")
=> "/root/Code/bar"
(f-long "/path/to/Code/bar")
=> "/path/to/Code/bar"
(f-canonical FILENAME)
;; Return the truename of FILENAME.
(f-canonical "/path/to/real/file")
=> "/path/to/real/file"
(f-canonical "/link/to/file")
=> /path/to/real/file
(f-slash PATH)
;; Append slash to PATH unless one already.
(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")
=> "/root/path/to/file"
(f-full "~/path/to/dir")
=> "/root/path/to/dir"
(f-full "~/path/to/dir/")
=> "/root/path/to/dir/"
(f-uniquify FILES)
;; Return unique suffixes of FILES.
(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 FILES)
;; Return alist mapping FILES to unique suffixes of FILES.
(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"))
I/O
(f-read-bytes PATH &optional BEG END)
;; Read binary data from PATH.
(f-read-bytes "path/to/binary/data")
->
(f-write-bytes DATA PATH)
;; Write binary DATA to PATH.
(f-write-bytes (unibyte-string 72 101 108 108 111 32 119 111 114 108 100) "path/to/binary/data")
->
(f-append-bytes DATA PATH)
;; Append binary DATA to PATH.
(f-append-bytes "path/to/file" (unibyte-string 72 101 108 108 111 32 119 111 114 108 100))
->
(f-read-text PATH &optional CODING)
;; Read text with PATH, using CODING.
(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.
(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.
(f-append-text "Hello world" 'utf-8 "path/to/file.txt")
->
(f-append "Hello world" 'utf-8 "path/to/file.txt")
->
Destructive
(f-mkdir &rest DIRS)
;; Create directories DIRS.
(f-mkdir "dir")
=> creates /default/directory/dir
(f-mkdir "other" "dir")
=> creates /default/directory/other/dir
(f-mkdir "/" "some" "path")
=> creates /some/path
(f-mkdir "~" "yet" "another" "dir")
=> creates ~/yet/another/dir
(f-mkdir-full-path DIR)
;; Create DIR from a full path.
(f-mkdir-full-path "dir")
=> creates /default/directory/dir
(f-mkdir-full-path "other/dir")
=> creates /default/directory/other/dir
(f-mkdir-full-path "/some/path")
=> creates /some/path
(f-mkdir-full-path "~/yet/another/dir")
=> creates ~/yet/another/dir
(f-delete PATH &optional FORCE)
;; Delete PATH, which can be file or directory.
(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")
->
Predicates
(f-exists-p FILENAME)
;; Return t if file FILENAME exists (whether or not you can read it).
(f-exists-p "path/to/file.txt")
->
(f-exists-p "path/to/dir")
->
(f-directory-p FILENAME)
;; Return t if FILENAME names an existing directory.
(f-directory-p "path/to/file.txt")
->
(f-directory-p "path/to/dir")
->
(f-file-p FILENAME)
;; Return t if FILENAME names a regular file.
(f-file-p "path/to/file.txt")
->
(f-file-p "path/to/dir")
->
(f-symlink-p PATH)
;; Return t if PATH is symlink, false otherwise.
(f-symlink-p "path/to/file.txt")
->
(f-symlink-p "path/to/dir")
->
(f-symlink-p "path/to/link")
->
(f-readable-p FILENAME)
;; Return t if file FILENAME exists and you can read it.
(f-readable-p "path/to/file.txt")
->
(f-readable-p "path/to/dir")
->
(f-writable-p FILENAME)
;; Return t if file FILENAME can be written or created by you.
(f-writable-p "path/to/file.txt")
->
(f-writable-p "path/to/dir")
->
(f-executable-p FILENAME)
;; Return t if FILENAME can be executed by you.
(f-executable-p "path/to/file.txt")
->
(f-executable-p "path/to/dir")
->
(f-absolute-p FILENAME)
;; Return t if FILENAME is an absolute file name.
(f-absolute-p "path/to/dir")
=> nil
(f-absolute-p "/full/path/to/dir")
=> t
(f-relative-p PATH)
;; Return t if PATH is relative, false otherwise.
(f-relative-p "path/to/dir")
=> t
(f-relative-p "/full/path/to/dir")
=> nil
(f-root-p PATH)
;; Return t if PATH is root directory, false otherwise.
(f-root-p "/")
=> t
(f-root-p "/not/root")
=> nil
(f-ext-p PATH &optional EXT)
;; Return t if extension of PATH is EXT, false otherwise.
(f-ext-p "path/to/file.el" "el")
=> t
(f-ext-p "path/to/file.el" "txt")
=> nil
(f-ext-p "path/to/file.el")
=> t
(f-ext-p "path/to/file")
=> nil
(f-same-p PATH-A PATH-B)
;; Return t if PATH-A and PATH-B are references to same file.
(f-same-p "foo.txt" "foo.txt")
=> t
(f-same-p "foo/bar/../baz" "foo/baz")
=> t
(f-same-p "/path/to/foo.txt" "/path/to/bar.txt")
=> nil
(f-parent-of-p PATH-A PATH-B)
;; Return t if PATH-A is parent of PATH-B.
(f-parent-of-p "/path/to" "/path/to/dir")
=> t
(f-parent-of-p "/path/to/dir" "/path/to")
=> nil
(f-parent-of-p "/path/to" "/path/to")
=> nil
(f-child-of-p PATH-A PATH-B)
;; Return t if PATH-A is child of PATH-B.
(f-child-of-p "/path/to" "/path/to/dir")
=> nil
(f-child-of-p "/path/to/dir" "/path/to")
=> t
(f-child-of-p "/path/to" "/path/to")
=> nil
(f-ancestor-of-p PATH-A PATH-B)
;; Return t if PATH-A is ancestor of PATH-B.
(f-ancestor-of-p "/path/to" "/path/to/dir")
=> t
(f-ancestor-of-p "/path" "/path/to/dir")
=> t
(f-ancestor-of-p "/path/to/dir" "/path/to")
=> nil
(f-ancestor-of-p "/path/to" "/path/to")
=> nil
(f-descendant-of-p PATH-A PATH-B)
;; Return t if PATH-A is desendant of PATH-B.
(f-descendant-of-p "/path/to/dir" "/path/to")
=> t
(f-descendant-of-p "/path/to/dir" "/path")
=> t
(f-descendant-of-p "/path/to" "/path/to/dir")
=> nil
(f-descendant-of-p "/path/to" "/path/to")
=> nil
(f-hidden-p PATH &optional BEHAVIOR)
;; Return t if PATH is hidden, nil otherwise.
(f-hidden-p "path/to/foo")
=> nil
(f-hidden-p ".path/to/foo")
=> t
(f-hidden-p "path/.to/foo")
=> nil
(f-hidden-p "path/to/.foo")
=> nil
(f-hidden-p ".path/to/foo" 'any)
=> t
(f-hidden-p "path/.to/foo" 'any)
=> t
(f-hidden-p "path/to/.foo" 'any)
=> t
(f-hidden-p ".path/to/foo" 'last)
=> nil
(f-hidden-p "path/.to/foo" 'last)
=> nil
(f-hidden-p "path/to/.foo" 'last)
=> t
(f-empty-p PATH)
;; If PATH is a file, return t if the file in PATH is empty, nil otherwise.
(f-empty-p "/path/to/empty-file")
=> t
(f-empty-p "/path/to/file-with-contents")
=> nil
(f-empty-p "/path/to/empty-dir/")
=> t
(f-empty-p "/path/to/dir-with-contents/")
=> nil
(f-older-p FILE OTHER &optional METHOD)
;; Compare if FILE is older than OTHER.
(f-older-p "older-file.txt" "newer-file.txt")
=> t
(f-older-p "newer-file.txt" "older-file.txt")
=> nil
(f-older-p "same-time1.txt" "same-time2.txt")
=> nil
(f-newer-p FILE OTHER &optional METHOD)
;; Compare if FILE is newer than OTHER.
(f-newer-p "newer-file.txt" "older-file.txt")
=> t
(f-newer-p "older-file.txt" "newer-file.txt")
=> nil
(f-newer-p "same-time1.txt" "same-time2.txt")
=> nil
(f-same-time-p FILE OTHER &optional METHOD)
;; Check if FILE and OTHER share the same access or modification time.
(f-same-time-p "same-time1.txt" "same-time2.txt")
=> t
(f-same-time-p "newer-file.txt" "older-file.txt")
=> nil
(f-same-time-p "older-file.txt" "newer-file.txt")
=> nil
Stats
(f-size PATH)
;; Return size of PATH.
(f-size "path/to/file.txt")
->
(f-size "path/to/dir")
->
(f-depth PATH)
;; Return the depth of PATH.
(f-depth "/")
=> 0
(f-depth "/var/")
=> 1
(f-depth "/usr/local/bin")
=> 3
(f-change-time PATH &optional TIMESTAMP-P)
;; Return the last status change time of PATH.
(f-change-time "path/to/file.txt")
=> (25517 48756 26337 111000)
(f-change-time "path/to/dir")
=> (25517 57887 344657 210000)
(f-change-time "path/to/file.txt" t)
=> (1672330868026337111 . 1000000000)
(f-change-time "path/to/dir" t)
=> (1672339999344657210 . 1000000000)
(f-change-time "path/to/file.txt" 'seconds)
=> 1672330868
(f-change-time "path/to/dir" 'seconds)
=> 1672339999
(f-modification-time PATH &optional TIMESTAMP-P)
;; Return the last modification time of PATH.
(f-modification-time "path/to/file.txt")
=> (25517 48756 26337 111000)
(f-modification-time "path/to/dir")
=> (25517 57887 344657 210000)
(f-modification-time "path/to/file.txt" t)
=> (1672330868026337111 . 1000000000)
(f-modification-time "path/to/dir" t)
=> (1672339999344657210 . 1000000000)
(f-modification-time "path/to/file.txt" 'seconds)
=> 1672330868
(f-modification-time "path/to/dir" 'seconds)
=> 1672339999
(f-access-time PATH &optional TIMESTAMP-P)
;; Return the last access time of PATH.
(f-access-time "path/to/file.txt")
=> (25517 48756 26337 111000)
(f-access-time "path/to/dir")
=> (25517 57887 344657 210000)
(f-access-time "path/to/file.txt" t)
=> (1672330868026337111 . 1000000000)
(f-access-time "path/to/dir" t)
=> (1672339999344657210 . 1000000000)
(f-access-time "path/to/file.txt" 'seconds)
=> 1672330868
(f-access-time "path/to/dir" 'seconds)
=> 1672339999
Misc
(f-this-file)
;; Return path to this file.
(f-this-file)
->
(f-path-separator)
;; Return path separator.
(f-path-separator)
=> "/"
(f-glob PATTERN &optional PATH)
;; Find PATTERN in PATH.
(f-glob "path/to/*.el")
->
(f-glob "*.el" "path/to")
->
(f-entries PATH &optional FN RECURSIVE)
;; Find all files and directories in PATH.
(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.
(f-traverse-upwards #'(lambda (path) (f-exists\? (f-expand ".git" path))) start-path)
->
(f--traverse-upwards (f-exists\? (f-expand ".git" it)) start-path)
->
(f-with-sandbox PATH-OR-PATHS &rest BODY)
;; Only allow PATH-OR-PATHS and descendants 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)))
Group: file
Inserting Contents
(insert-file-contents FILENAME &optional VISIT BEG END REPLACE)
;; Insert contents of file FILENAME after point.
(insert-file-contents "/tmp/foo")
e.g. => ("/tmp/foo" 6)
(insert-file-contents-literally FILENAME &optional VISIT BEG END REPLACE)
;; Like ‘insert-file-contents’, but only read in the file literally.
(insert-file-contents-literally "/tmp/foo")
e.g. => ("/tmp/foo" 6)
(find-file FILENAME &optional WILDCARDS)
;; Edit file FILENAME.
(find-file "/tmp/foo")
e.g. => #<buffer foo>
Predicates
(file-symlink-p FILENAME)
;; Return non-nil if file FILENAME is the name of a symbolic link.
(file-symlink-p "/tmp/foo")
e.g. => t
(file-directory-p FILENAME)
;; Return t if FILENAME names an existing directory.
(file-directory-p "/tmp")
e.g. => t
(file-regular-p FILENAME)
;; Return t if FILENAME names a regular file.
(file-regular-p "/tmp/foo")
e.g. => t
(file-exists-p FILENAME)
;; Return t if file FILENAME exists (whether or not you can read it).
(file-exists-p "/tmp/foo")
e.g. => t
(file-readable-p FILENAME)
;; Return t if file FILENAME exists and you can read it.
(file-readable-p "/tmp/foo")
e.g. => t
(file-accessible-directory-p FILENAME)
;; Return t if FILENAME names a directory you can open.
(file-accessible-directory-p "/tmp")
e.g. => t
(file-executable-p FILENAME)
;; Return t if FILENAME can be executed by you.
(file-executable-p "/bin/cat")
e.g. => t
(file-newer-than-file-p FILE1 FILE2)
;; Return t if file FILE1 is newer than file FILE2.
(file-newer-than-file-p "/tmp/foo" "/tmp/bar")
e.g. => nil
(file-equal-p FILE1 FILE2)
;; Return non-nil if files FILE1 and FILE2 name the same file.
(file-equal-p "/tmp/foo" "/tmp/bar")
e.g. => nil
(file-in-directory-p FILE DIR)
;; Return non-nil if FILE is in DIR or a subdirectory of DIR.
(file-in-directory-p "/tmp/foo" "/tmp/")
e.g. => t
(file-locked-p FILENAME)
;; Return a value indicating whether FILENAME is locked.
(file-locked-p "/tmp/foo")
e.g. => nil
Information
(file-attributes FILENAME &optional ID-FORMAT)
;; Return a list of attributes of file FILENAME.
(file-attributes "/tmp")
->
(file-truename FILENAME)
;; Return the truename of FILENAME.
(file-truename "/tmp/foo/bar")
e.g. => "/tmp/foo/zot"
(file-chase-links FILENAME &optional LIMIT)
;; Chase links in FILENAME until a name that is not a link.
(file-chase-links "/tmp/foo/bar")
e.g. => "/tmp/foo/zot"
(vc-responsible-backend FILE &optional NO-ERROR)
;; Return the name of a backend system that is responsible for FILE.
(vc-responsible-backend "/src/foo/bar.c")
e.g. => Git
(file-acl FILENAME)
;; Return ACL entries of file named FILENAME.
(file-acl "/tmp/foo")
e.g. => "user::rw-\ngroup::r--\nother::r--\n"
(file-extended-attributes FILENAME)
;; Return an alist of extended attributes of file FILENAME.
(file-extended-attributes "/tmp/foo")
->
(file-selinux-context FILENAME)
;; Return SELinux context of file named FILENAME.
(file-selinux-context "/tmp/foo")
->
(locate-file FILENAME PATH &optional SUFFIXES PREDICATE)
;; Search for FILENAME through PATH.
(locate-file "syslog" '("/var/log" "/usr/bin"))
e.g. => "/var/log/syslog"
(executable-find COMMAND &optional REMOTE)
;; Search for COMMAND in ‘exec-path’ and return the absolute file name.
(executable-find "ls")
e.g. => "/usr/bin/ls"
Creating
(make-temp-file PREFIX &optional DIR-FLAG SUFFIX TEXT)
;; Create a temporary file.
(make-temp-file "/tmp/foo-")
e.g. => "/tmp/foo-ZcXFMj"
(make-nearby-temp-file PREFIX &optional DIR-FLAG SUFFIX)
;; Create a temporary file as close as possible to ‘default-directory’.
(make-nearby-temp-file "/tmp/foo-")
e.g. => "/tmp/foo-xe8iON"
(write-region START END FILENAME &optional APPEND VISIT LOCKNAME MUSTBENEW)
;; Write current region into specified file.
(write-region (point-min) (point-max) "/tmp/foo")
Directories
(make-directory DIR &optional PARENTS)
;; Create the directory DIR and optionally any nonexistent parent dirs.
(make-directory "/tmp/bar/zot/" t)
(directory-files DIRECTORY &optional FULL MATCH NOSORT COUNT)
;; Return a list of names of files in DIRECTORY.
(directory-files "/tmp/")
e.g. => ("." ".." ".ICE-unix" ".Test-unix")
(directory-files-recursively DIR REGEXP &optional INCLUDE-DIRECTORIES PREDICATE FOLLOW-SYMLINKS)
;; Return list of all files under directory DIR whose names match REGEXP.
(directory-files-recursively "/tmp/" "\\.png\\'")
e.g. => ("/tmp/foo.png" "/tmp/zot.png" "/tmp/bar/foobar.png")
(directory-files-and-attributes DIRECTORY &optional FULL MATCH NOSORT ID-FORMAT COUNT)
;; Return a list of names of files and their attributes in DIRECTORY.
(directory-files-and-attributes "/tmp/foo")
->
(file-expand-wildcards PATTERN &optional FULL)
;; Expand (a.k.a. "glob") file-name wildcard pattern PATTERN.
(file-expand-wildcards "/tmp/*.png")
e.g. => ("/tmp/foo.png" "/tmp/zot.png")
(locate-dominating-file FILE NAME)
;; Starting at FILE, look up directory hierarchy for directory containing NAME.
(locate-dominating-file "foo.png" "/tmp/foo/bar/zot")
e.g. => "/tmp/foo.png"
(copy-directory DIRECTORY NEWNAME &optional KEEP-TIME PARENTS COPY-CONTENTS)
;; Copy DIRECTORY to NEWNAME. Both args must be strings.
(copy-directory "/tmp/bar/" "/tmp/barcopy")
(delete-directory DIRECTORY &optional RECURSIVE TRASH)
;; Delete the directory named DIRECTORY. Does not follow symlinks.
(delete-directory "/tmp/bar/")
File Operations
(rename-file FILE NEWNAME &optional OK-IF-ALREADY-EXISTS)
;; Rename FILE as NEWNAME. Both args must be strings.
(rename-file "/tmp/foo" "/tmp/newname")
(copy-file FILE NEWNAME &optional OK-IF-ALREADY-EXISTS KEEP-TIME PRESERVE-UID-GID PRESERVE-PERMISSIONS)
;; Copy FILE to NEWNAME. Both args must be strings.
(copy-file "/tmp/foo" "/tmp/foocopy")
(delete-file FILENAME &optional TRASH)
;; Delete file named FILENAME. If it is a symlink, remove the symlink.
(delete-file "/tmp/foo")
(make-empty-file FILENAME &optional PARENTS)
;; Create an empty file FILENAME.
(make-empty-file "/tmp/foo")
(make-symbolic-link TARGET LINKNAME &optional OK-IF-ALREADY-EXISTS)
;; Make a symbolic link to TARGET, named LINKNAME.
(make-symbolic-link "/tmp/foo" "/tmp/foosymlink")
(add-name-to-file FILE NEWNAME &optional OK-IF-ALREADY-EXISTS)
;; Give FILE additional name NEWNAME. Both args must be strings.
(add-name-to-file "/tmp/foo" "/tmp/bar")
(set-file-modes FILENAME MODE &optional FLAG)
;; Set mode bits of file named FILENAME to MODE (an integer).
(set-file-modes "/tmp/foo" #o644)
(set-file-times FILENAME &optional TIMESTAMP FLAG)
;; Set times of file FILENAME to TIMESTAMP.
(set-file-times "/tmp/foo" (current-time))
File Modes
(set-default-file-modes MODE)
;; Set the file permission bits for newly created files.
(set-default-file-modes #o755)
(default-file-modes)
;; Return the default file protection for created files.
(default-file-modes)
e.g. => #o755
(file-modes-symbolic-to-number MODES &optional FROM)
;; Convert symbolic file modes to numeric file modes.
(file-modes-symbolic-to-number "a+r")
e.g. => #o444
(file-modes-number-to-symbolic MODE &optional FILETYPE)
;; Return a string describing a file’s MODE.
(file-modes-number-to-symbolic #o444)
(set-file-extended-attributes FILENAME ATTRIBUTES)
;; Set extended attributes of file FILENAME to ATTRIBUTES.
(set-file-extended-attributes "/tmp/foo" '((acl . "group::rxx")))
e.g. => t
(set-file-selinux-context FILENAME CONTEXT)
;; Set SELinux context of file named FILENAME to CONTEXT.
(set-file-selinux-context "/tmp/foo" '(unconfined_u object_r user_home_t s0))
e.g. => t
(set-file-acl FILENAME ACL-STRING)
;; Set ACL of file named FILENAME to ACL-STRING.
(set-file-acl "/tmp/foo" "group::rxx")
e.g. => t
Group: file-name
File Name Manipulation
(file-name-directory FILENAME)
;; Return the directory component in file name FILENAME.
(file-name-directory "/tmp/foo")
=> "/tmp/"
(file-name-directory "/tmp/foo/")
=> "/tmp/foo/"
(file-name-nondirectory FILENAME)
;; Return file name FILENAME sans its directory.
(file-name-nondirectory "/tmp/foo")
=> "foo"
(file-name-nondirectory "/tmp/foo/")
=> ""
(file-name-sans-versions NAME &optional KEEP-BACKUP-VERSION)
;; Return file NAME sans backup versions or strings.
(file-name-sans-versions "/tmp/foo~")
=> "/tmp/foo"
(file-name-extension FILENAME &optional PERIOD)
;; Return FILENAME’s final "extension".
(file-name-extension "/tmp/foo.txt")
=> "txt"
(file-name-sans-extension FILENAME)
;; Return FILENAME sans final "extension".
(file-name-sans-extension "/tmp/foo.txt")
=> "/tmp/foo"
(file-name-with-extension FILENAME EXTENSION)
;; Return FILENAME modified to have the specified EXTENSION.
(file-name-with-extension "foo.txt" "bin")
=> "foo.bin"
(file-name-with-extension "foo" "bin")
=> "foo.bin"
(file-name-base FILENAME)
;; Return the base name of the FILENAME: no directory, no extension.
(file-name-base "/tmp/foo.txt")
=> "foo"
(file-relative-name FILENAME &optional DIRECTORY)
;; Convert FILENAME to be relative to DIRECTORY (default: ‘default-directory’).
(file-relative-name "/tmp/foo" "/tmp")
=> "foo"
(make-temp-name PREFIX)
;; Generate temporary file name (string) starting with PREFIX (a string).
(make-temp-name "/tmp/foo-")
=> "/tmp/foo-pzFEl3"
(file-name-concat DIRECTORY &rest COMPONENTS)
;; Append COMPONENTS to DIRECTORY and return the resulting string.
(file-name-concat "/tmp/" "foo")
=> "/tmp/foo"
(file-name-concat "/tmp" "foo")
=> "/tmp/foo"
(file-name-concat "/tmp" "foo" "bar/" "zot")
=> "/tmp/foo/bar/zot"
(file-name-concat "/tmp" "~")
=> "/tmp/~"
(expand-file-name NAME &optional DEFAULT-DIRECTORY)
;; Convert filename NAME to absolute, and canonicalize it.
(expand-file-name "foo" "/tmp/")
=> "/tmp/foo"
(expand-file-name "foo" "/tmp///")
=> "/tmp/foo"
(expand-file-name "foo" "/tmp/foo/.././")
=> "/tmp/foo"
(expand-file-name "~" "/tmp/")
=> "/root"
(substitute-in-file-name FILENAME)
;; Substitute environment variables referred to in FILENAME.
(substitute-in-file-name "$HOME/foo")
=> "/root/foo"
Directory Functions
(file-name-as-directory FILE)
;; Return a string representing the file name FILE interpreted as a directory.
(file-name-as-directory "/tmp/foo")
=> "/tmp/foo/"
(directory-file-name DIRECTORY)
;; Returns the file name of the directory named DIRECTORY.
(directory-file-name "/tmp/foo/")
=> "/tmp/foo"
(abbreviate-file-name FILENAME)
;; Return a version of FILENAME shortened using ‘directory-abbrev-alist’.
(abbreviate-file-name "/home/some-user")
e.g. => "~some-user"
Quoted File Names
(file-name-quote NAME &optional TOP)
;; Add the quotation prefix "/:" to file NAME.
(file-name-quote "/tmp/foo")
=> "/:/tmp/foo"
(file-name-unquote NAME &optional TOP)
;; Remove quotation prefix "/:" from file NAME, if any.
(file-name-unquote "/:/tmp/foo")
=> "/tmp/foo"
Predicates
(file-name-absolute-p FILENAME)
;; Return t if FILENAME is an absolute file name.
(file-name-absolute-p "/tmp/foo")
=> t
(file-name-absolute-p "foo")
=> nil
(directory-name-p NAME)
;; Return non-nil if NAME ends with a directory separator character.
(directory-name-p "/tmp/foo/")
=> t
(file-name-quoted-p NAME &optional TOP)
;; Whether NAME is quoted with prefix "/:".
(file-name-quoted-p "/:/tmp/foo")
=> t
Group: hash-table
Hash Table Basics
(make-hash-table &rest KEYWORD-ARGS)
;; Create and return a new hash table.
(make-hash-table)
=> #s(hash-table ...)
(puthash KEY VALUE TABLE)
;; Associate KEY with VALUE in hash table TABLE.
(puthash 'key "value" table)
(gethash KEY TABLE &optional DFLT)
;; Look up KEY in TABLE and return its associated value.
(gethash 'key table)
e.g. => "value"
(remhash KEY TABLE)
;; Remove KEY from TABLE.
(remhash 'key table)
=> nil
(clrhash TABLE)
;; Clear hash table TABLE and return it.
(clrhash table)
=> #s(hash-table ...)
(maphash FUNCTION TABLE)
;; Call FUNCTION for all entries in hash table TABLE.
(maphash (lambda (key value) (message value)) table)
=> nil
Other Hash Table Functions
(hash-table-p OBJ)
;; Return t if OBJ is a Lisp hash table object.
(hash-table-p 123)
=> nil
(copy-hash-table TABLE)
;; Return a copy of hash table TABLE.
(copy-hash-table table)
=> #s(hash-table ...)
(hash-table-count TABLE)
;; Return the number of elements in TABLE.
(hash-table-count table)
e.g. => 15
(hash-table-size TABLE)
;; Return the size of TABLE.
(hash-table-size table)
e.g. => 65
Group: list
Making Lists
(make-list LENGTH INIT)
;; Return a newly created list of length LENGTH, with each element being INIT.
(make-list 5 'a)
=> (a a a a a)
(cons CAR CDR)
;; Create a new cons, give it CAR and CDR as components, and return it.
(cons 1 '(2 3 4))
=> (1 2 3 4)
(list &rest OBJECTS)
;; Return a newly created list with specified arguments as elements.
(list 1 2 3)
=> (1 2 3)
(number-sequence FROM &optional TO INC)
;; Return a sequence of numbers from FROM to TO (both inclusive) as a list.
(number-sequence 5 8)
=> (5 6 7 8)
(ensure-list OBJECT)
;; Return OBJECT as a list.
(ensure-list "foo")
=> ("foo")
(ensure-list '(1 2 3))
=> (1 2 3)
Operations on Lists
(append &rest SEQUENCES)
;; Concatenate all the arguments and make the result a list.
(append '("foo" "bar") '("zot"))
=> ("foo" "bar" "zot")
(copy-tree TREE &optional VECP)
;; Make a copy of TREE.
(copy-tree '(1 (2 3) 4))
=> (1 (2 3) 4)
(flatten-tree TREE)
;; Return a "flattened" copy of TREE.
(flatten-tree '(1 (2 3) 4))
=> (1 2 3 4)
(car LIST)
;; Return the car of LIST. If LIST is nil, return nil.
(car '(one two three))
=> one
(car '(one . two))
=> one
(car nil)
=> nil
(cdr LIST)
;; Return the cdr of LIST. If LIST is nil, return nil.
(cdr '(one two three))
=> (two three)
(cdr '(one . two))
=> two
(cdr nil)
=> nil
(last LIST &optional N)
;; Return the last link of LIST. Its car is the last element.
(last '(one two three))
=> (three)
(butlast LIST &optional N)
;; Return a copy of LIST with the last N elements removed.
(butlast '(one two three))
=> (one two)
(nbutlast LIST &optional N)
;; Modify LIST to remove the last N elements.
(nbutlast (list 'one 'two 'three))
=> (one two)
(nth N LIST)
;; Return the Nth element of LIST.
(nth 1 '(one two three))
=> two
(nthcdr N LIST)
;; Take cdr N times on LIST, return the result.
(nthcdr 1 '(one two three))
=> (two three)
(elt SEQUENCE N)
;; Return element of SEQUENCE at index N.
(elt '(one two three) 1)
=> two
(car-safe OBJECT)
;; Return the car of OBJECT if it is a cons cell, or else nil.
(car-safe '(one two three))
=> one
(cdr-safe OBJECT)
;; Return the cdr of OBJECT if it is a cons cell, or else nil.
(cdr-safe '(one two three))
=> (two three)
(push NEWELT PLACE)
;; Add NEWELT to the list stored in the generalized variable PLACE.
(push 'a list)
->
(pop PLACE)
;; Return the first element of PLACE’s value, and remove it from the list.
(pop list)
->
(setcar CELL NEWCAR)
;; Set the car of CELL to be NEWCAR. Returns NEWCAR.
(setcar list 'c)
=> c
(setcdr CELL NEWCDR)
;; Set the cdr of CELL to be NEWCDR. Returns NEWCDR.
(setcdr list (list c))
=> '(c)
(nconc &rest LISTS)
;; Concatenate any number of lists by altering them.
(nconc (list 1) (list 2 3 4))
=> (1 2 3 4)
(delq ELT LIST)
;; Delete members of LIST which are ‘eq’ to ELT, and return the result.
(delq 2 (list 1 2 3 4))
=> (1 3 4)
(delq "a" (list "a" "b" "c" "d"))
=> ("a" "b" "c" "d")
(delete ELT SEQ)
;; Delete members of SEQ which are ‘equal’ to ELT, and return the result.
(delete 2 (list 1 2 3 4))
=> (1 3 4)
(delete "a" (list "a" "b" "c" "d"))
=> ("b" "c" "d")
(remove ELT SEQ)
;; Return a copy of SEQ with all occurrences of ELT removed.
(remove 2 '(1 2 3 4))
=> (1 3 4)
(remove "a" '("a" "b" "c" "d"))
=> ("b" "c" "d")
(delete-dups LIST)
;; Destructively remove ‘equal’ duplicates from LIST.
(delete-dups (list 1 2 4 3 2 4))
=> (1 2 4 3)
Mapping Over Lists
(mapcar FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE, and make a list of the results.
(mapcar #'list '(1 2 3))
=> ((1) (2) (3))
(mapcan FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE, and concatenate
(mapcan #'list '(1 2 3))
=> (1 2 3)
(mapc FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE for side effects only.
(mapc #'insert '("1" "2" "3"))
=> 123("1" "2" "3")
(reduce FUNCTION SEQ [KEYWORD VALUE]...)
;; Reduce two-argument FUNCTION across SEQ.
(reduce #'+ '(1 2 3))
=> 6
(mapconcat FUNCTION SEQUENCE SEPARATOR)
;; Apply FUNCTION to each element of SEQUENCE, and concat the results as strings.
(mapconcat #'identity '("foo" "bar") "|")
=> "foo|bar"
Predicates
(listp OBJECT)
;; Return t if OBJECT is a list, that is, a cons cell or nil.
(listp '(1 2 3))
=> t
(listp nil)
=> t
(listp '(1 . 2))
=> t
(consp OBJECT)
;; Return t if OBJECT is a cons cell.
(consp '(1 2 3))
=> t
(consp nil)
=> nil
(proper-list-p OBJECT)
;; Return OBJECT’s length if it is a proper list, nil otherwise.
(proper-list-p '(1 2 3))
=> 3
(proper-list-p nil)
=> 0
(proper-list-p '(1 . 2))
=> nil
(null OBJECT)
;; Return t if OBJECT is nil, and return nil otherwise.
(null nil)
=> t
(atom OBJECT)
;; Return t if OBJECT is not a cons cell. This includes nil.
(atom 'a)
=> t
(nlistp OBJECT)
;; Return t if OBJECT is not a list. Lists include nil.
(nlistp '(1 2 3))
=> nil
(nlistp t)
=> t
(nlistp '(1 . 2))
=> nil
Finding Elements
(memq ELT LIST)
;; Return non-nil if ELT is an element of LIST. Comparison done with ‘eq’.
(memq 2 '(1 2 3))
=> (2 3)
(memq 2.0 '(1.0 2.0 3.0))
=> nil
(memq "b" '("a" "b" "c"))
=> nil
(member ELT LIST)
;; Return non-nil if ELT is an element of LIST. Comparison done with ‘equal’.
(member 2 '(1 2 3))
=> (2 3)
(member "b" '("a" "b" "c"))
=> ("b" "c")
(remq ELT LIST)
;; Return LIST with all occurrences of ELT removed.
(remq 2 '(1 2 3 2 4 2))
=> (1 3 4)
(remq "b" '("a" "b" "c"))
=> ("a" "b" "c")
(memql ELT LIST)
;; Return non-nil if ELT is an element of LIST. Comparison done with ‘eql’.
(memql 2.0 '(1.0 2.0 3.0))
=> (2.0 3.0)
(member-ignore-case ELT LIST)
;; Like ‘member’, but ignore differences in case and text representation.
(member-ignore-case "foo" '("bar" "Foo" "zot"))
=> ("Foo" "zot")
Association Lists
(assoc KEY ALIST &optional TESTFN)
;; Return non-nil if KEY is equal to the car of an element of ALIST.
(assoc 'b '((a 1) (b 2)))
=> (b 2)
(rassoc KEY ALIST)
;; Return non-nil if KEY is ‘equal’ to the cdr of an element of ALIST.
(rassoc '2 '((a . 1) (b . 2)))
=> (b . 2)
(assq KEY ALIST)
;; Return non-nil if KEY is ‘eq’ to the car of an element of ALIST.
(assq 'b '((a 1) (b 2)))
=> (b 2)
(assq "a" '(("a" 1) ("b" 2)))
=> nil
(rassq KEY ALIST)
;; Return non-nil if KEY is ‘eq’ to the cdr of an element of ALIST.
(rassq '2 '((a . 1) (b . 2)))
=> (b . 2)
(assoc-string KEY LIST &optional CASE-FOLD)
;; Like ‘assoc’ but specifically for strings (and symbols).
(assoc-string "foo" '(("a" 1) (foo 2)))
=> (foo 2)
(alist-get KEY ALIST &optional DEFAULT REMOVE TESTFN)
;; Find the first element of ALIST whose ‘car’ equals KEY and return its ‘cdr’.
(alist-get 2 '((1 . a) (2 . b)))
=> b
(assoc-default KEY ALIST &optional TEST DEFAULT)
;; Find object KEY in a pseudo-alist ALIST.
(assoc-default 2 '((1 . a) (2 . b) #'=))
=> b
(copy-alist ALIST)
;; Return a copy of ALIST.
(copy-alist '((1 . a) (2 . b)))
=> ((1 . a) (2 . b))
(assq-delete-all KEY ALIST)
;; Delete from ALIST all elements whose car is ‘eq’ to KEY.
(assq-delete-all 2 (list '(1 . a) '(2 . b) '(2 . c)))
=> ((1 . a))
(assoc-delete-all KEY ALIST &optional TEST)
;; Delete from ALIST all elements whose car is KEY.
(assoc-delete-all "b" (list '("a" . a) '("b" . b) '("b" . c)))
=> (("a" . a))
Property Lists
(plist-get PLIST PROP)
;; Extract a value from a property list.
(plist-get '(a 1 b 2 c 3) 'b)
=> 2
(plist-put PLIST PROP VAL)
;; Change value in PLIST of PROP to VAL.
(setq plist (plist-put plist 'd 4))
(lax-plist-get PLIST PROP)
;; Extract a value from a property list, comparing with ‘equal’.
(lax-plist-get '("a" 1 "b" 2 "c" 3) "b")
=> 2
(lax-plist-put PLIST PROP VAL)
;; Change value in PLIST of PROP to VAL, comparing with ‘equal’.
(setq plist (lax-plist-put plist "d" 4))
(plist-member PLIST PROP)
;; Return non-nil if PLIST has the property PROP.
(plist-member '(a 1 b 2 c 3) 'b)
=> (b 2 c 3)
Data About Lists
(length SEQUENCE)
;; Return the length of vector, list or string SEQUENCE.
(length '(a b c))
=> 3
(length< SEQUENCE LENGTH)
;; Return non-nil if SEQUENCE is shorter than LENGTH.
(length< '(a b c) 1)
=> nil
(length> SEQUENCE LENGTH)
;; Return non-nil if SEQUENCE is longer than LENGTH.
(length> '(a b c) 1)
=> t
(length= SEQUENCE LENGTH)
;; Return non-nil if SEQUENCE has length equal to LENGTH.
(length= '(a b c) 3)
=> t
(safe-length LIST)
;; Return the length of a list, but avoid error or infinite loop.
(safe-length '(a b c))
=> 3
Group: number
Arithmetic
(+ &rest NUMBERS-OR-MARKERS)
;; Return sum of any number of arguments, which are numbers or markers.
(+ 1 2)
=> 3
(+ 1 2 3 4)
=> 10
(- &optional NUMBER-OR-MARKER &rest MORE-NUMBERS-OR-MARKERS)
;; Negate number or subtract numbers or markers and return the result.
(- 3 2)
=> 1
(- 6 3 2)
=> 1
(* &rest NUMBERS-OR-MARKERS)
;; Return product of any number of arguments, which are numbers or markers.
(* 3 4 5)
=> 60
(/ NUMBER &rest DIVISORS)
;; Divide number by divisors and return the result.
(/ 10 5)
=> 2
(/ 10 6)
=> 1
(/ 10.0 6)
=> 1.6666666666666667
(/ 10.0 3 3)
=> 1.1111111111111112
(% X Y)
;; Return remainder of X divided by Y.
(% 10 5)
=> 0
(% 10 6)
=> 4
(mod X Y)
;; Return X modulo Y.
(mod 10 5)
=> 0
(mod 10 6)
=> 4
(mod 10.5 6)
=> 4.5
(1+ NUMBER)
;; Return NUMBER plus one. NUMBER may be a number or a marker.
(1+ 2)
=> 3
(1- NUMBER)
;; Return NUMBER minus one. NUMBER may be a number or a marker.
(1- 4)
=> 3
Predicates
(= NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return t if args, all numbers or markers, are equal.
(= 4 4)
=> t
(= 4.0 4.0)
=> t
(= 4 5 6 7)
=> nil
(eq OBJ1 OBJ2)
;; Return t if the two args are the same Lisp object.
(eq 4 4)
=> t
(eq 4.0 4.0)
=> nil
(eql OBJ1 OBJ2)
;; Return t if the two args are ‘eq’ or are indistinguishable numbers.
(eql 4 4)
=> t
(eql 4 "4")
=> nil
(eql 4.0 4.0)
=> t
(/= NUM1 NUM2)
;; Return t if first arg is not equal to second arg. Both must be numbers or markers.
(/= 4 4)
=> nil
(< NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return t if each arg (a number or marker), is less than the next arg.
(< 4 4)
=> nil
(< 1 2 3)
=> t
(<= NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return t if each arg (a number or marker) is less than or equal to the next.
(<= 4 4)
=> t
(<= 1 2 3)
=> t
(> NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return t if each arg (a number or marker) is greater than the next arg.
(> 4 4)
=> nil
(> 1 2 3)
=> nil
(>= NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return t if each arg (a number or marker) is greater than or equal to the next.
(>= 4 4)
=> t
(>= 1 2 3)
=> nil
(zerop NUMBER)
;; Return t if NUMBER is zero.
(zerop 0)
=> t
(cl-plusp NUMBER)
;; Return t if NUMBER is positive.
(cl-plusp 0)
=> nil
(cl-plusp 1)
=> t
(cl-minusp NUMBER)
;; Return t if NUMBER is negative.
(cl-minusp 0)
=> nil
(cl-minusp -1)
=> t
(cl-oddp INTEGER)
;; Return t if INTEGER is odd.
(cl-oddp 3)
=> t
(cl-evenp INTEGER)
;; Return t if INTEGER is even.
(cl-evenp 6)
=> t
(natnump OBJECT)
;; Return t if OBJECT is a nonnegative integer.
(natnump -1)
=> nil
(natnump 23)
=> t
(bignump OBJECT)
;; Return t if OBJECT is a bignum.
(bignump 4)
=> nil
(bignump (expt 2 90))
=> t
(fixnump OBJECT)
;; Return t if OBJECT is a fixnum.
(fixnump 4)
=> t
(fixnump (expt 2 90))
=> nil
(floatp OBJECT)
;; Return t if OBJECT is a floating point number.
(floatp 5.4)
=> t
(integerp OBJECT)
;; Return t if OBJECT is an integer.
(integerp 5.4)
=> nil
(numberp OBJECT)
;; Return t if OBJECT is a number (floating point or integer).
(numberp "5.4")
=> nil
(cl-digit-char-p CHAR &optional RADIX)
;; Test if CHAR is a digit in the specified RADIX (default 10).
(cl-digit-char-p 53 10)
=> 5
(cl-digit-char-p 102 16)
=> 15
Operations
(max NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return largest of all the arguments (which must be numbers or markers).
(max 7 9 3)
=> 9
(min NUMBER-OR-MARKER &rest NUMBERS-OR-MARKERS)
;; Return smallest of all the arguments (which must be numbers or markers).
(min 7 9 3)
=> 3
(abs ARG)
;; Return the absolute value of ARG.
(abs -4)
=> 4
(float ARG)
;; Return the floating point number equal to ARG.
(float 2)
=> 2.0
(truncate ARG &optional DIVISOR)
;; Truncate a floating point number to an int.
(truncate 1.2)
=> 1
(truncate -1.2)
=> -1
(truncate 5.4 2)
=> 2
(floor ARG &optional DIVISOR)
;; Return the largest integer no greater than ARG.
(floor 1.2)
=> 1
(floor -1.2)
=> -2
(floor 5.4 2)
=> 2
(ceiling ARG &optional DIVISOR)
;; Return the smallest integer no less than ARG.
(ceiling 1.2)
=> 2
(ceiling -1.2)
=> -1
(ceiling 5.4 2)
=> 3
(round ARG &optional DIVISOR)
;; Return the nearest integer to ARG.
(round 1.2)
=> 1
(round -1.2)
=> -1
(round 5.4 2)
=> 3
(random &optional LIMIT)
;; Return a pseudo-random integer.
(random 6)
=> 2
Bit Operations
(ash VALUE COUNT)
;; Return VALUE with its bits shifted left by COUNT.
(ash 1 4)
=> 16
(ash 16 -1)
=> 8
(lsh VALUE COUNT)
;; Return VALUE with its bits shifted left by COUNT.
(lsh 1 4)
=> 16
(lsh 16 -1)
=> 8
(logand &rest INTS-OR-MARKERS)
;; Return bitwise-and of all the arguments.
(logand #b10 #b111)
=> #b10
(logior &rest INTS-OR-MARKERS)
;; Return bitwise-or of all the arguments.
(logior 4 16)
=> 20
(logxor &rest INTS-OR-MARKERS)
;; Return bitwise-exclusive-or of all the arguments.
(logxor 4 16)
=> 20
(lognot NUMBER)
;; Return the bitwise complement of NUMBER. NUMBER must be an integer.
(lognot 5)
=> -6
(logcount VALUE)
;; Return population count of VALUE.
(logcount 5)
=> 2
Floating Point
(isnan X)
;; Return non-nil if argument X is a NaN.
(isnan 5.0)
=> nil
(frexp X)
;; Get significand and exponent of a floating point number.
(frexp 5.7)
=> (0.7125 . 3)
(ldexp SGNFCAND EXPONENT)
;; Return SGNFCAND * 2**EXPONENT, as a floating point number.
(ldexp 0.7125 3)
=> 5.7
(logb ARG)
;; Returns largest integer <= the base 2 log of the magnitude of ARG.
(logb 10.5)
=> 3
(ffloor ARG)
;; Return the largest integer no greater than ARG, as a float.
(ffloor 1.2)
=> 1.0
(fceiling ARG)
;; Return the smallest integer no less than ARG, as a float.
(fceiling 1.2)
=> 2.0
(ftruncate ARG)
;; Truncate a floating point number to an integral float value.
(ftruncate 1.2)
=> 1.0
(fround ARG)
;; Return the nearest integer to ARG, as a float.
(fround 1.2)
=> 1.0
Standard Math Functions
(sin ARG)
;; Return the sine of ARG.
(sin float-pi)
=> 1.2246467991473532e-16
(cos ARG)
;; Return the cosine of ARG.
(cos float-pi)
=> -1.0
(tan ARG)
;; Return the tangent of ARG.
(tan float-pi)
=> -1.2246467991473532e-16
(asin ARG)
;; Return the inverse sine of ARG.
(asin float-pi)
=> 0.0e+NaN
(acos ARG)
;; Return the inverse cosine of ARG.
(acos float-pi)
=> 0.0e+NaN
(atan Y &optional X)
;; Return the inverse tangent of the arguments.
(atan float-pi)
=> 1.2626272556789118
(exp ARG)
;; Return the exponential base e of ARG.
(exp 4)
=> 54.598150033144236
(log ARG &optional BASE)
;; Return the natural logarithm of ARG.
(log 54.59)
=> 3.9998507157936665
(expt ARG1 ARG2)
;; Return the exponential ARG1 ** ARG2.
(expt 2 16)
=> 65536
(sqrt ARG)
;; Return the square root of ARG.
(sqrt -1)
=> -0.0e+NaN
Group: overlay
Predicates
(overlayp OBJECT)
;; Return t if OBJECT is an overlay.
(overlayp some-overlay)
e.g. => t
Creation and Deletion
(make-overlay BEG END &optional BUFFER FRONT-ADVANCE REAR-ADVANCE)
;; Create a new overlay with range BEG to END in BUFFER and return it.
(make-overlay 1 10)
e.g. => #<overlay from 1 to 10 in *foo*>
(delete-overlay OVERLAY)
;; Delete the overlay OVERLAY from its buffer.
(delete-overlay foo)
e.g. => t
Searching Overlays
(overlays-at POS &optional SORTED)
;; Return a list of the overlays that contain the character at POS.
(overlays-at 15)
e.g. => (#<overlay from 1 to 10 in *foo*>)
(overlays-in BEG END)
;; Return a list of the overlays that overlap the region BEG ... END.
(overlays-in 1 30)
e.g. => (#<overlay from 1 to 10 in *foo*>)
(next-overlay-change POS)
;; Return the next position after POS where an overlay starts or ends.
(next-overlay-change 1)
e.g. => 20
(previous-overlay-change POS)
;; Return the previous position before POS where an overlay starts or ends.
(previous-overlay-change 30)
e.g. => 20
Overlay Properties
(overlay-start OVERLAY)
;; Return the position at which OVERLAY starts.
(overlay-start foo)
e.g. => 1
(overlay-end OVERLAY)
;; Return the position at which OVERLAY ends.
(overlay-end foo)
e.g. => 10
(overlay-put OVERLAY PROP VALUE)
;; Set one property of overlay OVERLAY: give property PROP value VALUE.
(overlay-put foo 'happy t)
e.g. => t
(overlay-get OVERLAY PROP)
;; Get the property of overlay OVERLAY with property name PROP.
(overlay-get foo 'happy)
e.g. => t
(overlay-buffer OVERLAY)
;; Return the buffer OVERLAY belongs to.
(overlay-buffer foo)
Moving Overlays
(move-overlay OVERLAY BEG END &optional BUFFER)
;; Set the endpoints of OVERLAY to BEG and END in BUFFER.
(move-overlay foo 5 20)
e.g. => #<overlay from 5 to 20 in *foo*>
Group: process
(make-process &rest ARGS)
;; Start a program in a subprocess. Return the process object for it.
(make-process :name "foo" :command '("cat" "/tmp/foo"))
e.g. => #<process foo>
(processp OBJECT)
;; Return t if OBJECT is a process.
(processp t)
=> nil
(delete-process PROCESS)
;; Delete PROCESS: kill it and forget about it immediately.
(delete-process process)
(kill-process &optional PROCESS CURRENT-GROUP)
;; Kill process PROCESS. May be process or name of one.
(kill-process process)
(set-process-sentinel PROCESS SENTINEL)
;; Give PROCESS the sentinel SENTINEL; nil for default.
(set-process-sentinel process (lambda (proc string)))
(process-buffer PROCESS)
;; Return the buffer PROCESS is associated with.
(process-buffer process)
e.g. => #<buffer *foo*>
(get-buffer-process BUFFER)
;; Return the (or a) live process associated with BUFFER.
(get-buffer-process buffer)
e.g. => #<process foo>
(process-live-p PROCESS)
;; Return non-nil if PROCESS is alive.
(process-live-p process)
e.g. => t
Group: regexp
Matching Strings
(replace-regexp-in-string REGEXP REP STRING &optional FIXEDCASE LITERAL SUBEXP START)
;; Replace all matches for REGEXP with REP in STRING.
(replace-regexp-in-string "[a-z]+" "_" "*foo*")
=> "*_*"
(string-match-p REGEXP STRING &optional START)
;; Same as ‘string-match’ except this function does not change the match data.
(string-match-p "^[fo]+" "foobar")
=> 0
Looking in Buffers
(re-search-forward REGEXP &optional BOUND NOERROR COUNT)
;; Search forward from point for regular expression REGEXP.
(re-search-forward "^foo$" nil t)
e.g. => 43
(re-search-backward REGEXP &optional BOUND NOERROR COUNT)
;; Search backward from point for regular expression REGEXP.
(re-search-backward "^foo$" nil t)
e.g. => 43
(looking-at-p REGEXP)
;; Same as ‘looking-at’ except this function does not change the match data.
(looking-at-p "f[0-9]")
e.g. => t
Match Data
(match-string NUM &optional STRING)
;; Return the string of text matched by the previous search or regexp operation.
(and (string-match "^\\([fo]+\\)b" "foobar") (match-string 0 "foobar"))
=> "foob"
(match-beginning SUBEXP)
;; Return position of start of text matched by last search.
(match-beginning 1)
e.g. => 0
(match-end SUBEXP)
;; Return position of end of text matched by last search.
(match-end 1)
e.g. => 3
(save-match-data &rest BODY)
;; Execute the BODY forms, restoring the global value of the match data.
(save-match-data \.\.\.)
Replacing Match
(replace-match NEWTEXT &optional FIXEDCASE LITERAL STRING SUBEXP)
;; Replace text matched by last search with NEWTEXT.
(replace-match "new")
e.g. => nil
(match-substitute-replacement REPLACEMENT &optional FIXEDCASE LITERAL STRING SUBEXP)
;; Return REPLACEMENT as it will be inserted by ‘replace-match’.
(match-substitute-replacement "new")
e.g. => "new"
(replace-regexp-in-region REGEXP REPLACEMENT &optional START END)
;; Replace REGEXP with REPLACEMENT in the region from START to END.
(replace-regexp-in-region "[0-9]+" "Num \\&")
Utilities
(regexp-quote STRING)
;; Return a regexp string which matches exactly STRING and nothing else.
(regexp-quote "foo.*bar")
=> "foo\\.\\*bar"
(regexp-opt STRINGS &optional PAREN)
;; Return a regexp to match a string in the list STRINGS.
(regexp-opt '("foo" "bar"))
=> "\\(?:bar\\|foo\\)"
(regexp-opt-depth REGEXP)
;; Return the depth of REGEXP.
(regexp-opt-depth "\\(a\\(b\\)\\)")
=> 2
(regexp-opt-charset CHARS)
;; Return a regexp to match a character in CHARS.
(regexp-opt-charset '(97 98 99 100 101))
=> "[a-e]"
The `rx' Structured Regexp Notation
(rx REGEXPS...)
;; Translate regular expressions REGEXPS in sexp form to a regexp string.
(rx "IP=" (+ digit) (= 3 "." (+ digit)))
=> "IP=[[:digit:]]+\\(?:\\.[[:digit:]]+\\)\\{3\\}"
(rx-to-string FORM &optional NO-GROUP)
;; Translate FORM from ‘rx’ sexp syntax into a string regexp.
(rx-to-string '(| "foo" "bar"))
=> "\\(?:bar\\|foo\\)"
(rx-define NAME [(ARGS...)] RX)
;; Define NAME as a global ‘rx’ definition.
(and (rx-define haskell-comment (seq "--" (zero-or-more nonl)))
(rx haskell-comment))
=> "--.*"
(rx-let BINDINGS BODY...)
;; Evaluate BODY with local BINDINGS for ‘rx’.
(rx-let ((comma-separated (item) (seq item (0+ "," item)))
(number (1+ digit))
(numbers (comma-separated number)))
(rx "(" numbers ")"))
=> "([[:digit:]]+\\(?:,[[:digit:]]+\\)*)"
(rx-let-eval BINDINGS BODY...)
;; Evaluate BODY with local BINDINGS for ‘rx-to-string’.
(rx-let-eval
'((ponder (x) (seq "Where have all the " x " gone?")))
(rx-to-string
'(ponder (or "flowers" "cars" "socks"))))
=> "\\(?:Where have all the \\(?:\\(?:car\\|flower\\|sock\\)s\\) gone\\?\\)"
Group: sequence
Sequence Predicates
(seq-contains-p SEQUENCE ELT &optional TESTFN)
;; Return non-nil if SEQUENCE contains an element "equal" to ELT.
(seq-contains-p '(a b c) 'b)
=> t
(seq-contains-p '(a b c) 'd)
=> nil
(seq-every-p PRED SEQUENCE)
;; Return non-nil if PRED returns non-nil for all the elements of SEQUENCE.
(seq-every-p #'numberp '(1 2 3))
=> t
(seq-empty-p SEQUENCE)
;; Return non-nil if the SEQUENCE is empty, nil otherwise.
(seq-empty-p [])
=> t
(seq-set-equal-p SEQUENCE1 SEQUENCE2 &optional TESTFN)
;; Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements.
(seq-set-equal-p '(1 2 3) '(3 1 2))
=> t
(seq-some PRED SEQUENCE)
;; Return non-nil if PRED returns non-nil for at least one element of SEQUENCE.
(seq-some #'cl-evenp '(1 2 3))
=> t
Building Sequences
(seq-concatenate TYPE SEQUENCE...)
;; Concatenate SEQUENCES into a single sequence of type TYPE.
(seq-concatenate 'vector '(1 2) '(c d))
=> [1 2 c d]
(seq-copy SEQUENCE)
;; Return a shallow copy of SEQUENCE.
(seq-copy '(a 2))
=> (a 2)
(seq-into SEQUENCE TYPE)
;; Concatenate the elements of SEQUENCE into a sequence of type TYPE.
(seq-into '(1 2 3) 'vector)
=> [1 2 3]
Utility Functions
(seq-count PRED SEQUENCE)
;; Return the number of elements in SEQUENCE for which PRED returns non-nil.
(seq-count #'numberp '(1 b c 4))
=> 2
(seq-elt SEQUENCE N)
;; Return the Nth element of SEQUENCE.
(seq-elt '(a b c) 1)
=> b
(seq-random-elt SEQUENCE)
;; Return a randomly chosen element from SEQUENCE.
(seq-random-elt '(a b c))
e.g. => c
(seq-find PRED SEQUENCE &optional DEFAULT)
;; Return the first element in SEQUENCE for which PRED returns non-nil.
(seq-find #'numberp '(a b 3 4 f 6))
=> 3
(seq-position SEQUENCE ELT &optional TESTFN)
;; Return the (zero-based) index of the first element in SEQUENCE "equal" to ELT.
(seq-position '(a b c) 'c)
=> 2
(seq-length SEQUENCE)
;; Return the number of elements in SEQUENCE.
(seq-length "abcde")
=> 5
(seq-max SEQUENCE)
;; Return the largest element of SEQUENCE.
(seq-max [1 2 3])
=> 3
(seq-min SEQUENCE)
;; Return the smallest element of SEQUENCE.
(seq-min [1 2 3])
=> 1
(seq-first SEQUENCE)
;; Return the first element of SEQUENCE.
(seq-first [a b c])
=> a
(seq-rest SEQUENCE)
;; Return SEQUENCE with its first element removed.
(seq-rest '[1 2 3])
=> [2 3]
(seq-reverse SEQUENCE)
;; Return a sequence with elements of SEQUENCE in reverse order.
(seq-reverse '(1 2 3))
=> (3 2 1)
(seq-sort PRED SEQUENCE)
;; Sort SEQUENCE using PRED as the sorting comparison function.
(seq-sort #'> '(1 2 3))
=> (3 2 1)
(seq-sort-by FUNCTION PRED SEQUENCE)
;; Sort SEQUENCE transformed by FUNCTION using PRED as the comparison function.
(seq-sort-by (lambda (a) (/ 1.0 a)) #'< '(1 2 3))
=> (3 2 1)
Mapping Over Sequences
(seq-map FUNCTION SEQUENCE)
;; Return the result of applying FUNCTION to each element of SEQUENCE.
(seq-map #'1+ '(1 2 3))
=> (2 3 4)
(seq-map-indexed FUNCTION SEQUENCE)
;; Return the result of applying FUNCTION to each element of SEQUENCE.
(seq-map-indexed (lambda (a i) (cons i a)) '(a b c))
=> ((0 . a) (1 . b) (2 . c))
(seq-mapcat FUNCTION SEQUENCE &optional TYPE)
;; Concatenate the results of applying FUNCTION to each element of SEQUENCE.
(seq-mapcat #'upcase '("a" "b" "c") 'string)
=> "ABC"
(seq-do FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE.
(seq-do (lambda (a) (insert a)) '("foo" "bar"))
e.g. => ("foo" "bar")
(seq-do-indexed FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE and return nil.
(seq-do-indexed (lambda (a index) (message "%s:%s" index a)) '("foo" "bar"))
e.g. => nil
(seq-reduce FUNCTION SEQUENCE INITIAL-VALUE)
;; Reduce the function FUNCTION across SEQUENCE, starting with INITIAL-VALUE.
(seq-reduce #'* [1 2 3] 2)
=> 12
Excerpting Sequences
(seq-drop SEQUENCE N)
;; Remove the first N elements of SEQUENCE and return the resulting sequence.
(seq-drop '(a b c) 2)
=> (c)
(seq-drop-while PRED SEQUENCE)
;; Remove the successive elements of SEQUENCE for which PRED returns non-nil.
(seq-drop-while #'numberp '(1 2 c d 5))
=> (c d 5)
(seq-filter PRED SEQUENCE)
;; Return a list of all the elements in SEQUENCE for which PRED returns non-nil.
(seq-filter #'numberp '(a b 3 4 f 6))
=> (3 4 6)
(seq-remove PRED SEQUENCE)
;; Return a list of all the elements in SEQUENCE for which PRED returns nil.
(seq-remove #'numberp '(1 2 c d 5))
=> (c d)
(seq-group-by FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE.
(seq-group-by #'cl-plusp '(-1 2 3 -4 -5 6))
=> ((nil -1 -4 -5) (t 2 3 6))
(seq-union SEQUENCE1 SEQUENCE2 &optional TESTFN)
;; Return a list of all the elements that appear in either SEQUENCE1 or SEQUENCE2.
(seq-union '(1 2 3) '(3 5))
=> (1 2 3 5)
(seq-difference SEQUENCE1 SEQUENCE2 &optional TESTFN)
;; Return list of all the elements that appear in SEQUENCE1 but not in SEQUENCE2.
(seq-difference '(1 2 3) '(2 3 4))
=> (1)
(seq-intersection SEQUENCE1 SEQUENCE2 &optional TESTFN)
;; Return a list of all the elements that appear in both SEQUENCE1 and SEQUENCE2.
(seq-intersection '(1 2 3) '(2 3 4))
=> (2 3)
(seq-partition SEQUENCE N)
;; Return list of elements of SEQUENCE grouped into sub-sequences of length N.
(seq-partition '(a b c d e f g h) 3)
=> ((a b c) (d e f) (g h))
(seq-subseq SEQUENCE START &optional END)
;; Return the sequence of elements of SEQUENCE from START to END.
(seq-subseq '(a b c d e) 2 4)
=> (c d)
(seq-take SEQUENCE N)
;; Return the sequence made of the first N elements of SEQUENCE.
(seq-take '(a b c d e) 3)
=> (a b c)
(seq-take-while PRED SEQUENCE)
;; Take the successive elements of SEQUENCE for which PRED returns non-nil.
(seq-take-while #'cl-evenp [2 4 9 6 5])
=> [2 4]
(seq-uniq SEQUENCE &optional TESTFN)
;; Return a list of the elements of SEQUENCE with duplicates removed.
(seq-uniq '(a b d b a c))
=> (a b d c)
Group: string
Making Strings
(make-string LENGTH INIT &optional MULTIBYTE)
;; Return a newly created string of length LENGTH, with INIT in each element.
(make-string 5 ?x)
(string &rest CHARACTERS)
;; Concatenate all the argument characters and make the result a string.
(string ?a ?b ?c)
(concat &rest SEQUENCES)
;; Concatenate all the arguments and make the result a string.
(concat "foo" "bar" "zot")
=> "foobarzot"
(string-join STRINGS &optional SEPARATOR)
;; Join all STRINGS using SEPARATOR.
(string-join '("foo" "bar" "zot") " ")
=> "foo bar zot"
(mapconcat FUNCTION SEQUENCE SEPARATOR)
;; Apply FUNCTION to each element of SEQUENCE, and concat the results as strings.
(mapconcat (lambda (a) (concat "[" a "]")) '("foo" "bar" "zot") " ")
=> "[foo] [bar] [zot]"
(string-pad STRING LENGTH &optional PADDING START)
;; Pad STRING to LENGTH using PADDING.
(string-pad "foo" 5)
=> "foo "
(string-pad "foobar" 5)
=> "foobar"
(string-pad "foo" 5 45 t)
=> "--foo"
(mapcar FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE, and make a list of the results.
(mapcar #'identity "123")
=> (49 50 51)
(format STRING &rest OBJECTS)
;; Format a string out of a format-string and arguments.
(format "This number is %d" 4)
=> "This number is 4"
Manipulating Strings
(substring STRING &optional FROM TO)
;; Return a new string whose contents are a substring of STRING.
(substring "foobar" 0 3)
=> "foo"
(substring "foobar" 3)
=> "bar"
(string-limit STRING LENGTH &optional END CODING-SYSTEM)
;; Return a substring of STRING that is (up to) LENGTH characters long.
(string-limit "foobar" 3)
=> "foo"
(string-limit "foobar" 3 t)
=> "bar"
(string-limit "foobar" 10)
=> "foobar"
(string-limit "fo好" 3 nil 'utf-8)
=> "fo"
(truncate-string-to-width STR END-COLUMN &optional START-COLUMN PADDING ELLIPSIS ELLIPSIS-TEXT-PROPERTY)
;; Truncate string STR to end at column END-COLUMN.
(truncate-string-to-width "foobar" 3)
=> "foo"
(truncate-string-to-width "你好bar" 5)
=> "你好b"
(split-string STRING &optional SEPARATORS OMIT-NULLS TRIM)
;; Split STRING into substrings bounded by matches for SEPARATORS.
(split-string "foo bar")
=> ("foo" "bar")
(split-string "|foo|bar|" "|")
=> ("" "foo" "bar" "")
(split-string "|foo|bar|" "|" t)
=> ("foo" "bar")
(split-string-and-unquote STRING &optional SEPARATOR)
;; Split the STRING into a list of strings.
(split-string-and-unquote "foo \"bar zot\"")
=> ("foo" "bar zot")
(split-string-shell-command STRING)
;; Split STRING (a shell command) into a list of strings.
(split-string-shell-command "ls /tmp/'foo bar'")
=> ("ls" "/tmp/foo bar")
(string-lines STRING &optional OMIT-NULLS)
;; Split STRING into a list of lines.
(string-lines "foo\n\nbar")
=> ("foo" "" "bar")
(string-lines "foo\n\nbar" t)
=> ("foo" "bar")
(string-replace FROM-STRING TO-STRING IN-STRING)
;; Replace FROM-STRING with TO-STRING in IN-STRING each time it occurs.
(string-replace "foo" "bar" "foozot")
=> "barzot"
(replace-regexp-in-string REGEXP REP STRING &optional FIXEDCASE LITERAL SUBEXP START)
;; Replace all matches for REGEXP with REP in STRING.
(replace-regexp-in-string "[a-z]+" "_" "*foo*")
=> "*_*"
(string-trim STRING &optional TRIM-LEFT TRIM-RIGHT)
;; Trim STRING of leading and trailing strings matching TRIM-LEFT and TRIM-RIGHT.
(string-trim " foo ")
=> "foo"
(string-trim-left STRING &optional REGEXP)
;; Trim STRING of leading string matching REGEXP.
(string-trim-left "oofoo" "o+")
=> "foo"
(string-trim-right STRING &optional REGEXP)
;; Trim STRING of trailing string matching REGEXP.
(string-trim-right "barkss" "s+")
=> "bark"
(string-truncate-left STRING LENGTH)
;; Truncate STRING to LENGTH, replacing initial surplus with "...".
(string-truncate-left "longstring" 8)
=> "...string"
(string-remove-suffix SUFFIX STRING)
;; Remove SUFFIX from STRING if present.
(string-remove-suffix "bar" "foobar")
=> "foo"
(string-remove-prefix PREFIX STRING)
;; Remove PREFIX from STRING if present.
(string-remove-prefix "foo" "foobar")
=> "bar"
(string-chop-newline STRING)
;; Remove the final newline (if any) from STRING.
(string-chop-newline "foo\n")
=> "foo"
(string-clean-whitespace STRING)
;; Clean up whitespace in STRING.
(string-clean-whitespace " foo bar ")
=> "foo bar"
(string-fill STRING LENGTH)
;; Try to word-wrap STRING so that no lines are longer than LENGTH.
(string-fill "Three short words" 12)
=> "Three short\nwords"
(string-fill "Long-word" 3)
=> "Long-word"
(reverse SEQ)
;; Return the reversed copy of list, vector, or string SEQ.
(reverse "foo")
=> "oof"
(substring-no-properties STRING &optional FROM TO)
;; Return a substring of STRING, without text properties.
(substring-no-properties (propertize "foobar" 'face 'bold) 0 3)
=> "foo"
(try-completion STRING COLLECTION &optional PREDICATE)
;; Return common substring of all completions of STRING in COLLECTION.
(try-completion "foo" '("foobar" "foozot" "gazonk"))
=> "foo"
Predicates for Strings
(string-equal S1 S2)
;; Return t if two strings have identical contents.
(string-equal "foo" "foo")
=> t
(eq OBJ1 OBJ2)
;; Return t if the two args are the same Lisp object.
(eq "foo" "foo")
=> nil
(eql OBJ1 OBJ2)
;; Return t if the two args are ‘eq’ or are indistinguishable numbers.
(eql "foo" "foo")
=> nil
(equal O1 O2)
;; Return t if two Lisp objects have similar structure and contents.
(equal "foo" "foo")
=> t
(cl-equalp X Y)
;; Return t if two Lisp objects have similar structures and contents.
(cl-equalp "Foo" "foo")
=> t
(stringp OBJECT)
;; Return t if OBJECT is a string.
(stringp ?a)
(string-empty-p STRING)
;; Check whether STRING is empty.
(string-empty-p "")
=> t
(string-blank-p STRING)
;; Check whether STRING is either empty or only whitespace.
(string-blank-p " \n")
=> 0
(string-lessp STRING1 STRING2)
;; Return non-nil if STRING1 is less than STRING2 in lexicographic order.
(string-lessp "foo" "bar")
=> nil
(string-greaterp STRING1 STRING2)
;; Return non-nil if STRING1 is greater than STRING2 in lexicographic order.
(string-greaterp "foo" "bar")
=> t
(string-version-lessp STRING1 STRING2)
;; Return non-nil if S1 is less than S2, as version strings.
(string-version-lessp "pic4.png" "pic32.png")
=> t
(string-prefix-p PREFIX STRING &optional IGNORE-CASE)
;; Return non-nil if PREFIX is a prefix of STRING.
(string-prefix-p "foo" "foobar")
=> t
(string-suffix-p SUFFIX STRING &optional IGNORE-CASE)
;; Return non-nil if SUFFIX is a suffix of STRING.
(string-suffix-p "bar" "foobar")
=> t
Case Manipulation
(upcase OBJ)
;; Convert argument to upper case and return that.
(upcase "foo")
=> "FOO"
(downcase OBJ)
;; Convert argument to lower case and return that.
(downcase "FOObar")
=> "foobar"
(capitalize OBJ)
;; Convert argument to capitalized form and return that.
(capitalize "foo bar zot")
=> "Foo Bar Zot"
(upcase-initials OBJ)
;; Convert the initial of each word in the argument to upper case.
(upcase-initials "The CAT in the hAt")
=> "The CAT In The HAt"
Converting Strings
(string-to-number STRING &optional BASE)
;; Parse STRING as a decimal number and return the number.
(string-to-number "42")
=> 42
(string-to-number "deadbeef" 16)
=> 3735928559
(number-to-string NUMBER)
;; Return the decimal representation of NUMBER as a string.
(number-to-string 42)
=> "42"
Data About Strings
(length SEQUENCE)
;; Return the length of vector, list or string SEQUENCE.
(length "foo")
=> 3
(string-search NEEDLE HAYSTACK &optional START-POS)
;; Search for the string NEEDLE in the string HAYSTACK.
(string-search "bar" "foobarzot")
=> 3
(assoc-string KEY LIST &optional CASE-FOLD)
;; Like ‘assoc’ but specifically for strings (and symbols).
(assoc-string "foo" '(("a" 1) (foo 2)))
=> (foo 2)
(seq-position SEQUENCE ELT &optional TESTFN)
;; Return the (zero-based) index of the first element in SEQUENCE "equal" to ELT.
(seq-position "foobarzot" ?z)
Group: text-properties
Examining Text Properties
(get-text-property POSITION PROP &optional OBJECT)
;; Return the value of POSITION’s property PROP, in OBJECT.
(get-text-property 0 'foo (propertize "x" 'foo t))
=> t
(get-char-property POSITION PROP &optional OBJECT)
;; Return the value of POSITION’s property PROP, in OBJECT.
(get-char-property 0 'foo (propertize "x" 'foo t))
=> t
(get-pos-property POSITION PROP &optional OBJECT)
;; Return the value of POSITION’s property PROP, in OBJECT.
(get-pos-property 0 'foo (propertize "x" 'foo t))
=> t
(get-char-property-and-overlay POSITION PROP &optional OBJECT)
;; Like ‘get-char-property’, but with extra overlay information.
(get-char-property-and-overlay 0 'foo (propertize "x" 'foo t))
=> (t)
(text-properties-at POSITION &optional OBJECT)
;; Return the list of properties of the character at POSITION in OBJECT.
(text-properties-at (point))
=> nil
Changing Text Properties
(put-text-property START END PROPERTY VALUE &optional OBJECT)
;; Set one property of the text from START to END.
(let ((s "abc")) (put-text-property 0 1 'foo t s) s)
=> #("abc" 0 1 (foo t))
(put-text-property (point) (1+ (point)) 'face 'error)
(add-text-properties START END PROPERTIES &optional OBJECT)
;; Add properties to the text from START to END.
(add-text-properties (point) (1+ (point)) '(face error))
(remove-text-properties START END PROPERTIES &optional OBJECT)
;; Remove some properties from text from START to END.
(remove-text-properties (point) (1+ (point)) '(face nil))
(remove-list-of-text-properties START END LIST-OF-PROPERTIES &optional OBJECT)
;; Remove some properties from text from START to END.
(remove-list-of-text-properties (point) (1+ (point)) '(face font-lock-face))
(set-text-properties START END PROPERTIES &optional OBJECT)
;; Completely replace properties of text from START to END.
(set-text-properties (point) (1+ (point)) '(face error))
(add-face-text-property START END FACE &optional APPEND OBJECT)
;; Add the face property to the text from START to END.
(propertize STRING &rest PROPERTIES)
;; Return a copy of STRING with text properties added.
(propertize "foo" 'face 'italic 'mouse-face 'bold-italic)
=> #("foo" 0 3 (mouse-face bold-italic face italic))
Searching for Text Properties
(next-property-change POSITION &optional OBJECT LIMIT)
;; Return the position of next property change.
(next-property-change (point) (current-buffer))
(previous-property-change POSITION &optional OBJECT LIMIT)
;; Return the position of previous property change.
(previous-property-change (point) (current-buffer))
(next-single-property-change POSITION PROP &optional OBJECT LIMIT)
;; Return the position of next property change for a specific property.
(next-single-property-change (point) 'face (current-buffer))
(previous-single-property-change POSITION PROP &optional OBJECT LIMIT)
;; Return the position of previous property change for a specific property.
(previous-single-property-change (point) 'face (current-buffer))
(text-property-search-forward PROPERTY &optional VALUE PREDICATE NOT-CURRENT)
;; Search for the next region of text where PREDICATE is true.
(text-property-search-forward 'face nil t)
(text-property-search-backward PROPERTY &optional VALUE PREDICATE NOT-CURRENT)
;; Search for the previous region of text whose PROPERTY matches VALUE.
(text-property-search-backward 'face nil t)
Group: vector
Making Vectors
(make-vector LENGTH INIT)
;; Return a newly created vector of length LENGTH, with each element being INIT.
(make-vector 5 "foo")
=> ["foo" "foo" "foo" "foo" "foo"]
(vector &rest OBJECTS)
;; Return a newly created vector with specified arguments as elements.
(vector 1 "b" 3)
=> [1 "b" 3]
Operations on Vectors
(vectorp OBJECT)
;; Return t if OBJECT is a vector.
(vectorp [1])
=> t
(vectorp "1")
=> nil
(vconcat &rest SEQUENCES)
;; Concatenate all the arguments and make the result a vector.
(vconcat '(1 2) [3 4])
=> [1 2 3 4]
(append &rest SEQUENCES)
;; Concatenate all the arguments and make the result a list.
(append [1 2] nil)
=> (1 2)
(length SEQUENCE)
;; Return the length of vector, list or string SEQUENCE.
(length [1 2 3])
=> 3
(seq-reduce FUNCTION SEQUENCE INITIAL-VALUE)
;; Reduce the function FUNCTION across SEQUENCE, starting with INITIAL-VALUE.
(seq-reduce #'+ [1 2 3] 0)
=> 6
(seq-subseq SEQUENCE START &optional END)
;; Return the sequence of elements of SEQUENCE from START to END.
(seq-subseq [1 2 3 4 5] 1 3)
=> [2 3]
(seq-subseq [1 2 3 4 5] 1)
=> [2 3 4 5]
Mapping Over Vectors
(mapcar FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE, and make a list of the results.
(mapcar #'identity [1 2 3])
=> (1 2 3)
(mapc FUNCTION SEQUENCE)
;; Apply FUNCTION to each element of SEQUENCE for side effects only.
(mapc #'insert ["1" "2" "3"])
=> 123["1" "2" "3"]