Elisp Basics

After our MS Graph with PowerShell post, we now have a command-line program we can run to run MS Graph queries to retrieve information like contacts and calendar. The next step is to bring this into Emacs, and we're going to cover our basics in this post, and then discuss how to properly run the program asynchronoulsy next time to tie everything together.

Elisp Introduction

An Introduction to Programming in Emacs Lisp is a great gentle introduction to getting productive with elisp.

Here I present a shorter version on how to get going with elisp linking mostly to the reference docs, assuming that you already know a programming language.

• Getting help. Useful commands while coding include C-h f (provides help for a function), and C-h v (provides help for a variable). C-h m to describe the buffer mode, and C-h b to displays the active key bindings will help you move around.
• Running code. Elisp runs directly within emacs by an evaluation engine.
• The easiest way to get going is to use the *scratch* buffer, which uses Lisp Interaction mode, a major mode for typing and evaluating Lisp forms. Simply place the cursor after the code you want to run, and run C-u C-x C-e to evaluate that expression and insert into the buffer (or C-j to insert printed text into buffer directly).
• For example, type 1 and put the cursor after the closing parens, then run C-j. You will see the result of the evaluation.
• Try (+ 1 2) to evaluate a function (+) instead.
• Evaluating expressions. A Lisp object to be evaluated is an expression.
• Fundamental types are integer, float, cons, symbol, string, vector, hash-table, subr, byte-code function, and record, as well as a bunch of Editing Types, those that are more entwined with Emacs as a program/editor.
• nil is the symbol for false, and for an empty list.
• t is the symbol for true. When bool is expected, any non-nil value will be true.
• Numbers, strings and vectors self-evaluate (meaning they evaluate to the value they represent). For example, 1 or "text".
• Symbols evaluate to their bound (or set) value. For example, (setq a 1) lets you evaluate a and yields 1.
• A form that is a nonempty list is either a function call, a macro call, or a special form, according to its first element. The first element is not evaluated. If it's a symbol, then the bound value is looked up and if it's a function (or lambda or something of the sort), then the body is evaluated. If it's a macro, then the arguments are passed as-is (rather than evaluated), and the macro gets to return an expression (its "expansion"), which is evaluated.
• A quote ((quote a) or 'a) yields the un-evaluated expression, which is useful to constant symbols are lists which would otherwise evaluate.
• Declaring a function. To declare a function, use the defun macro.
• For example, (defun my-fun (first-arg &optional second-arg &rest anything-left) "my function" (interactive) (print "hi there")).
• Declaring a variable. A variable is a name that can be bound (or set) to an object (i.e. a symbol).
• You can set a value globally with set or setq, eg (setq a 123).
• You can set a value locally with let, eg (let ((a 1) (b 2)) (print "do something with a and b")).
• You can add documentation to your global variable with defvar. See tips here.
• Flow control. Many of the special forms allow you to control the flow of evaluation.
• Use progn to evaluate multiple expressions and yield the last one. Eg (progn (print "hi") "result").
• Conditionals include (if cond then else-forms...), (when cond then-forms...), (unless cond then-forms...).
• Use cond as a kind of switch: (cond (cond-1 result-1) (cond-2 result-2)).
• Logical operators (short-circuited): (not cond), (and cond-forms...), (or cond-forms...), (xor cond-1 cond-2).
• Looping: (while cond then...) (always nil rather than last), and the dolist and dotimes macros.

This will more than cover everything that we need to integrate MS Graph into Emacs.

Code Organization

Based on the previous section, you should be able to following along and get things working with your own programs. Let's cover some practices on how to organize code then.

• Coding style. The default formatting should help, and the coding conventions will set you on the right path. Documentation and comments have their own section.
• File organization.
• My suggestion is to stick to a single file for as long as feasible.
• Libraries are .el files in the library path. It may be handy to call (add-to-list 'load-path "/path/to/my/lisp/library") if you have many personal libraries. You can require or autoload from your .emacs file. See Libraries of Lisp Code for Emacs for more information.
• There are conventions for code layout within library files.
• Packages. Packages are the standard way of distributing libraries. If your library is a single file, you can use a simple package layout, which is basically a single file with special comments.

Using the Editor

Here are some of the most important reference points when working with the editor.

• Buffers. These are the most direct way to work with Emacs content. You'll use points and markers to refer to locations within buffers. You will manipulate the text within, including styling, custom properties, editing operations, and much more.
• Keymaps. As a keyboard-heavy editor, you'll want to make sure you have good keybindings for your functions.
• Windows and frames. In Emacs, a window gives you access to each partition within a "rectangle with a menu", while a frame is the top-level thing your operating system manages. A frame has one or more windows.

Happy Emacs Lisp coding!

Tags:  emacs

Home