Emacs Lisp

https://www.gnu.org/software/emacs/manual/html_node/elisp/
Admin
Emacs Lisp is a dialect of the Lisp programming language used by the GNU Emacs text editor as a full...
Tokens:1,520,613
Snippets:12,395
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### process-command example

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Process-Information.html

Returns the command that started the process as a list of strings. The example shows the command for the "shell" process.

```emacs-lisp
(process-command (get-process "shell"))
     ⇒ ("bash" "-i")

```

--------------------------------

### start-process example with sleep and ls

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Asynchronous-Processes.html

Starts two asynchronous processes using start-process. The first sleeps for 100 seconds, the second lists /bin. The output buffer 'foo' shows the directory listing and process finished messages.

```emacs-lisp
(start-process "my-process" "foo" "sleep" "100")
     ⇒ #<process my-process>
```

```emacs-lisp
(start-process "my-process" "foo" "ls" "-l" "/bin")
     ⇒ #<process my-process<1>>

---------- Buffer: foo ----------
total 8336
-rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
-rwxr-xr-x 1 root root 146920 Jul  5  2011 bsd-csh
...
-rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4

Process my-process<1> finished

Process my-process finished
---------- Buffer: foo ----------
```

--------------------------------

### string-match example with start argument

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html

Shows the result of (string-match "quick" "The quick brown fox jumped quickly." 8) which returns 27, the index of the second match.

```emacs-lisp
(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     ⇒ 27
```

--------------------------------

### string-match example with default start

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Regexp-Search.html

Shows the result of (string-match "quick" "The quick brown fox jumped quickly.") which returns 4, the index of the first match.

```emacs-lisp
(string-match
 "quick" "The quick brown fox jumped quickly.")
     ⇒ 4
```

--------------------------------

### put and get example: setting and retrieving symbol properties

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Symbol-Plists.html

Shows how to use put to set properties on a symbol and get to retrieve them. The output of each expression is shown after the arrow. The final symbol-plist call displays the entire property list.

```emacs-lisp
(put 'fly 'verb 'transitive)
     ⇒'transitive
(put 'fly 'noun '(a buzzing little bug))
     ⇒ (a buzzing little bug)
(get 'fly 'verb)
     ⇒ transitive
(symbol-plist 'fly)
     ⇒ (verb transitive noun (a buzzing little bug))

```

--------------------------------

### Division with /

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Arithmetic-Operations.html

Examples of the / function, demonstrating integer and floating-point division behavior.

```elisp
(/ 6 2)
     ⇒ 3
```

```elisp
(/ 5 2)
     ⇒ 2
```

```elisp
(/ 5.0 2)
     ⇒ 2.5
```

```elisp
(/ 5 2.0)
     ⇒ 2.5
```

```elisp
(/ 5.0 2.0)
     ⇒ 2.5
```

```elisp
(/ 4.0)
     ⇒ 0.25
```

```elisp
(/ 4)
     ⇒ 0
```

```elisp
(/ 25 3 2)
     ⇒ 4
```

```elisp
(/ -17 6)
     ⇒ -2
```

--------------------------------

### Using re-search-forward and match-beginning to get buffer match positions

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html

Shows how to use re-search-forward to search in a buffer and then use match-beginning with counts 0 and 1 to get the start positions of the entire match and the first subexpression. The example includes a buffer display showing the positions of the match.

```emacs-lisp
(list
  (re-search-forward "The \\(cat \\)")
  (match-beginning 0)
  (match-beginning 1))
    ⇒ (17 9 13)

```

```text
---------- Buffer: foo ----------
I read "The cat ∗in the hat comes back" twice.
        ^   ^
        9  13
---------- Buffer: foo ----------

```

--------------------------------

### Using match-beginning and match-end to get match positions

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html

Shows how to use match-beginning and match-end to retrieve the start and end positions of the entire match and of subexpressions after a string-match. The comments show the expected positions in the example string.

```emacs-lisp
(match-beginning 1)       ; The beginning of the match
     ⇒ 4                 ;   with ‘qu’ is at index 4.

```

```emacs-lisp
(match-beginning 2)       ; The beginning of the match
     ⇒ 6                 ;   with ‘ick’ is at index 6.

```

```emacs-lisp
(match-end 1)             ; The end of the match
     ⇒ 6                 ;   with ‘qu’ is at index 6.

(match-end 2)             ; The end of the match
     ⇒ 9                 ;   with ‘ick’ is at index 9.

```

--------------------------------

### Example treesit-thing-settings for C

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/User_002ddefined-Things.html

