Intro to Emacs lisp

A basic overview of elisp to start crafting plugins and customizing Emacs. For more details see docs

Comments

Semicolon ;; defines comment enywhere in a line

;; Some text as comment

Arithmetic

(+ 3 2 1) ;; 6
(- 8 5) ;; 3
(* 3 4) ;; 12
(/ 1 2.0) ;; 0.5
(/ 1 2) ;; 0
(% 12 5) ;; 2
(expt 3 4) ;; 81

Type conversions

(float 6) ;; 6.0
(truncate 6.3) ;; 6
(floor 6.3) ;; 6
(ceiling 6.3) ;; 7
(round 6.3) ;; 6
(string-to-number "2") ;; 2
(number-to-string 2) ;; "2"
(char-to-string #xe0b0) ;; ""

Variables

Global

(setq x 1)
(setq a 3 b 2 c 7)

Local

(let (a b)
 (setq a 3)
 (setq b 4)
 (+ a b))

Buffer-local

 (setq-local x "some value")

Constants

(defconst a "some value"
  "Some documentation.")

Functions

(defun foo-bar (a b c)
  "Some doc text A B C."
  (concat a b c))

Lambdas

(lambda (a b c)
  "Some doc text A B C."
  (concat a b c))

Control structures

Sequencing

Evaluates all of the forms, in textual order, returning the result of the final form.

 (progn a b c ...)

Example:

(progn (print "The first form")
       (print "The second form")
       (print "The third form"))
    -| "The first form"
    -| "The second form"
    -| "The third form"
  ⇒ "The third form"

Conditionals

If condition has the value nil, and no else-forms are given, if returns nil.

(if nil
    (message "true")
  (message "false"))
  ⇒ "false""

Variant of if where there are no else-forms, and possibly several then-forms.

(when condition a b c)

Same as can be represented using if expression

(if condition (progn a b c) nil)

Variant of if where there is no then-form

(unless condition a b c)

Same as can be represented using if expression

(if condition nil (progn a b c))

Conditional selects matching expressions

(setq a 5)
(cond ((eq a 'hack) 'foo)
       (t "default"))
  ⇒ "default"

Combining conditions

not special form returns t if condition is nil, and nil otherwise.

(not nil)
  ⇒ t

and special form tests whether all the conditions are true.

(and arg1 arg2 arg3)
  ⇒ t

or special form tests whether at least one of the conditions is true.

(or arg1 arg2 arg3)
  ⇒ t

Pattern-Matching

(pcase (get-return-code x)
       ;; string
       ((and (pred stringp) msg)
        (message "%s" msg))
       ;; symbol
       ('success       (message "Done!"))
       ('would-block   (message "Sorry, can't do it now"))
       ('read-only     (message "The shmliblick is read-only"))
       ('access-denied (message "You do not have the needed rights"))
       ;; default
       (code           (message "Unknown return code %S" code)))

Iteration

while first evaluates condition. If the result is non-nil, it evaluates forms in textual order then it reevaluates condition, and if the result is non-nil, it evaluates forms again.

(setq num 0)
  ⇒ 0
(while (< num 4)
  (princ (format "Iteration %d." num))
  (setq num (1+ num)))
      -| Iteration 0.
      -| Iteration 1.
      -| Iteration 2.
      -| Iteration 3.
  ⇒ nil

Repeat-until loop, which will execute something on each iteration and then do the end-test

(while (progn
        (forward-line 1)
        (not (looking-at "^$")))
    (do-something))

Executes body once for each element of list, binding the variable var locally to hold the current element.

(dolist (elt list)
            (setq value (cons elt value)))

Executes body once for each integer from 0 (inclusive) to count (exclusive), binding the variable var to the integer for the current iteration.

(dotimes (i 100)
          (insert (format "i: %s" i)))