colin/org-notebook-tutorial.git

‎

1. Learning Common Lisp and Emacs with an Org Mode Notebook Tutorial

1 Learning Common Lisp and Emacs with an Org Mode Notebook Tutorial

There's a lot to learning Common Lisp, even if you already know how to program in some other language. There's the language itself with its many odd features and terms: CONS, CAR and CDR; generic functions and multiple dispatch methods; ancillary methods; special variables; macros; CLOS and multiple inheritance; the condition system; S-expressions; interactive development, and so on.

That would be challenging enough. But then… then there's Emacs. It is oft remarked by wistful Lispers nursing their bitterness about the eternal decline of Lisp that if only Emacs weren't so foreign to the users of today… if only there were a "more modern" IDE… then maybe Lisp would rule the world like it seemed destined to do in the late 80s and early 90s….

[Aside: A joke about this, btw, is that Common Lisp isn't dead: it's Undead]

Fair enough. Emacs is in fact, yet another thing to learn. But hopefully… well hopefully learning Emacs will pay some dividends beyond being able to use SLIME for your Common Lisp work.

This document offers up one such dividend: Orgmode with Babel for polyglot computational notebooks.

1.1 What is Orgmode?

Orgmode is a text format AND a built-in editor mod for Emacs. Its principle purpose is to turn Emacs into a fan-f*cking-tastic editor for structured hierarchical documents.

[Aside: That is a link in the above paragraph. Visit it by placing your cursor on it and typing C-c C-o.

You are reading an .org file right now. When Emacs opens file ending in .org into a buffer, it becomes aware of several headings, which may be collapsed and expanded at will for quick perusal.

Try it. Navigate up to this section's heading. Now hit TAB a couple of times.

The absolute bare minimum things you need to know about using Org.

navigate between headers with C-c C-n and C-c C-p for the next and previous headers respectively.
Make headlines by typing some number of asterisks and then some text
The first headline above this one with fewer leading asterisks is called the parent of this headline. E.g. The headline of this section is "What is Orgmode?" and its parent is "Learning Common Lisp and Emacs with an Org Mode Notebook Tutorial".
Headlines with the same parent as this one are called sibling headlines.
You can move this headline around among its siblings by typing M-Up and M-Down. These same commands work for lists too (like this one! Try it: navigate to the first line of this text and move 5 into the 4 spot.
You can shift an item into a sub-list or sub-headline by using M-Left and M-Right. Again try it with this list!

Pretty cool right? That ain't the half of it. Let's keep going!

1.2 Computational Notebooks in Org

To write nice, syntax highlighted code, that you can execute from Orgmode, you must place that code inside of a block.

Lets generate one by typing either M-x org-insert-structure-template, or by typing C-c C-, and then hitting s.

Did you do it?

1.2.1 A Python Example

You can write code in practically any language, evaluate it, and embed evaluated results right into emacs. Those results can be images, tables, strings, whatever.

But, like with most things in Emacs, some configuration is in order. Don't worry! You do that from org too!

Configure our Emacs to Execute Python and Lisp from Org
The following block sets a particular variable and loads some code associated with it. The details are weedy, but you get the idea.
```
(org-babel-do-load-languages
 'org-babel-load-languages
 '((emacs-lisp . t)
   (python . t)
   (lisp . t)))
```
Now place your cursor inside that block and type C-c C-c.

Voilà! You should now be able to run Lisp and Python code from Org for the remainder of this Emacs session.

If you want to save those changes, place the above code into your Emacs init file.
And Now … Some Python
Nothing fancy, just a function:
```
def oh_neat(x,y):
    return x+y

# this is a bit of a hack, but if you want to see the output you need
# to return something from the block itself.
return oh_neat(1,2) 
```
Go ahead, evaluate it with C-c C-c

Pretty neat eh? You can do more than simply return numbers or strings: if you wanted to use Emacs as a python notebook, you should consult the docs.

1.3 Trying it with Lisp

Before you can evaluate code, you must first start a SLIME session with M-x slime. So do that now.

Next, observe the structure of this code block:

(defun okcool (cool)
  cool)

(okcool "cool!")

After begin_src we have lisp. This tells org mode what language to use. Emacs correctly identifies Common Lisp as the only true Lisp, so you need not write common_lisp or something equally spurious. 🤣

Second, we specify that we want raw results. Essentially, this is just the return value of the last expression in the block.

Go ahead and try it out now with C-c C-c

Now that you have defined a function, you can call it in other blocks:

(okcool "wow")

Behind the scenes, Org is using SLIME in the normal way.

1.4 Fin

So that's the basics. If you like this style, you can use org-mode as you learn Common Lisp. Some people find it a dandy way to take notes while they work through examples and exercises in various texts.

Created: 2023-03-15 Wed 08:48

Validate