A sample configuration for the C language defining various 'things' like defun, sexp, comment, and string.

```elisp
((c
  (defun "function_definition")
  (sexp (not "[](),[{}]"))
  (comment "comment")
  (string "raw_string_literal")
  (text (or comment string)))
```

--------------------------------

### Example environment variable output

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/System-Environment.html

A sample display of environment variables.

```text
TERM=xterm
SHELL=/bin/bash
HOME=/home/lewis
```

--------------------------------

### Use object-intervals to list text properties

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Examining-Properties.html

Shows how to use object-intervals to get a copy of the intervals (text properties) of a string or buffer. The example propertizes the string "foo" with a face property and returns a list of intervals, each with start, end, and property list.

```emacs-lisp
(object-intervals (propertize "foo" 'face 'bold))
     ⇒ ((0 3 (face bold)))
```

--------------------------------

### split-string examples

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Creating-Strings.html

Examples demonstrating how to use the split-string function with different separators, trimming, and empty string handling.

```elisp
(split-string "  one  two   ")            ⇒ ("one" "two")
(split-string "one::two:" ":")            ⇒ ("one" "" "two" "")
(split-string "one::two:" ":+")           ⇒ ("one" "two" "")
(split-string "one::two:" ":" t)          ⇒ ("one" "two")
(split-string "one: : two : " ":" t " +") ⇒ ("one" "two")
```

--------------------------------

### Triple semicolon section headings example

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Comment-Tips.html

Comments starting with three or more semicolons should start at the left margin and are used as headings by Outline minor mode. This example shows typical top-level sections in a library.

```emacs-lisp
;;; backquote.el --- implement the ` Lisp construct...
;;; Commentary:...
;;; Code:...
;;; backquote.el ends here

```

--------------------------------

### read-from-string example: reading from start index 0

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Input-Functions.html

Reads starting at the first character (index 0) of the string. The result is the expression and the position after it.

```emacs-lisp
;; Read starting at the first character.
(read-from-string "(list 112)" 0)
     ⇒ ((list 112) . 10)
```

--------------------------------

### Create and update a progress reporter

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Progress.html

This example demonstrates the basic workflow of initializing a progress reporter with make-progress-reporter, updating it within a loop using progress-reporter-update, and finalizing it with progress-reporter-done.

```elisp
(let ((progress-reporter
       (make-progress-reporter "Collecting mana for Emacs..."
                               0  500)))
  (dotimes (k 500)
    (sit-for 0.01)
    (progress-reporter-update progress-reporter k))
  (progress-reporter-done progress-reporter))
```

--------------------------------

### read-from-string example: reading from start index 1

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Input-Functions.html

Reads starting at the second character (index 1) of the string. The result is the symbol 'list' and the position after it.

```emacs-lisp
;; Read starting at the second character.
(read-from-string "(list 112)" 1)
     ⇒ (list . 5)
```

--------------------------------

### Special form count-loop example with omitted from and to

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/A-Sample-Function-Description.html

Example of count-loop where from and to are omitted, so var is bound to nil and the loop exits if var is non-nil at the start of an iteration.

```emacs-lisp
(count-loop (done)
  (if (pending)
      (fixit)
    (setq done t)))

