Documentation for Common Lisp code blocks in Babel
[worg.git] / org-contrib / babel / languages / ob-doc-lisp.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE:      Common Lisp Source Code Blocks in Org Mode
6 #+AUTHOR:     Thomas S. Dye
7 #+EMAIL:      tsd[at]tsdye[dot]com
8 #+LANGUAGE:   en
9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+LINK_UP:    ../languages.html
11 #+LINK_HOME:  http://orgmode.org/worg/
12 #+EXPORT_EXCLUDE_TAGS: noexport
13
14 #+name: banner
15 #+begin_html
16   <div id="subtitle" style="float: center; text-align: center;">
17   <p>
18   Org Mode support for <a href="http://common-lisp.net/project/slime/">Common Lisp</a>
19   </p>
20   <p>
21   <a href="http://common-lisp.net/project/slime/">
22   <img src="./images/slime-small.png"/>
23   </a>
24   </p>
25   </div>
26 #+end_html
27
28 * Template Checklist [12/12]                                       :noexport:
29   - [X] Revise #+TITLE:
30   - [X] Indicate #+AUTHOR:
31   - [X] Add #+EMAIL:
32   - [X] Revise banner source block [3/3]
33     - [X] Add link to a useful language web site
34     - [X] Replace "Language" with language name
35     - [X] Find a suitable graphic and use it to link to the language
36       web site
37   - [X] Write an [[Introduction]]
38   - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
39   - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
40   - [X] Describe [[Header%20Arguments][Header Arguments]]
41   - [X] Describe support for [[Sessions]]
42   - [X] Describe [[Result%20Types][Result Types]]
43   - [X] Describe [[Other]] differences from supported languages
44   - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
45 * Introduction
46 According to [[http://en.wikiquote.org/wiki/Lisp_programming_language][John Foderaro]], Lisp is a programmable programming language.
47
48 * Requirements and Setup
49
50 Common Lisp source code blocks are evaluated by Babel with the Superior Lisp
51 Interaction Mode for Emacs, or [[http://common-lisp.net/project/slime/][SLIME]].  [[http://common-lisp.net/project/slime/][SLIME]] supports many Common
52 Lisp implementations and is compatible with GNU Emacs version 21 and
53 later and with XEmacs version 21.
54
55 You'll need a working installation one of the many Common Lisp
56 implementations supported by [[http://common-lisp.net/project/slime/][SLIME]], and [[http://common-lisp.net/project/slime/][SLIME]] itself. Consult the
57 installation instructions for the Common Lisp implementation of your
58 choice. [[http://common-lisp.net/project/slime/doc/html/Installation.html#Installation][SLIME installation]] requires just a few lines in =.emacs=.
59
60 To configure Common Lisp source code blocks in Org mode, add the
61 appropriate dotted pair to =org-babel-load-languages=:
62
63 #+begin_src emacs-lisp :exports code
64   (org-babel-do-load-languages
65    'org-babel-load-languages
66    '((lisp . t)))
67 #+end_src
68
69 * Org Mode Features for Common Lisp Source Code Blocks
70 ** Header Arguments
71 There are no language-specific default values for header arguments
72 to Common Lisp source code blocks.
73
74 A single language-specific header argument is defined for Common Lisp
75 source code blocks:
76
77 - :package :: a string that names a Common Lisp package within which
78               to execute the source code block. The default value is
79               =:any=, which will execute the source code block in the
80               current package.
81 ** Sessions
82
83 By their nature, Common Lisp interpreters always run "sessions."
84
85 ** Result Types
86 All result types are supported.
87 ** Other
88
89 The SLIME session must be running when the Common Lisp source code
90 block is executed.
91
92 * Examples of Use
93
94 Start SLIME: =M-x slime <RET>=.
95
96 #+begin_example
97 ,#+name: hello-world
98 ,#+header: :var message="Hello World!"
99 ,#+begin_src lisp
100   (princ message)
101 ,#+end_src
102 #+end_example
103  
104 Execute the source code block with =C-c C-c= to yield this result:
105 #+name: hello-world
106 #+header: :exports results
107 #+header: :var message="Hello World!"
108 #+begin_src lisp
109 (princ message)
110 #+end_src
111
112 #+results: hello-world
113 : Hello World!
114
115
116 * Links to Tutorials and Other Resources
117
118 On-line Lisp books include an [[http://www.lisperati.com/casting.html][introductory comic book]], a [[http://www.gigamonkeys.com/book/][dead-sexy
119 introduction and tutorial]], and a [[http://paulgraham.com/onlisp.html][comprehensive study of advanced Lisp
120 techniques]].  Highly recommended.
121