Babel provides what is known as literate programming to org-mode, from Org’s manual:
“Source code here refers to any plain text collection of computer instructions, possibly with comments, written using a human-readable programming language. Org can manage source code in an Org document when the source code is identified with begin and end markers. Working with source code begins with identifying source code blocks. A source code block can be placed almost anywhere in an Org document; it is not restricted to the preamble or the end of the document. However, Org cannot manage a source code block if it is placed inside an Org comment or within a fixed width section.”
Example:
+BEGIN_SRC elixir
"hello" <> " world"
+END_SRC
+RESULTS:
hello world
The result was generated using the ob-elixir library, with the
help of `org-babel-execute-src-block’ interface function.
Checkout the complete manual here
- Alpha: 0.0.3
- ob
- ob-tangle
- Erlang
- Elixir
- REPL: iex
- FreeBSD 12.1
- Emacs 27.1, 28.0.50
- Org-mode 9.3
Clone ob-elixir repository to an arbitrary location:
$ git clone https://github.com/lambdart/ob-elixir ~/.emacs.d/site-elisp/ob-elixir
Add ob-elixir directory to load-path in your
Emacs initialization file (init.el) and load it.
;; add to load-path
(add-to-list 'load-path "/replace/me/to/ob-elixir/full/path")
;; load ob-elixir feature
(require 'ob-elixir nil t)
- TIP: For a more dynamic approach:
M-x load-library RET ob-elixir RET
- Note: Optional (recommended).
To compile the files to the Elisp byte-compiled representation:
[at-ob-elixir-root-directory]$ make
Configure babel support in org-mode, i.e, evaluate this
code snippet during Emacs initialization (or latter).
(org-babel-do-load-languages
'org-babel-load-languages
'((emacs-lisp . t)
(elixir . t)))Passing arguments to be evaluate can be achieved using the source
code block header keyword :var, the value types will be parsed
from Elisp to Elixir syntax, note cons cells () will be mapped
to tuples, and vector [] to list.
The other basic types (Atom, Boolean, Integer, Float, and String) have a direct relation.
See the examples below for a better understanding of what does it really means.
+BEGIN_SRC elixir :results “replace” :var n=’:atom
i n
+END_SRC
+RESULTS:
Term :atom Data type Atom Reference modules Atom Implemented protocols IEx.Info, Inspect, List.Chars, String.Chars
+BEGIN_SRC elixir :results “replace” :var n=’true
is_boolean(n)
+END_SRC
+RESULTS:
true
+BEGIN_SRC elixir :results “replace” :var n=1
i n
+END_SRC
+RESULTS:
Term 1 Data type Integer Reference modules Integer Implemented protocols IEx.Info, Inspect, List.Chars, String.
+BEGIN_SRC elixir :var n=1.0
i n
+END_SRC
+RESULTS:
Term 1.0 Data type Float Reference modules Float Implemented protocols IEx.Info, Inspect, List.Chars, String.Chars
+BEGIN_SRC elixir :results “replace” :var n=”string”
i n
+END_SRC
+RESULTS:
Term "string" Data type BitString Byte size 6 Description This is a string: a UTF-8 encoded binary. It's printed surrounded by "double quotes" because all UTF-8 encoded code points in it are printable. Raw representation <<115, 116, 114, 105, 110, 103>> Reference modules String, :binary Implemented protocols Collectable, IEx.Info, Inspect, List.Chars, String.Chars
+BEGIN_SRC elixir :results “replace” :var n=’(1 2 3)
i n
+END_SRC
+RESULTS:
Term [1, 2, 3] Data type List Reference modules List Implemented protocols Collectable, Enumerable, IEx.Info, Inspect, List.Chars, String.Chars
+BEGIN_SRC elixir :results “replace” :var n=’[1 “tuple” :true]
i n
+END_SRC
+RESULTS:
Term
{1, "tuple", true}
Data type
Tuple
Reference modules
Tuple
Implemented protocols
IEx.Info, Inspect
- Note: To see all the options inside
Emacsand customize it, use:M-x customize-group RET ob-babel RET.
ob-babel-elixir-program- Name of the program that will execute the Elixir source code block. (Default: iex)
ob-babel-elixir-timeout- Subprocess output timeout in seconds. (Default: 60)
ob-babel-elixir-mode- Elixir major mode. (Default ‘elixir-mode)
ob-babel-elixir-table-flag- Non-nil means reassemble tables in the RESULTS. (Default nil)
MIT
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."
| Donald Knuth |