Elvince: B. Guery, org maintainer

2017-05-18T20:48:26Z

B. Guery, org maintainer

166.200.168.217: Commented the intended lines of hello-to-bonjour ()

2014-10-28T04:49:38Z

Commented the intended lines of hello-to-bonjour ()

Holocronweaver: correct spelling error

2014-04-17T02:27:40Z

correct spelling error

Elvince: cats

2014-04-16T10:54:25Z

cats

Elvince: elisp in 15 min

2014-04-16T10:53:42Z

elisp in 15 min

New page

This gives an introduction to Emacs Lisp in 15 minutes (v0.2d)

Author: Bastien / @bzg2 / http://bzg.fr

First make sure you read this text by Peter Norvig:
http://norvig.com/21-days.html

Going through this tutorial won't damage your computer unless
you get so angry that you throw it on the floor. In that case,
I hereby decline any responsability. Have fun!

=== Write and execute lisp ===

Fire up Emacs.

Hit the '''q''' key to dismiss the welcome message.

Now look at the gray line at the bottom of the window:

"*scratch*" is the name of the editing space you are now in.
This editing space is called a "buffer".

The scratch buffer is the default buffer when opening Emacs.
You are never editing files: you are editing buffers that you
can save to a file.

"Lisp interaction" refers to a set of commands available here.

Emacs has a built-in set of commands available in every buffer,
and several subsets of commands available when you activate a
specific mode. Here we use the `lisp-interaction-mode', which
comes with commands to evaluate and navigate within Elisp code.

Semi-colons start comments anywhere on a line.

Elisp programs are made of symbolic expressions ("sexps"):

<source lang=lisp>
(+ 2 2) ;; this is a comment
</source>

This symbolic expression reads as "Add 2 to 2".

Sexps are enclosed into parentheses, possibly nested:

<source lang=lisp>
(+ 2 (+ 1 1))
</source>

A symbolic expression contains atoms or other symbolic
expressions. In the above examples, 1 and 2 are atoms,
(+ 2 (+ 1 1)) and (+ 1 1) are symbolic expressions.

From `lisp-interaction-mode' you can evaluate sexps.
Put the cursor right after the closing parenthesis then
hold down the control and hit the j keys ("C-j" for short).

<source lang=lisp>
(+ 3 (+ 1 2))
</source>
{{Keys | C-j }} => 6

{{Keys | C-j }} inserts the result of the evaluation in the buffer.

{{Keys | C-xC-e }} displays the same result in Emacs bottom line,
called the "minibuffer". We will generally use `C-xC-e',
as we don't want to clutter the buffer with useless text.

=== Variables ===

'''setq''' stores a value into a variable:

<source lang=lisp>
(setq my-name "Bastien")
</source>
{{Keys | C-xC-e }} => "Bastien" (displayed in the mini-buffer)

=== Insert text ===

'''insert''' will insert "Hello!" where the cursor is:

<source lang=lisp>
(insert "Hello!")
</source>
{{Keys | C-xC-e }} => "Hello!"

We used '''insert''' with only one argument "Hello!", but
we can pass more arguments -- here we use two:

<source lang=lisp>
(insert "Hello" " world!")
</source>
{{Keys | C-xC-e }} => "Hello world!"

You can use variables instead of strings:

<source lang=lisp>
(insert "Hello, I am " my-name)
</source>
{{Keys | C-xC-e }} => "Hello, I am Bastien"

=== Functions ===

You can combine sexps into functions:

<source lang=lisp>
(defun hello () (insert "Hello, I am " my-name))
</source>
{{Keys | C-xC-e }} => hello

You can evaluate functions:

<source lang=lisp>
(hello)
</source>
{{Keys | C-xC-e }} => Hello, I am Bastien

The empty parentheses in the function's definition means that
it does not accept arguments. But always using `my-name' is
boring, let's tell the function to accept one argument (here
the argument is called "name"):

<source lang=lisp>
(defun hello (name) (insert "Hello " name))
</source>
{{Keys | C-xC-e }} => hello

Now let's call the function with the string "you" as the value
for its unique argument:

<source lang=lisp>
(hello "you")
</source>
{{Keys | C-xC-e }} => "Hello you"

Yeah!

Take a breath.

=== Switch buffers ===

Now switch to a new buffer named "*test*" in another window:

<source lang=lisp>
(switch-to-buffer-other-window "*test*")
</source>
{{Keys | C-xC-e }}
=> [screen has two windows and cursor is in the *test* buffer]

