elisp

General

Apparently, there is no built-in function composition.
Comments: Starts with ;
progn: evaluate each statement in body sequentially and return value from last statement.
- Kind of like comma operator in C.
- https://www.gnu.org/software/emacs/manual/html_node/eintr/progn.html
(1- x) is same as (- x 1). Former form is considered better style.
Invoke shell commands: (shell-command "cmd")
Search text with regex: (re-search-forward "^* The specific heading")
Write text to current buffer: (insert "text")
(file-name-nondirectory arg): get filename and extension
- Remove everything after last slash
(name) is a function (as in name() in C), but name is a value
let is normal let, let* is like letrec
elisp has vectors
- https://www.gnu.org/software/emacs/manual/html_node/elisp/Vectors.html
(signal ..) and (error ..): ways to indicate errors programmatically
- https://www.gnu.org/software/emacs/manual/html_node/elisp/Signaling-Errors.html

Type conversions

Check value of a type:

(integerp v): return t if v is an integer
(sequencep '(1 2)) ;; t: check if value is a sequence
- (sequencep (make-hash-table)) ;; nil
(hash-table-p v) : hash tables

Type conversions:

String to number:
- (+ 2 (string-to-number "3")) ;; 5
- https://www.gnu.org/software/emacs/manual/html_node/elisp/String-Conversion.html

funcall and apply

Quite similar.
funcall f args: calls function f with args as arguments
apply takes args as a list, but they are passed to f as separate args
https://www.gnu.org/software/emacs/manual/html_node/elisp/Calling-Functions.html

(funcall '+ 2 3)
; 5

(apply '+ '(2 3))
; 5

Emacs terminology

Printed representation and read syntax
- https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Printed-Representation

Point

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

org narrow => point is restricted to accessible region
Excursion: Temporarily change point position
- Eg: with (save-excursion)

Associated functions:

(point): current value of point in buffer
(point-min) / (point-max): minimum/maximum accessible value of point in buffer

Kill ring

Kill: cut
Yank: paste
Kill ring holds a list of recently killed text
- This list is (kill-ring) ??
(kill-ring-max) maximum size of kill ring

See:

Single characters

Preceded by a ? for syntax.

; ?a is like 'a' in C
?a
97

See:

Lists

mapcar: map function over a sequence like lists
seq-uniq: Get unique elements in a list
- (seq-uniq '(1 2 2 2 2)) ;; (1 2)

nth element of a list

(nth idx lst): get n-th element of lst
(nthcdr n lst): Like calling cdr n times on lst

(nth 0 '(0 1 2 3 4 5))
0

(nth 3 '(0 1 2 3 4 5))
3

(nthcdr 3 '(0 1 2 3 4 5))
(3 4 5)

(nthcdr 10 '(0 1 2 3 4 5))
nil

https://www.gnu.org/software/emacs/manual/html_node/eintr/nth.html

`car` and `cdr`

Head and tail functions for lists.
Name is due to historical reasons: IBM 704.
- https://www.gnu.org/software/emacs/manual/html_node/eintr/Strange-Names.html
  - car: contents of address part of register
  - cdr (pronounced 'could-er'): contents of decrement part of register

–

car: get head element of a list
cdr: get tail of a list

(car '("a" "b" "c"))
; "a"

(car '(0 1 2))
; 0

(car '())
; nil

(cdr '("a" "b" "c"))
; ("b" "c")

(cdr '(0 1 2))
; (1 2)

(cdr '())
; nil

https://www.gnu.org/software/emacs/manual/html_node/eintr/car-_0026-cdr.html

Strings

Find length of a string: string-width
- Note: '\n' is not counted in this function
- (string-width "hi") ; 2
- (string-width "\n") ; 0
Make a string from a char: (string ?a) ; "a"
Repeat a character n times (make-string <count> <char>)
- (make-string 2 ?a) ; "aa"
String concatenations: (concat str1 str2)
Concatenate list of strings: string-join
- (string-join '("hi " "how are" " you?")) ;; "hi how are you?"
Looks like numbers are integers by default in elisp.
- (/ 3 2) is 1
- (/ (float 3) 2) is 1.5
- (/ 3 2.0) is 1.5

See:

Uppercase and lowercase

Convert string/char to lowercase: downcase
Convert string/char to uppercase: upcase

If argument is char, return value is int for both downcase and upcase.

Splitting a string

split-string

Note: Second argument is a regex

(split-string "1.2.3" "\\.")
; ("1" "2" "3")

(split-string "a-b c" "-")
; ("a" "b c")

https://stackoverflow.com/questions/6236196/elisp-split-string-function-to-split-a-string-by-character

Functions

defun foo () (5)
(foo)  ;5

(defun fact (a) (cond
    ((= a 0) 1)
    (t (* a
          (fact (- a 1))
       )
    )))

(fact 5)  ; 120

(defun gcd (a b)
  (cond
    ((< a b) (gcd b a))
    ((= (% a b) 0) b)
    (t (gcd b (% a b)))
  ))

(gcd 1000 10)  ; 10

(atom 1)  ; t
(atom (list 1 2))  ; nil

;; NOT WORKING
; find sqrt of a.
; x is starting value
; e is permissible error
(defun sqrt_nr (a x e)
  (cond
    ((< (abs (- (* x x) a)) e) x)
    (t (sqrt_nr a (* (/ 1 2) (+ x (/ a x))) e))
  ))

Plist (Property list)

Paired list of elements
Effectively just list which can be treated specially
https://www.gnu.org/software/emacs/manual/html_node/elisp/Plists-and-Alists.html

Functions:

plist-put: add new key-element pair
plist-get: add element given a key
plist-member: check membership for a key
https://www.gnu.org/software/emacs/manual/html_node/elisp/Plist-Access.html

—

In:

(pine cones numbers (1 2 3) color "blue")

it's like:

(pine,cones)
(numbers, (1 2 3))
(color, "blue")

—

Examples:

(setq-local myplist '("pine" "cones" "numbers" (1 2 3) "color" "blue"))
; ("pine" "cones" "numbers" (1 2 3) "color" "blue")

(setq-local myplist (plist-put myplist "vive" "la"))
; ("pine" "cones" "numbers" (1 2 3) "color" "blue" "vive" "la")

(setq-local l myplist)
; ("pine" "cones" "numbers" (1 2 3) "color" "blue" "vive" "la")

(plist-get '(foo 4) 'foo)
; 4

Alist (Association list)

Similar to plists
Syntax: (key . value)
https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
Just a fancy list?? Allows multiple entries with same 'key'

(setq-local myalist
  '(("name" . "joe")
   ("age" . 50)
   ("planet" . "earth")))
; (("name" . "joe") ("age" . 50) ("planet" . "earth"))

Functions:

(assq key alist): return element of alist whose car is key

—

Folding over an alist (courtesy of chatgpt):

(require 'cl-lib)

(setq-local my-alist '((a . 1) (b . 2) (c . 3)))
((a . 1) (b . 2) (c . 3))

(cl-reduce (lambda (acc pair)
            (+ acc (cdr pair)))  ;; Accumulate the values (cdr of each pair)
           my-alist
           :initial-value 0)
; 6

Hash table

Kind of like a faster alist
- ie, like python dictionary
https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Hash-Tables

Creating hash tables

make-hash-table
- :test argument specifies how hashing would be done
- Default :test method is eql
Can also be made using read syntax
- #s(hash-table size 50 data (key1 val1) (key2 (val2)

#s(hash-table data (key1 val1 key2 300))
; #s(hash-table size 65 test eql rehash-size 1.5 rehash-threshold 0.8125 data (key1 val1 key2 300 ...))

#s(hash-table (key1 val1 key2 300))
; #s(hash-table size 65 test eql rehash-size 1.5 rehash-threshold 0.8125 data ( ...))

#s(key1 val1 key2 300)
; #s(key1 val1 key2 300)

Example usage:

(make-hash-table)
; #s(hash-table size 65 test eql rehash-size 1.5 rehash-threshold 0.8125 data ( ...))

#s(hash-table size 30 data (key1 val1 key2 300))
; #s(hash-table size 30 test eql rehash-size 1.5 rehash-threshold 0.8125 data (key1 val1 key2 300 ...))

(setq-local myht #s(hash-table size 30 data ("a" 10 "b" 20)))
; #s(hash-table size 30 test eql rehash-size 1.5 rehash-threshold 0.8125 data ("a" 10 "b" 20 ...))

Functions

gethash key table
puthash key table
remhash key table
clrhash table: empty the hash table
maphash function table: in-place map over hashtable
hash-table-keys table: get all keys of hashtable

https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Hash-Access

(hash-table-keys #s(hash-table data ("a" 1 "b" 2)))
; ("a" "b")

; No unique keys ???
(hash-table-keys #s(hash-table data ("a" 1 "b" 2 "a" 3)))
; ("a" "b" "a")

(hash-table-p #s("a" 1))
; nil

(hash-table-p #s(hash-table "a" 1))
; t

(hash-table-p (make-hash-table))
; t

Text properties in strings

https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Text-Props-and-Strings

For example, the following means:

#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))

Part of string	Slice	Property
"foo"	str[0: 3]	bold
" "	str[3: 4]	NA
"bar"	str[4: 7]	italic

Conditionals

if statement: (if (condition) (then-clause) (else-clause))
- https://www.gnu.org/software/emacs/manual/html_node/eintr/else.html
when: like if without else
unless: like if with only else

Equality check

eq: equal only both args are the same object
eql: For non-atomic types, looks inside for eq-style equality ??
- ie, not too strict at top level, but is like eq for looking at internal structure ??
equal

See:

`eq`

(setq-local a 3)
(setq-local b 3)

(eq 'a 'a)
; t

(eq 'a 'b)
; nil

(eq 'a '3)
; nil

`equal`

(eq "2" "2")
; nil

(equal "2" "2")
; t

(equal 2 2)
; nil

Built-in functions

Math functions:

abs: absolute value
sqrt: square root

Advising functions

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

Change the default behaviour of an existing function ('by giving some advice') rather than redefining the whole function.

Codes for interactive prompts

First character of argument of (interactive).

https://www.gnu.org/software/emacs/manual/html_node/elisp/Interactive-Codes.html

(interactive): function can be called with M-x as well
- What does (interactive "p") mean?: See this

Read input from user interactively:

Function	Description
`read-char`	Reads a character. Returns int
`read-int`	Reads int
`read-string`	Reads string
`read-key`
`read-char-choice`
`yes-or-no-p`	Ask a yes/no answer
`y-or-n-p`	Ask a y/n answer

`dotimes` and `dolist`

dotimes (counter limit result) body

counter starts from 0.
body is the loop body
Resultant value is result.
- If no value for result is given, nil is returned.

dolist is looping on a list.

(dolist list-name
  (operation list-elem)

is like the following python:

for list_elem in list_name:
  operation(list_elem)

Append a string to a file

Use write-region.

(write-region <string> nil <filename> 'append)

https://stackoverflow.com/questions/17376706/in-emacs-lisp-how-can-i-append-a-string-to-a-file-that-i-dont-like-to-open

Run an external command and get its output

shell-command-to-string: run a command and gets its output as a string
shell-command: just run the command. Don't use its output
async-shell-command

(message (shell-command-to-string "/bin/echo -n hello"))
; Output: hello

True and false

There is no boolean type in elisp
- http://xahlee.info/emacs/emacs/elisp_boolean.html
Following can stand in:
- True: t
- False: nil or empty list

(and t nil)
; nil

(or t nil)
; t

(if '() "T" "F")
; "F"

(if () "T" "F")
; "F"

Managing parenthesis

Find unbalanced parenthesis (vanilla emacs): M-x check-parens
Third party packages: paredit, lispy
- http://danmidwood.com/content/2014/11/21/animated-paredit.html

See:

https://www.gnu.org/software/emacs/manual/html_node/emacs/Parentheses.html
Stuff available in vanilla emacs itself: http://web.archive.org/web/20160712150651/https://cl-cookbook.sourceforge.net/emacs-ide.html
https://www.emacswiki.org/emacs/NavigatingParentheses

Handling time and date

(current-time)
; (26423 47784 405993 901000)

(decode-time)
; (42 48 2 16 11 2024 6 nil 19800)

format-time-string: formats current datetime if no datetime argument is given

(format-time-string "%Y-%m-%d")
"2024-11-16"

(format-time-string "%Y-%m-%d" (decode-time))
"1970-01-07"

(decode-time)
; (59 6 3 16 11 2024 6 nil 19800)

(encode-time (decode-time))
; (26423 48961)

(format-time-string "%Y-%m-%d" (encode-time (decode-time)))
; "2024-11-16"

See:

car and cdr

car: head of list
- car of empty list gives nil
cdr: tail of list

(car '(0 1 2 3))
; 0

(car nil)
; nil

(cdr '(0 1 2 3))
; (1 2 3)

(cdr (cdr '(0 1 2 3)))
; (2 3)

nthcdr repeats cdr function n times

nth element in a list/tuple

Indexing starts from zero.

(nth 2 '(1 2 3))
; 3

`let` expressions

See: https://www.gnu.org/software/emacs/manual/html_node/eintr/let.html

`let`

(let 
  ((x 1)
   (y 2))
  (message (format "x=%d, y=%d" x y)))
; x=1, y=2

Each binding should be defined independent of the other.

Otherwise it will give error. For example:

(let
  ((x 1)
   (y (+ x 2)))
  (message (format "x=%d, y=%d" x y)))

; Debugger entered--Lisp error: (void-variable x)
; (+ x 2)
; (let ((x 1) (y (+ x 2))) (message (format "x=%d, y=%d" x y)))
; eval((let ((x 1) (y (+ x 2))) (message (format "x=%d, y=%d" x y))) t)
; eval-expression((let ((x 1) (y (+ x 2))) (message (format "x=%d, y=%d" x y))) nil nil 127)
; funcall-interactively(eval-expression (let ((x 1) (y (+ x 2))) (message (format "x=%d, y=%d" x y))) nil nil 127)
; call-interactively(eval-expression nil nil)
; command-execute(eval-expression)

`let*`

Unlike let, bindings can be defined dependent on other values mentioned in the same let* expression.

(let*
  ((x 1)
   (y (+ x 2)))
  (message (format "x=%d, y=%d" x y)))
; x=1, y=3

https://emacs.stackexchange.com/questions/42449/what-does-let-let-asterisk-mean-in-elisp

Copy whole buffer

These functions update the kill ring. To just delete text without disturbing kill ring use functions that start with kill-.

Copy without deleting: (copy-region-as-kill (point-min) (point-max))
Copy with deleting: (kill-region (point-min) (point-max))

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

Writing to file

https://www.gnu.org/software/emacs/manual/html_node/elisp/Writing-to-Files.html

Lisp interaction mode

Handy to try out lisp snippets. Maybe in *scratch* buffer.

Enable mode: M-x lisp-interaction-mode
C-j: Evaluate last line

https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Interaction.html

References:

Common lisp

May not be true for elisp.

Complex numbers??
- #c(2 3) means 2+3i
- Apparently not available in elisp

elisp libraries

dash: like a bettern cl.el ??
- https://github.com/magnars/dash.el
s.el: string manipulation
- https://github.com/magnars/s.el

File system management

(directory-files "/foo" nil directory-files-no-dot-files-regexp)

https://www.gnu.org/software/emacs/manual/html_node/elisp/Contents-of-Directories.html

References

An elisp style guide
Emacs common lisp emulation: https://www.gnu.org/software/emacs/manual/html_node/cl/
https://www.gnu.org/software/emacs/manual/pdf/eintr.pdf

General

Type conversions

funcall and apply

Emacs terminology

Point

Kill ring

Single characters

Lists

nth element of a list

car and cdr

Strings

Uppercase and lowercase

Splitting a string

Functions

Plist (Property list)

Alist (Association list)

Hash table

Creating hash tables

Functions

Text properties in strings

Conditionals

Equality check

eq

equal

Built-in functions

Advising functions

Codes for interactive prompts

Read input from user interactively:

dotimes and dolist

Append a string to a file

Run an external command and get its output

True and false

Managing parenthesis

Handling time and date

car and cdr

nth element in a list/tuple

let expressions

let

let*

Copy whole buffer

Writing to file

Lisp interaction mode

Common lisp

elisp libraries

File system management

References

`car` and `cdr`

`eq`

`equal`

`dotimes` and `dolist`

`let` expressions

`let`

`let*`