```

--------------------------------

### describe-symbols example output

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Accessing-Documentation.html

Example of calling describe-symbols with the argument "goal" and the resulting *Help* buffer output showing documentation for related symbols.

```lisp
(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option
Semipermanent goal column for vertical motion, as set by ...


```

```text
minibuffer-temporary-goal-position      Variable
not documented


```

```text
set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.


```

```text
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument ARG, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.

(fn ARG)


```

```text
temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was at the start of the current run
of vertical motion commands.

When moving by visual lines via the function `line-move-visual', it is a cons
cell (COL . HSCROLL), where COL is the x-position, in pixels,
divided by the default column width, and HSCROLL is the number of
columns by which window is scrolled from left margin.

When the `track-eol' feature is doing its job, the value is
`most-positive-fixnum'.
---------- Buffer: *Help* ----------


```

--------------------------------

### Lazily initialize connection-local settings with setq-connection-local

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Applying-Connection-Local-Variables.html

This example shows how to define a profile and use setq-connection-local to lazily initialize a variable within a function.

```elisp
(defvar my-app-variable nil)

(connection-local-set-profile-variables
 'my-app-connection-default-profile
 '((my-app-variable . nil)))

(connection-local-set-profiles
 '(:application my-app)
 'my-app-connection-default-profile)
```

```elisp
(defun my-app-get-variable ()
  (with-connection-local-application-variables 'my-app
    (or my-app-variable
        (setq-connection-local my-app-variable
                               do something useful))))
```

--------------------------------

### seq-drop-while examples

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Sequence-Functions.html

Returns elements in order, starting from the first for which predicate returns nil.

```emacs-lisp
(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (-1 -2)
```

```emacs-lisp
(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6])
⇒ [1 4 6]
```

--------------------------------

### Extract buffer substring with point-max

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-Contents.html

Example of extracting a substring using point-max as the start position.

```elisp
(buffer-substring (point-max) 10)
     ⇒ "he contents of buffer foo\n"
```

--------------------------------

### format-spec with custom alist and multiple examples

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Custom-Format-Strings.html

Shows how to build an alist of replacements and use format-spec with custom specification characters. The first example formats system information, the second formats user name and email.

```lisp
(setq my-site-info
      (list (cons ?s system-name)
            (cons ?t (symbol-name system-type))
            (cons ?c system-configuration)
            (cons ?v emacs-version)
            (cons ?e invocation-name)
            (cons ?p (number-to-string (emacs-pid)))
            (cons ?a user-mail-address)
            (cons ?n user-full-name)))
```

```lisp
(format-spec "%e %v (%c)" my-site-info)
     ⇒ "emacs 27.1 (x86_64-pc-linux-gnu)"
```

```lisp
(format-spec "%n <%a>" my-site-info)
     ⇒ "Emacs Developers <emacs-devel@gnu.org>"
```

--------------------------------

### Usage examples for grok/pcase

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/pcase-Macro.html

Example calls to the pcase-based implementation showing identical behavior to the traditional version.

```elisp
(grok/pcase "key:0")   ⇒ "0"
(grok/pcase "key:149") ⇒ "149"
(grok/pcase 'monolith) ⇒ ("149" default)
```

--------------------------------

### read-from-string example: reading with start and end indices

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Input-Functions.html

Reads starting at the seventh character (index 6) and stops at the ninth character (index 8). The result is the number 11 and the position 8.

```emacs-lisp
;; Read starting at the seventh character,
;;   and stopping at the ninth.
(read-from-string "(list 112)" 6 8)
     ⇒ (11 . 8)
```

--------------------------------

### Access third element of values with nth 3

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Eval.html

Uses (nth 3 values) to get the element that was next-to-most-recent before this example, which is 1. This example shows how to access older elements of the values list.

```emacs-lisp
;; This gets the element that was next-to-most-recent
;;   before this example.
(nth 3 values)
     ⇒ 1
```

--------------------------------

### make-backup-file-name example output

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Backup-Names.html

Shows the result of calling make-backup-file-name on "backups.texi" with the customized definition.

```lisp
(make-backup-file-name "backups.texi")
     ⇒ ".backups.texi~"
```

--------------------------------

### String stream example: read from string

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Input-Streams.html

Reads a Lisp expression from a string, starting at the first character.

```emacs-lisp
(read "(When in) the course")
     ⇒ (When in)
```

--------------------------------

### Using a ring as a FIFO queue

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Rings.html

Example demonstrating how to use a ring of size 5 as a first-in-first-out queue by inserting and removing elements.

```elisp
(let ((fifo (make-ring 5)))
  (mapc (lambda (obj) (ring-insert fifo obj))
        '(0 one "two"))
  (list (ring-remove fifo) t
        (ring-remove fifo) t
        (ring-remove fifo)))
     ⇒ (0 t one t "two")
```

--------------------------------

### Create directory for file watch example

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html

Creates a directory to be used as the target for file notification watch examples. The output shows an event indicating the directory was created.

```lisp
(make-directory "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/foo")

```

--------------------------------

### Get hard link count for non-existent file

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Attributes.html

Example of using file-nlinks on a file that does not exist, which returns nil.

```elisp
(file-nlinks "doesnt-exist")
     ⇒ nil
```

--------------------------------

### Get hard link count

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Attributes.html

Example of using file-nlinks to retrieve the number of hard links for an existing file.

```elisp
(file-nlinks "foo")
     ⇒ 2
```

--------------------------------

### Partitioning arguments with multiple-command-partition-arguments

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Shell-Arguments.html

Demonstrates partitioning a list of arguments into sublists to respect an artificially small command line length limit.

```elisp
(let ((system-type 'gnu/linux)
      (command-line-max-length 20)
      (process-environment '("BLAH=blah")))
  (multiple-command-partition-arguments "cmd" '("foo" "bar" "baz")))
     ⇒ (("foo" "bar") ("baz"))
```

--------------------------------

### Access second element of values with nth 1

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Eval.html

Uses (nth 1 values) to get the element that was most recent before the previous example, which is (A 3 t). This example shows that adding a new element shifts all elements back one.

```emacs-lisp
;; That put a new element on,
;;   so all elements move back one.
(nth 1 values)
     ⇒ (A 3 t)
```

--------------------------------

### Helper-describe-bindings

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Help-Functions.html

Pops up a window displaying a help buffer with all key bindings from local and global keymaps. Intended for modes that need to provide help without relinquishing control.

```APIDOC
## Command: Helper-describe-bindings

### Description
This command pops up a window displaying a help buffer containing a listing of all of the key bindings from both the local and global keymaps. It works by calling `describe-bindings`.

### Parameters
None.

### Returns
No return value.
```

--------------------------------

### Truncate string to width examples

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Size-of-Displayed-Text.html

Examples demonstrating the use of truncate-string-to-width to truncate strings and apply padding.

```elisp
(truncate-string-to-width "\tab\t" 12 4)
     ⇒ "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\s)
     ⇒ "    ab  "
```

--------------------------------

### set-window-start example

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Window-Start-and-End.html

Sets the window start to the beginning of line 2 (position 37) using save-excursion and forward-line. Returns 37.

```emacs-lisp
(set-window-start
 (selected-window)
 (save-excursion
   (goto-char 1)
   (forward-line 1)
   (point)))
⇒ 37
```

--------------------------------

### Anchored-highlighter example: highlight 'item' after 'anchor'

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Search_002dbased-Fontification.html

Example of an anchored-highlighter element that highlights occurrences of the word 'item' following an occurrence of the word 'anchor' on the same line, using item-face. pre-form and post-form are nil, so searching for 'item' starts at the end of the 'anchor' match.

```emacs-lisp
;; Highlight occurrences of the word ‘item’ following
;; an occurrence of the word ‘anchor’ (on the same line)
;; in the value of item-face.
("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))
```

--------------------------------

### Using image-load-path-for-library

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Images.html

Example of using image-load-path-for-library to set up the image load path for the mh-e package.

```elisp
(defvar image-load-path) ; shush compiler
(let* ((load-path (image-load-path-for-library
                    "mh-e" "mh-logo.xpm"))
       (image-load-path (cons (car load-path)
                              image-load-path)))
  (mh-tool-bar-folder-buttons-init))
```

--------------------------------

### Usage examples for grok/traditional

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/pcase-Macro.html

Example calls to the traditional implementation showing expected output for valid and invalid inputs.

```elisp
(grok/traditional "key:0")   ⇒ "0"
(grok/traditional "key:149") ⇒ "149"
(grok/traditional 'monolith) ⇒ ("149" default)
```

--------------------------------

### number-to-string examples

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/String-Conversion.html

Shows the output of number-to-string for positive, negative, and floating-point numbers. The returned string starts with a minus sign for negative arguments.

```emacs-lisp
(number-to-string 256)
     ⇒ "256"
```

```emacs-lisp
(number-to-string -23)
     ⇒ "-23"
```

```emacs-lisp
(number-to-string -23.5)
     ⇒ "-23.5"
```

--------------------------------

### Set Advertised Calling Convention for sit-for

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Obsolete-Functions.html

Example of using set-advertised-calling-convention to deprecate an old calling convention for sit-for starting in version 22.1.

```emacs-lisp
(set-advertised-calling-convention
  'sit-for '(seconds &optional nodisp) "22.1")
```

--------------------------------

### Basic let-alist example with setq and let-alist

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html

Shows how to use let-alist to bind dot-prefixed symbols to values in an association list. The body is inspected during macro-expansion, and symbols with a leading dot are bound using assq. The example returns white.

```emacs-lisp
(setq colors '((rose . red) (lily . white) (buttercup . yellow)))
(let-alist colors
  (if (eq .rose 'red)
      .lily))
     ⇒ white
```

--------------------------------

### Check if a symbol is a built-in function with subrp

Source: https://www.gnu.org/software/emacs/manual/html_node/elisp/What-Is-a-Function.html

The subrp function returns t if the object is a built-in function (a Lisp primitive). The first example shows that a symbol is not a subr object, while the second example uses symbol-function to get the actual function and returns t.

```Emacs Lisp
(subrp 'message)            ; message is a symbol,
     ⇒ nil                 ;   not a subr object.

```

```Emacs Lisp
(subrp (symbol-function 'message))
     ⇒ t

```
Tokens:
Raw