Mouse over the top window and left-click to go back. Or you can
use `C-xo' (i.e. hold down control-x and hit o) to go to the other
window interactively.

=== Expression blocks ===

You can combine several sexps with '''progn''':

<source lang=lisp>
(progn
(switch-to-buffer-other-window "*test*")
(hello "you"))
</source>

{{Keys | C-xC-e }}
=> [The screen has two windows and cursor is in the *test* buffer]

Now if you don't mind, I'll stop asking you to hit `C-xC-e': do it
for every sexp that follows.

Always go back to the *scratch* buffer with the mouse or `C-xo'.

It's often useful to erase the buffer:

<source lang=lisp>
(progn
(switch-to-buffer-other-window "*test*")
(erase-buffer)
(hello "there"))
</source>

Or to go back to the other window:

<source lang=lisp>
(progn
(switch-to-buffer-other-window "*test*")
(erase-buffer)
(hello "you")
(other-window 1))
</source>

=== Local variables ===

You can bind a value to a local variable with '''let''':

<source lang=lisp>
(let ((local-name "you"))
(switch-to-buffer-other-window "*test*")
(erase-buffer)
(hello local-name)
(other-window 1))
</source>

No need to use '''progn''' in that case, since '''let''' also combines
several sexps.

=== Strings handling ===

Let's format a string:

<source lang=lisp>
(format "Hello %s!\n" "visitor")
</source>

%s is a place-holder for a string, replaced by "visitor".
\n is the newline character.

Let's refine our function by using format:

<source lang=lisp>
(defun hello (name)
(insert (format "Hello %s!\n" name)))

(hello "you")
</source>

Let's create another function which uses '''let''':

<source lang=lisp>
(defun greeting (name)
(let ((your-name "Bastien"))
(insert (format "Hello %s!\n\nI am %s."
name ; the argument of the function
your-name ; the let-bound variable "Bastien"
))))
</source>

And evaluate it:

<source lang=lisp>
(greeting "you")
</source>

=== Interactive functions ===

Some function are interactive:

<source lang=lisp>
(read-from-minibuffer "Enter your name: ")
</source>

Evaluating this function returns what you entered at the prompt.

Let's make our '''greeting''' function prompt for your name:

<source lang=lisp>
(defun greeting (from-name)
(let ((your-name (read-from-minibuffer "Enter your name: ")))
(insert (format "Hello!\n\nI am %s and you are %s."
from-name ; the argument of the function
your-name ; the let-bound var, entered at prompt
))))

(greeting "Bastien")
</source>

Let's complete it by displaying the results in the other window:

<source lang=lisp>
(defun greeting (from-name)
(let ((your-name (read-from-minibuffer "Enter your name: ")))
(switch-to-buffer-other-window "*test*")
(erase-buffer)
(insert (format "Hello %s!\n\nI am %s." your-name from-name))
(other-window 1)))
</source>

Now test it:
(greeting "Bastien")

Take a breath.

=== Lists ===

Let's store a list of names:

<source lang=lisp>
(setq list-of-names '("Sarah" "Chloe" "Mathilde"))
</source>

Get the first element of this list with '''car''':

<source lang=lisp>
(car list-of-names)
</source>

Get a list of all but the first element with '''cdr''':

<source lang=lisp>
(cdr list-of-names)
</source>

Add an element to the beginning of a list with '''push''':

<source lang=lisp>
(push "Stephanie" list-of-names)
</source>

NOTE: '''car''' and '''cdr''' don't modify the list, but '''push''' does.
This is an important difference: some functions don't have any
side-effects (like '''car''') while others have (like '''push''').

Let's call '''hello''' for each element in `list-of-names':

