Merge branch 'worg-new-exporter'
[worg.git] / org-contrib / babel / languages / ob-doc-clojure.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t 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:      Org-babel-clojure
6 #+AUTHOR:     Joel Boehland
7 #+EMAIL:      joel dot boehland at evocomputing dot com
8 #+LANGUAGE:   en
9 #+HTML_HEAD:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+LINK_UP:    ../languages.html
11 #+LINK_HOME:  http://orgmode.org/worg/
12
13 #+begin_html
14   <div id="subtitle" style="float: center; text-align: center;">
15   <p>
16   Org-babel support for
17   <a href="http://clojure.org/">Clojure</a>
18   </p>
19   <p>
20   <a href="http://clojure.org/">
21   <img src="http://clojure.org/space/showimage/clojure-icon.gif"/>
22   </a>
23   </p>
24   </div>
25 #+end_html
26
27 * Notes                                                            :noexport:
28 ** Template Design
29   - What the user wants to know:
30     - Required software
31     - How to install it
32     - How to configure it in Org-babel
33     - Org-babel conventions that might affect the language
34     - How it modifies Org-babel
35     - Common ways to use it
36
37 * Requirements
38 ** A working Java install, version 1.5 or later
39    Installation instructions for java are beyond the scope of this
40    document, but instructions for all major platforms can easily be
41    found on [[http://java.sun.com][Sun's java website]].
42
43 ** A working Clojure install
44    You can set Clojure up separately as described in the
45    [[http://clojure.org/getting_started][official install document]] from the Clojure web site, but as you 
46    will see below, if you use ELPA to install the required packages, 
47    it can install Clojure for you.
48
49 ** Emacs ELPA package manager
50    Although it is possible to grab the different pieces and line all
51    the version numbers up so that it works, the process will most
52    likely bring you to bitter tears unless you are very experienced
53    and patient with setting up emacs, clojure, slime and swank. Save
54    yourself some trouble and use the [[http://tromey.com/elpa][Emacs Lisp Package Archive (ELPA)]].
55
56 ** Working (and recent) emacs ELPA clojure packages
57    You will need to install the following packages:
58    clojure-mode, swank-clojure, slime, slime-repl
59
60 *** Installation
61     Once you have installed ELPA, you can do this easily in one step
62     within emacs by issuing the command:
63     
64 #+begin_example
65    M-x package-list-packages
66 #+end_example
67    
68    You will be presented with a buffer where you can select all of
69    these packages. Simply enter "i" on the lines of the packages you
70    wish to install, and when you are done selecting packages enter "x"
71    and ELPA will download and install these packages for you.
72    
73    Install these packages:
74
75 #+begin_example
76    clojure-mode swank-clojure slime slime-repl
77 #+end_example
78
79    At this point you should be able to start SLIME and have access to
80    a working Clojure REPL:
81
82 #+begin_example
83    M-x slime
84 #+end_example
85    
86    Note that if swank-clojure can't detect the Clojure jars, it will
87    prompt you for permission to download the required jars.
88
89 ** An up-to-date install of emacs-org-mode
90    You will probably need org-mode 6.34 or later
91
92 * Advanced setup
93   There are quite a few usage modes for using emacs, clojure-mode,
94   swank-clojure, slime, and clojure. Following is a short description
95   in roughly easy to hard order. Note that the documentation for this
96   section comes mostly from Technomancy's writeup for the
97   [[http://github.com/technomancy/swank-clojure][swank-clojure project]].
98    
99 ** Use ELPA to install it for you (Easiest)
100    This is the shortest path to victory. Assuming you have a suitable
101    Java installed on your system, and the ELPA package manager
102    installed, you can simply install the required elisp packages, as
103    well as Clojure. 
104    
105 ** Project
106    Put your project's dependencies in the lib/ directory, either
107    manually or using [[http://github.com/technomancy/leiningen][Leiningen]] or Maven then launch:
108
109 #+begin_example
110    M-x swank-clojure-project
111 #+end_example
112
113    Note that you must have swank-clojure.jar in the lib/ directory, it
114    will not automatically add itself to the classpath as it did in
115    past versions that had to run from a checkout.
116
117 ** Server
118    Users of [[http://github.com/technomancy/leiningen][Leiningen]] or clojure-maven-plugin can launch a server from
119    a shell and connect to it from within Emacs.
120    
121 *** Set up Leiningen project.clj file
122     You should set up your project's project.clj file to look
123     something like this
124
125 #+begin_src clojure
126   (defproject my-project "0.1.0"
127     :description "My great Clojure project"
128     :dependencies [[org.clojure/clojure "1.1.0-alpha-SNAPSHOT"]
129                    [org.clojure/clojure-contrib "1.0-SNAPSHOT"]]
130     :dev-dependencies [[leiningen/lein-swank "1.0.0-SNAPSHOT"]])
131 #+end_src
132     
133     Then from your project directory you can run the following:
134
135 #+begin_example
136     $ lein swank
137 #+end_example
138
139     A REPL should get started up on port 4005. Launch Emacs. Once Emacs is
140     up and running type:
141
142 #+begin_example
143     M-x slime-connect
144 #+end_example
145
146     Use the default settings. You’re now connected to a Clojure REPL with a properly
147     configured classpath for this particular project.
148     
149     Note that you could also connect to a remote server that you
150     started with the lein swank command as well using slime-connect.
151
152 ** Custom classpath (Hard)
153    If you know your way around setting up Java Classpaths and Emacs
154    load-paths, then you can set all of this up in your own custom
155    way. Set swank-clojure-classpath to a list of paths to the jars you
156    want to use and then use slime as before.
157
158 *** Example
159      Let's say you have have the clojure.jar, clojure-contrib.jar and
160      swank-clojure.jar files in the directory ~/.my-clojure-jars.
161
162      You could properly set swank-clojure-classpath by entering the
163      following elisp code into your *scratch* buffer:
164
165 #+begin_example
166      (setq swank-clojure-classpath (directory-files "~/.my-clojure-jars" t ".jar$"))
167 #+end_example
168
169      Then, move the cursor to the end of that elisp code and enter the command:
170
171 #+begin_example
172      M-j
173 #+end_example
174     
175      You should now be able to start slime and have it be using the
176      jars entered above.
177
178 #+begin_example
179      M-x slime
180 #+end_example
181      
182 * Usage
183   All the usage examples assume that you have a basic Clojure,
184   clojure-mode, swank-clojure and slime set up correctly. You should
185   be able to get a Clojure REPL when you issue the command:
186 #+begin_example
187   M-x slime
188 #+end_example
189   Make sure this is working for you before proceeding with the
190   org-babel-clojure examples.
191 ** Non session execution
192     By default, org-babel will execute each block by starting up a
193     Clojure process and having it execute each source block in
194     isolation from the other source blocks. Due to the relatively long
195     startup time of a Java JVM, this can make execution of many blocks
196     very *slow*. Unless you really need the execution isolation for
197     some reason, it is recommended that you use sessions in
198     org-babel-clojure.
199     
200 *** Examples
201 **** Basic Functionality
202      Let's start really simple. We will just test the execution of a
203      simple Clojure form. Create an org file and insert the following:
204 #+begin_example
205      #+name: basic-clojure
206      #+begin_src clojure :results silent
207        (+ 1 4)
208      #+end_src
209 #+end_example
210     
211      Now place the cursor anywhere between the begin_src..end_src lines
212      and enter the command:
213
214 #+begin_example
215     C-c C-c
216 #+end_example
217     
218     This should execute the Clojure form, and echo the results: "5".
219     
220     Now let's insert the results into the buffer immediately after the
221     Clojure src block. Insert the following into your org file:
222
223 #+begin_example
224     #+name: basic-clojure-table-results
225     #+begin_src clojure :results value
226       [ 1 2 3 4]
227     #+end_src
228 #+end_example
229
230     Execute as before:
231 #+begin_example
232     C-c C-c
233 #+end_example
234     
235     Now, immediately following this block, the following block should
236     have been inserted:
237
238 #+begin_example
239     #+resname: basic-clojure-table-results
240     | 1 | 2 | 3 | 4 |
241 #+end_example
242
243     Note that the Clojure vector has been automagically converted to
244     an org table.
245 ** Session execution
246    org-babel-clojure supports executing code blocks in the context of
247    one or more SLIME REPL sessions. This means that after the initial
248    startup time, the code blocks will execute much quicker. It also
249    means that you can easily go back and inspect the transcript
250    between Emacs and Clojure that will be stored in the
251    *inferior-lisp* and REPL buffers. You can also use the powerful
252    debugging and inspection facilities provided by SLIME.
253
254 *** Examples
255 **** Basic Functionality
256      Let's mirror the simple non-session examples we did above, but
257      execute them within a session.
258      
259      Create an org file and insert the following:
260 #+begin_example
261      #+name: basic-session-clojure :session s1
262      #+begin_src clojure :results silent
263         (+ 1 4)
264      #+end_src
265 #+end_example
266     
267      This will initialize a session named "s1". Now place the cursor
268      anywhere between the begin_src..end_src lines and enter the
269      command:
270
271 #+begin_example
272      C-c C-c
273 #+end_example
274     
275      This should create a SLIME REPL buffer named "s1", and execute the
276      Clojure form, and echo the results: "5". Note that the initial
277      creation of this SLIME REPL can take several seconds. Once this
278      session has been created, the execution will happen very quickly.
279
280      Now let's insert the results into the buffer immediately after the
281      Clojure src block. Insert the following into your org file:
282
283 #+begin_example
284      #+name: basic-session-clojure-table-results
285      #+begin_src clojure :session s1 :results value
286         [ 1 2 3 4]
287      #+end_src
288 #+end_example
289
290      Execute as before:
291 #+begin_example
292      C-c C-c
293 #+end_example
294     
295      As with the non-session code block, immediately following this block, the following block should
296      have been inserted:
297
298 #+begin_example
299      #+resname: basic-session-clojure-table-results
300      | 1 | 2 | 3 | 4 |
301 #+end_example
302
303 **** Multiple sessions
304      org-babel-clojure also supports multiple sessions executing
305      concurrently. The following example will illustrate two different
306      sessions running in isolation from each other.
307      
308      Create an org file with the following content:
309 #+begin_example
310      #+name: set-clojure-session-var-s1
311      #+begin_src clojure :session s1 :results value
312      (def *var* [1 2 3])
313      #+end_src
314      
315      #+name: set-clojure-session-var-s2
316      #+begin_src clojure :session s2 :results value
317      (def *var* [3 4 5 6 7 8 9])
318      #+end_src
319
320      #+name: get-clojure-session-var-s1
321      #+begin_src clojure :session s1 :results value
322      (count *var*)
323      #+end_src
324      
325      #+name: get-clojure-session-var-s2
326      #+begin_src clojure :session s2 :results value
327      (count *var*)
328      #+end_src
329 #+end_example
330
331      Execute the entire buffer
332 #+begin_example
333      C-c M-b b
334 #+end_example
335     
336      You should have two separate SLIME REPL sessions being created,
337      and the results from executing each source block will be inserted
338      after the respective block. The resulting buffer should look
339      something like this:
340 #+begin_example
341      #+name: set-clojure-session-var-s1
342      #+begin_src clojure :session s1 :results value
343      (def *var* [1 2 3])
344      #+end_src
345      
346      #+results: set-clojure-session-var-s1
347      : #'user/*var*
348
349      #+name: set-clojure-session-var-s2
350      #+begin_src clojure :session s2 :results value
351      (def *var* [3 4 5 6 7 8 9])
352      #+end_src
353
354      #+results: set-clojure-session-var-s2
355      : #'user/*var*
356
357      #+name: get-clojure-session-var-s1
358      #+begin_src clojure :session s1 :results value
359      (count *var*)
360      #+end_src
361      
362      #+results: get-clojure-session-var-s1
363      : 3
364
365      #+name: get-clojure-session-var-s2
366      #+begin_src clojure :session s2 :results value
367      (count *var*)
368      #+end_src
369    
370      #+results: get-clojure-session-var-s2
371      : 7
372 #+end_example
373