Tag Archives: elisp

Sidebar for Emacs Org Mode

It would be nice to have a sidebar when using org mode. The sidebar would display the headlines of an org file. When a headline is selected, the subheadings and text would be displayed in another buffer. 

You can currently do this by using C-c C-x b which is bound to (org-tree-to-indirect-buffer). The command opens a subtree in an indirect buffer which is sort of what I’m looking for, but you have to enter the command each time you land on a new headline.

You can make the process automatic by adding a hook as follows:

(add-hook 'post-command-hook #'org-tree-to-indirect-buffer nil :local)

The solution works, but it’s not quite there.

Searching the internet I found a useful suggestion from the delightfully named My Other Soup’s a Borscht: 

M-x occur then search for the regexp "*+ " (note the space at the end)

This gives more of the functionality I want and has the advantage of being customizable. One problem: I wanted the sidebar to appear on the left hand side.

So I looked a little further and discovered side windows. 

My first thought was so what? I can already do that by splitting windows. The advantage of side windows is that you can set them to stay in position and to fix the buffer they display. No more losing your layout when you hit C-x 1.

If the above seems a little confusing (and it did to me at first) there’s an example of what you can do here in the Emacs Manual 

So I combined the two things I’d learned and came up with the following function:

(defun my-sidebar-occur()
 (interactive)
 (setq fit-window-to-buffer-horizontally t)
        (setq window-resize-pixelwise t)

        (setq
       display-buffer-alist
       `(("\\*Occur\\*" display-buffer-in-side-window
          (side . left) (slot . 0) (window-width . fit-window-to-buffer)
          (preserve-size . (t . nil)) 
          (window-parameters . ((no-delete-other-windows . t)))))))

Here’s a video of the process in action.

One last thing. org-sidebar appears to solve my problem, but at the time of writing it’s still a little buggy. It’s nicely done though and could well become the standard in the future. Until then, I’ll use my workaround.

Common Lisp Loops

I can’t think why you wouldn’t use the Common Lisp loop macro in Emacs. Don’t forget to (require ‘cl-lib)

Simple Loops

;; keywords: to, upto, below, downto, above, by
;; keywords: collect, append, nconc, count, sum, maximize, minimize

(cl-loop
    do (princ 1))
=> 111111... infinite loop

(cl-loop repeat 5
     do (princ 1)
     (princ 2))
=> 1212121212

(cl-loop for i from 1 below 10
     maximize i)
=> 9

(cl-loop for x from 9 downto 1
     collect x)
=> (9 8 7 6 5 4 3 2 1)

(cl-loop for i from 10 above 1 by 2
     collect i)
=> (10 8 6 4 2)

Looping over Sets and Arrays

;; keywords: in, on, across, by
;; Remember in for lists
;; across for vectors

(cl-loop for l in '(1 2 3 4 5)
     do (princ l))
=> 12345

(cl-loop for l in '(1 2 3 4 5) by #'cddr
     collect l)
=> (1 3 5)

(cl-loop for l on '(1 2 3 4 5)
     collect l)
=> ((1 2 3 4 5) (2 3 4 5) (3 4 5) (4 5) (5))

(cl-loop for l on '(1 2 3 4 5) by #'cddr
     collect l)
=> ((1 2 3 4 5) (3 4 5) (5))

;; Remember that a string is an array in lisp, so...
;; Add up the digits in 90125
(cl-loop for d across "90125"
    sum (- d 48))
=> 17

Destructuring

(cl-loop for (a nil) in '((1 2) (2 3) (3 4))
     collect a)
=> (1 2 3)

(cl-loop for (a b) in '((1 2) (2 3) (3 4))
     collect (* a b))
=> (2 6 12)

(cl-loop for (a b) on '(1 2 3 4 5) while b
      collect (+ a b))
=> (3 5 7 9)

(cl-loop for (a b) on '(1 2 3 4 5) by #'cddr while b
     collect (+ a b))
=> (3 7)

Hashtables

(cl-loop for key being the hash-keys of myhashtable
        using (hash-value value)
        do (princ value))

Parallel fors

(cl-loop for i from 1 to 5
     for l in '(a b c d)
     collect (list i l))
=> ((1 a) (2 b) (3 c) (4 d))

(cl-loop for i from 1 to 5
     for j from 2 to 10 by 2
     collect (* i j))
=> (2 8 18 32 50)

Nested fors

(cl-loop for i from 1 to 5
     collect (cl-loop for j from 1 to 5
             collect (* i j)))
=> ((1 2 3 4 5) (2 4 6 8 10) (3 6 9 12 15) (4 8 12 16 20) (5 10 15 20 25))

(cl-loop for i from 1 to 5
     append (cl-loop for j from 1 to 5
             collect (* i j)))
=> (1 2 3 4 5 2 4 6 8 10 3 6 ...)

(cl-loop for i from 1 to 5
     collect (cl-loop for j from 1 to 5
             sum (* i j)))
=> (15 30 45 60 75)

(cl-loop for i from 1 to 5
     sum (cl-loop for j from 1 to 5
             sum (* i j)))
=> 225

Selection

;; if, when, unless

(cl-loop for i from 1 to 20
     unless (cl-evenp i) collect i)
=> (1 3 5 7 9 11 13 15 17 19)

(cl-loop for i from 1 to 20
     when (= (% i 3) 0) collect i into fizz
     when (= (% i 5) 0) collect i into buzz
     finally return (list fizz buzz))
=> ((3 6 9 12 15 18) (5 10 15 20))

(cl-loop for i from 1 to 20
     if (and (= (% i 3) 0) (= (% i 5) 0)) collect i into fizzbuzz
     else if (= (% i 3) 0) collect i into fizz
     else if (= (% i 5) 0) collect i into buzz
     finally return (list fizz buzz fizzbuzz))
=> ((3 6 9 12 18) (5 10 20) (15))

(cl-loop for i from 1 to 10
     if (cl-evenp i)
     collect i into evens
     and sum i into evensum
     else
     collect i into odds
     and sum i into oddsum
     finally return (list evens evensum odds oddsum))
=> ((2 4 6 8 10) 30 (1 3 5 7 9) 25)

Find c from comp where diff is never a member of squares
(cl-loop for c in comp
     if  (cl-loop for p in pri
              for diff = (/ (- c p) 2)
              never (member diff squares))
     collect c)

Then Iteration

(cl-loop for i from 1 to 5
     for square = (* i i)
     collect square)

;; Though you'd be better with
(cl-loop for i from 1 to 5
     collect (* i i))

;; However, this leads to Triangle Numbers
(cl-loop for n from 1 to 10
     for triangle = 1 then (+ triangle n)
     collect triangle)
=> (1 3 6 10 15 21 28 36 45 55)

(cl-loop for x = 0 then y
     for y = 1 then (+ x y)
     while (< y 30)
     collect y)
=> (1 2 4 8 16)

;; Fibonacci Sequence (note the and)
(cl-loop for x = 0 then y
     and y = 1 then (+ x y)
     while (< y 30)
     collect y)
=> (1 1 2 3 5 8 13 21)

Termination

;; while, until, always, never, and thereis

while and until are straightforward

(cl-loop for n from 1
for tri = 1 then (+ tri n)
until (> (divs tri) 500)
finally return tri)

never, thereis and always are shorthand for a combination of when-return

(defun isprime(n)
  (cond
   ((< n 2) nil)
   ((= n 2) t)
   ((cl-evenp n) nil)
   (t
    (cl-loop for i from 3 to (sqrt n) by 2
         never (= (% n i) 0)))))

3 Interactive Functions that work on Regions

1 Start Point, End Point and Contents of a Region

The following function prints the contents of the selected region, together with its start and end points.

1: (defun region-contents (rStart rEnd)
2:   "Prints region contents of region selected, and the start and end positions of that region"
3:   (interactive "r")
4:   (setq rStr (buffer-substring rStart rEnd))
5:   (message "The string of the selected region is %s.  It starts at  %d and ends at %d"  rStr  rStart rEnd)
6: )

2 Iterate through the words in a region

You might want to iterate through the words in a selected region. The following function gives an example of this, it prints out the words in the region in reverse order.

1: (defun reverse-region-message (rStart rEnd)
2:   "Reverses order of words"
3:   (interactive "r")
4:   (setq myStr (buffer-substring rStart rEnd))
5:   (setq myWords (split-string myStr))
6:   (setq reversed (reverse myWords))
7:   (message (mapconcat 'identity reversed " "))
8: )

Note the use of the following functions:

  • split-string: splits the string into a list of words
  • reverse: reverses a list
  • mapconcat: Convert a list into a string

It’s interesting to compare the mapconcat function with the concat function. Note that concat does not accept lists, as you might expect at first glance. You can get round this using the apply function.

(concat "this" "that" "other") => "thisthatother"
(concat '("this" "that" "other")) => error
(apply 'concat '("this" "that"  "other")) => "thisthatother"
(mapconcat 'identity '("this" "that" "other") " ") => "thisthatother"

Here’s the function, rewritten to delete the selected region and to replace it with the words in reverse order.

1: (defun reverse-region (rStart rEnd)
2:   "Reverses order of words"
3:   (interactive "r")
4:   (setq myStr (buffer-substring rStart rEnd))
5:   (delete-region rStart rEnd)
6:   (setq myWords (split-string myStr))
7:   (setq reversed (reverse myWords))
8:   (insert (mapconcat 'identity reversed " "))
9:  )

3 Iterate through the letters in a region

You can spend a lot of time writing code to solve a problem only to find that Emacs Lisp already provides a function to do what you want.
For example, suppose you want to iterate through the letters in a region to convert SEPARATE to S-E-P-A-R-A-T-E. The easiest way is to use the mapconcat function, as seen in the previous section.

(mapconcat 'string "SEPARATE" "-")

Here’s the separator as a function that operates on the selected region.

1: (defun region-seperator (rStart rEnd)
2:   "Reverses order of words"
3:   (interactive "r")
4:   (setq rStr (buffer-substring rStart rEnd))
5:   (delete-region rStart rEnd)
6:   (insert (mapconcat 'string rStr "-"))
7:  )

3.1 string-to-list, mapcar and apply

The function string-to-list converts a string to characters.

(setq rStr (string-to-list "example")) => (101 120 97 109 112 108 101)

use char-to-string to convert a character code to a string

(char-to-string 101) => "e"

Note the use of apply, as discussed previously.

(apply 'string (reverse (string-to-list "example"))) => "elpmaxe"

Note that apply returns a value. If you want a list of characters, use mapcar

(mapcar 'char-to-string (string-to-list "example")) => ("e" "x" "a" "m" "p" "l" "e")

Remember, mapcar returns a list, apply returns a value. Many of the errors you make when beginning come down to confusing the two return types.
Finally, use a lambda function (discussed later) for complex functions in mapcar

(mapcar 'char-to-string (mapcar '(lambda (x) (+ x 1)) (string-to-list "foo")))

4 Enclose a Region

This tutorial has been written using emacs org mode. The code samples are marked up using the tags

#+BEGIN_SRC emacs-lisp -n
and
#+END_SRC

I wrote the following function to make the markup easier. Now I just select the region and run the function. The appropriate tags are placed at the start and end of the region.

1: (defun myMark-elisp-region (rStart rEnd)
2:   "Mark region as Elisp source code for org mode export."
3:   (interactive "r")
4:   (save-excursion
5:     (goto-char rEnd) (insert "\n#+END_SRC\n")
6:     (goto-char rStart) (insert "#+BEGIN_SRC emacs-lisp -n\n"))
7: )

Note the use of the save-excursion function to return the point to where it was before the function was run. Note also the way the above function is laid out. An interesting exercise is to reverse the order of lines 5 and 6. See if you can figure out why the function doesn’t work as you might expect.

5 Find and Replace in a Region: Strip Smart Quotes in a Region

These are smart quotes: “ ” ‘ ’
For editing purposes I sometimes need to replace these with the plain quotes ” and ‘. I only want this to replacement to occur on a specified region of text, not on the whole buffer.
Here’s a function to do this. It narrows to a region, uses save-restriction to remember how things were before the narrowing and then uses two regex searches to find first double quotes and then single quotes, replacing both with plain quotes.

 1: (defun strip-smart-quotes (rStart rEnd)
 2:   "Replace smart quotes with plain quotes in text"
 3:   (interactive "r")
 4:   (save-restriction
 5:   (narrow-to-region rStart rEnd)
 6:   (goto-char (point-min))
 7:   (while (re-search-forward "[“”]" nil t) (replace-match "\"" nil t))
 8:   (goto-char (point-min))
 9:   (while (re-search-forward "[‘’]" nil t) (replace-match "'" nil t))
10: ))

6 Choosing between Operating on a Region or the Whole Buffer

The previous example only stripped smart quotes from the selected region. This function uses the (when (uses-region-p) …) construction to determine whether or not a region is selected. If no region is selected, the whole buffer is operated upon.

 1: (defun region-or-buffer ()
 2:  "Strip smart quotes from region, or whole buffer if region not set"
 3:  (interactive)
 4:  (save-excursion
 5:    (save-restriction
 6:      (when (use-region-p) (narrow-to-region (region-beginning) (region-end)))
 7:      (goto-char (point-min))
 8:      (while (re-search-forward "[“”]" nil t) (replace-match "\"" nil t))
 9:      (goto-char (point-min))
10:      (while (re-search-forward "[‘’]" nil t) (replace-match "'" nil t))
11: )))

Next: Yodaizer – Manipulating Strings Example

2 Functions in Elisp

Here’s how to define a simple LISP function

1: (defun pi ()
2:   "A sample non-interactive function"
3:   3.1415
4: )

The above is a non-interactive function that simply returns 3.1415. Evaluate it (C-x C-e, remember?) and you will see the word pi appear in the echo area. Try M-x pi, though, and Emacs won’t find the function. If you want to be able to call a function using M-x, you have to make it interactive, as follows.

1: (defun print-pi()
2:     "Insert an approximation to pi"
3:     (interactive)
4:     (insert "3.1415")
5: )

So why would you want a non-interactive function? Perhaps because you want it to be called from another function, as follows:

1: (defun circumference-of-circle()
2:     (interactive)
3:     (message "The circumference of a circle diameter 3 is %f" (* pi 3))
4: )

Before evaluating the above function, make sure that you have evaluated the non-interactive function pi.

There are lots of different types of interactive functions. The next interactive function is more useful in that it prompts for the diameter to be input (the n at the start of “nInput diameter of circle:” is what tells Emacs to prompt for a number)

1: (defun circumference-of-circle(diameter)
2:     "Calculate the circumference of a circle given the diameter"
3:     (interactive "nInput diameter of circle:")
4:     (message "The circumference of a circle diameter %d is %f" diameter (* 3.1415 diameter))
5: )

Here’s the same function but this time set up to receive the parameter from the universal argument. That is to say, in the form C-u 4 M-x circumference-of-circle.

1: (defun circumference-of-circle(diameter)
2: (interactive "p")
3: (message "The circumference of a circle diameter %d is %f" diameter (* 3.1415 diameter))
4: )

Here’s an example of a function that reads strings and tests your knowledge of capital cities.

1: (defun capital-of-france(answer)
2:     "Simple quiz example."
3:     (interactive "sWhat's the Capital of France?")
4:     (if (string= answer "paris") (message "Correct!") (message "Wrong!"))
5: )

Argument codes for interactive functions can be found here http://www.gnu.org/software/emacs/manual/html_node/elisp/Interactive-Codes.html#Interactive-Codes

Next: Interactive Functions that work on Regions

1 Beginning Emacs Lisp

LISP is derived from the term LISt Processing.

A list in LISP looks like this:

(Knife Fork Spoon)

or like these two examples
(set-background-color "yellow")    <- C-x C-e
(set-background-color "white")    <- C-x C-e

If the first item in the list is a function you can evaluate the list by placing the cursor just after the bracket at the end of the list and pressing C-x C-e. Try it with the two lists above. Copy them into Emacs and then C-x C-e where indicated to turn the Emacs background yellow and then to set it white again.

If you try to evaluate the (Knife Fork Spoon) list you’ll get an error telling you that Knife is a void function.

Try evaluating the following lists in Emacs by typing C-x C-e after the closing bracket:
(linum-mode)
(message "This is the echo area")
(* 2 3)
(+ 4 5)

The last three will output their results in the echo area, the area at the bottom of Emacs.

You can also evaluate a function by typing M-x (function name). So M-x visual-line-mode will turn word wrap on and off.

Emacs supports TAB completion, so typing M-x visu and pressing TAB is enough to fill in the function name.

You set a variable as follows:

(set 'name 'John) C-x C-e to set the variable

name C-x C-e to see the contents of the variable “name”

If you press C-x C-e after (name)you’ll get an error. Remember, name is a variable, (name) is a function, and you haven’t defined a function called name.
It’s a nuisance typing in ‘ all the time, so the following is often used
(setq animal 'cat)

Evaluate the above and then evaluate animal …

C-u C-x C-e will insert any output directly in the text area, rather than in the echo area.

Here is a list of cheeses called cheese:
(setq cheese '(Stilton Wensleydale Cheddar Cheshire))

Evaluate the list.

The first item in a list is called the car, the remaining items are called the cdr (pronounced could-er) The Emacs Lisp tutorial will tell you why. Evaluate the following:

(car cheese)
(cdr cheese)

… and there you are

Next: Functions in Elisp