<source lang=lisp>
(mapcar 'hello list-of-names)
</source>

Refine '''greeting''' to say hello to everyone in `list-of-names':

<source lang=lisp>
(defun greeting ()
(switch-to-buffer-other-window "*test*")
(erase-buffer)
(mapcar 'hello list-of-names)
(other-window 1))

(greeting)
</source>

Remember the '''hello''' function we defined above? It takes one
argument, a name. '''mapcar''' calls '''hello''', successively using each
element of `list-of-names' as the argument for '''hello'''.

Now let's arrange a bit what we have in the displayed buffer:

<source lang=lisp>
(defun replace-hello-by-bonjour ()
(switch-to-buffer-other-window "*test*")
(goto-char (point-min))
(while (search-forward "Hello")
(replace-match "Bonjour"))
(other-window 1))
</source>

=== Moving around ===

(goto-char (point-min)) goes to the beginning of the buffer.
(search-forward "Hello") searches for the string "Hello".
(while x y) evaluates the y sexp(s) while x returns something.
If x returns '''nil''' (nothing), we exit the while loop.

<source lang=lisp>
(replace-hello-by-bonjour)
</source>

You should see all occurrences of "Hello" in the *test* buffer
replaced by "Bonjour".

You should also get an error: "Search failed: Hello".

To avoid this error, you need to tell `search-forward' whether it
should stop searching at some point in the buffer, and whether it
should silently fail when nothing is found:

(search-forward "Hello" nil t) does the trick:

The '''nil''' argument says: the search is not bound to a position.
The '''t''' argument says: silently fail when nothing is found.

We use this sexp in the function below, which doesn't throw an error:

<source lang=lisp>
(defun hello-to-bonjour ()
(switch-to-buffer-other-window "*test*")
(erase-buffer)
Say hello to names in `list-of-names'
(mapcar 'hello list-of-names)
(goto-char (point-min))
Replace "Hello" by "Bonjour"
(while (search-forward "Hello" nil t)
(replace-match "Bonjour"))
(other-window 1))

(hello-to-bonjour)
</source>

=== Change fonts ===

Let's colorize the names:

<source lang=lisp>
(defun boldify-names ()
(switch-to-buffer-other-window "*test*")
(goto-char (point-min))
(while (re-search-forward "Bonjour \\(.+\\)!" nil t)
(add-text-properties (match-beginning 1)
(match-end 1)
(list 'face 'bold)))
(other-window 1))
</source>

=== Searching regexps ===

This functions introduces `re-search-forward': instead of
searching for the string "Bonjour", you search for a pattern,
using a "regular expression" (abbreviated in the prefix "re-").

The regular expression is "Bonjour \\(.+\\)!" and it reads:
the string "Bonjour ", and
a group of (this is the \\( ... \\) construct)
any character (this is the .)
possibly repeated (this is the +)
and the "!" string.

Ready? Test it!

<source lang=lisp>
(boldify-names)
</source>

`add-text-properties' adds... text properties, like a face.

OK, we are done. Happy hacking!

=== How to get documentation ===

If you want to know more about a variable or a function:

C-h v a-variable RET
C-h f a-function RET

To read the Emacs Lisp manual with Emacs:

C-h i m elisp RET

To read an online introduction to Emacs Lisp:
https://www.gnu.org/software/emacs/manual/html_node/eintr/index.html

Thanks to these people for their feedback and suggestions:
* Wes Hardaker
* notbob
* Kevin Montuori
* Arne Babenhauserheide
* Alan Schmitt
* LinXitoW
* Aaron Meurer

← Older revision		Revision as of 10:54, 16 April 2014
Line 465:		Line 465:
	* LinXitoW		* LinXitoW
	* Aaron Meurer		* Aaron Meurer
		+
		+	[[Category:Customization]]
		+	[[Category:Intermediate]]
		+	[[Category:Emacs Lisp]]
		+	[[Category:Lisp]]
		+	[[Category:Programming]]
		+	[[Category:Tutorial]]

@@ Line 2: / Line 2: @@
 This gives an introduction to Emacs Lisp in 15 minutes (v0.2d)
-Author: Bastien / @bzg2 / http://bzg.fr
+Author: Bastien / @bzg2 / http://bzg.fr (the [[Org]] maintainer for many years)
 First make sure you read this text by Peter Norvig:

@@ Line 392: / Line 392: @@
      (switch-to-buffer-other-window "*test*")
      (erase-buffer)
-     Say hello to names in `list-of-names'
+     ;; Say hello to names in `list-of-names'
      (mapcar 'hello list-of-names)
      (goto-char (point-min))
-     Replace "Hello" by "Bonjour"
+     ;; Replace "Hello" by "Bonjour"
      (while (search-forward "Hello" nil t)
        (replace-match "Bonjour"))

@@ Line 9: / Line 9: @@
 Going through this tutorial won't damage your computer unless
 you get so angry that you throw it on the floor.  In that case,
-I hereby decline any responsability.  Have fun!
+I hereby decline any responsibility.  Have fun!

Emacs Lisp in 15 minutes - Revision history

Elvince: B. Guery, org maintainer

166.200.168.217: Commented the intended lines of hello-to-bonjour ()

Holocronweaver: correct spelling error

Elvince: cats

Elvince: elisp in 15 min