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